迁移附件保留的关键，是把附件当作独立数据对象来管理：先盘点来源系统中附件的存放位置、命名规则、版本与权限，再建立“业务对象—附件—目标存放位置”的映射关系，通过小批量试迁移验证文件完整性、可打开性与关联关系，最后按批次切换并保留回退点。本文按盘点、映射、试迁移、核验与回退的顺序，给出一套可执行的方法和配套表格。
要点总览（TL;DR）
- 附件保留要按独立数据对象管理：先盘点业务对象详情附件、富文本内嵌图片、文档附件和评论附件，再建立“业务对象—附件—目标位置”映射。
- 映射表至少包含来源对象ID、来源附件ID、文件名、哈希或大小、目标对象ID、目标附件ID和映射状态，用哈希区分同名文件，并事先约定多版本附件保留规则。
- 试迁移抽样覆盖不同对象类型、文件类型、大文件、同名文件、多版本附件和内嵌图片，按导出—传输—导入—关联—记录五步执行，未达标不进入全量迁移。
- 核验用数量比对、哈希或大小抽样、目标系统打开预览下载、从业务对象详情确认挂载四种方式，并留存核验记录与差异清单。
- 预设停止与回退条件，例如缺失比例超阈值、大范围文件损坏、关联错乱无法修复；回退时保留来源系统只读状态、导出包和映射表，按批次回滚。
附件迁移要保留什么：来源、目标与范围界定
附件迁移的第一步是界定范围。研发系统里的“附件”往往分散在多个位置，如果只按业务对象详情页的附件列表导出，容易漏掉正文中的图片和评论里的文件。建议按来源位置逐项盘点，形成一份可核对的清单。
来源位置盘点
- 业务对象详情内的附件：需求、缺陷、任务等工作项详情页中上传的文件。
- 富文本内嵌图片：描述、评论、文档正文中以图片形式嵌入的内容，这类内容通常不显示在附件列表中。
- 文档附件：知识库页面、文档空间中挂载的文件。
- 评论附件：讨论记录中随评论上传的文件。
目标侧需要保留的要素
判断附件是否“保留成功”，不能只看文件是否到了目标系统，还要看以下要素是否完整：文件本体、文件名、文件类型、文件大小、上传时间、上传人，以及与业务对象的关联关系。其中关联关系最容易出问题，也最影响后续使用——文件在，但挂错了需求或缺陷，等于没有保留。
范围边界与清单圈定
本文聚焦迁移数据内容中的附件保留。工作流配置、插件行为的迁移属于相邻主题，迁移后的整体切换管理与上线决策也另行处理，本文只在回退环节提及必要的衔接动作。圈定迁移清单时，建议按“业务对象类型 × 项目范围”两个维度交叉确定，例如“A项目的需求与缺陷附件”“知识库B空间的页面附件”，并标注每个范围对应的来源位置和目标位置。
| 来源位置 | 对象类型 | 目标位置 | 需保留要素 |
|---|---|---|---|
| 工作项详情附件 | 需求、缺陷、任务 | 目标工作项附件区 | 文件本体、名称、类型、大小、上传时间、上传人、关联对象 |
| 富文本内嵌图片 | 描述、评论正文 | 目标正文对应位置 | 图片本体、显示位置、关联对象 |
| 文档附件 | 知识库页面 | 目标页面附件区 | 文件本体、名称、类型、大小、上传人、所属页面 |
| 评论附件 | 讨论记录 | 目标评论附件区 | 文件本体、名称、上传时间、所属评论与对象 |
迁移前的输入与依赖准备
附件迁移中途返工，多数源于前置条件没有确认。开工前应把下列输入逐项落实，形成核对表并由责任人签字确认。
- 来源附件清单与导出方式：确认来源系统能导出附件列表及文件本体，明确导出是整包还是按对象分批，记录导出时间点，作为后续数量核验的基准。
- 目标系统限制：确认目标环境的附件容量、单文件大小上限、允许的文件类型。这些参数直接影响大文件和特殊格式文件的处理方式，需要在实施前向原厂或实际环境确认，不能凭经验假设。
- 关联关系数据：导出附件与业务对象的关联字段，至少包含对象ID、附件ID和关联字段，这是建立映射表的原始依据。
- 账号映射表：整理上传人、附件可见范围涉及的人员在来源与目标系统之间的对应关系。人员映射缺失会导致上传人信息丢失或权限错配。
- 存储与网络条件：估算导出包总大小，确定传输方式（专线、跳板机、数据包导入等）和迁移窗口，避免在业务高峰执行大批量传输。
这些输入之间存在依赖：附件清单决定导出包规模，导出包规模决定传输方式和窗口，目标限制决定是否需要提前拆分大文件。建议按依赖顺序逐项确认，任何一项未落实都不进入试迁移。
附件与业务对象的映射方法
映射是附件保留的核心环节。做法是建立一张附件映射表，把每个来源附件与目标对象、目标附件逐一对应，并在迁移过程中持续更新状态。
映射表字段设计
| 字段 | 用途 |
|---|---|
| 来源对象ID | 定位附件所属的需求、缺陷或页面 |
| 来源附件ID | 附件的唯一标识，用于去重和回溯 |
| 文件名 | 展示名称，同名文件需结合其他字段区分 |
| 文件哈希或大小 | 判断内容是否一致，区分同名不同内容的文件 |
| 目标对象ID | 附件在目标系统中应挂载的业务对象 |
| 目标附件ID | 导入后回填，用于核验 |
| 映射状态 | 待映射、已映射、待核验、已核验、异常 |
同名文件与多版本处理
同名文件在研发系统中很常见，例如多个缺陷都上传了“日志.txt”。区分时优先使用文件哈希，哈希相同可视为同一内容；哈希不同则结合上传时间、上传人和文件大小判断，并在映射表中保留判断依据。多版本附件需要事先定规则：保留全部版本，或只保留最新版。选择保留全部版本时，要确认目标系统支持同一对象挂载多个同名文件；选择只保留最新版时，应在映射表中记录被舍弃的版本及取舍理由，便于事后追溯。
富文本内嵌图片与关联校验
内嵌图片有两种处理方式：随正文一起迁移，由迁移工具重写图片引用；或单独提取为附件后在正文中重新插入。前者对工具能力依赖较高，后者可控性强但工作量大，建议在试迁移阶段对比两种方式的实际效果再决定。映射完成后必须做关联校验：逐条确认每个附件都能从正确的业务对象详情进入并看到，没有挂到错误对象或成为孤立附件。
试迁移：小批量验证附件完整性
试迁移的目的是在正式迁移前暴露问题。抽样不能只挑小文件，应覆盖可能出问题的类型。
抽样原则
- 覆盖不同业务对象类型：需求、缺陷、任务、知识库页面各取若干。
- 覆盖不同文件类型：文档、表格、图片、压缩包、日志文本等。
- 包含大文件：接近目标系统单文件大小上限的文件必须纳入样本。
- 包含同名文件和多版本附件：验证区分规则和取舍规则是否可执行。
- 包含富文本内嵌图片和评论附件：验证非附件列表位置的迁移效果。
执行步骤与检查项
试迁移按“导出—传输—导入—关联—记录结果”五步执行，每一步完成后记录时间和操作人。检查项包括：文件数量是否与来源一致；文件能否在目标系统中正常打开、预览、下载；文件名、类型、大小是否保持；附件是否挂在正确的业务对象上。试迁移结果应记入表格，问题按“文件缺失、文件损坏、名称或类型异常、关联错误、权限异常”分类，并标注处理状态。
| 样本编号 | 对象类型 | 文件类型 | 检查项结果 | 问题分类 | 处理状态 |
|---|---|---|---|---|---|
| 示例-01 | 需求 | 大文件压缩包 | 可下载，大小一致 | 无 | 已通过 |
| 示例-02 | 缺陷 | 同名日志文本 | 两份文件均挂载正确 | 无 | 已通过 |
| 示例-03 | 知识库页面 | 内嵌图片 | 正文图片显示正常 | 无 | 已通过 |
试迁移通过的标准应事先约定，例如样本附件全部可打开、关联全部正确、无未分类异常。未达标时先修正映射规则或导出方式，再重新抽样，不带着已知问题进入全量迁移。
核验与证据留存
核验要回答一个问题：附件保留是否达到约定标准。判断依据应可复核，结论应可追溯。
- 数量核验：以导出时间点的来源附件总数为基准，与目标附件总数比对，差异逐条说明原因。
- 内容核验：按哈希或文件大小抽样比对，确认文件未被截断、替换或压缩失真。大文件应优先纳入抽样。
- 可用性核验：随机抽取附件在目标系统中打开、预览、下载，确认文件可正常使用。
- 关联核验：从业务对象详情进入，确认附件挂载正确，重点检查同名文件和多版本附件。
- 证据留存：保存核验记录、差异清单、处理结论和责任人，与映射表一并归档。
核验记录建议包含核验批次、核验时间、样本范围、核验方法、结果和遗留问题。差异清单中的每一条都应有明确结论：已修复、接受差异或待处理，避免出现无人认领的差异项。
回退与停止条件
附件迁移需要预设停止和回退的判断依据，避免问题扩大后再被动处理。
停止条件
- 附件缺失比例超出预设阈值，例如某批次缺失率高于试迁移阶段约定的上限。
- 出现大范围文件损坏，抽样中多个文件无法打开或内容异常。
- 关联关系错乱且无法通过映射表修复，例如大量附件挂到错误对象。
回退方式与后续动作
回退的前提是保留可恢复的现场：来源系统附件保持只读状态，导出包与映射表完整保存，按批次执行回滚，避免全量重来。回退后应复核回滚是否彻底，确认目标系统中不残留半迁移的附件和错误关联，再针对触发回退的原因修正映射规则或导出方式，重新走试迁移。切换完成后的观察期内，继续跟踪遗留问题，按责任人闭环。
在附件随工作项和文档管理的场景中，ONES 的迁移方案覆盖了 Jira 工作项数据中的附件、评论等信息，以及 Confluence 页面正文、附件、图片、常用宏和批注的迁移，并支持批量迁移与数据包导入两种方式。附件与业务对象的关联、同名文件与多版本处理的具体规则，以及容量和文件类型限制，需要在实施前结合实际方案确认；把上述映射表、试迁移记录和核验清单作为迁移方案的配套交付物，可以让附件保留的每个环节都有据可查。
常见问题
附件迁移时，富文本内嵌图片应该随正文迁移还是单独提取为附件？
两种方式各有适用条件。随正文迁移由迁移工具重写图片引用，工作量小，但对工具能力依赖较高，需要确认目标系统能正确解析原正文中的图片引用格式。单独提取为附件再重新插入，可控性强，适合图片数量不多或工具处理效果不稳定的情况，但人工工作量明显增加。建议在试迁移阶段各取若干样本对比实际效果，再确定统一规则；同一批迁移内尽量保持一致，避免后续核验口径混乱。
目标系统对单文件大小和文件类型有限制时，大附件怎么处理？
先在迁移前向原厂或实际环境确认容量、单文件大小上限和允许的文件类型，再据此决定处理方式。接近上限的文件应在试迁移中优先抽样，确认能否正常导入和下载。超出上限的文件通常需要拆分、压缩或单独走数据包导入通道，具体做法取决于目标系统的实际限制。处理方式确定后要写入映射表备注，核验时按同一口径检查，避免正式迁移时才发现大文件无法导入。
同名文件和多版本附件在核验阶段怎么判断保留是否正确？
核验时不能只看文件名。同名文件应结合文件哈希或大小比对内容，确认目标侧挂载的是对应来源文件，而不是另一份同名文件。多版本附件按迁移前约定的规则判断：保留全部版本的，核验同一业务对象下各版本是否齐全且顺序可辨；只保留最新版的，核验保留的是否为约定版本，并核对映射表中记录的舍弃版本与理由。关联核验要从业务对象详情进入，确认附件挂载在正确对象上。
试迁移通过后，全量迁移还需要保留回退点吗？
需要。试迁移通过只说明抽样范围内的方法可行，全量迁移的数据量和批次更多，仍可能出现试迁移未覆盖的异常。建议按批次切换，每批完成后保留来源系统附件只读状态、导出包和映射表，确认该批次核验通过后再进入下一批。出现缺失比例超出预设阈值、大范围文件损坏或关联错乱无法修复时，按批次回滚，复核目标系统不残留半迁移附件，修正原因后重新走试迁移。
附件上传人和可见范围在迁移中容易丢失，应该怎么准备？
上传人和可见范围依赖人员映射，属于迁移前的输入准备。开工前整理账号映射表，覆盖上传人以及附件可见范围涉及的人员在来源与目标系统之间的对应关系，并确认目标系统中这些账号已存在且状态正常。映射缺失会导致上传人信息丢失或权限错配，核验时应把上传人字段和可见范围纳入检查项。人员变动较多的项目，建议在正式迁移前刷新一次映射表，避免使用过期对应关系。
