最近在项目中使用了 CouchDB 作为文档数据库，考虑到生产环境的需求，研究了一套基于 Prometheus 的监控方案。这套方案全部跑在 Docker 环境下，现在整理成文，供有需要的同学参考。

为什么需要监控 CouchDB 链接到标题

CouchDB 是一个面向文档的 NoSQL 数据库，默认提供 HTTP API。在生产环境中，我们需要关注：

  • 服务可用性：数据库是否正常运行
  • 请求性能：QPS、延迟、错误率
  • 资源消耗：内存、磁盘、文件描述符
  • 复制状态：多节点集群的同步健康度

CouchDB 自身提供了 /_stats 和 /_active_tasks 等 HTTP 端点，而 couchdb-prometheus-exporter 可以把这些数据转换为 Prometheus 可抓取的格式。

Docker Compose 部署 链接到标题

整个监控架构分为两层：CouchDB 数据库 + CouchDB Exporter。

services:
  couchdb:
    image: docker.m.daocloud.io/library/couchdb:3.5.1
    container_name: couchdb
    user: 1000:1000
    environment:
      - COUCHDB_USER=${COUCHDB_USER}
      - COUCHDB_PASSWORD=${COUCHDB_PASSWORD}
    volumes:
      - couchdb-data:/opt/couchdb/data
    restart: unless-stopped
    ports:
      - 5984:5984
    networks:
      - couchdb-net

  couchdb-exporter:
    image: gesellix/couchdb-prometheus-exporter:v30.17.0
    container_name: couchdb-exporter
    ports:
      - 9984:9984
    environment:
      COUCHDB_URI: http://${COUCHDB_USER}:${COUCHDB_PASSWORD}@couchdb:5984
      COUCHDB_USERNAME: ${COUCHDB_USER}
      COUCHDB_PASSWORD: ${COUCHDB_PASSWORD}
    depends_on:
      - couchdb
    networks:
      - couchdb-net
    restart: unless-stopped

volumes:
  couchdb-data:
    name: couchdb-service_couchdb-data

networks:
  couchdb-net:
    name: couchdb-net
    driver: bridge

关键配置说明：

配置项 说明
couchdb-exporter 镜像 使用 gesellix/couchdb-prometheus-exporter，当前稳定版本 v30.17.0
Exporter 端口 9984，Prometheus 通过此端口抓取 metrics
认证方式 通过环境变量传入 CouchDB 的用户名密码
网络模式 CouchDB 和 Exporter 在同一 bridge 网络中通信

Prometheus 配置 链接到标题

添加抓取目标 链接到标题

在 prometheus.yml 中添加新的 job：

scrape_configs:
  # ... 其他 job ...

  - job_name: couchdb
    static_configs:
      - targets:
          - <COUCHDB_HOST>:9100      # node-exporter
          - <COUCHDB_HOST>:9984      # couchdb-exporter
        labels:
          service: couchdb

其中 9100 端口是主机层面的 node-exporter（用于监控宿主机的 CPU、内存、磁盘），9984 端口是 CouchDB 专用的 exporter。

验证抓取 链接到标题 

curl http://localhost:9984/metrics | grep couchdb_httpd_up

正常情况下应该看到 couchdb_httpd_up 1，表示 CouchDB 连接健康。

CouchDB 监控指标详解 链接到标题

couchdb-prometheus-exporter 暴露的指标非常全面，涵盖 CouchDB 运行的方方面面。下面按类别介绍。

服务健康指标 链接到标题

指标名 说明
couchdb_httpd_up CouchDB 连接健康检查（1=正常，0=异常）
couchdb_up Exporter 自身健康状态

这是最基础的指标，用于判断服务是否存活。

请求与性能指标 链接到标题

指标名 说明
couchdb_httpd_requests HTTP 请求总数
couchdb_httpd_request_methods{method="GET/POST/PUT/DELETE"} 按 HTTP Method 统计的请求数
couchdb_httpd_request_time 请求处理时长（不含 MochiWeb 层）
couchdb_httpd_database_reads 文档读取次数
couchdb_httpd_database_writes 数据库写入次数
couchdb_httpd_bulk_requests 批量操作请求数

HTTP 响应状态码 链接到标题

指标名 说明
couchdb_httpd_status_codes{code="2xx/4xx/5xx"} 按状态码分类的响应统计

通过 rate(couchdb_httpd_status_codes{code=~"5.."}[5m]) 可以计算 5xx 错误率。

认证与缓存 链接到标题

指标名 说明
couchdb_httpd_auth_cache_hits 认证缓存命中数
couchdb_httpd_auth_cache_misses 认证缓存未命中数

缓存命中率高说明认证效率好。如果未命中率高，可能需要调整 CouchDB 的认证缓存配置。

