对于 Couchbase 的全局二级索引而言，写入高峰、大量文档过期或删除都会让索引页出现碎片，查询延迟逐渐上升。直接删除并重建索引虽然简单，但会让依赖该索引的 N1QL 查询立即报错或退化为全量扫描。Couchbase 提供的在线重建通过 ALTER INDEX 语句的 rebuild 动作，让索引服务在后台异步构建新索引，构建完成后原子切换到新索引，旧索引继续对外服务。因此它更适合生产环境中不能接受长时间索引缺失的场景。
在线重建并不是完全没有开销，它仍然需要额外的磁盘空间和内存来创建新索引，同时会提高索引节点的 CPU 与 IO 负载。理解它的工作方式、监控手段和回退策略，比单纯记住一句 SQL 更重要。
在线重建与删除重建的核心区别
从行为上看，先执行 DROP INDEX 再执行 CREATE INDEX 时，索引名称对应的对象会被删除，所有用到该索引的查询在空窗期内面临两种结果：要么直接报索引不存在，要么优化器选择主键扫描，高并发下可能拖垮数据节点。在线重建则不同，重建任务先读取当前索引定义，在索引服务中构建一个临时对象，原索引保持 online 状态。等新索引数据追平后，服务端完成元数据切换，查询才指向新索引。
需要注意的是，如果重建的是副本索引，Couchbase 会按分区逐批构建，并同步更新副本。切换过程通常很快，但构建时间取决于数据量、索引键长度和索引节点性能。在线重建期间索引名称不会改变，因此应用侧不需要修改查询语句，这也是它比创建新索引再切换流量更易于操作的原因。
-- 直接删除再创建，索引不可用窗口长 DROP INDEX `idx_name` ON `bucket_name`; CREATE INDEX `idx_name` ON `bucket_name(col1, col2)`;
-- 在线重建，旧索引继续服务
ALTER INDEX `idx_name` ON `bucket_name` WITH {"action":"rebuild"};
从执行结果看，删除重建是破坏性操作，一旦新索引构建失败，业务查询可能长时间没有可用索引。而在线重建即使失败，旧索引仍然存在，查询可以继续执行。这个特性决定了生产环境中应优先选择在线重建，尤其是查询流量较大的核心业务索引。
在线重建的执行步骤与权限准备
执行前应确认登录账号具备 Query Manage Index 权限，通常由 Full Admin 或 Query Manage Index 角色提供。如果通过 REST API 调用，还需要集群管理端口 8091 或查询服务端口 8093 的访问权限。权限不足会导致 ALTER INDEX 返回未授权错误，而任务不会进入构建队列。
先用系统表查看索引当前状态，避免对已经处于 building 状态的索引再次重建。接下来执行 ALTER INDEX 语句，动作参数为 rebuild。该语句会返回一个 requestId，用于后续跟踪。也可以在 Couchbase Web 控制台索引页找到对应索引，点击重建按钮。
-- 查看索引状态 SELECT name, state, bucket_id, index_key FROM system:indexes WHERE name = "idx_name";
-- 在线重建索引
ALTER INDEX `idx_name` ON `bucket_name` WITH {"action":"rebuild"};
如果希望通过命令行快速执行，可以在 Couchbase 安装目录下使用 cbq 工具。Windows 路径类似 C:Program FilesCouchbaseServerbincbq.exe，Linux 环境一般为 /opt/couchbase/bin/cbq。执行时建议加上超时参数，避免交互式会话被长时间任务占用。
cbq -u Administrator -p password -e http://127.0.0.1:8091
-s 'ALTER INDEX `idx_name` ON `bucket_name` WITH {"action":"rebuild"};'
重建任务提交后，Couchbase 会将它放入索引服务的任务队列。如果当前索引服务正在执行其他构建任务，新任务可能处于排队状态。提交成功不代表构建完成，必须通过监控手段确认索引最终回到 online 状态。
重建期间的监控与验证
重建任务开始后，不能只凭语句返回成功就认为完成。ALTER INDEX 只是提交任务，实际构建在后台进行。可以通过查询系统表 system:indexes 观察索引状态。初始状态从 online 变为 building，完成后回到 online。部分版本中可能看到旧索引与新索引短暂共存，但最终只有目标索引保持 online。
另一个有效的监控对象是 Web 控制台索引页，它会展示构建进度、已扫描文档数量和错误信息。如果集群配置了 Prometheus 或 Couchbase 自带的指标接口，还可以关注索引节点的磁盘写入速率、内存使用率和队列深度。单独一次重建一般不会占满资源，但如果同时重建多个大索引，就需要控制并发。
-- 查看所有索引状态 SELECT name, state, bucket_id FROM system:indexes WHERE bucket_id = "bucket_name";
验证阶段应选择几个典型查询，对比重建前后的执行计划。可以用 EXPLAIN 查看查询是否仍然命中目标索引，以及扫描行数是否合理。执行计划中如果出现 PrimaryScan 或索引选择变化，说明切换未完成或统计信息过期，需要先收集统计信息。
EXPLAIN SELECT col1, col2 FROM `bucket_name` WHERE idx_key = "value";
如果 EXPLAIN 结果显示查询仍然使用旧索引名称，但状态已经 online，通常表示元数据切换已经完成。若执行计划回退到主键扫描，需要检查索引状态是否真的恢复正常，以及查询条件的数据类型是否与索引键类型匹配。类型不匹配会导致优化器无法使用索引，这是在线重建后常见的排查点。
风险控制、资源评估与回滚策略
在线重建最大的风险不是切换失败，而是资源竞争。因为旧索引继续服务的同时，新索引构建也在消耗同一批索引节点的 CPU、内存和磁盘。如果 bucket 数据量达到数亿文档，重建可能持续数十分钟甚至更久。执行前要确认索引节点有足够的磁盘空间，通常建议至少预留目标索引大小的两倍以上，因为新旧索引会同时存在一段时间。
内存方面，索引服务使用内存配额缓存索引页。若配额接近上限，重建会频繁触发页面换出，构建速度明显下降，也会影响线上查询的命中率。可以在维护窗口前临时调高索引服务内存配额，但必须确保节点物理内存足够，否则会触发 OOM。重建期间还要注意不要同时执行数据节点 Rebalance 或大规模文档导入，避免资源争抢导致构建失败。
回滚原则是：只要旧索引仍可服务，任务失败不会造成查询中断。如果发现新索引数据不一致或构建卡住，可以将错误信息导出，停止重建任务，让旧索引继续处理请求。真正需要恢复原状时，可以删除重建产生的新对象，但不要直接删除原索引。如果重建动作已经切换且新索引有问题，需要重新执行一次重建，或基于旧定义创建另一个索引。
常见误区与适用边界
第一个误区是把在线重建当成零影响操作。它只减少了索引不可用窗口，并没有消除资源开销。执行前仍然要评估数据量、节点负载和业务高峰，尤其在副本数量较多时，所有副本都会重新构建。如果索引节点已经在高负载下运行，在线重建可能成为压垮性能的最后一根稻草。
第二个误区是试图通过 rebuild 修改索引定义。例如想增加一个索引字段或调整排序规则，rebuild 不会读取新的表达式，它只按照当前元数据重新构造索引数据。需要变更索引键或分区方式时，应创建新索引，等待构建完成后再删除旧索引。
第三个误区是把索引重建和集群 Rebalance 混为一谈。Rebalance 解决的是数据节点扩容、缩容或故障转移时的 vBucket 迁移问题，而重建只针对 GSI 索引对象本身。两者可能在同一维护窗口出现，但操作对象和影响范围不同。适合在线重建的典型场景包括：碎片率高导致查询延迟上升、索引文件异常膨胀、少量索引数据损坏或重建测试。对需要长时间修改定义、调整节点分布或更换索引分区策略的需求，更合适的做法是创建新索引并逐步切换流量。