迁移附件保留的核心做法，是把附件当作独立数据对象来迁移，而不是随记录正文一起搬运。具体顺序是：先盘点附件来源、存储方式与引用关系，建立附件清单和字段映射；再按“先试迁移、后全量”的节奏执行；最后用数量、哈希、可打开性和引用链接四类证据核验。同名字段含义不同、附件分散在正文与独立文件库、链接指向旧系统地址，是附件丢失或错挂的常见原因，需要分别处理。本文聚焦附件数据内容的迁移操作，工作流与插件行为不在讨论范围内。
要点总览（TL;DR）
- 附件保留要把附件当作独立数据对象迁移：先按承载位置盘点范围，再建立含文件名、大小、哈希、所属对象ID的附件清单。
- 字段映射按语义对齐而非按名称对齐，同名字段含义不同时新增中间字段或标记待人工确认，避免附件错挂。
- 执行顺序为抽样试迁移、核对差异、全量分批迁移、增量补齐，每批次保留失败清单与重试记录。
- 核验取四类证据：数量逐类比对、大小与哈希比对、抽样打开检查、记录内链接指向正确文件。
- 执行前设定暂停阈值与三个回退点，触发后先修复映射、容量或传输问题，再重新启动全量迁移。
来源与目标：附件保留要覆盖哪些对象
附件迁移的第一步是写清方向：数据从哪个来源系统迁往哪个目标系统，这个方向在整份方案里不能颠倒。盘点、导出、映射、核验都按“来源→目标”的顺序描述，避免执行时把目标系统的字段当成来源字段使用。
附件范围要按承载位置逐类列出，而不是笼统写一句“迁移所有附件”。常见的附件对象包括：
- 记录内嵌附件：直接挂在工作项、任务或工单上的文件；
- 独立文件库：以文件夹或文档库形式集中存放的文件；
- 正文内嵌图片：写在描述、评论或页面正文中的图片；
- 评论附件：随评论一起提交的文件；
- 历史版本附件：记录或页面在历史版本中保留的文件。
在列出对象的同时，要区分“需要保留”和“可以清理”两类。临时导出文件、重复上传的同一文件、已失效的草稿附件，如果业务上不再需要，应在盘点阶段标记为不纳入迁移，并记录判断依据。这样既能缩小迁移体积，也能避免核验时把主动清理的文件误判为丢失。
本阶段的交付物是一份附件范围清单，建议按“来源位置、目标位置、附件类型、是否纳入迁移、备注”五列组织。清单确认后再进入输入准备，范围之外的对象不临时追加。
迁移前要准备哪些输入与依赖
附件迁移中途返工，多数是因为输入没备齐。执行前应逐项确认以下依赖，并把结果记成一张检查表，标注“已具备、待确认、缺口”三种状态。
| 输入项 | 需要确认的内容 | 缺失时的处理 |
|---|---|---|
| 源系统导出能力 | 能否按对象批量导出附件，导出格式是原文件还是打包文件，是否附带元数据 | 改为按对象分批导出，或先导出关联关系再逐条取文件 |
| 目标系统限制 | 附件容量、单文件大小上限、允许的文件格式 | 超限文件单独列出，评估压缩、拆分或另行归档 |
| 关联关系数据 | 附件所属的项目、工作项、评论、版本标识是否可导出 | 补齐关联字段导出，否则附件无法挂到正确对象 |
| 存储与网络条件 | 附件总体积、可用传输时间窗口、是否需要断点续传 | 按体积划分批次，安排低峰时段执行 |
| 权限与账号映射 | 源系统附件可见范围与目标系统账号、角色的对应关系 | 先完成账号映射，再执行附件迁移 |
其中账号映射是容易被忽略的前置项。附件的可见性往往继承所属对象的权限，如果账号没有对齐，迁移后可能出现附件存在但无人可见的情况。容量与格式限制属于目标系统的硬约束，应在试迁移前就确认，避免全量阶段才发现大批文件无法入库。
附件清单与字段映射怎么做
附件错挂的根源通常不在传输环节，而在映射环节。建议以附件唯一标识为主线建立清单，每行至少包含：文件名、文件大小、哈希值、来源路径、所属对象ID、附件类型。哈希值用于后续完整性比对，所属对象ID用于建立关联，两者缺一不可。
字段映射表按“源字段、目标字段、转换规则、示例值”四列编写。转换规则要写具体，例如日期格式如何转换、多值字段如何拆分、空值如何填充。示例值的作用是让执行人和复核人用同一口径理解规则，减少歧义。
同名字段含义不同是最需要警惕的情况。两个系统都有“附件”字段，但一个指记录主附件，另一个指全部关联文件；两个系统都有“版本”，但一个指文件版本，另一个指记录版本。处理原则是按语义对齐而非按名称对齐：先确认字段在业务上承载什么，再决定映射到哪个目标字段；语义无法一一对应时，新增中间字段承载转换结果，或把该字段标记为待人工确认，不强行套用同名映射。
附件与业务对象的关联要分路径处理：
- 工作项附件：通过工作项ID关联，映射到目标系统对应工作项的附件区；
- 评论附件：先定位评论所属记录，再挂到目标系统对应评论下；
- 正文内嵌图片：随正文一起迁移，并检查图片引用是否仍指向新地址；
- 历史版本附件：按版本号逐版映射，保留版本顺序。
对于无法映射的附件，要提前定好挂载策略，三选一：挂到迁移记录下作为兜底、单独归档到指定位置、标记为待人工处理并进入差异清单。策略一旦确定，全量阶段统一执行，不逐条临时决定。
在ONES的迁移方案中，Jira问题数据迁移到ONES Project时包含附件、评论等信息，Confluence迁移到ONES Wiki时支持页面正文、附件、图片等内容，附件与工作项、评论、页面正文的关联可以在迁移范围内一并处理。具体到单文件大小、格式范围和链接重写规则，需要在迁移前向实施方确认，并以确认结果调整映射表。
试迁移与全量执行的操作顺序
试迁移的目的是用少量样本暴露映射和传输问题，而不是提前完成迁移。抽样应覆盖不同附件类型、不同大小区间和不同关联对象：既要有小体积的工作项附件，也要有大体积的文件库文件；既要有评论附件，也要有历史版本附件。样本数量以能覆盖上述组合为准，不必追求比例。
试迁移的执行步骤建议如下：
- 按附件清单导出样本文件及关联关系数据；
- 按映射表导入目标系统，记录每条附件的导入结果；
- 对照清单检查数量、大小、哈希和挂载位置；
- 抽样打开文件，确认格式与内容正常；
- 整理差异清单，修正映射规则后重新试迁移差异部分。
试迁移通过后进入全量阶段。全量迁移按批次划分，批次可以按项目、按对象类型或按附件体积切分，每批次完成后立即核验该批次，而不是全部跑完再统一检查。迁移窗口内如果源系统仍有新增附件，应记录变更时间点，在全量结束后做增量补齐；无法暂停写入的场景，更需要保留这份变更记录。
执行过程中要为失败项保留重试记录：哪些附件失败、失败原因、重试次数、最终状态。断点续传能力如果具备，按批次断点恢复；如果不具备，则以批次为单位整体重跑，避免出现半批次状态。
附件保留的核验证据怎么取
判断附件是否真正保留，不能只看导入日志显示成功，要取四类证据。
| 核验类型 | 比对方法 | 通过标准 |
|---|---|---|
| 数量核验 | 源清单与目标清单按附件类型逐类比对条数 | 各类数量一致，差异项有明确说明 |
| 完整性核验 | 逐条比对文件大小与哈希值 | 哈希一致；不一致项进入差异清单 |
| 可用性核验 | 按类型抽样打开附件，检查格式与内容 | 文件可正常打开，内容与源文件一致 |
| 引用核验 | 在记录内点击附件链接，确认指向正确文件 | 链接可点击，打开的是对应附件而非旧地址 |
数量核验适合先做，能快速发现整类遗漏；哈希比对适合全量执行，是判断文件内容是否一致的直接证据；可用性核验以抽样为主，重点覆盖大文件、特殊格式和历史版本附件；引用核验针对正文内嵌图片和记录内链接，检查是否仍指向来源系统地址。
核验结果汇总成附件核验报告，包含比对总数、一致数、差异数、差异明细和人工复核结论。差异明细要写清附件标识、差异类型、可能原因和处理动作，便于逐条闭环。
什么情况下应暂停或回退
暂停条件应在执行前定好阈值，而不是出问题后再讨论。常见触发条件包括：哈希不一致比例超过预设阈值、附件关联错挂比例超过阈值、目标系统容量余量不足、大批附件因格式或大小限制无法入库。阈值由迁移负责人根据业务容忍度设定，写入迁移计划。
回退点建议设在三个位置：试迁移完成后、全量迁移开始前、正式切换前。每个回退点保留当时的源系统数据快照和目标系统状态记录。触发回退时，目标系统中已导入的附件按批次标记或清理，源系统保持只读或维持原状，避免两边同时变更导致状态混乱。
回退之后要记录原因：是映射规则错误、容量不足还是传输失败，并针对原因修复后再执行。修复项包括调整映射表、补充容量、更换传输方式或缩小批次。未完成修复前不重新启动全量迁移，避免同一问题重复出现。
常见问题
迁移期间源系统还在产生新附件，怎么保证不遗漏？
先记录迁移窗口的起始时间点，全量迁移完成后按这个时间点做增量补齐，把窗口内新增的附件和关联关系再迁一次。如果源系统可以短暂停写，把停写区间安排在批次切换处最省事；无法停写时，保留变更记录是后续补齐的依据，不要依赖“迁移时刚好没人上传”这种假设。
附件数量对得上，但打开后发现内容不对，可能是什么原因？
数量一致只能说明条数没丢，内容错位通常出在映射环节：同名文件被覆盖、附件与对象的关联ID对应错行、或者多值字段拆分后顺序错乱。处理办法是回到附件清单，用哈希值定位具体是哪些文件不一致，再检查这些文件在映射表中的所属对象ID和转换规则。哈希不一致的文件应全部进入差异清单逐条复核，不能只抽查。
正文里引用的图片和附件链接，迁移后需要单独处理吗？
需要。正文内嵌图片和记录内链接在迁移后可能仍指向来源系统地址，表现为链接可点击但打开的是旧系统页面或失效地址。核验时应逐条点击确认指向目标系统中的对应文件。链接重写的具体规则与覆盖范围，需要在迁移前向实施方确认，并按确认结果调整核验方案；确认之前不要把“链接自动重写”当作既定前提写进计划。
历史版本中的附件要不要全部迁移？
取决于业务是否需要回溯历史版本。需要保留的，按版本号逐版映射并保持版本顺序，核验时把历史版本附件单独列为一类抽样检查；业务上不再回溯的，在盘点阶段标记为不纳入迁移并记录判断依据，核验时就不会把主动清理的文件误判为丢失。两类处理都要写进附件范围清单，避免执行时口径不一。
试迁移通过后，全量阶段还需要再核验吗？
需要，而且建议每批次完成后立即核验该批次，而不是全部跑完再统一检查。试迁移的样本量小，覆盖不到大体积文件、特殊格式和长尾关联对象；全量阶段按批次核验能更早发现容量、格式或关联路径上的问题，把返工范围控制在单批次内。批次核验结果汇总进附件核验报告，差异项逐条闭环。
