迁移附件时，真正容易出问题的地方往往是附件与工作项、评论、文档版本之间的关联关系，文件本身反而相对简单。本文按盘点、映射、分批执行、核验、回退五个阶段展开，说明如何把附件当作有归属的数据对象来管理，并给出可直接套用的盘点表、映射表和核验表结构。
要点总览（TL;DR）
- 附件保留的关键在关联关系：先把工作项、评论、文档页面等父对象迁到目标系统并拿到目标ID，再挂载附件，避免出现无归属的孤立文件。
- 动手前先产出附件盘点表，字段覆盖源附件ID、所属实体、文件名、大小、类型、创建人、创建时间、存储路径或URL，外链与失效链接单独标记。
- 执行时按项目或时间分批，先小批量试迁，先搬文件本体再回写关联关系，失败项记录后断点续迁，迁移窗口内的新增附件单独作为增量批次处理。
- 核验用三类证据：数量对账、可打开性抽检、关联正确性双向抽检，差异项汇总成差异清单并留存，作为验收依据。
- 回退以批次为单位，触发条件包括失败率超阈值、关联错挂无法定位、目标存储容量不足，回退期间源系统保持只读，恢复前逐条补齐检查项。
附件保留要迁移哪些内容：来源、目标与范围界定
附件迁移的第一步是把方向固定下来：从源系统迁往目标系统，源系统在迁移窗口内保持可读，目标系统承担迁移后的日常使用。方向一旦确认，后续所有盘点、映射和核验都围绕这条单向链路展开，避免出现两边同时写入、责任不清的情况。动手前需要记录源系统与目标系统各自的版本号和附件存储方式，例如附件是存放在数据库、对象存储还是本地文件目录，这决定了导出手段和搬运方式。
“附件”在研发系统里通常分散在多个位置，需要拆成可盘点的类别，否则范围含糊会直接导致漏迁或重复迁。常见类别包括：
- 工作项附件：直接上传在需求、任务、缺陷等工作项上的文件。
- 评论附件：随评论一起提交的文件，归属对象是评论而非工作项本身。
- 文档附件：挂在知识库页面、文档版本下的文件，可能随版本迭代存在多份。
- 图片与截图：正文内嵌或粘贴产生的图片，部分系统将其作为独立附件存储，部分作为富文本资源。
- 外链文件：以链接形式引用的外部网盘或共享目录文件，本体不在源系统内。
范围边界要写成明确的纳入与排除项。纳入本次迁移的通常是仍在使用、与在办项目相关、有业务追溯价值的附件；历史项目归档件、重复上传的临时文件、明确失效的外链可以留在源系统归档，但要在清单中标注“排除”及理由，便于日后追溯。附件迁移与流程、插件行为的迁移属于两条线：工作流状态、自动化规则、插件配置的迁移不改变附件的归属逻辑，但插件生成的附件（如构建产物、报告导出）需要单独确认是否纳入，避免被默认规则漏掉。
本阶段的交付物是一份附件迁移范围清单，至少包含四列：源系统与版本、目标系统与版本、附件类别、纳入或排除及理由。这份清单是后续盘点表的上级文档，范围调整时同步更新。
迁移前需要准备什么：盘点表、权限与存储依赖
盘点要在正式搬运前完成，产出一张能逐行核对的附件盘点表。建议字段如下：
| 字段 | 说明 | 用途 |
|---|---|---|
| 源附件ID | 源系统中的唯一标识 | 全程追溯的主键 |
| 所属实体 | 工作项、评论、文档页面等，附父对象ID | 确定挂载位置 |
| 文件名 | 原始文件名，含扩展名 | 同名冲突识别 |
| 大小 | 字节数 | 容量核算与完整性比对 |
| 类型 | 扩展名或MIME类型 | 可打开性核验 |
| 创建人 | 上传者账号 | 元数据保留核对 |
| 创建时间 | 上传时间戳 | 批次切分依据 |
| 存储路径或URL | 实际存放位置 | 搬运取数 |
| 链接状态 | 正常、外链、已失效 | 边界情况单独处理 |
权限方面要提前确认两件事：源系统的导出权限是否覆盖全部附件类别，部分系统对评论附件或历史版本附件的导出有单独开关；目标系统的写入权限是否包含附件上传、关联挂载和元数据写入，仅有工作项创建权限往往不足以完成附件回写。权限缺口在盘点阶段暴露，比在执行阶段中断要划算得多。
存储依赖同样需要核对：目标端可用容量应大于盘点总大小并留出余量，单文件大小限制要与源系统中最大的附件比对，超限文件需要提前规划拆分、压缩或单独归档。外链附件和已失效链接在盘点表中单独标记，外链记录原URL和可访问状态，失效链接标注失效时间，这两类不进入常规搬运流程，而是作为独立清单交由业务方确认处理方式。
附件与工作项的映射方法：建立可追溯的对应关系
映射的顺序是先实体、后附件。工作项、评论、文档页面这些父对象先在目标系统落地并拿到目标ID，附件才有可挂载的位置。如果先搬文件再补关联，一旦父对象创建失败，附件就成了无归属的孤立文件，后续只能靠文件名猜测归属，追溯成本很高。
附件映射表建议包含以下字段：源附件ID、源父对象ID、目标父对象ID、目标附件ID、迁移状态、备注。填写规则上，源附件ID与源父对象ID从盘点表带入，目标父对象ID在父对象迁移完成后回填，目标附件ID在文件上传成功后回填，迁移状态用固定枚举值（待迁移、成功、失败、跳过），备注记录失败原因或跳过理由。这张表是执行与核验共用的主表，任何一方修改都要留痕。
同名文件和多版本附件是映射中最容易混淆的部分。同名文件的区分依靠源附件ID，映射表中不以文件名作为匹配依据；多版本附件（如同一文档的多个历史版本）用“源附件ID+版本号”组合标识，并在备注中记录版本顺序，确保目标端挂载后版本关系可还原。映射失败时不要直接删除记录，而是将状态置为失败并写入重试标记，重试成功后更新状态并保留原失败记录，形成完整的处理轨迹。
在ONES的迁移方案中，Jira的问题数据迁移覆盖属性和属性值、附件、评论等信息，Confluence迁移则覆盖页面正文、附件、图片、常用宏及批注，附件与父对象的关联随迁移一并处理。实际项目中，附件挂载到哪个工作项或文档页面、元数据保留到什么程度，仍需在实施前按上述映射表逐项确认。
分批迁移与关联回写的执行步骤
执行阶段的核心原则是把文件搬运与关联回写分成两个动作，按批次推进。批次可以按项目切分，也可以按创建时间切分，前者便于业务方按项目验收，后者便于控制单批数据量。无论哪种切法，第一批都应是规模小、代表性强的试迁批次，用来验证盘点口径、映射规则和目标端限制是否成立。
- 选定试迁批次，通常取一个项目或一周内的附件，数量控制在便于人工抽检的范围内。
- 搬运文件本体：按盘点表的存储路径或URL取数，上传至目标端对应位置，记录目标附件ID。此阶段只处理文件，不建立关联。
- 回写关联关系：依据映射表，把已上传的附件挂载到对应的目标工作项、评论或文档页面下，更新迁移状态。
- 试迁批次核验通过后，按批次放大执行，每批完成后立即对账，不积压到全部结束再查。
- 失败项记录到批次记录表，标注失败环节（取数、上传、挂载），修复后断点续迁，从失败项继续而非整批重来。
先迁文件再回写关联的原因在于两类操作的失败模式不同：文件搬运失败多与网络、容量、格式有关，重试成本低；关联回写失败多与父对象缺失、ID错配有关，需要人工判断。分开处理后，失败定位更准确，也不会因为一次挂载失败而重复上传大文件。
迁移窗口内源系统仍可能有新增附件，这部分要单独标记为增量批次，按固定节奏（如每日一次）收集并纳入下一批处理，不与存量批次混在一起。增量附件的盘点字段与存量一致，映射表沿用同一结构，批次记录表中注明“增量”及收集时间，便于核验时区分口径。
附件保留的核验证据：数量、可打开性与关联正确性
核验不能只看迁移工具给出的完成提示，而要用三类可逐项判断的证据说明附件确实保留下来了。
数量核验采用对账口径：源盘点数、迁移成功数、失败数、跳过数四项相加应等于盘点总数，任何一项对不上都要定位到具体记录。对账以映射表为准，按批次汇总，增量批次单独对账后并入总数。
可打开性抽检按文件类型分层抽样，覆盖文档、表格、图片、压缩包等主要类别，每类抽取一定比例。检查项包括：能否下载、能否在线预览、打开后内容是否完整、文件大小与盘点记录是否一致、类型是否被错误转换。抽检发现的问题按类型归类，判断是单文件损坏还是某类文件的系统性转换问题。
关联正确性抽检从目标端反向检查：随机选取目标工作项和评论，确认其下挂载的附件与映射表中记录一致；再随机选取映射表中的附件，确认其挂载位置正确。双向抽检能发现单向检查遗漏的错挂和漏挂。核验结果记入附件迁移核验表，差异项汇总为差异清单，逐条标注处理状态（已修复、待确认、接受差异），差异清单与核验表一并留存，作为迁移验收的依据。
回退与停止条件：什么情况下暂停附件迁移
回退以批次为单位，而不是整体推倒重来。触发暂停的条件应在执行前写定，常见的有三类：单批失败率超过约定阈值，说明盘点或映射规则存在系统性问题；关联错挂被抽检发现且无法定位原因，继续推进只会扩大错误范围；目标端存储容量接近上限，后续批次无法安全写入。阈值具体取多少由项目组根据数据规模和风险偏好确定，写进回退触发条件表。
回退操作的范围限于当前批次：清理本批次已上传但未通过核验的附件及其关联记录，保留已通过核验的前序批次不动。清理时以映射表中的目标附件ID为依据逐条删除，避免误删其他批次数据。源系统在回退期间保持原数据完整，建议设为只读或暂停写入，防止回退过程中源端数据变化导致盘点表失效。
恢复迁移前需要补齐检查项：失败原因是否已定位并修正映射规则、目标端容量是否已扩容、增量附件是否已收集完毕、上一批次的差异清单是否已处理完毕。检查项逐条确认后再启动下一批，并在批次记录表中注明恢复时间和依据。ONES的迁移方案建议把迁移工具、原厂服务和分阶段切换结合起来，在正式迁移前确认数据范围、功能匹配和系统适配，这一思路同样适用于附件迁移的暂停与恢复决策。
常见问题
迁移窗口内源系统还在新增附件，怎么保证不漏迁？
把迁移窗口内的新增附件单独标记为增量批次，按固定节奏（例如每日一次）收集，盘点字段与存量批次保持一致，映射表沿用同一结构，批次记录表中注明“增量”及收集时间。核验时增量批次单独对账后再并入总数，避免与存量口径混在一起。迁移收尾阶段需要确认源系统已停止写入，再做最后一次增量收集，否则窗口末尾的附件容易遗漏。
同名文件和多版本附件在映射时怎么区分？
映射表不以文件名作为匹配依据，同名文件依靠源附件ID区分。多版本附件（如同一文档的多个历史版本）用“源附件ID+版本号”组合标识，并在备注中记录版本顺序，确保目标端挂载后版本关系可还原。映射失败时保留原记录，将状态置为失败并写入重试标记，重试成功后更新状态，形成完整的处理轨迹。
附件迁移失败后是整批重来还是从失败项继续？
从失败项继续。执行阶段把文件搬运与关联回写分成两个动作，失败项记录到批次记录表并标注失败环节（取数、上传、挂载），修复后断点续迁。文件搬运失败多与网络、容量、格式有关，重试成本低；关联回写失败多与父对象缺失、ID错配有关，需要人工判断。分开处理后失败定位更准确，也不会因为一次挂载失败而重复上传大文件。
外链附件和已失效链接要不要迁？
这两类不进入常规搬运流程。外链附件的本体不在源系统内，盘点时记录原URL和可访问状态；已失效链接标注失效时间。两类在盘点表中单独标记，作为独立清单交由业务方确认处理方式，可以纳入迁移、替换为新链接或留在源系统归档，处理结论写回清单便于追溯。
ONES 的迁移方案对附件保留提供了哪些支持？
按官方资料描述，ONES 的 Jira 迁移方案围绕项目、工作项、状态、字段、流程、附件和历史记录进行迁移，迁移问题数据时覆盖属性和属性值、附件、评论等信息；Confluence 迁移支持页面正文、附件、图片、常用宏及批注，并提供批量迁移与数据包导入两种方式。附件大小上限、单批次数量上限、关联回写方式与增量同步机制等细节，资料未提及，需要在实施前向实施方逐项确认。
核验时抽检比例怎么定，抽多少才算够？
抽检比例没有统一标准，取决于数据规模与风险偏好。可打开性抽检按文件类型分层，覆盖文档、表格、图片、压缩包等主要类别，每类抽取一定比例，试迁批次建议全量或高比例抽检，放大执行后可适当降低。关联正确性采用双向抽检：从目标端随机选工作项和评论反查附件，再从映射表随机选附件正查挂载位置。抽检发现的问题按类型归类，判断是单文件损坏还是某类文件的系统性转换问题，后者需要暂停并修正规则。
