迁移链接保留的核心，是把“链接指向的对象”和“链接的呈现形式”分开处理：先确认目标对象是否随迁移落到新系统，再确认旧对象ID能否稳定映射到新对象ID，最后确认链接格式能否被目标系统识别。三项逐类确认后，再决定改写、重建还是降级为文本引用。本文按盘点、映射改写、校验、回退四个阶段展开，适用于源系统到目标系统的数据内容链接处理。
要点总览（TL;DR）
- 链接保留先分清两件事：链接指向的对象是否随迁移落到新系统，以及链接的呈现形式能否被目标系统识别；两项都确认后再决定改写、重建或降级。
- 盘点阶段按工作项互链、文档内链与锚点、附件引用、外部URL、评论中的链接分类统计，并把流程与插件行为、整体验收排除在本文范围之外。
- 映射阶段以旧对象ID到新对象ID的映射表为唯一依据，匹配规则优先用问题编号、页面路径等稳定业务键，待定项不进入批量改写。
- 校验先按链接类型分层抽样确认指向正确，再全量扫描区分断链与指向错误对象两类问题，记录链接总数、成功数、降级数和待人工处理数。
- 批量改写前保留源系统只读窗口，映射错误率或指向错误比例超过预设阈值时暂停推进，切换前关闭未决链接问题或明确接受降级。
链接保留的源目标与对象范围怎么界定
动手盘点之前，先把迁移方向和对象边界写清楚。方向必须固定为“源系统 → 目标系统”，后续所有映射表、改写脚本和校验记录都以这个方向为准，避免中途出现反向对照导致ID错位。范围界定要落到两份清单上：一份是链接类型清单，一份是对象范围清单。
链接类型建议按承载位置和目标对象分类盘点，每一类单独统计数量、目标对象类型和可迁移性：
- 工作项互链：需求、任务、缺陷、子任务之间的关联关系，通常以对象ID或业务编号形式存储。
- 文档内链：知识库页面之间的引用，包含页面级链接和带锚点的段落级链接。
- 附件引用：正文或评论中指向附件文件的地址，可能依赖文件存储路径。
- 外部URL：指向外部网站、外部系统或第三方工具的地址，目标系统通常只做展示。
- 评论中的链接：散落在评论文本里的各类地址，格式不统一，最容易在盘点中被漏掉。
范围清单要明确纳入项和排除项。纳入项是上述五类链接在数据内容中的存储与呈现；排除项包括工作流与插件行为本身的迁移、迁移结果的整体验收与切换管理，这些内容由其他环节负责，本文只在链接层面给出交接点。把排除项写进清单，可以防止盘点阶段把插件生成的动态链接、流程触发的跳转规则一并算进来，导致后续映射规则失焦。
本阶段需要的输入与依赖
链接映射不是独立动作，它依赖上游几项产出。执行前逐项核对，缺一项就先补齐再进入改写，否则映射表会反复返工。
| 输入项 | 用途 | 核对要点 |
|---|---|---|
| 源系统对象清单 | 确定链接目标对象的全集 | 覆盖所有纳入的链接类型，含已归档对象 |
| 源系统链接关系数据 | 提取每条链接的源对象、目标对象和原始地址 | 能导出为结构化数据，保留原始字符串 |
| 目标系统对象创建结果 | 提供新对象ID，作为映射表的右列 | 对象创建完成且ID稳定，不再批量变动 |
| 字段与对象映射表初版 | 确定对象级对应关系，链接映射在其上叠加 | 已覆盖主要对象类型，遗留项有标注 |
| 权限与导出范围 | 确认能读到的数据边界 | 导出账号具备所需范围，敏感内容有脱敏约定 |
其中目标系统的ID回填能力是关键依赖。链接改写本质上是把旧ID替换为新ID，如果新对象ID在改写时还未生成或仍会变化，批量改写就会产生一批指向错误对象的链接，比断链更难排查。因此改写动作应安排在对象创建完成、ID稳定之后。权限方面，导出范围受限时要在盘点清单中标注“未覆盖”区域，避免把不完整的盘点结果当成全量结论。
链接映射的具体做法：从ID映射到链接改写
映射阶段的主产物是一张旧ID到新ID的映射表，它是所有改写动作的唯一依据。匹配规则优先使用稳定业务键，例如原系统的问题编号、页面路径或附件原始文件名加路径组合；名称、标题这类字段容易在迁移中被修订，不宜作为主键。映射表至少包含四列：旧对象ID、旧对象类型、新对象ID、匹配依据与置信状态。置信状态用于标记自动匹配、人工确认和待定三类，待定项不进入批量改写。
不同链接类型走不同处理路径，建议按下表分路径执行：
| 链接类型 | 处理路径 | 失败时的处置 |
|---|---|---|
| 工作项互链 | 按映射表批量改写为目标系统对象地址 | 目标对象未迁移时降级为文本引用，保留原编号 |
| 文档内链（页面级） | 按页面映射表批量改写 | 页面未迁移时保留原地址并标注状态 |
| 文档内链（锚点） | 目标页面结构一致时重建锚点；结构变化时改为指向页面顶部并附说明 | 无法定位段落时降级为文本引用，附原锚点标识 |
| 附件引用 | 按附件映射关系改写为新的文件地址 | 附件未迁移时保留原地址并标注“源系统附件” |
| 外部URL | 原样保留，不改写 | 不适用，仅记录可达性状态 |
| 评论中的链接 | 按上述规则识别后改写，无法识别的保持原文 | 进入人工复核队列 |
批量改写前先做小批量试改，取几十条覆盖各类型的链接，改写后在目标系统逐条打开确认。试改通过再扩大范围。改写过程保留原始链接字符串，写入映射表的附加列，便于回退和人工复核时对照。
无法映射的链接统一进入人工复核队列，每条记录原链接、源对象、目标对象候选、失败原因和处置结论。处置结论限定为三种：改写成功、降级为文本引用、确认放弃。队列要有明确的清空标准，例如“待定项清零或全部标注可接受降级”，否则未决问题会带入切换阶段。
在ONES的迁移场景中，工作项与文档的关联关系依托对象本身承载，Jira迁移方案覆盖项目、工作项、状态、字段、流程、附件和历史记录，Confluence迁移方案将空间、页面、附件和权限结构迁入ONES Wiki。链接改写仍应以上述映射表为准，把对象级映射做扎实，再处理链接层面的替换。
核验与证据：怎么确认链接真的可用
校验分两步：先抽样确认指向正确，再全量扫描确认没有遗漏。抽样解决“改得对不对”，全量解决“有没有漏改”。
抽样样本按链接类型分层抽取，每类不少于一个可判断的样本量，覆盖已改写、已降级、外部URL三类结果。通过标准是：打开链接后落到预期对象，对象类型和内容与源系统一致；降级项显示为文本引用且原地址可读；外部URL保持原样。抽样中发现指向错误对象的，立即暂停该类链接的批量改写，回到映射表排查匹配规则。
全量扫描要区分两类问题分别统计：断链，即地址无法打开或返回空；指向错误对象，即能打开但落到了别的对象上。第二类更隐蔽，扫描时可用“链接文本描述与目标对象标题是否一致”作为辅助判断。扫描结果形成校验记录，至少包含以下字段：
- 链接总数，按类型分列；
- 改写成功数；
- 降级为文本引用数；
- 待人工处理数；
- 断链数与指向错误数。
校验记录要指定复核责任人和留档方式。责任人按链接类型分工，例如工作项互链由业务侧复核，文档内链由知识库维护人复核；留档方式可以是校验记录表加扫描结果文件，随迁移项目归档，作为切换决策的依据之一。
回退与停止条件
回退机制要在批量改写之前就位，而不是等问题出现再补。核心是保留源系统的只读窗口，在目标系统校验通过之前不关闭源系统访问，确保任何时刻都能对照原始链接。
停止条件建议按可观测指标设定：映射表错误率超过预设阈值时，暂停批量改写，先修正匹配规则并重新试改；全量扫描中指向错误对象的比例超过可接受范围时，同样停止推进，回到映射表逐类排查。阈值和样本量结合项目规模与风险偏好确定，写进迁移方案并在执行前与相关方确认。
降级为文本引用是可接受的处置结果，但有边界：降级项必须逐条标注原地址和降级原因，且经过责任人确认。指向外部系统或已下线对象的链接，保留原地址并标注状态即可，不强行改写为无效内链。
切换前需要关闭的未决链接问题包括：人工复核队列中未给出处置结论的条目、抽样中发现的指向错误、以及映射表中仍为待定状态的对象。这些问题要么处理完毕，要么明确记录为可接受降级并取得确认，二者都不满足时不宜进入切换。
常见问题
源系统里有些链接指向的对象这次不迁移，这些链接怎么处理？
这类链接不进入批量改写，按“保留原地址并标注状态”处理。具体做法是在映射表中把目标对象标记为未迁移，链接层面保留原始地址字符串，并在链接所在位置或校验记录中注明“源系统对象，未迁移”。如果该链接出现在正文中且读者需要理解上下文，可以降级为文本引用，写出原对象编号或标题，避免留下一个打开后报错的地址。降级项要逐条记录原地址和降级原因，由责任人确认后再进入切换。
文档内链带锚点，迁移后段落位置变了，还能保留吗？
能否保留取决于目标页面结构是否与源页面一致。目标页面段落结构一致时，可以按页面映射表改写链接并重建锚点；结构发生变化、原锚点无法定位时，改为指向目标页面顶部并附一句说明，或者降级为文本引用并保留原锚点标识。不建议把锚点强行拼到新地址上，那样链接能打开但落不到预期段落，属于指向错误，比断链更难排查。处理结果记入人工复核队列，标注处置结论。
映射表里出现一个旧对象对应多个新对象候选，怎么定？
这种情况说明匹配规则不够唯一，先不要自动选定。把该条记录标为待定，附上全部候选和匹配依据，交给熟悉源数据的业务侧人员确认。确认时以稳定业务键为准，例如原系统问题编号或页面路径；名称、标题在迁移中可能被修订，只能作为辅助线索。确认结果回填映射表并更新置信状态，待定项清零或全部标注可接受降级后，才允许该类链接进入批量改写。
全量扫描发现链接能打开但落到了别的对象上，怎么定位原因？
先按链接类型缩小范围，再回到映射表核对匹配规则。常见原因是匹配主键不唯一，例如用标题匹配时出现重名，或者新对象ID在改写时还未稳定。定位方法是用“链接文本描述与目标对象标题是否一致”做辅助判断，把不一致的记录逐条对照映射表。确认是规则问题后，暂停该类链接的批量改写，修正规则并重新小批量试改；确认是个别数据问题，则进入人工复核队列单独处置。
评论里的链接格式很杂，盘点时怎么保证不漏？
评论中的链接通常没有结构化存储，靠人工翻查容易遗漏。可行做法是先导出全部评论文本，用地址特征做一轮机器识别，把识别出的链接按目标类型归类，识别不出的保持原文并进入人工复核队列。盘点清单中单独列出“评论链接”一类，记录识别数量和待人工确认数量。改写时只处理已确认目标对象的链接，其余保持原文，避免误改普通文本中的编号或路径。