数据库层面指标 链接到标题

指标名 说明
couchdb_httpd_databases_total 集群数据库总数
couchdb_httpd_open_databases 当前打开的数据库数
couchdb_httpd_open_os_files 打开的文件描述符数量
couchdb_database_doc_count{db_name="xxx"} 各数据库文档数量
couchdb_database_data_size{db_name="xxx"} 各数据库数据大小（字节）
couchdb_database_disk_size{db_name="xxx"} 各数据库磁盘占用（字节）
couchdb_database_overhead{db_name="xxx"} 磁盘开销（overhead）

couchdb_database_overhead 是一个重要指标，当这个值超过磁盘大小的 50% 时，意味着数据库碎片化严重，建议执行 compact 操作来回收空间。

复制器指标 链接到标题

CouchDB 内置了双向复制功能，复制器指标对于集群运维至关重要：

指标名 说明
couchdb_replicator_jobs{metric="running/pending/crashed"} 复制任务状态分布
couchdb_replicator_cluster_is_stable 集群是否稳定（1=稳定，0=不稳定）
couchdb_replicator_failed_starts 复制启动失败次数
couchdb_replicator_checkpoints{metric="failure/success"} 复制检查点状态

Fabric 分布式指标 链接到标题

在 CouchDB 集群模式下，一些内部协调操作会暴露为 fabric 指标：

指标名 说明
couchdb_fabric_doc_update{metric="errors"} 文档更新错误数
couchdb_fabric_read_repairs{metric="failure/success"} 读修复操作的成败统计
couchdb_fabric_open_shard{metric="timeout"} 分片打开超时计数

Erlang 虚拟机指标 链接到标题

CouchDB 底层使用 Erlang/OTP，运行时环境的一些关键指标：

指标名 说明
couchdb_erlang_memory_atom Atom 表内存使用
couchdb_erlang_memory_processes 进程内存
couchdb_erlang_memory_binary 二进制数据内存
couchdb_erlang_memory_code 代码加载内存

日志统计 链接到标题

指标名 说明
couchdb_server_couch_log{level="error/warning/info"} 按级别统计的日志消息数量

通过监控 error 级别日志的数量，可以及时发现 CouchDB 的异常情况。

Prometheus 告警规则 链接到标题

有了指标数据，还需要配置告警规则来及时发现问题。下面是一组实用的告警规则：

groups:
  - name: couchdb_alerts
    interval: 30s
    rules:
      - alert: CouchDBDown
        expr: couchdb_httpd_up == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "CouchDB 已宕机"
          description: "CouchDB 已停止运行超过 1 分钟"

      - alert: CouchDBExporterDown
        expr: up{job="couchdb-exporter"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "CouchDB Exporter 已宕机"
          description: "CouchDB 指标采集器已停止运行"

      - alert: CouchDBHighErrorRate
        expr: |
          rate(couchdb_httpd_status_codes{code=~"5.."}[5m])
          / ignoring(code) rate(couchdb_httpd_requests[5m]) > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "CouchDB 错误率过高"
          description: "5xx 错误率超过 5%"

      - alert: CouchDBReplicatorUnstable
        expr: couchdb_replicator_cluster_is_stable == 0
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "CouchDB 复制器集群不稳定"
          description: "复制器集群状态不稳定，可能影响数据同步"

      - alert: CouchDBDiskOverheadHigh
        expr: couchdb_database_overhead / couchdb_database_disk_size > 0.5
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "CouchDB 数据库磁盘开销过高"
          description: "数据库 {{ $labels.db_name }} 磁盘开销超过实际数据的 50%，建议执行 compact"

告警通知链路 链接到标题

完整的告警流程是：

CouchDB Metrics → couchdb-exporter (:9984) → Prometheus (:9090)
                                              ↓
                                        Alertmanager (:9093)
                                              ↓
                                      alert-transformer (:9091)
                                              ↓
                                        OpenClaw (:18789)
                                              ↓
                                          飞书通知

Alertmanager 接收 Prometheus 的告警，去重后转发给 alert-transformer 进行格式转换，最终通过 OpenClaw Agent 发送到飞书群。

总结 链接到标题

这套方案的优势：

  1. 零侵入：不需要修改 CouchDB 本身，只需部署额外的 exporter 容器
  2. 全面覆盖：从服务健康到数据库内部状态，都有对应的指标
  3. 自动化告警：基于 Prometheus 的规则引擎，可以灵活配置告警条件
  4. 可扩展：如果要监控多个 CouchDB 实例，只需要在 Prometheus 中添加新的 target 即可

如果你的项目正在使用 CouchDB，不妨把这套监控方案用起来。数据的稳定性是应用稳定性的基础，而监控是保障稳定性的第一道防线。