在运维Couchbase集群时，各项运行指标分散在节点详情页、桶监控页和查询统计页中，难以跨节点汇总，也不方便与现有监控体系整合。通过Prometheus exporter可以把这些指标统一暴露到/metrics端点，由Prometheus按固定频率采集，后续无论是画Grafana面板还是配置Alertmanager告警都会简单很多。本文围绕exporter的部署、抓取配置、关键指标和常见问题展开，帮助你完成一套可用的Couchbase监控链路。

Couchbase指标暴露架构与exporter定位

Couchbase Server在7.0之后开始提供原生Prometheus格式端点，但很多团队仍选择官方exporter，原因在于exporter可以基于REST API做字段规整，并且不同版本间有更好的兼容性。exporter作为一个独立进程，使用管理员或只读账号调用Couchbase的/pools/default/stats等接口，将响应中的数值转换为以cbnode_、cbucket_、cbquery_等为前缀的时间序列指标。Prometheus不直接和Couchbase通信，而是从exporter的HTTP端口抓取数据，这样也便于在一个抓取任务下聚合多套集群。

从部署形态看，exporter可以运行在任意能访问Couchbase 8091端口的机器上，不要求必须和数据库节点同机。生产环境通常会把exporter与Grafana、Alertmanager放在同一网段，或者用容器编排统一调度。exporter默认监听9191端口，并暴露/metrics路径，Prometheus通过静态配置或服务发现找到这些目标。一个exporter实例可以指向一个Couchbase集群，也可以启动多个实例分别对接开发、测试和生产环境。

需要区分的是，exporter本身只负责读取和转换，不保存任何历史数据。它的可用性会直接影响指标采集，因此在告警体系中最好加上对exporter进程存活的监控。如果exporter频繁重启或响应变慢，Prometheus会在Targets页面显示抓取失败，这时需要优先排查exporter与Couchbase之间的网络和认证。

部署exporter并验证指标输出

先下载官方发布的couchbase-exporter二进制文件，放到/usr/local/bin目录。启动时需要指定Couchbase集群地址、账号密码以及监听地址。下面是一个最小启动命令，假设Couchbase节点地址是192.168.1.20，账号为monitor，密码为secret。该账号建议使用Couchbase的只读角色，避免监控组件持有过高权限。

./couchbase-exporter \
  --couchbase.url=http://192.168.1.20:8091 \
  --couchbase.username=monitor \
  --couchbase.password=secret \
  --web.listen-address=:9191

启动后可以用curl检查指标是否生成。执行curl http://127.0.0.1:9191/metrics，如果能看到类似cbnode_up 1、cbucket_ops_per_sec的输出，说明exporter已经成功连接Couchbase并开始转换指标。如果只看到go运行时指标而没有cb开头指标，通常是认证失败或REST API路径不可达。可以查看exporter日志中是否有401或超时记录。生产环境建议通过systemd或容器守护进程运行，保证开机自启。

如果Couchbase启用了TLS，启动参数中需要加入CA证书路径，或者使用HTTPS地址。部分环境还会配置安全标头或IP白名单，这些都会影响exporter的HTTP请求。对于大规模集群，可以先把抓取间隔设为30秒，避免REST API统计接口压力过大。等确认指标完整后再调低到15秒或10秒。

配置Prometheus抓取与热加载

在Prometheus的配置文件prometheus.yml中，为Couchbase exporter增加一个抓取任务。目标地址填写exporter所在机器的IP和9191端口，不要填写Couchbase 8091端口，因为Prometheus读取的是exporter暴露的指标。下面是一个带集群标签的配置：

scrape_configs:
  - job_name: 'couchbase'
    scrape_interval: 15s
    scrape_timeout: 10s
    static_configs:
      - targets: ['192.168.1.30:9191']
        labels:
          cluster: 'prod-couchbase'

如果每个Couchbase节点都部署了一个exporter，可以在targets数组中列出多个地址。也可以在Kubernetes环境中使用pod annotations或service discovery自动发现exporter，避免手工维护目标列表。对大多数中小集群，静态配置已经足够。配置完成后，执行Prometheus热加载命令，例如kill -HUP $(pidof prometheus)或调用/-/reload接口，不要直接重启导致短暂断采。然后在Prometheus的Status - Targets页面找到couchbase任务，确认所有目标状态为UP。

