Couchbase作为一款分布式NoSQL数据库，日常运维中离不开对桶运行状态的深入观察。虽然官方管理控制台能看到部分指标，但真正要排查问题时，命令行工具cbstats才是最有力的武器。它能输出几百项细粒度统计，覆盖内存、磁盘、队列、vBucket等各个层面，是判断桶健康状态的第一手资料。本文将系统讲解cbstats的用法和核心指标含义。
cbstats基础：语法、参数与常用子命令
cbstats是Couchbase Server安装后自带的工具，位于安装目录的bin文件夹下，Linux环境一般在/opt/couchbase/bin/cbstats。它通过Memcached文本协议连接到目标节点的11210端口，拉取桶级别的统计信息，因此执行时需要指定节点地址、端口、桶名称以及具备该桶访问权限的账号密码。基本语法如下：
/opt/couchbase/bin/cbstats localhost:11210 -u Administrator -p password -b travel-data all
其中all参数表示输出全部统计项，实际输出可能多达数百行。更常见的做法是使用具体子命令做过滤，比如mem、checkpoint、vbucket、workload等，这样输出更聚焦，可读性更好。如果只想看某一项指标，也可以直接用grep过滤关键字：
cbstats localhost:11210 -u Administrator -p password -b travel-data mem | grep curr_items
需要特别注意的是，cbstats只能反映单个节点的统计情况。Couchbase是分布式架构，同一个桶的数据分布在集群所有节点上，如果想知道整个桶的全貌，需要依次对每个节点执行，或者结合cbstats提供的聚合视角参数。另外，执行cbstats的机器需要能连通目标节点的11210端口，跨防火墙环境要先确认网络策略。
核心指标解读：内存、磁盘与队列状态
内存相关指标是排查性能问题时的重点。ep_max_size表示bucket配额，单位为字节；curr_items是当前桶内活跃文档数量；ep_mem_low_wat和ep_mem_high_wat分别是低水位和高水位阈值，当内存占用触碰到高水位时，Couchbase会启动items eviction机制，把部分文档从内存驱逐到磁盘以释放空间。如果观察到ep_oom_errors持续增长，说明内存配额严重不足，写入请求已经出现内存分配失败，需要考虑扩容配额或优化数据模型。
cbstats localhost:11210 -u Administrator -p password -b travel-data mem # 关注这些字段： # ep_max_size bucket内存配额 # ep_mem_high_wat 高水位线 # ep_mem_low_wat 低水位线 # curr_items 当前活跃items数量 # ep_oom_errors 内存不足导致的错误次数 # ep_mem_ht_memory hash表占用内存
磁盘与持久化队列方面，disk_commit_num、ep_flusher_total可以反映磁盘写入吞吐；ep_queue_size是持久化待写入队列长度，正常情况下该值应该在毫秒级内被消化。如果ep_queue_size长期处于高位，说明磁盘IO成为瓶颈，或者磁盘写入速度跟不上写入速率。对启用了副本的桶，还需要关注ep_replica_queue_size，副本队列堆积同样会拉低集群容灾能力。此外，eq_writeq、disk_insert、disk_update等指标可以进一步细分写入类型，帮助判断是插入型业务还是更新型业务造成的压力。
checkpoint相关指标常被忽视但实际上很关键。checkpoint是Couchbase内存中变更记录的载体，ep_num_checkpoints表示当前checkpoint数量，ep_checkpoint_size反映checkpoint占用内存。当DcpProducer连接断开重连、或者消费速度过慢时，checkpoint无法被及时回收，会出现checkpoint堆积，导致内存被白白占用。这也是很多集群内存莫名其妙被吃满的元凶之一，值得重点监控。
vBucket统计与典型故障排查场景
Couchbase将桶数据划分为1024个vBucket，每个vBucket有active、replica、pending、dead四种状态。使用vbucket子命令可以查看当前节点承载的vBucket分布：
cbstats localhost:11210 -u Administrator -p password -b travel-data vbucket | grep active | head # 输出类似： # vb_0:active # vb_3:active # vb_7:replica # vb_11:pending
第一种典型场景是响应变慢。可以先抓取cbstats workload查看读写比例和get、set操作的耗时分布，再对比ep_bg_fetched指标，这个值代表请求需要从磁盘回源的次数。如果比例异常升高，说明工作集超出了内存配额，大量读请求打到了磁盘上，延迟自然上升。解决办法是提升内存配额让工作集尽量驻留内存，或者通过应用层缓存减少回源。
第二种场景是副本不一致或数据迁移异常。failover或rebalance过程中，可以周期性采集vb_num_curr_items和vb_replica_curr_items，对比active vBucket与replica vBucket的文档数量是否收敛一致。如果长时间存在明显差异，说明DcpProducer副本同步通道可能卡住，此时配合checkpoint统计观察队列是否有堆积，往往能快速定位问题节点。
第三种场景是自动化巡检。cbstats输出的是纯文本键值对，非常适合脚本化采集。可以写一个简单的shell脚本定时抓取关键指标并输出汇总，便于横向比较各节点状态：
#!/bin/bash
NODES=("192.168.1.10" "192.168.1.11" "192.168.1.12")
BUCKET="travel-data"
USER="Administrator"
PASS="password"
for node in "${NODES[@]}"; do
echo "===== $node ====="
cbstats $node:11210 -u $USER -p $PASS -b $BUCKET mem \
| egrep "ep_oom_errors|curr_items|ep_mem_high_wat"
cbstats $node:11210 -u $USER -p $PASS -b $BUCKET checkpoint \
| egrep "ep_num_checkpoints|ep_checkpoint_size"
done总的来说，cbstats是理解Couchbase桶内部运行机制的窗口。建议把内存水位、持久化队列、checkpoint数量、磁盘回源比例这几项纳入常规监控，阈值告警结合人工cbstats深入分析，就能覆盖大部分线上故障的定位需求。熟练之后，它比图形界面更快、更准，也更适合嵌入自动化运维体系。