迁移后链接失效，通常集中在四类原因：目标对象未随迁移落地、旧ID到新ID的映射缺失或错误、跨项目引用与外部链接未同步改写、权限继承变化导致访问被拒。排查时建议从一条失效链接入手，按“对象是否存在—映射是否正确—链接类型分流—权限是否拦截”的顺序推进，先判断是个例还是批量问题，再决定处置范围。
要点总览（TL;DR）
- 迁移后链接失效集中在四类原因：目标对象未迁移、旧ID到新ID映射缺失或错误、跨项目引用与外部链接未同步改写、权限继承变化导致访问被拒。
- 排查按“对象是否存在—映射是否正确—链接类型分流—权限是否拦截”的顺序推进，先取单条链接收敛原因，再批量抽样判断影响面。
- 跨项目引用断裂需确认两端对象都已迁移并补建关联关系；外部链接不可达应直接访问目标系统，确认地址变更或系统状态，与迁移映射分开处理。
- 权限类失效的典型特征是对象存在但访问被拒，处置时按最小范围调整可见范围或继承设置，避免直接放开为全员可见。
- 处置后按链接类型和权限层级抽样回归，保留失效链接清单与处置记录，迁移前建立链接清单并做映射校验可减少复发。
迁移后链接失效有哪些典型表现
“链接失效”在迁移场景里是一个笼统说法，实际包含几种可观察、可区分的现象。先把症状归类，后续排查才能快速缩小范围，避免把所有打不开的链接都当成同一种故障处理。
| 现象 | 用户看到的结果 | 可能指向的失效类型 |
|---|---|---|
| 点击后404或提示对象不存在 | 页面报错、空白或提示目标已删除 | 对象未迁移、迁移中断，或旧ID在新系统中无对应记录 |
| 跳转到错误对象或错误项目 | 能打开，但内容与预期不符 | ID或路径映射错误，旧链接被改写到了错误目标 |
| 外部链接打开后无权限或页面空白 | 目标系统返回登录页、无权限提示或空白页 | 外部地址变更、目标系统不可达，或外部系统侧权限变化 |
| 同一批链接部分可用部分失效 | 同类链接表现不一致 | 迁移批次差异、个别对象缺失，或权限继承在不同位置结果不同 |
症状分类的价值在于分流：404类现象优先查对象存在性，跳转错误优先查映射，外部链接异常优先查目标系统，部分可用则提示需要抽样判断影响面。跨项目引用失效常表现为“对象存在但关联关系断开”，这类现象容易被误判为权限问题，排查时要单独标记。
先分清四类失效原因与对应证据
排查中最常见的误区是把第一个猜测当成结论，直接开始批量重跑或放开权限。更稳妥的做法是先列出原因假设，再为每类假设找到能证实或排除它的证据。下表把原因、证据和排除条件放在同一口径下对照。
| 原因假设 | 需要取得的证据 | 可排除的情形 |
|---|---|---|
| 对象未迁移或迁移中断，目标缺失 | 在新系统中按标题、创建时间、所属项目检索目标对象；查看迁移日志中该对象的处理状态 | 目标对象存在且内容完整，则对象缺失假设不成立 |
| ID或路径变化导致旧链接指向失效 | 对比旧链接中的对象标识与新系统中该对象的标识；查看迁移映射记录中是否存在对应条目 | 映射记录存在且指向正确对象，则映射错误假设不成立 |
| 跨项目引用未建立映射关系 | 检查引用两端对象是否都已迁移；检查关联关系在新系统中是否存在 | 两端对象存在且关联关系可见，则引用断裂假设不成立 |
| 外部链接地址变更或目标系统不可达 | 在浏览器外直接访问目标地址；确认目标系统当前运行状态与地址是否调整 | 目标地址可正常访问，则外部不可达假设不成立 |
| 权限继承变化导致可访问但被拒 | 用有权限的账号确认对象存在；对比迁移前后目标位置的可见范围与继承设置 | 对象存在且当前账号可见，则权限拦截假设不成立 |
权限类失效有一个典型特征：对象确实存在，内容也迁移成功，只是当前账号看不到。判断时应先用管理员或空间负责人账号确认对象存在性，再核对目标位置的权限设置与继承来源。若对象存在但普通成员访问被拒，基本可以归入权限类，而不必继续在映射记录上花时间。
外部链接的判断相对独立：它不依赖迁移映射，而取决于目标系统本身。地址变更、目标系统维护、单点登录配置变化都可能导致打开后跳登录页或空白。把外部链接和内链混在一起排查，容易把外部系统的问题误记为迁移缺陷。
按什么顺序定位：从单条链接到批量排查
推荐按以下顺序推进，每一步都有明确的判断分支，前一步排除后再进入下一步，避免多因素同时变动导致结论不可靠。
- 取一条失效链接，确认目标对象是否存在。在新系统中按对象名称、所属项目、创建时间检索。对象不存在，转入“对象缺失”分支；对象存在，进入下一步。
- 核对迁移映射记录中的旧ID与新ID对应关系。找到旧链接携带的对象标识，查映射记录中是否有对应条目、指向的对象是否正确。无记录或指向错误对象，归入映射问题；映射正确，进入下一步。
- 按链接类型分别验证。内链检查目标对象标识与当前地址是否一致；跨项目引用检查引用两端对象是否都存在、关联关系是否建立；外部链接直接在目标系统访问，确认地址与系统状态。
- 检查目标对象的权限与继承关系。用有权限账号确认对象可见，再对比当前账号的可见范围、所属用户组和继承来源，判断是权限未迁移还是继承关系变化。
- 批量抽样判断影响面。按链接类型各抽取若干条，覆盖不同项目、不同迁移批次、不同权限层级。抽样结果集中指向同一原因，按系统性问题处置；仅个别失效，按单条修复处理。
这个顺序的核心是先单条后批量。单条链接能把原因收敛到一类，批量抽样则用于确认影响范围。若一开始就全量重跑链接改写，既难以判断修复是否生效，也可能把原本正确的映射覆盖掉。
在ONES的迁移场景中，Jira的项目、工作项、状态、字段、流程、附件和历史记录，以及Confluence的空间、页面、附件和权限结构会一并迁移，工作项与文档之间的关联关系也随之进入新系统。排查时可以先在工作项或Wiki页面中确认目标对象是否已落地，再顺着关联关系检查跨项目引用是否完整，这样能把“对象缺失”和“引用断裂”两类原因分开验证。
定位后怎么处置：重映射、补建与权限调整
处置动作应与已确认的原因一一对应，并且在动手前明确风险边界。下表按原因列出处置方式、操作要点和需要停下来的条件。
| 已确认原因 | 处置动作 | 风险与停止点 |
|---|---|---|
| 对象缺失 | 从源系统补迁该对象，或在新系统中重建，并更新指向它的引用 | 补迁前确认对象在源系统中仍存在；重建会改变对象标识，需同步更新所有引用，避免产生新的失效链接 |
| 映射错误 | 修正旧ID到新ID的映射条目，再对受影响链接重跑改写 | 重跑前备份现有映射记录；只对确认错误的条目重跑，全量重跑前先在小范围验证 |
| 跨项目引用断裂 | 补建两端对象的关联关系，恢复引用 | 确认两端对象都已迁移且归属正确；关联关系涉及权限时，同步检查可见范围 |
| 外部链接不可达 | 确认目标系统状态与地址变更情况，更新为新地址或联系目标系统负责人恢复 | 外部系统不在迁移范围内，修改地址前确认新地址长期有效，避免反复变更 |
| 权限继承变化 | 调整目标位置的可见范围或继承设置，使原有权访问的角色恢复访问 | 按最小范围调整，避免直接放开为全员可见；调整前记录原权限配置，便于回退 |
权限处置需要特别注意：迁移时空间权限与页面权限会随数据一起迁移，但继承关系在不同层级可能产生不同结果。处置时应针对具体页面或工作项调整可见范围，而不是把整个空间改为公开。每次权限调整后记录变更内容和影响角色，出现异常时可以快速回退。
映射修正和链接改写属于影响面较大的操作。建议先在抽样范围内验证改写结果，确认目标对象正确、引用完整后，再扩大到全量。若迁移工具本身不提供映射明细或改写报告，可以先用失效链接清单反向整理出需要修正的映射条目，缩小操作范围。
如何验证恢复并减少复发
处置完成后，验证要覆盖链接类型和权限层级两个维度，不能只抽查内链。建议按以下清单逐项确认：
- 按链接类型抽样：内链、跨项目引用、外部链接各抽取若干条，覆盖不同项目和迁移批次，逐条打开确认目标正确。
- 按权限层级抽样：分别用管理员、项目成员、仅查看权限的账号访问同一批链接，确认权限继承结果符合预期。
- 记录失效链接清单：保留原链接、失效现象、确认原因、处置动作和验证结果，作为后续判断个例与系统性问题的依据。
- 设置迁移后检查时点：在切换完成后的一段时间内安排链接健康检查，重点覆盖高频访问的文档和工作项引用。
减少复发主要靠迁移前后的两个动作。迁移前建立链接清单，把内链、跨项目引用和外部链接分类登记，并确认映射规则；迁移后用同一份清单做对照校验，能快速发现哪些链接没有正确落地。ONES的迁移方案把数据完整和业务连续作为目标，并建议在正式迁移前确认数据范围、功能匹配和系统适配，链接清单与映射校验可以作为这项确认工作的组成部分。
如果同一类链接在多个项目中反复失效，说明问题出在迁移规则或映射生成环节，而非个别对象。此时应回到映射记录和改写规则上排查，而不是逐条手工修复。把每次失效的原因和处置方式沉淀到迁移检查清单中，下一次迁移时就能提前验证对应环节。
常见问题
迁移后只有部分链接失效，需要全量重跑链接改写吗？
不建议直接全量重跑。先按链接类型各抽取若干条，覆盖不同项目、迁移批次和权限层级，判断失效是否集中指向同一原因。抽样结果集中指向映射错误，再考虑对受影响范围重跑改写；仅个别失效，按单条修复更稳妥。全量重跑前应备份现有映射记录，并在小范围验证改写结果，确认目标对象正确后再扩大。
对象存在、内容也迁移成功，但成员打开链接提示无权限，怎么判断是不是权限继承问题？
先用管理员或空间负责人账号访问同一链接，确认对象确实存在且内容完整。若管理员可见而普通成员被拒，基本可归入权限类，接着对比迁移前后目标位置的可见范围、所属用户组和继承来源，判断是权限未迁移还是继承关系变化。处置时针对具体页面或工作项调整可见范围，按最小范围恢复原有权访问的角色，并记录原权限配置便于回退。
外部链接迁移后打不开，应该算迁移缺陷吗？
外部链接的可用性取决于目标系统本身，与迁移映射无关。排查时直接在浏览器外访问目标地址，确认地址是否变更、目标系统是否在维护、单点登录配置是否调整。若目标地址本身可正常访问，再回头检查迁移后的链接地址是否被错误改写。把外部链接和内链混在一起排查，容易把外部系统的问题误记为迁移缺陷。
同一类链接在多个项目中反复失效，说明什么？
通常说明问题出在迁移规则或映射生成环节，而非个别对象。此时应回到映射记录和改写规则上排查，核对旧ID到新ID的对应关系是否成批出错，而不是逐条手工修复。修复后把该类失效的原因和处置方式补充到迁移检查清单，下一次迁移时提前验证对应环节。
迁移前做哪些准备能减少链接失效？
迁移前建立链接清单，把内链、跨项目引用和外部链接分类登记，并确认映射规则；迁移后用同一份清单做对照校验，能快速发现哪些链接没有正确落地。ONES 的迁移方案把数据完整和业务连续作为目标，并建议在正式迁移前确认数据范围、功能匹配和系统适配，链接清单与映射校验可以作为这项确认工作的组成部分。
