迁移附件保留的关键，是把附件当作独立数据对象来管理，而不是随业务数据“顺带”搬过去。可执行的做法是：先盘点源端附件的存放位置、命名规则和关联关系，再确定目标端的承载方式与字段映射，然后小批量试迁移，逐条比对文件数量、大小、哈希和访问权限，最后在切换前保留源端只读副本作为回退依据。附件能否完整保留，取决于源端导出方式、目标端上传接口和权限模型三者的配合，需要以实际核验结果为准。
要点总览（TL;DR）
- 把附件当作独立数据对象处理：先盘点源端附件的存放位置、命名规则和关联关系，再确定目标端承载方式与字段映射，避免只迁业务数据、附件变成孤立文件。
- 盘点表至少记录源对象ID、附件ID、文件名、大小、创建人、创建时间和存储位置；正文内嵌图片要单独标记，因为导出时可能只拿到引用地址而非文件本体。
- 映射的核心是建立源对象ID到目标对象ID的对照表，附件随业务对象挂接；重名文件、历史版本和无法映射的孤立附件都要有统一规则并写入映射规则表。
- 先选小项目试迁移，逐条比对附件数量、大小、哈希、可打开性、挂接对象和权限可见性，差异清零后再按批次放大，每批保留核验记录。
- 迁移前约定停止阈值和回退方式：源端保持只读，目标端清理本批导入数据后重来，源端只读副本的保留期限应覆盖切换后的稳定观察期。
迁移附件保留的范围：哪些附件要迁、迁到哪里
动手之前先把范围写清楚，后续的盘点、映射和核验才有统一口径。范围清单至少要回答三个问题：从哪个系统迁到哪个系统、迁哪些附件、哪些内容不在本次处理。
迁移方向需要明确为源系统到目标系统的单向迁移。源系统可能是自建研发管理平台、第三方项目管理工具或文档平台，目标系统是团队选定的新平台。方向确定后，所有导出、映射和核验动作都围绕这个方向展开，避免中途出现双向同步导致的数据覆盖。
附件对象类型建议按业务对象逐类列出：
- 工单、需求、任务、缺陷等工作项上直接上传的附件；
- 评论中上传的附件；
- 描述、评论等富文本正文中内嵌的图片和文件引用；
- 文档页面上的附件与正文图片（如知识库场景）。
其中正文内嵌图片容易被遗漏。这类图片在源端往往以富文本引用形式存在，导出时可能只拿到引用地址而非文件本体，需要在盘点阶段单独标记。
以下内容不纳入本文：工作流与插件行为的迁移、迁移后的整体结果验证与切换管理。这些环节与附件迁移相邻，但处理方法和责任分工不同，应另行安排。
同时初步确认源系统的版本和可用的导出方式。导出方式决定了能拿到哪些附件元数据：有的系统提供完整的数据导出包，有的只能通过接口逐条拉取，有的需要从存储层直接取文件。这一步的结论会直接影响后续盘点表能填多少字段。
本节的交付物是一份附件迁移范围清单，列明源端对象类型、各类附件的数量级、目标端承载位置。数量级不必精确到个位，但要让团队对迁移工作量有基本判断。
迁移前要准备什么：附件清单、存储位置与权限
这一阶段的输入是范围清单，输出是一张可用的附件盘点表和一份前置条件核对表。盘点做得越细，后面的映射和核验越省力。
导出附件清单
盘点表建议至少包含以下字段，每个附件一行：
| 字段 | 用途 |
|---|---|
| 源对象ID | 定位附件所属的业务对象，用于建立映射 |
| 附件ID | 源端唯一标识，处理重名和回溯差异 |
| 文件名 | 核对目标端文件名是否一致 |
| 文件大小 | 核验完整性，识别截断或空文件 |
| 创建人 | 权限映射和归属确认 |
| 创建时间 | 判断版本取舍，核对时间字段迁移 |
| 关联业务对象 | 确认附件挂接位置 |
| 源端存储位置 | 定位文件本体，判断导出途径 |
确认源端存储方式与导出途径
附件的实际存放位置决定了怎么把文件本体取出来。常见情况有三种：存放在对象存储（如各类云存储服务），通过存储桶批量导出；存放在本地磁盘，通过服务器文件目录打包；存放在第三方图床或外部链接，文件本体可能不在源系统内。第三种情况要特别标注，因为这类附件能否迁移取决于外部服务是否仍可访问。
确认目标端的上传方式与限制
目标端对单文件大小、文件类型、单批上传数量通常有约束。这些限制没有统一标准，需要以目标系统的实际配置为准。确认这些限制后，才能设计分批策略：单批对象数量、单文件是否需要压缩拆分、超大附件是否需要单独通道处理。
账号与权限映射
附件的可见范围依赖成员、角色和项目权限。迁移前要建立源端账号到目标端账号的对照表，并确认附件继承的权限规则：附件跟随所属业务对象的可见范围，还是可以单独设置。权限映射出错会导致两类问题，一是迁移后附件对不该看到的人可见，二是原可见成员看不到附件。
迁移窗口与源端冻结策略
确定迁移执行的时间窗口，并在窗口开始前对源端实施只读冻结，避免迁移过程中源端继续产生新附件或修改已有附件。冻结策略要写明冻结范围、起止时间和解冻条件，并通知相关团队。
本节的交付物是附件盘点表与迁移前置条件核对表。核对表逐项确认：清单已导出、存储位置已确认、目标端限制已确认、账号映射已完成、冻结策略已发布。
附件与业务对象的映射方法
附件迁移的核心难点不在搬文件，而在把文件挂到正确的业务对象上。只迁文件不迁关联，迁移完成后附件会变成一堆找不到归属的孤立文件。
建立对象ID映射表
先建立源对象ID到目标对象ID的对照表。业务对象（工作项、文档页面等）迁移完成后会获得新的目标端ID，附件按这张对照表挂接到对应对象。映射表是附件挂接的唯一依据，建议在对象迁移完成后立即生成并冻结，后续附件导入只读这张表。
处理文件名冲突
同一业务对象下出现同名附件是常见情况。处理规则建议统一：保留原文件名，在冲突时追加源附件ID或序号作为前缀或后缀，确保目标端可区分且能回溯到源记录。规则要写进映射规则表，避免不同批次采用不同做法。
正文内嵌图片与富文本引用
正文中的图片和文件引用需要单独处理。迁移富文本内容时，引用地址要替换为目标端的实际文件地址。处理顺序建议先迁文件本体、拿到目标端地址，再改写正文引用，最后核对正文渲染效果。这一步不能只核对附件列表，必须打开正文确认图片正常显示。
附件版本的取舍
源端附件可能存在多个历史版本。保留最新版还是全量版本，取决于业务需要和迁移成本。如果历史版本对审计或追溯有价值，应全量保留并在盘点表中标注版本号；如果只需当前有效版本，要在范围清单中写明，避免迁移后出现“版本丢失”的争议。
无法映射的附件单独处理
孤立附件（所属对象已删除或从未关联）、已删除对象的附件、外部链接类附件，往往无法自动映射。这类附件单独列入异常清单，标注原因，交人工判断是补挂、归档还是放弃。默认丢弃会带来数据损失，默认全部导入又可能污染目标端数据。
本节的交付物是附件映射规则表与异常附件清单。规则表写明ID对照、重名处理、正文引用改写和版本策略；异常清单逐条记录无法映射的附件及处理建议。
分批试迁移与逐条核验
映射规则确定后，先用小批量验证规则是否成立，再按批次放大。试迁移的价值在于用较低成本暴露映射错误，避免全量迁移后返工。
选择试迁移样本
选一个小项目或一批对象作为试迁移样本。样本应覆盖主要附件类型：工作项附件、评论附件、正文内嵌图片、大文件、重名文件。样本量不必大，但要能代表实际数据的分布。
核验项与核验方法
核验以可观察的证据为准，建议逐项记录：
| 核验项 | 核验方法 | 通过标准 |
|---|---|---|
| 附件数量 | 对比源端与目标端附件条数 | 数量一致，差异有记录 |
| 文件大小 | 逐条比对字节数 | 大小一致 |
| 文件哈希 | 对源文件和目标文件计算哈希值比对 | 哈希一致 |
| 可打开性 | 随机抽取附件下载并打开 | 文件可正常下载、内容完整 |
| 关联关系 | 检查附件是否挂在正确业务对象下 | 挂接对象与映射表一致 |
| 正文图片 | 打开正文查看图片渲染 | 图片正常显示，无失效引用 |
| 权限可见性 | 用不同角色账号查看附件 | 可见范围与源端一致 |
哈希比对是判断文件内容是否完整最直接的手段。如果迁移工具本身不提供哈希校验或差异报告，需要在迁移前后分别计算文件哈希并自行比对，这部分工作量要提前计入计划。
记录差异并修正规则
试迁移中出现的不一致逐条记入差异清单，标注差异类型（缺失、大小不符、挂接错误、权限异常），回溯到映射规则或导出环节找原因。规则修正后重新跑试迁移样本，直到差异清零或剩余差异均有明确处理结论。
按批次放大迁移
试迁移通过后按批次放大。每批完成后保留核验记录：批次范围、附件数量、核验结果、差异处理情况。批次划分建议按项目或业务模块，便于出问题时定位和回退。
在附件挂接业务对象和权限核验这两个环节，ONES 的工作项与附件管理能力可以承接迁移后的附件归属：ONES 的 Jira 迁移方案覆盖项目、工作项、状态、字段、流程、附件和历史记录，Confluence 迁移可将空间、页面、附件和权限结构迁入 ONES Wiki，Jira 问题数据迁移内容包括属性和属性值、附件、评论等信息。具体迁移范围和校验方式仍需按实际项目评估确认。
回退与停止条件
正常路径的核验之外，还要提前约定异常路径的处置规则。停止条件和回退方式应在迁移开始前确定，而不是等问题出现后再讨论。
停止条件
出现以下情况应暂停当前批次并排查：
- 附件缺失率超过事先约定的阈值；
- 哈希不一致集中出现，说明导出或上传环节存在系统性问题；
- 出现权限越权可见，即附件对源端不可见的成员可见；
- 正文图片大面积失效，引用改写规则需要重新设计。
阈值在迁移前约定，例如缺失率超过某一比例即停止。阈值高低取决于附件的业务重要性，没有统一标准。
回退方式
回退的基本做法是：源端保持只读状态不解除，目标端清理本批导入的附件数据后重新执行。清理范围要限定在本批次，避免影响已通过核验的批次。回退前记录本批的差异清单，作为重跑时的检查依据。
切换前的最终确认
全部批次完成并通过核验后，在切换前确认：源端只读副本的保留期限、保管责任人和访问方式；迁移完成后的抽查机制，包括抽查比例、抽查对象和责任人。源端只读副本是回退的最后依托，保留期限应覆盖切换后的稳定观察期。
ONES 的迁移方案把数据完整、业务连续和系统稳定作为目标，并建议在正式迁移前确认数据范围、功能匹配和系统适配。附件保留的最终结论，应以试迁移和分批核验的实际记录为准。
常见问题
源端附件存在第三方图床或外部链接里，还能迁吗？
这类附件要单独处理。文件本体不在源系统内时，能否迁移取决于外部服务是否仍可访问、是否允许批量下载。盘点阶段应把这类附件标注出来，先验证链接可用性，再决定是下载后作为普通文件上传，还是列入异常清单交人工判断。不要默认它们会随业务数据自动带过去。
迁移工具不提供哈希校验，怎么确认文件没有损坏？
可以在迁移前后分别计算文件哈希并自行比对。具体做法是：导出阶段对源端文件生成哈希清单，导入完成后对目标端文件重新计算，按附件ID逐条对照。工作量要提前计入计划，样本量大时可以按批次抽算加全量数量核对结合。哈希不一致的文件优先排查导出截断和上传中断两类原因。
正文里的图片迁移后显示不出来，问题一般出在哪？
常见原因是引用地址没有改写。富文本正文中的图片以引用形式存在，文件本体迁到目标端后会获得新地址，正文里的旧引用就失效了。处理顺序是先迁文件本体、拿到目标端地址，再改写正文引用，最后打开正文确认渲染效果。只核对附件列表发现不了这类问题，必须实际打开正文查看。
附件历史版本要不要全部保留？
取决于业务需要和迁移成本。历史版本对审计、追溯有价值时应全量保留，并在盘点表中标注版本号；只需当前有效版本时，要在范围清单里写明，避免迁移后出现版本丢失的争议。无论选哪种，规则都要在迁移前确定并写入映射规则表，不要不同批次采用不同做法。
迁移中途发现附件大面积缺失，应该继续还是停下来？
应暂停当前批次排查。缺失集中出现通常说明导出或上传环节存在系统性问题，继续放大只会扩大返工范围。暂停后先核对本批差异清单，定位是导出不完整、映射表错误还是上传失败，修正后重跑试迁移样本。停止阈值建议在迁移开始前约定，例如缺失率超过某一比例即停止，阈值高低取决于附件的业务重要性。
