本文目录
搜索索引重建的完成标准，不是文档数量相同，而是每类业务查询在明确的新鲜度边界内得到可解释结果
面向维护商品、订单、客户、工单或知识库检索的产品、研发、数据与运维负责人：先确认数据库或业务服务仍是事实主责，把文档 ID、字段来源、分词排序、权限过滤和删除语义写成版本化契约。再冻结全量回填水位，持续接入该水位后的新增、更新和删除，按业务查询样本比较旧、新索引，最后通过稳定查询入口分批切流。搜索通常是近实时派生视图，不应承担唯一业务事实；文档总数、抽样关键词和接口可用都不能单独证明迁移正确。
按变更范围选择重建与切换路线
| 变更场景 | 建议路线 | 主要风险 |
|---|---|---|
| 同集群修改字段或分词 | 创建带版本的新索引，按新契约回填和追平后，通过稳定别名切换查询 | 直接修改线上索引，旧文档与新文档按不同规则混用且无法完整回退 |
| 跨集群或跨产品迁移 | 从业务事实源导出全量基线，并用可重放变更流追平；旧、新集群独立验收 | 只复制旧索引，把历史脏字段、遗漏删除和引擎私有行为一并带入新环境 |
| 只修复少量缺失文档 | 先定位同步链路与影响范围，再按稳定 ID 定向补建并做全量差异扫描 | 反复手工补数据却不修复断点，下一次更新后再次漂移 |
| 搜索已参与业务写入判断 | 先把库存、权限、唯一性等判断迁回事实服务，再进行索引升级 | 在近实时索引上决定扣减、审批或授权，延迟和重复会变成业务错误 |
适用边界：先确认搜索是派生视图，不是唯一事实库
本文适用于旧系统仍在写入业务数据库或权威服务，而搜索引擎承担全文检索、筛选、聚合和排序的场景。若搜索集群已保存唯一原文、唯一附件或唯一审核状态，应先恢复事实主责和备份能力，不能把一次 reindex 当成完整数据迁移。
盘点所有搜索入口：管理后台、用户端、小程序、APP、AI 智能体工具、定时导出和内部接口。对每个入口记录索引或别名、查询字段、过滤条件、排序、分页、权限上下文、允许的新鲜度、无结果补救和责任人。再从实际请求、模板、代码、网关和搜索慢日志交叉核对，避免只按索引名称推断用途。
把“查不到”拆成数据从未进入事实库、同步未送达、文档构建失败、分词变化、权限过滤、查询模板错误和刷新尚未可见等不同原因。旧索引若仍被业务当作唯一去重、库存或授权依据，应先改造该依赖；新索引上线不能继续固化错误主责。
- 列出入口、查询模板、事实来源、权限和新鲜度目标。
- 区分搜索可用、文档已写入、对查询可见和业务结果正确。
- 把唯一性、金额、库存与授权判断保留在权威业务边界内。
先定义文档契约：稳定 ID、字段来源、版本和删除都要可解释
新索引不是旧字段的机械复制。每类文档都需要稳定且不可复用的业务 ID，以及从权威数据到搜索字段的明确转换；同一实体重复回放必须覆盖到同一文档，而不是产生第二份副本。
为标题、正文、状态、时间、金额、租户、权限标识和排序特征记录来源表或服务、空值规则、字符集、时区、精度、枚举映射、分词器与契约版本。嵌套对象、同义词和多语言字段在升级前准备代表样本，避免动态 mapping 根据第一批数据猜错类型。索引模板、分析器、分片和副本属于新版本配置，应在回填前显式创建并纳入版本管理。
删除不能依赖“下一次全量覆盖自然消失”。业务删除、软删除、租户迁移、权限收回与数据合并都要生成可重放动作，并携带实体 ID、版本或变更序号。若一个业务实体展开为多份文档，需要稳定派生规则和反向清单，才能在源记录变化后删除旧展开结果。
- 文档 ID 来自稳定业务身份，不使用每次回填随机生成的值。
- 字段、分词、权限、排序和索引配置都有版本及负责人。
- 新增、更新、删除、合并和重建使用同一套幂等文档语义。
实施步骤：冻结全量水位，再用可重放增量追到切换点
全量与增量之间必须有可证明的交接位置。推荐先记录事实源水位，再按该水位读取一致或可解释的全量基线，同时把之后的变更写入持久队列、事务发件箱或可恢复变更流。
第一步建立新索引、模板和只面向迁移任务的写入凭据；第二步保存回填起始水位及查询条件；第三步按稳定顺序分批读取事实源、构建文档并用固定 ID 批量写入；第四步记录每批范围、成功、失败和重试，控制读取、网络、CPU、磁盘与合并压力；第五步从保存的水位消费增量，直到积压、新旧版本差和删除待办进入切换阈值。
回填任务应能从已确认批次继续，不因进程重启从头覆盖，也不能把批量接口部分失败当成整批成功。迟到事件用业务版本、更新时间或单调变更序号判断，防止旧回填覆盖新变更；若源系统没有可靠顺序，应在适配层保存处理状态并安排切换前二次扫描。并行切片只在分区边界稳定、资源预算明确时使用，不能用更高并发掩盖源库被拖慢。
- 全量起点、增量起点和切换水位能形成连续证据。
- 批次有范围、幂等键、部分失败、重试与恢复记录。
- 限速依据源库、集群和线上查询余量动态调整，不照抄固定并发数。
双读只做比较：用业务查询集验证召回、过滤、排序和权限
文档数量和字段校验用于发现结构问题，但搜索升级还会改变分词、相关性、聚合、排序和分页。验收要从真实业务意图出发，保存一组脱敏、可重复的查询集和期望约束。
查询集至少覆盖精确编号、常见词、别名、错别字策略、空条件、组合筛选、时间与金额边界、无权限数据、已删除数据、同分排序、深分页以及中文和英文混合输入。比较结果时分别看集合差异、前若干项排序、关键记录必现、禁止记录不出现、聚合口径和响应错误；相关性允许变化时由产品或业务负责人按意图确认，不能只追求与旧引擎逐位相同。
影子查询不应把新结果返回用户，也不能复制包含敏感信息的完整请求到无权限环境。对双读采样设置预算、脱敏和超时隔离，旧查询完成后不等待影子结果。记录查询模板版本、索引版本与差异原因，将“预期改进”“可接受差异”“数据缺陷”和“待修复错误”分开处理。
- 数量、字段、查询集合、排序、权限和新鲜度分层验收。
- 影子比较有采样、超时、脱敏和资源隔离，不拖慢生产请求。
- 相关性变化由业务意图确认，权限遗漏和删除残留不能按差异豁免。
切换查询主责前先演练回滚，并保持单一写入事实来源
应用应查询稳定别名或受控路由，而不是把物理索引名散落在客户端。具备别名能力时，可在一次受控操作中把查询入口从旧索引移到新索引；跨产品迁移则由网关或服务配置分批切流。
切换前确认增量积压、失败队列、未决删除、集群健康、磁盘余量、权限过滤、查询延迟和业务查询差异均满足预设条件。先切内部账号或低风险租户，再逐批扩大；每批记录入口、租户、版本、开始时间、观察窗口和回退人。写入仍从事实源产生，不让旧、新搜索集群互相同步，以免形成环路和无法判断的新旧覆盖。
回滚是把查询入口指回仍在追增量的旧索引或旧集群，不是恢复一个已经停止更新的快照。新索引在回滚后保留只读证据和差异记录，待问题修复后从明确水位继续；确认观察期、备份和审计要求后再回收旧索引。别名切换只能保证入口指向变化的原子性，不能自动保证文档完整、缓存失效或客户端没有硬编码。
- 切换条件、批次、观察窗口、回退动作和责任人预先演练。
- 旧索引在可回滚期持续接收合法增量，并禁止业务直接双写两套不同逻辑。
- 客户端、缓存、查询模板与别名同时核对，避免物理索引名绕过路由。
验收与风险：同时证明完整性、新鲜度、权限和可恢复性
上线证据应覆盖事实源到搜索结果的全链路，而不是一张集群绿色截图。指标按文档类型、租户和变更动作拆分，避免总体数量正常却掩盖某个租户或删除流程长期失败。
验收包括：按事实源口径统计应有文档及删除数；对稳定样本重建并比较规范化字段摘要；追踪新增、更新、删除从提交到查询可见的延迟分布；运行代表查询和权限反例；模拟重复消息、乱序、部分批次失败、进程重启、源库超时、磁盘水位、节点故障与切换回滚。结果记录数据水位、索引版本和查询版本，才能在后续投诉时重放。
常见风险包括强制刷新导致写入和查询成本上升、回填抢占线上资源、动态字段爆炸、错误映射无法原地修复、旧事件覆盖新文档、删除漏传、缓存继续返回旧结果，以及搜索结果泄露已撤销权限。刷新频率和副本等参数需按采用产品、版本和实测负载决定；文档不承诺固定延迟、吞吐或零停机，无法取得可靠事实源与增量水位时应停止切换并先补齐数据链路。
- 逐类型、逐租户核对文档、删除、失败和延迟，不只看总量。
- 重复、乱序、断点、资源不足、节点故障、回滚和权限撤销均已演练。
- 保留水位、契约、查询集和差异证据，旧索引按审批与备份策略退役。
需求讨论中的问题
新旧索引文档数量相同，可以直接切换吗？
不可以。数量相同仍可能存在 ID 对错、字段转换错误、删除残留、租户串数据、分词与排序变化。至少还要核对字段摘要、代表查询、权限反例、增量水位和故障回滚。
业务写入时直接双写旧、新搜索集群是不是最简单？
通常不应让业务请求承担两套搜索写入成功。应先提交权威业务状态，再由可重放链路构建派生索引；否则一次成功一次失败会让接口结果、重试和补偿难以解释。短期双投也必须由同一持久事件驱动。
使用索引别名切换就一定零停机吗？
别名可以让支持该能力的引擎原子改变指向，但不能保证新索引完整、缓存立即失效、客户端没有硬编码，也不能代替跨集群网络和权限验证。零停机仍取决于完整迁移方案与实测。
每次写入后强制 refresh，能解决搜索延迟吗？
它会改变写入对搜索可见的时点，但刷新有资源成本，也不能修复漏消息、错误字段或权限缓存。应先定义业务允许的新鲜度，按产品官方语义和真实负载选择刷新与等待方式。
AI 智能体检索知识库时可以绕过现有权限过滤吗？
不可以。智能体查询必须绑定用户、租户、数据范围和工具权限，索引文档也要携带可验证的访问边界。影子比较和评测数据同样不能把无权内容暴露给模型或日志。
旧系统搜索索引重建上线验收清单
可逐项勾选，辅助本次阅读；刷新页面后不保留。
参考资料
技术概念可进一步阅读以下资料；文中的业务场景与实施清单用于方案讨论。
- Elastic Docs · Reindex documents
核对 reindex 从源复制文档、目标必须不同、依赖 _source，以及目标 mapping、分片和副本需事先配置等边界；实际能力以采用版本为准。
- Elastic Docs · Aliases
核对索引别名可为应用提供稳定名称，并支持通过一次 aliases API 请求原子执行多项指向变更；别名不替代数据完整性验收。
- Elastic Docs · The refresh parameter
核对写入对搜索可见与 refresh 的关系，以及强制 refresh 可能影响索引和搜索性能；刷新策略需按业务新鲜度和负载验证。
- OpenSearch Documentation · Reindexing data
核对目标索引不会自动继承源索引配置、大规模重建有 I/O 成本并可考虑限速等官方说明；不同产品与版本不得混用具体参数。
旧系统搜索一改 mapping 就要停机，重建后又不敢切流？
提供脱敏后的索引结构、事实来源、同步方式、查询样例、权限规则和常见差异，月弦科技可以协助划分回填水位、增量链路、灰度批次与验收证据。