附件上传后正文关键词搜不到，通常涉及检索入口、附件解析、索引范围和权限四段链路中的某一段没有走通。排查时先确认症状属于哪一类，再用解析状态、索引更新时间、不同权限账号的检索结果等可观察证据逐段验证，避免凭猜测直接改配置。下文按诊断顺序给出检查点和处置方法，并说明如何验收恢复、减少同类问题复发。
要点总览（TL;DR）
- 附件正文搜不到，先区分两种症状：标题能搜到但正文词搜不到，指向解析或索引；任何入口都搜不到，优先查入口、权限和附件状态。
- 按检索入口、附件解析、索引范围、权限四段链路逐项验证，每段用解析状态、索引更新时间、不同权限账号的检索结果等可观察证据确认。
- 扫描件和图片型 PDF 需要 OCR 才能得到正文，加密、受保护或损坏的文件可能导致解析中断，解析失败时先看失败原因再决定重传或换文件。
- 处置顺序建议先修入口与查询方式，再补解析，再触发索引，最后处理权限；重建索引前确认影响范围，权限调整前确认不扩大可见范围。
- 验收时用正文独有关键词在全局搜索和库内搜索分别复测，并用不同权限账号核对结果，同时把根因和处置动作整理成排查清单预防复发。
先确认症状：是全文搜不到还是入口不对
排查的第一步是把故障范围界定清楚。附件正文搜不到有两种典型表现：一种是附件标题或文件名能搜到，但正文里的独有关键词搜不到，这通常指向解析或索引环节；另一种是在任何入口都搜不到该附件，连标题也命不中，这时要优先怀疑检索入口、权限或附件本身的状态。两类表现对应的排查路径不同，先归类能少走弯路。
确认检索入口是否一致，是区分入口问题与内容问题的关键。同一个关键词，分别在全局搜索、附件所在知识库的库内搜索、附件所在页面的局部搜索中试一次，记录结果差异。如果全局搜索无结果而库内搜索能命中，问题更可能出在入口的检索范围或过滤条件上；如果三个入口结果一致地搜不到，再往解析、索引、权限方向查。
试搜时用三类关键词分别测试：附件标题、文件名、正文中独有的词。标题能命中而正文词不命中，说明附件已被系统识别，问题集中在正文提取或正文索引；三类都命不中，说明附件整体没有被检索到。同时记录检索时间点与附件上传、更新时间的间隔，刚上传不久的附件可能还在解析或索引排队中，隔一段时间复测能排除这类时序因素。
| 检索入口 | 关键词类型 | 检索结果 | 检索时间点 | 与上传/更新时间的间隔 |
|---|---|---|---|---|
| 全局搜索 | 附件标题 | |||
| 全局搜索 | 正文独有关键词 | |||
| 知识库内搜索 | 正文独有关键词 | |||
| 页面局部搜索 | 正文独有关键词 |
这张症状记录表填完后，通常能得出一个初步判断：是入口范围问题、正文未被检索问题，还是附件整体不可见问题。带着这个判断进入下一段检查，比逐项盲查更有效率。
核对附件解析：正文是否被成功提取
如果症状表现为标题能搜到、正文关键词搜不到，解析环节是首要怀疑对象。正文要能被检索，前提是系统先把附件中的文字提取出来。查看附件详情或管理后台中的解析状态、解析时间与失败原因，是判断这一步是否走通最直接的证据。解析状态一般会区分已解析、解析中、解析失败、未解析几种情况，不同状态对应不同的处置动作。
文件类型直接决定解析难度。可提取文本的文档，如常规的 Word、文本型 PDF，解析通常能直接得到正文；扫描件和图片型 PDF 的页面本质是图像，需要经过 OCR 才能得到可检索的文字，如果系统未启用 OCR 或该文件未走 OCR 流程，正文自然搜不到。判断方法可以看文件是否为扫描生成、页面文字能否被选中复制，能选中复制的一般属于文本型，不能选中的多为图像型。
文件本身的状态也会中断解析。加密或设置了打开密码的文件、受保护限制编辑的文档、传输中损坏的文件，都可能导致解析任务失败或只提取到部分内容。遇到解析失败时，先看失败原因是否指向文件加密、格式异常或内容损坏，再决定是重新上传一个可解析的版本，还是联系文件提供方解除保护。
还要确认解析任务是否只是排队未完成。大文件、批量上传或系统繁忙时，解析可能处于等待状态，此时搜不到属于暂时现象。查看解析任务的排队情况和最近一次重试记录，能区分“还没解析完”和“解析已经失败”这两种情况，避免把等待中的任务当成故障去反复重传。
综合以上检查点，解析环节的结论应归入四类之一：已解析、解析失败、未解析、需 OCR。这个结论决定了后续是补解析、换文件，还是继续往索引方向排查。
检查索引范围：解析结果有没有进入可检索范围
解析成功但依然搜不到，问题往往出在索引环节。首先要确认该附件所在的知识库、目录或空间是否在索引范围内。有些系统允许按空间或目录配置是否参与全文检索，附件放在未被纳入索引的位置，即使解析完成也不会出现在搜索结果里。核对索引范围配置，是排除这一类原因的直接方法。
索引更新存在延迟是另一类常见原因。附件解析完成后，正文进入索引通常需要一段同步时间，批量导入或索引重建期间延迟会更明显。查看最近一次索引重建或同步的时间，与附件上传、解析完成的时间做对比，能判断是延迟未到还是索引确实没有覆盖。如果刚做过索引重建，还要确认重建任务是否已经完成。
文件类型是否属于被索引的范围也需要确认。部分系统对可检索的文件类型有明确清单，清单之外的类型可能只索引标题和元数据，不索引正文。把出问题的附件类型与系统声明的可索引类型对照，能快速判断是否属于格式兼容性问题。
附件作为独立文档被索引，与作为页面附件被索引，覆盖范围可能不同。独立文档通常有完整的正文索引；页面附件是否索引正文，取决于系统的处理策略和该页面的配置。确认该附件在系统中的存在形式，再对照对应的索引规则，能解释为什么同一份文件换个位置上传后结果不一样。
这一段的核对结论应明确写出：附件是否在索引范围内、索引是否已更新到最新、文件类型是否被覆盖、附件以何种形式被索引。四项都确认后，若仍搜不到，再进入权限排查。
排查权限：当前账号能否看到该附件正文
权限过滤会让检索结果在用户无感知的情况下被隐藏。检索系统通常只返回当前账号有权查看的内容，附件存在、已解析、已索引，但账号没有查看权限时，搜索结果里同样不会出现。确认当前账号对附件所在空间、页面或文档是否具备查看权限，是排除这一类原因的第一步。
验证权限最有效的方法是用具备更高权限的账号或管理员账号复测同一关键词。如果管理员能搜到而普通账号搜不到，基本可以定位为权限问题；如果管理员也搜不到，权限因素可以暂时排除，回到解析和索引方向继续查。复测时使用同一组关键词、同一检索入口，保证对比条件一致。
附件是否单独设置了访问限制，或继承关系是否被改动，也需要检查。有些附件在继承所在页面权限之外，还被单独设置了更严格的访问范围；页面移动、目录调整也可能改变权限继承链。这类改动往往发生在附件上传之后，容易被忽略，核对附件的权限来源和继承状态能发现这类隐性限制。
权限变更后索引是否已按新权限刷新，是容易遗漏的一环。刚调整过权限的附件，检索结果可能仍按旧权限返回，需要等待权限同步完成后再复测。权限验证的结论归为三类：权限不足、权限正常、权限变更未刷新，三类对应的处置动作不同。
在 ONES 知识库这类以空间和页面组织内容的产品中，附件通常随所在页面继承查看权限，排查时可以沿着“空间—页面—附件”的层级确认权限来源，再用不同权限的账号复测检索结果。具体权限项的名称和配置位置以实际系统界面为准。
按顺序处置并验证恢复
前面的检查会得出一个或多个可疑环节，处置时按固定顺序推进，能避免无效操作和相互干扰。建议顺序是：先修入口与查询方式，再补解析，再触发索引，最后处理权限。入口问题成本最低，先排除；解析是索引的前提，解析没通过时重建索引没有意义；权限调整影响面最大，放在最后处理。
补解析时，针对解析失败的文件，先确认失败原因再决定动作：加密或受保护的文件，解除保护后重新上传；损坏的文件，换一份完整版本；扫描件，确认 OCR 流程是否启用。重新解析或重建索引前，先确认影响范围，涉及全库重建的操作应选择低峰时段，必要时先备份重要配置，避免影响其他用户的正常检索。
触发索引时，优先选择只针对该附件或该目录的局部重建，减少对全库的影响。重建后记录开始和完成时间，作为后续复测的时间基准。涉及权限调整时，只做恢复正确可见范围所必需的改动，确认调整不会把附件暴露给原本无权查看的账号，权限放宽前先与内容负责人确认。
每完成一步处置，都用与症状记录表相同的一组关键词复测，并记录结果。复测结果与处置前的记录对比，能判断这一步是否有效；如果某一步没有改善，不要急着叠加下一步操作，先确认该步是否真正生效，例如解析是否完成、索引是否更新到位。
| 处置顺序 | 处置动作 | 风险边界 | 复测关键词 | 复测结果 |
|---|---|---|---|---|
| 1 | 核对并修正检索入口与查询方式 | 无破坏性，可直接操作 | 正文独有关键词 | |
| 2 | 补解析或更换可解析文件 | 重传前保留原文件 | 正文独有关键词 | |
| 3 | 触发局部索引重建 | 确认影响范围，低峰时段执行 | 正文独有关键词 | |
| 4 | 修正权限或等待权限刷新 | 确认不扩大可见范围 | 正文独有关键词 |
验证恢复与预防复发
处置完成后需要一套明确的验收标准，而不是“看起来能搜到了”就结束。验收时用正文独有关键词在全局搜索和库内搜索分别复测，两处都能命中才算正文检索恢复；再用权限不同的账号各测一次，确认有权限的账号能搜到、无权限的账号搜不到，结果符合预期。标题、文件名、正文词三类关键词都应覆盖，避免只修好了其中一类。
预防复发可以从上传环节和例行检查两方面入手。上传环节对扫描件、加密文件等特殊格式给出提示，提醒上传人确认是否需要 OCR 或先解除保护，能减少解析失败的发生。建立上传后解析与索引状态的例行检查，对批量导入或重要附件在上传后的一段时间内抽查解析状态，能及早发现排队积压或解析失败。
把本次故障的根因、处置动作和复测结果记录下来，整理成排查清单，下次遇到同类问题时可以直接按清单逐项核对。清单应包含症状记录表、解析状态结论、索引核对结论、权限验证结果和验收记录，形成从发现到恢复的完整闭环。长期看，这份清单还能帮助团队识别高频出问题的文件类型或上传路径，从源头上减少附件正文检索失效的情况。
常见问题
附件刚上传不久就搜不到正文，需要马上排查吗？
先不用急着改配置。大文件、批量上传或系统繁忙时，解析和索引可能处于排队状态，此时搜不到属于暂时现象。查看解析任务的排队情况和最近一次索引同步时间，与上传时间做对比，能区分“还没处理完”和“处理已经失败”。建议隔一段时间用同一组关键词复测，如果超过合理等待时间仍无结果，再按解析、索引、权限的顺序逐段排查。
扫描件和图片型 PDF 的正文为什么搜不到，怎么确认？
扫描件和图片型 PDF 的页面本质是图像，需要经过 OCR 才能得到可检索的文字。如果系统未启用 OCR 或该文件未走 OCR 流程，正文就不会进入检索范围。判断方法可以看页面文字能否被选中复制：能选中复制的通常属于文本型，不能选中的多为图像型。确认属于图像型后，检查 OCR 流程是否启用，或换一份带文本层的版本重新上传。
管理员能搜到、普通账号搜不到，说明什么？
这基本可以定位为权限问题。检索系统通常只返回当前账号有权查看的内容，附件存在、已解析、已索引，但账号没有查看权限时，搜索结果里同样不会出现。用同一组关键词、同一检索入口，分别用管理员账号和普通账号复测，结果差异明显时，沿着“空间—页面—附件”的层级核对权限来源和继承状态，确认附件是否被单独设置了更严格的访问限制。
重新解析或重建索引前要注意什么？
先确认影响范围再动手。针对单个附件或单个目录的局部重建，影响面小，可以直接执行；涉及全库重建的操作，应选择低峰时段，必要时先备份重要配置，避免影响其他用户的正常检索。补解析时保留原文件，加密或受保护的文件解除保护后重新上传，损坏的文件换一份完整版本。每完成一步都用同一组关键词复测，确认这一步真正生效后再进行下一步。
权限调整后搜索结果没有变化，是什么原因？
权限变更后索引可能仍按旧权限返回结果，需要等待权限同步完成后再复测。确认权限调整已经保存生效，并查看索引是否已按新权限刷新。如果等待后结果仍不符合预期，核对附件的权限来源是否被其他继承关系覆盖，例如页面移动或目录调整改变了继承链。权限验证的结论归为权限不足、权限正常、权限变更未刷新三类，对应不同的处置动作。
