附件上传后正文关键词搜不到，通常意味着检索链路中某一环没有走通：附件未被解析成可检索文本、解析结果未进入索引、索引范围或字段未覆盖附件正文、检索者权限看不到内容，或当前入口本身不查附件正文。排查时先确认现象范围，再按解析、索引、权限、入口逐项验证，用可观察证据区分原因，避免直接重建索引。
要点总览（TL;DR）
- 先确认失效范围：是标题搜不到还是正文关键词搜不到、是个别文件还是同格式批量失效、是所有入口还是特定入口，这三个答案决定优先排查哪个环节。
- 按解析、索引、权限、入口的顺序逐项验证，一次只改一个变量：解析看附件解析状态与结果，索引看任务状态与索引范围，权限换有权限账号复测，入口对比不同搜索位置的结果。
- 扫描件和图片型 PDF 需要 OCR 才能产生可检索文本，未做 OCR 时正文搜不到属于预期表现，应在上传前约定转换方式。
- 处置对准定位到的环节：解析失败补做解析或转换格式，索引缺失在确认范围后重建，权限只补充必要成员，入口不匹配优先换检索方式。
- 重建索引和调整权限前记录配置、选择低峰时段并设定停止点；处置后用原关键词、同类附件和不同入口复测，确认正文真正可检索。
先确认搜不到的范围和表现
“搜不到”是一个笼统描述，可能对应完全不同的故障位置。排查第一步是把现象拆成可验证的事实：搜的是附件标题还是正文关键词、失效的是个别文件还是一批文件、同一关键词在普通正文文档中是否正常、不同检索入口表现是否一致。这一步的目标是缩小范围，暂不解释原因。
现象确认清单
建议按以下条目逐项记录，每条都写明“是/否”和具体例子，形成一份可复核的现场记录：
- 搜的是标题还是正文：用附件文件名中的词搜索，能命中说明标题索引正常；再用附件正文中独有的词搜索，若标题能搜到、正文词搜不到，问题集中在正文解析或正文索引环节。
- 失效范围：换一个同格式附件、换一个不同格式附件分别测试。只有个别文件失效，优先查该文件的解析状态；同一格式批量失效，查该格式的解析支持与任务；全部附件失效，查索引范围或入口配置。
- 格式类型：重点区分可提取文本的文件（如常规文档、表格、演示文件）与扫描件、图片型 PDF。后者需要 OCR 才能产生可检索文本，若未做 OCR，正文搜不到属于预期表现而非故障。
- 对照组：用同一关键词在普通正文文档中搜索。正文文档能命中、附件不能命中，说明检索服务本身可用，问题在附件链路；两者都搜不到，则先检查关键词、检索范围和入口。
- 入口一致性：分别测试全局搜索、知识库内搜索、附件列表筛选。若知识库内能搜到而全局搜不到，问题偏向索引范围或入口覆盖；若所有入口都搜不到，问题更可能在解析或索引。
完成清单后，应能回答三个问题：失效是个别还是批量、是标题还是正文、是所有入口还是特定入口。这三个答案直接决定下一步优先验证哪个环节。
按解析、索引、权限、入口逐项找原因
附件正文检索依赖一条链路：文件上传后先被解析成文本，文本写入索引，检索时再按权限过滤并经由入口返回结果。任一环断开都会表现为“搜不到”。下面按排查顺序列出原因假设、验证动作和可观察证据，验证时一次只改一个变量，避免多个因素互相掩盖。
原因假设与验证证据对照
| 环节 | 原因假设 | 验证动作 | 可观察证据 |
|---|---|---|---|
| 解析 | 文件格式无法提取文本，或扫描件、图片型 PDF 未做 OCR | 查看该附件的解析状态与解析结果；用同格式的可提取文本文件做对照 | 解析状态显示失败、排队中或“无文本”；解析结果为空或只有页眉页脚 |
| 解析 | 解析任务未完成或报错 | 查看解析任务记录与错误信息，确认上传时间与任务时间是否吻合 | 任务处于等待、重试或失败状态，错误信息指向格式、加密或文件损坏 |
| 索引 | 附件正文不在索引范围内 | 检查索引配置中是否包含附件正文内容，而非仅索引标题或正文文档 | 配置项明确列出索引字段，附件正文未在范围内 |
| 索引 | 索引任务延迟或失败 | 查看索引任务状态与最近一次成功时间，对比附件上传时间 | 任务积压、失败重试，或索引更新时间早于附件上传时间 |
| 权限 | 检索者无权查看附件所在空间或文档 | 用有权限的账号复测同一关键词；核对空间成员与文档权限设置 | 换账号后能搜到；权限列表中没有当前检索者 |
| 权限 | 权限过滤把结果挡掉但未提示 | 确认搜索结果是否做了权限裁剪，检查附件是否继承自上级空间的受限权限 | 结果数量与预期不符，且被裁剪内容均属于受限空间 |
| 入口 | 当前搜索入口只检索标题或正文文档 | 换用覆盖附件正文的入口或调整检索条件后复测 | 某入口始终无附件结果，另一入口可命中 |
如何用证据区分四类原因
四类原因的表现有交叉，需要用组合证据排除。解析问题通常伴随“该文件单独失效、同格式其他文件正常或同样失效”，且解析状态可直接观察；索引问题往往表现为“解析成功但检索无结果”，且影响面与索引任务时间相关；权限问题最典型的证据是“换一个有权限的账号就能搜到”；入口问题则表现为“同一关键词在不同入口结果不同”，且与文件本身无关。
排查顺序建议从解析开始，因为解析是链路起点，状态最直观；解析正常再看索引任务与索引范围；索引正常再换账号验证权限；最后对比不同入口。每步记录结论，避免在未验证的情况下同时调整多个配置。
在 ONES 这类研发管理平台中，附件通常挂在需求、任务或知识库文档下，解析与索引状态、空间成员权限都可以在对应位置查看。排查时可先确认附件所在工作项或文档的解析状态，再核对索引是否覆盖附件正文，最后用同空间内有权限的成员账号复测，这样能把平台侧的管理动作与上面的四环节对应起来。
按排查结果处置并控制风险
定位到具体环节后，处置动作应对准该环节，并先评估影响范围。重建索引、调整权限这类操作会影响其他用户或其他内容，执行前要明确前提、备份方式和停止点。
分场景处置步骤
- 解析失败：先确认失败原因是格式不支持、文件加密还是文件损坏。格式问题可转换为可提取文本的格式后重新上传；扫描件和图片型 PDF 需先完成 OCR 再入库；文件损坏则重新获取源文件。重新上传后确认解析状态变为成功，并检查解析结果中是否包含目标关键词。
- 索引缺失或延迟：先等待索引任务自然完成，观察任务队列是否在推进。若确认索引范围未覆盖附件正文，调整索引配置后触发重新索引。重建索引前应确认影响范围（涉及哪些知识库或空间）、选择低峰时段，并对关键配置做记录或导出，便于回退。
- 权限问题：核对附件所在空间成员列表与文档权限继承关系，确认检索者应具备的查看权限。调整前明确授权范围，只补充必要成员，避免为排查方便而扩大权限；调整后记录变更内容与操作人。
- 入口不匹配：改用覆盖附件正文的检索方式，或在检索时调整条件（如限定知识库范围、切换搜索类型）。这类处置不改变数据，风险最低，可优先尝试以验证判断。
破坏性操作的条件与停止点
重建索引属于影响面较大的操作，执行条件应包括：已确认解析正常、已排除权限与入口因素、已记录当前索引配置。操作前对配置做备份或截图留存，选择业务低峰执行，并设定观察窗口。若重建后索引任务持续失败、错误量上升或影响其他知识库检索，应停止操作并回退到备份配置，再单独分析失败原因。权限调整同样应有停止点：若调整后出现越权可见或大范围权限异常，立即恢复原权限设置并复核继承关系。
验证恢复并减少再次发生
处置完成不等于问题解决，需要用原场景复测，确认正文真正进入可检索状态，而不是靠换入口或换账号暂时绕过。
验证清单
- 用最初搜不到的原关键词重新搜索，确认目标附件出现在结果中，且命中位置在正文而非仅标题。
- 用同类附件（同格式、同来源）复测，确认不是单个文件偶然恢复。
- 分别在不同检索入口复测，确认全局搜索与知识库内搜索结果一致。
- 用无权限账号复测，确认权限过滤仍按预期生效，没有因处置而扩大可见范围。
- 查看解析任务与索引任务状态，确认最近任务成功、无积压或持续报错。
复发预防约定
把容易反复出问题的环节固化为上传前约定和日常检查。对扫描件、图片型附件，在上传前明确是否需要 OCR、由谁完成转换，避免直接上传后才发现正文不可检索；对批量导入的附件，上传后抽查解析状态。将附件解析成功率、索引任务状态纳入日常巡检，明确责任人和检查频率，发现任务积压或失败及时处理。新成员加入空间时同步核对权限配置，减少因权限遗漏导致的“搜不到”重复发生。
常见问题
附件标题能搜到、正文关键词搜不到，说明问题出在哪一环？
标题能命中说明附件记录本身已进入索引，问题集中在正文链路。优先检查两处：一是该附件的解析状态与解析结果，确认是否成功提取出文本、结果中是否包含目标关键词；二是索引配置是否覆盖附件正文内容，而非只索引标题。若解析结果为空或只有页眉页脚，问题在解析环节；解析结果正常但检索无结果，问题更可能在索引范围或索引任务。
扫描件和图片型 PDF 搜不到正文，算故障吗？
这类文件本身不含可直接提取的文本层，需要经过 OCR 才能产生可检索文本。若上传时未做 OCR，正文搜不到属于预期表现，应作为格式约定问题处理，而非按故障排查。处置方式是在上传前明确哪些附件需要 OCR、由谁完成转换，转换后再入库；对已上传的文件补做 OCR 或转换为可提取文本的格式后重新上传，并复测原关键词。
换一个有权限的账号就能搜到，接下来该怎么处理？
这说明解析与索引链路基本正常，问题在权限过滤。先核对附件所在空间的成员列表与文档权限继承关系，确认原检索者应具备的查看权限，再判断是成员遗漏还是继承关系被覆盖。调整时只补充必要成员，明确授权范围并记录变更内容与操作人；调整后用原账号复测，同时用无权限账号确认权限过滤仍按预期生效，避免为排查方便扩大可见范围。
什么时候才需要重建索引，重建前要准备什么？
重建索引影响面较大，应在确认解析正常、已排除权限与入口因素、且确认索引范围或索引任务确实存在问题之后再执行。准备事项包括：记录或导出当前索引配置便于回退，确认受影响的 knowledge 库或空间范围，选择业务低峰时段执行，并设定观察窗口。若重建后任务持续失败、错误量上升或影响其他知识库检索，应停止操作并回退到备份配置，再单独分析失败原因。
处置完成后怎么确认问题真的解决了？
用最初搜不到的原关键词重新搜索，确认目标附件出现在结果中且命中位置在正文；再用同格式、同来源的同类附件复测，排除单个文件偶然恢复；分别在不同检索入口复测，确认全局搜索与知识库内搜索结果一致；用无权限账号复测，确认权限过滤未被放宽；最后查看解析任务与索引任务状态，确认最近任务成功、无积压或持续报错。以上都通过，才算真正恢复。
