从 Confluence 迁出后发现附件缺失或链接失效，先不要急着改配置或重新导入。更有效的做法是把迁移拆成导出、传输、导入、链接重写、权限继承五段，用同一批样本页面逐段比对，确认异常在哪一段产生、影响多少页面，再针对该段修复。下面按“先分类症状、再分段排查、分别验证附件与链接、最后处置和验收”的顺序展开。
要点总览（TL;DR）
- 先把“附件缺失”和“链接失效”拆成具体类型并统计影响范围，选取10–20个典型页面作为对照样本，避免笼统排查。
- 按导出、传输、导入、链接重写、权限继承五段逐段比对，每段只回答“异常是否在这一段产生”，结论只记正常、异常或待验证。
- 附件缺失优先核对导出包附件目录与页面引用是否一致，再查导入端大小或类型限制、同名覆盖和权限继承。
- 链接失效先区分同空间页内链、跨空间链接、附件与锚点链接、外部链接四类，分别用映射表和重写规则覆盖范围验证。
- 处置按先补附件、再重建映射并重写链接、最后调整权限的顺序推进；批量重写或覆盖导入前备份目标空间或小批量试跑，修复后按样本清单逐页验收并更新检查清单。
先确认症状范围：缺的是哪类附件、断的是哪类链接
“附件缺失”和“链接失效”都是笼统描述，直接排查容易把不同原因混在一起。第一步是把症状拆细，形成可核对的分类，并确定影响面。
附件按类型统计：图片、文档类附件、嵌入页面的文件分别计数。不同类型的附件在导出和导入环节的处理方式可能不同，混在一起统计会掩盖规律。链接按类型统计：同空间页内链、跨空间链接、外部链接、附件链接（含锚点链接）分别记录断链数量。
确认影响范围时，重点看三个维度：是全部页面还是特定空间、特定批次；是否与页面大小、附件数量相关；是否集中在某次导入之后。如果异常只出现在某个空间或某一批导入中，原因通常在该批次的导出包或导入过程；如果全量出现，则更可能是重写规则或权限继承的系统性问题。
在此基础上选取10–20个典型页面作为对照样本，覆盖不同附件类型和链接类型，记录每个页面在源端的原始状态：附件清单、页面链接关系、权限设置。样本清单是后续分段比对的基础，没有它，排查容易变成逐个页面碰运气。
本节交付物是一份症状分类与样本清单，标明每类异常的页面数和典型例子，作为后续所有验证的对照基准。
按迁移链路分段排查：导出、传输、导入、重写、权限
分段排查的核心是：每一段只回答一个问题——异常是否在这一段产生。用同一批样本页面逐段比对，把原因假设落到具体环节，并用证据区分假设与结论。
| 迁移段 | 检查项 | 证据来源 | 结论记录 |
|---|---|---|---|
| 导出 | 导出包是否包含附件目录；页面是否被单独导出而遗漏附件；导出过程是否中断 | 导出包文件清单、导出日志 | 正常 / 异常 / 待验证 |
| 传输 | 包完整性：文件数、总大小、校验值是否与导出时一致 | 校验值比对记录、上传日志 | 正常 / 异常 / 待验证 |
| 导入 | 导入日志中的跳过、失败、超限记录；附件存储路径与大小限制 | 导入日志、目标端限制配置 | 正常 / 异常 / 待验证 |
| 重写 | 页面ID、空间键、标题变更后，链接重写规则是否覆盖跨空间链接与附件链接 | 链接映射表、重写规则说明 | 正常 / 异常 / 待验证 |
| 权限 | 源空间权限、目标空间默认权限、页面级限制的继承关系 | 权限对照表 | 正常 / 异常 / 待验证 |
排查顺序建议从导出段开始向后推进，因为后段的问题常常被前段的异常掩盖。例如导出包本身缺少附件目录，导入日志再正常也无法恢复附件。每段结论只写“正常、异常、待验证”三种状态，待验证项要注明还需要什么证据，避免把推测写成定论。
传输段容易被忽略。大附件包在上传过程中出现截断或分片失败，表现与导入失败相似，但修复方式完全不同。核对文件数和校验值是区分两者的直接证据。
如果迁移在 ONES Wiki 一侧进行，ONES 的 Confluence 迁移方案支持迁移空间、页面、附件和权限结构，也支持批量迁移与数据包导入，排查时可以按导出包、导入记录、权限对照三条线分别取证。具体导入包格式与操作细节以实际迁移指南或原厂服务说明为准。
附件缺失的常见原因与验证方法
附件缺失的原因假设主要有四类，每类都有对应的验证动作和判定证据。先验证再下结论，避免把“导入失败”直接当成原因。
| 原因假设 | 验证动作 | 判定证据 |
|---|---|---|
| 附件未随页面导出 | 比对导出包内附件目录与页面中的附件引用清单 | 引用存在但包内无对应文件，说明导出段遗漏 |
| 附件超出目标端大小或类型限制 | 查导入日志中的超限记录，核对目标端限制配置 | 日志有明确超限条目，且缺失附件集中在大文件或特定类型 |
| 同名附件覆盖或路径冲突 | 比对源端与目标端附件命名及存放路径 | 目标端同名文件只剩一份，或路径被合并 |
| 附件权限未继承 | 确认附件是否跟随页面权限，是否存在单独限制 | 附件存在但特定用户不可见，权限对照表显示差异 |
验证时优先使用样本清单中的页面，逐页核对“源端附件数—导出包附件数—目标端附件数”三个数字。三个数字一致说明附件链路完整，差异出现在哪一段就回到哪一段深入。对于超限类问题，缺失往往集中在少数大文件上，统计分布能快速印证假设。
权限类问题容易被误判为附件丢失。用户看不到附件时，先确认附件在目标端是否存在，再查权限继承关系，两者结论不同，修复动作也不同。
链接失效的常见原因与验证方法
链接失效需要先分类再验证。四类链接的成因和判定依据不同，统一按“重写失败”处理会漏掉真正原因。
| 链接类型 | 常见成因 | 验证方式 | 修复方向 |
|---|---|---|---|
| 同空间页内链 | 页面ID或标题变化导致固定链接失效 | 抽查原链接与目标链接的映射关系 | 按映射表重建链接 |
| 跨空间链接 | 空间键变化导致断链 | 核对空间键映射表 | 更新空间键映射后重写 |
| 附件链接与锚点链接 | 重写规则未覆盖此类链接 | 检查重写规则覆盖范围，抽查样本页面的附件链接与锚点 | 补充规则后小批量重跑 |
| 外部链接 | 源站原有失效，与迁移无关 | 在源端验证同一链接是否可达 | 不纳入迁移修复范围，单独登记 |
验证页面ID与标题变化时，重点看使用固定链接的页面。Confluence 中页面改名或移动后，旧链接可能依赖重定向，迁移后重定向关系是否保留需要逐项确认。跨空间链接的断链通常成批出现，空间键映射表是最直接的证据。
外部链接要单独区分：先在源端确认链接本身是否可达，再判断迁移是否引入了新的失效。把源站原有失效计入迁移问题，会虚增断链数量，干扰后续验收口径。
处置顺序与风险边界
定位完成后，处置按“先数据完整性、再链接重写、最后权限调整”的顺序推进。这个顺序的原因是：附件和页面数据不完整时重写链接没有意义；权限调整影响面最大，放在最后可以减少返工。
具体步骤与停止条件：
- 补齐缺失附件，确认导出包与目标端附件数一致。此阶段只做数据补全，不改链接和权限。
- 重建页面ID、空间键映射关系，核对映射表覆盖样本清单中的全部链接类型。
- 执行链接重写。批量重写前先备份目标空间，或选取小批量页面试跑，确认重写结果符合预期后再扩大范围。
- 调整权限。涉及范围授权时，先列出受影响页面清单，确认清单后再执行。
- 出现大面积失败时停止增量导入，回到导出段重新核对，不在问题未定位时反复覆盖导入。
批量重写、覆盖导入、范围授权三类操作具有破坏性，执行前必须有备份或试跑记录。停止条件要提前写清楚，例如“试跑样本中断链率高于预期即暂停”，避免问题扩大后才回头处理。
迁移实施中，ONES 建议把迁移工具、原厂服务和分阶段切换结合起来，在正式迁移前确认数据范围、功能匹配和系统适配；对于依赖插件或定制的场景，迁移前逐项评估，避免假设所有插件都能一一对应。这些建议同样适用于处置阶段的节奏控制。
验证恢复与复发预防
修复后的验收分两层：抽样验证和统计验证。抽样验证按最初的样本清单逐页核对，确认附件可下载、链接可跳转、权限符合预期。统计验证对比迁移前后页面数、附件数、断链数的差异，差异应能逐项解释，无法解释的差异要回到分段排查表查找对应环节。
验收核对表建议包含以下条目：
- 样本页面附件数量与源端一致，且可正常下载；
- 四类链接逐类抽查，断链数为零或剩余断链均有明确原因（如外部链接原有失效）；
- 权限对照表中源空间与目标空间的授权关系一致，页面级限制已确认；
- 迁移前后页面数、附件数、断链数统计表已归档。
复发预防的关键是把本次异常类型沉淀为检查项。迁移前检查清单增加：导出包附件目录核对、空间键映射表确认、重写规则覆盖范围确认、目标端附件限制预检。迁移后验收清单增加：样本页面逐页核对、断链分类统计、权限对照。同时记录导出包校验值、重写规则版本和导入日志的留存位置，下次出现同类问题时可以直接调取比对。
如果迁移后的知识库在 ONES Wiki 中运行，页面、附件与权限的核对结果可以落到具体的工作项或验收记录中跟踪，把本次排查结论转化为下一次迁移的固定检查动作，减少同类问题重复出现。
常见问题
迁移后附件在目标端能看到文件名但下载失败，和附件缺失是同一类问题吗？
两者表现不同，排查路径也不同。文件名可见但下载失败，通常说明附件记录已导入，问题出在存储路径、文件实体或下载权限上；附件缺失则是目标端根本没有对应记录。建议先确认目标端附件记录是否存在，再检查文件实体是否完整、下载权限是否跟随页面。如果记录存在而实体缺失，回到导入段查看是否有跳过或失败记录；如果记录和实体都在但用户下载失败，优先核对附件权限继承关系。
只迁移了一部分空间，跨空间链接断链很多，应该先修链接还是先补迁剩余空间？
建议先确认迁移范围与链接映射的对应关系。如果剩余空间尚未迁移，跨空间链接指向的目标页面在目标端不存在，此时重写链接没有意义，应先完成剩余空间迁移或明确哪些链接暂不纳入本次修复范围。可以先把断链按“目标空间已迁移”和“目标空间未迁移”分开统计，已迁移部分的断链按映射表修复，未迁移部分登记为待迁移后处理，避免反复重写。
导入日志显示成功，但抽样发现部分页面附件数比源端少，应该从哪里查起？
导入日志的“成功”通常指页面记录导入完成，不一定覆盖每个附件的实体写入。建议按“源端附件数—导出包附件数—目标端附件数”三个数字逐页比对：如果导出包内附件数已经少于源端，问题在导出段；如果导出包完整而目标端偏少，回到导入段查看是否有超限、跳过或同名覆盖记录。同时核对缺失附件是否集中在大文件或特定类型上，这能帮助判断是否与目标端限制有关。
批量重写链接前做小批量试跑，样本应该怎么选才有代表性？
试跑样本应覆盖四类链接和主要附件类型，而不是随机抽取。建议从最初的症状分类样本中选取：包含同空间页内链、跨空间链接、附件链接与锚点链接、外部链接的页面各若干，并覆盖不同空间和不同批次。试跑后逐项核对链接跳转结果与映射表是否一致，确认重写规则覆盖了预期类型。如果试跑中发现某类链接未被覆盖，先补充规则再扩大范围，避免批量重写后返工。
权限错配导致用户看不到页面或附件，修复时如何控制影响范围？
权限调整影响面大，建议先列出受影响页面和用户组清单，确认清单后再执行。排查时比对源空间权限、目标空间默认权限和页面级限制三者的继承关系，区分是空间级授权缺失还是页面级限制过严。调整时优先修正空间级默认权限，再处理个别页面级例外；涉及范围授权时保留调整前的权限对照表，便于回退和验收核对。