这里顺带提醒，scrape_timeout必须小于scrape_interval，否则Prometheus会在大响应体或慢网络下放弃本次抓取。Couchbase的统计接口有时要扫描多个桶，第一次请求可能超过10秒，建议先放宽到20秒观察，稳定后再收紧。如果exporter和Prometheus之间经过NAT或防火墙，需要放行9191端口，同时确认Prometheus所在主机能访问exporter。

关键指标与告警规则

接入Prometheus后，最先关注的是节点存活类指标。例如cbnode_up表示节点是否在线，值1为正常、0为离线。节点资源方面可以查看cbnode_cpu_utilization_rate、cbnode_memory_free和cbnode_disk_used。桶维度指标则包括cbucket_ops_per_sec（每秒操作数）、cbucket_mem_used（已用内存）和cbucket_quota_bytes（桶配额字节数）。这些指标能快速判断集群是否出现热点、内存水位是否逼近上限、磁盘增长速度是否异常。

常用的PromQL查询例如计算所有桶的内存使用率：

100 * (cbucket_mem_used / cbucket_quota_bytes)

如果要查某个桶最近5分钟的平均每秒操作数：

rate(cbucket_ops_per_sec[5m])

这些表达式可以直接用于Grafana面板，也可以作为告警规则的基础。注意不同exporter版本对指标名称可能有细微差异，配置前最好先通过/metrics输出确认实际前缀和后缀。

下面给出一个告警规则文件示例，监控节点离线、桶内存使用率超过90%以及节点磁盘使用率超过85%。其中使用率计算中的大于号需要按PromQL语法正常书写，在Prometheus规则文件中不会被当作HTML标签，但在本文代码块中已做转义处理。

groups:
  - name: couchbase_alerts
    rules:
      - alert: CouchbaseNodeDown
        expr: cbnode_up == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: Couchbase 节点离线
      - alert: CouchbaseBucketMemoryHigh
        expr: 100 * (cbucket_mem_used / cbucket_quota_bytes) > 90
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: 桶内存使用率超过 90%
      - alert: CouchbaseDiskHigh
        expr: 100 * (cbnode_disk_used / cbnode_disk_total) > 85
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: 节点磁盘使用率超过 85%

将规则文件挂载到Prometheus的rule_files路径后，Prometheus会自动加载。告警触发后只会进入Alertmanager，不会影响抓取。为了避免误报，建议把for持续时间设置得稍长一些，并先从只读告警开始，观察一周再调整阈值。

常见问题与优化建议

第一个常见问题是抓取超时。如果exporter请求Couchbase的/stats接口耗时过长，Prometheus会记录scrape timeout错误。解决办法包括提高scrape_timeout、降低抓取频率，或者在exporter侧增加结果缓存。部分exporter支持通过启动参数设置内部刷新间隔，让Prometheus抓取时直接读取缓存，减少对Couchbase的实时压力。

第二个问题是权限过高或过低。使用Full Admin账号虽然能拉取所有指标，但也会带来安全风险；权限过低则可能看不到部分桶或索引指标。推荐在Couchbase中创建一个自定义只读角色，仅授予集群统计、桶统计和查询统计的读取权限。创建后可以在exporter日志和指标列表中验证是否缺少特定前缀的指标。

第三个问题是时间序列基数膨胀。当桶数量很多或索引数量很大时，exporter输出的指标数量可能迅速增加，导致Prometheus内存占用上升。可以在prometheus.yml中使用metric_relabel_configs丢弃部分不关心的指标，例如只保留cbnode_和cbucket_前缀：

metric_relabel_configs:
  - source_labels: [__name__]
    regex: 'cbindex_.*'
    action: drop

这样可以在采集阶段减少序列数量。还可以在exporter侧通过配置禁用某些采集模块，从源头降低指标体量。

完成上述配置后，建议用Prometheus的Targets页面和Grafana看板持续观察一天，确认所有节点和桶的曲线完整、没有断点。监控自身的稳定性同样重要，可以再增加一条针对exporter进程的告警，例如用up{job="couchbase"} == 0来检测采集目标不可用。