Couchbase 的 rebalance 是集群拓扑变化后重新分配 vBucket 的核心机制。与关系型数据库分库分表不同，Couchbase 使用 1024 个 vBucket 作为数据分布的最小逻辑单元，每个 vBucket 内部才是文档哈希后的实际存储。当节点加入、主动退出、故障转移或副本数调整时，旧映射不再匹配新拓扑，rebalance 就是让数据重新对齐这个拓扑的过程。理解这一点，就能明白 rebalance 不是在搬运整个桶，而是在移动一个个 vBucket 及其副本。
一、重新平衡的触发场景与核心机制
触发 rebalance 最常见的原因是集群扩缩容。比如原本 3 个数据节点部署 2 副本的服务，现在要横向增加到 4 个节点。新节点加入后并不会自动持有数据，必须执行 rebalance 才会把约四分之一的活跃 vBucket 和副本迁移过去。反之，如果要下线某个节点，直接关机会触发故障转移，而主动执行 rebalance 配合 graceful failover 可以让被下线节点上的 vBucket 先迁移到其他节点，降低服务影响。
另一个触发场景是副本数变更。一个桶从 1 副本改为 2 副本时，每个活跃 vBucket 都需要在另外两个节点上生成副本。此时 rebalance 会优先补足缺失副本，再考虑调整活跃 vBucket 的分布。故障恢复后的 rebalance 也比较特殊：当故障节点重新加入集群时，它之前承担的 vBucket 已经被其他节点接管，如果直接 rebalance，可能会再次发生大量数据回迁。因此 Couchbase 提供 delta recovery 选项，只同步故障节点宕机期间变化的数据，而不是全量恢复。
核心机制上，rebalance 由集群协调器执行，它根据当前拓扑和配置生成目标 vBucket 映射表。映射表包含每个 vBucket 的活跃副本和副本副本分别落在哪些节点。迁移阶段分为在目标节点建立副本、等待数据达到一定一致状态、切换活跃角色、清理源数据几个步骤。整个过程中客户端通过集群映射更新保持读写，但短时间内可能出现访问延迟升高，因为客户端需要拉取新映射并重新连接数据节点。
二、执行rebalance前的检查与参数调优
执行 rebalance 前先要确认集群状态健康。可以通过管理界面或命令行查看节点是否都处于 healthy，是否存在未处理的 failover 节点。如果有节点处于 down 状态，rebalance 可能无法启动，或者会把大量副本迁移任务排入队列。建议先处理告警，再开始拓扑调整。还要确认目标节点的服务类型一致，数据节点不能与索引节点混用，否则 rebalance 后索引服务可能找不到对应的数据副本。
参数调优直接影响 rebalance 的耗时和对业务的影响。Couchbase 提供几个关键参数：rebalanceMovesPerNode 控制单节点同时迁移的 vBucket 数量，默认值偏保守，适合在线业务；rebalanceMovesBeforeCompaction 决定迁移多少个 vBucket 后触发一次压缩；maxConcurrentReps 限制副本并发同步数。对于临时维护窗口，可以适当调大这些值以加快迁移，但会增加内存和网络压力。例如使用 REST 接口调整：
curl -u Administrator:password -X POST http://127.0.0.1:8091/settings/rebalance \ -d rebalanceMovesPerNode=4 \ -d rebalanceMovesBeforeCompaction=64 \ -d maxConcurrentReps=2
还要关注磁盘 I/O 和网络带宽。rebalance 期间，源节点需要持续发送 vBucket 数据，目标节点持续写入并构建索引。如果集群同时承载高并发写请求，迁移会抢占资源。建议在低峰期操作，或者使用 Couchbase 的速率限制能力。部分版本支持通过 rebalanceMovesPerNode 动态控制速率，但不能无限调低，否则迁移持续时间过长，反而增加风险窗口。
区分 rebalance 与 swap rebalance 也很重要。swap rebalance 用于同时加入新节点并移除旧节点，适合节点替换场景。它会尽量保持数据在旧节点到新节点之间的一对一迁移，减少跨节点流量。如果只是简单先加节点再 rebalance，再移除旧节点，数据可能被搬运两次。因此替换硬件时优先使用 swap rebalance。
三、rebalance操作过程与监控指标
命令行执行 rebalance 常用 couchbase-cli rebalance。下面这个例子在集群中添加两个新数据节点，并等待任务完成：
couchbase-cli rebalance -c 192.168.1.10:8091 \ -u Administrator -p password \ --server-add=192.168.1.11,192.168.1.12 \ --server-add-username=Administrator \ --server-add-password=password \ --no-wait
如果希望观察进度，可以去掉 --no-wait，但长时间阻塞命令行并不适合生产环境。更好的方式是提交任务后通过 REST 接口查询任务状态：
curl -u Administrator:password http://127.0.0.1:8091/pools/default/tasks
返回结果中会包含 rebalance 任务的进度百分比、迁移的 vBucket 数量以及当前阶段。监控时重点看三类指标：一是任务的 progress，二是单个节点的 vbucket_map 变化，三是网络发送接收字节数。如果进度长时间停在某个百分比，通常说明某个 vBucket 迁移卡住，可以检查目标节点磁盘是否写满，或者是否存在大文档拖慢回填。
UI 管理界面也提供直观的 Rebalance 按钮和进度条，但在自动化场景下更推荐脚本调用 REST。任务失败时不要盲目重试，先查看 /pools/default/tasks 中的错误信息和节点日志。常见错误包括目标节点容量不足、认证失败、服务未启动、网络分区等。修正错误后再重新发起任务，未完成的 vBucket 会继续迁移，不会从头再来。
四、常见问题与避坑建议
第一个常见误区是认为 rebalance 会自动平衡所有服务的数据。实际上 rebalance 主要面向 Data Service 的 vBucket，索引、查询、搜索等服务不会自动重新分布索引。比如增加数据节点后，全局二级索引不会自动迁移到新节点，需要手动重建或调整索引复制。因此扩缩容前要评估索引服务是否需要同步调整，否则查询性能不会提升，反而可能因为数据节点与索引节点拓扑不一致而下降。
第二个问题是 rebalance 期间大量超时或写入失败。这通常不是 rebalance 本身有 bug，而是迁移参数设置得过于激进。默认参数已经考虑了在线业务，但某些团队为了加快速度会调大并发数，结果导致内存不足或网络拥塞。Couchbase 的流控机制会在内存达到高水位时暂停迁移，表现就是进度停滞，同时客户端写入延迟升高。建议保持默认值或只小幅调整，并监控 curr_items、mem_used 和高水位触发次数。
第三个常见问题是故障节点恢复后直接 rebalance 造成大量无效迁移。比如 3 节点集群中一台机器重启，另外两台通过 failover 接管了它的 vBucket。机器恢复后如果先做全量 rebalance，会把已经接管的 vBucket 再迁回原节点，可能造成短时间数据抖动。正确做法是评估是否真的需要迁回：如果原节点只是短暂离线且数据没有太大变化，可以使用 delta recovery 减少迁移数据量；如果原节点磁盘已经损坏，则应当将其彻底移除并重新初始化后再加入。
最后建议把 rebalance 纳入变更管理。生产环境执行前备份集群配置和关键数据，准备回滚方案。可以在测试环境模拟多次扩缩容，记录不同参数下的迁移耗时和性能影响。对于大规模集群，可以考虑分批次调整，而不是一次性加入多个节点。rebalance 完成后验证所有 vBucket 的活跃和副本分布是否符合预期，并观察一段时间读写延迟和错误率。这样可以把 rebalance 从一个高风险操作变成一个可重复的常规维护流程。
总结来看，Couchbase rebalance 的核心是 vBucket 映射的重新计算和数据迁移控制。只要提前检查健康状态、合理设置迁移参数、持续监控任务进度，就能在保证服务可用的前提下完成节点扩缩容、副本调整和故障恢复。对参数不敏感或忽视迁移机制，很容易在小变更中引发集群性能问题。
Couchbase rebalance集群再平衡vBucket迁移修改时间：2026-09-26 23:28:13