Jira 附件迁移的关键，是把文件本体和文件与工作项的关联关系分开处理：文件本体关注内容、大小和校验值，关联关系关注附件挂在哪个工作项、由谁在何时上传。本文按范围界定、输入准备、映射建立、分批试迁、核验取证、回退与停止六个阶段展开，迁移方向固定为从 Jira 到目标系统，不承诺零损或一键完成。
要点总览（TL;DR）
- 先划定迁移范围：确认 Jira 附件存储方式、目标承载对象（工作项附件、文档库或文件服务），并按项目、时间、大小、类型明确纳入与排除项。
- 以单个附件为一行建立映射表，记录原附件ID、原工作项Key、目标对象ID、新文件地址和校验值，同名文件与目标对象缺失要有专门规则。
- 先取单项目或近三个月附件做小样本试迁移，验证映射字段、打开下载和内嵌图片改写，再按项目或时间分批推进。
- 核验分三层：数量对账、大小与哈希比对、按类型抽样打开；核验报告与差异清单需业务和技术双方签字。
- 回退点设在试迁移通过后、全量前和切换前，停止条件提前量化，切换后源系统保留只读期并写入运维文档。
迁移范围：哪些附件要迁、迁到哪里
附件迁移的第一步是划定边界。Jira 实例里的文件数量往往远超业务需要，如果把所有文件都当作迁移对象，工作量会失控，核验也难以收敛。范围清单要同时写清三件事：从哪来、迁到哪、哪些不迁。
来源侧需要确认 Jira 的附件存储方式。常见形态包括本地目录挂载、对象存储以及由插件托管的附件。存储方式决定了取文件的手段：本地目录可以直接按目录结构批量读取，对象存储需要通过接口或同步工具拉取，插件托管的附件则要先确认插件是否提供导出入口。三种方式的盘点口径不同，范围清单里应注明每个 Jira 项目对应的存储形态。
目标侧要先确定附件的承载对象。常见选择有三类：挂到目标系统的工作项附件区，放入文档库作为独立文档，或存入独立的文件服务再通过链接引用。承载对象不同，映射表的目标字段和核验方式也不同。工作项附件便于跟随工作项一起查看和下载，文档库适合沉淀评审材料、设计稿等需要单独检索的文件，独立文件服务适合大容量或需要外部系统读取的场景。
纳入与排除范围建议按四个维度划分：项目、时间区间、附件大小、文件类型。例如纳入三个核心研发项目近两年的附件，排除单文件超过目标系统上限的文件，排除日志压缩包等临时产物。每个维度都要写明具体取值，避免执行阶段反复确认。
还要区分业务附件与非业务附件。评论中的截图、描述里的内嵌图片通常属于业务附件，需要随正文一起迁移并处理引用关系；用户头像、系统图标、邮件通知模板中的图片属于非业务附件，一般排除在迁移范围之外。内嵌图片如果被排除，正文中的图片链接会失效，因此这类文件要么纳入迁移，要么在正文中做占位说明。
| 范围项 | 需要记录的内容 | 示例口径 |
|---|---|---|
| 纳入项目 | 项目 Key 列表 | 三个核心研发项目 |
| 时间区间 | 附件创建时间起止 | 近两年内上传的附件 |
| 大小限制 | 单文件上限与总量 | 按目标系统上限设定 |
| 文件类型 | 纳入与排除的扩展名 | 排除临时日志压缩包 |
| 目标承载对象 | 工作项附件、文档库或文件服务 | 按文件用途分类承载 |
| 明确排除项 | 头像、系统图标等 | 非业务附件不迁 |
范围清单完成后，应给出纳入附件的总数量与总容量估算。这两个数字是后续分批计划和停止阈值的基数，估算偏差过大会让批次容量失去参考意义。
迁移前要准备哪些输入与依赖
范围确定后，进入输入准备阶段。这一阶段的目标是把执行时需要的权限、配额和基础数据提前拿到，减少中途因缺少条件而返工。建议用一张输入依赖清单逐项登记，每项标注责任人、获取方式和到位状态。
Jira 侧需要两类权限：数据导出权限和附件目录访问权限。导出权限用于获取工作项、评论、用户等结构化数据，附件目录访问权限用于直接读取文件本体。部分企业将附件存放在独立存储上，还需要存储管理方开通读取账号。权限申请通常有审批周期，应放在计划的前置环节。
目标系统侧需要确认三项限制：单个附件大小上限、允许的文件类型、存储配额。大小上限直接决定哪些文件需要排除或拆分，文件类型限制可能影响可执行文件、压缩包的迁移，存储配额则决定全量迁移是否可行。这些参数没有统一标准，应在实施前向目标系统的管理方确认，并写入输入清单。
字段与对象映射需要的基础数据包括：项目清单及对应关系、用户账号对照表、工作项编号规则。用户对照表尤其重要，附件的创建人信息要随附件一起保留，如果目标系统账号与 Jira 账号无法一一对应，需要提前确定映射规则或占位账号。
时间估算要基于网络带宽和附件总量。可以先用一个小批次实测传输速率，再推算全量迁移所需时间，并预留失败重试和人工处理的余量。迁移窗口应避开业务高峰，同时确认源系统在窗口期内可以维持只读或限制写入。
- Jira 导出权限与附件目录读取账号，标注审批人和预计到位时间
- 目标系统附件大小上限、允许类型、存储配额，标注确认来源
- 项目对照表、用户账号对照表、工作项编号规则
- 实测传输速率与全量时间估算，含重试余量
- 迁移窗口与源系统只读安排
附件与工作项的映射方法
映射表是整个迁移过程的核心记录。它既描述每个附件应该去哪里，也承担失败重试和对账的依据。建议以单个附件为一行，字段至少覆盖下表内容。
| 字段 | 用途 |
|---|---|
| 原附件ID | Jira 侧唯一标识，用于回溯 |
| 原工作项Key | 附件所属工作项 |
| 文件名 | 原始文件名，含扩展名 |
| 大小 | 字节数，用于完整性比对 |
| MIME类型 | 判断文件类别与打开方式 |
| 创建人 | 上传者账号 |
| 创建时间 | 上传时间 |
| 目标对象ID | 目标系统工作项或文档的标识 |
| 新文件地址 | 迁移后的存储位置或访问地址 |
| 校验值 | 哈希值，用于内容比对 |
| 状态 | 待迁、成功、失败、排除、挂起 |
同名文件与重复附件需要专门规则。同一工作项下可能存在多个同名文件，Jira 通常以内部 ID 区分，目标系统若按文件名存储会发生覆盖。处理方式是在目标文件名中加入原附件ID后缀或序号，映射表中保留原始文件名，确保展示名称与存储名称可以对应。跨工作项的重复附件如果内容哈希一致，可以选择只存一份并在多处引用，也可以各自独立存储，选择依据是目标系统是否支持文件引用。
附件归属对象在目标侧不存在时，有三种处理方式：挂起等待目标对象创建后补迁、挂到预先建立的占位对象、直接排除并记录原因。挂起适合目标对象稍后会同步生成的场景，占位对象适合需要保留附件可见性的场景，排除适合附件本身价值不高的场景。无论选哪种，都要在映射表状态字段中体现，并在核验时单独统计。
内嵌图片与正文引用的链接改写是容易被忽略的环节。Jira 描述和评论中的图片通常以内部地址引用，迁移后这些地址失效，需要替换为目标系统的新文件地址。改写规则应在映射表中记录原引用地址与新地址的对应关系，改写完成后抽样打开正文确认图片正常显示。
如果目标系统选择 ONES，附件可以随工作项一起承载。ONES 的 Jira 迁移方案覆盖项目、工作项、状态、字段、流程、附件和历史记录，问题数据迁移包括属性和属性值、附件、评论等信息，附件与工作项的关联可以在迁移过程中一并保留。具体到附件大小上限、存储配额和校验机制，需要在实施前与迁移服务方确认，再据此设定批次容量和核验方式。
分批试迁移与执行步骤
全量迁移之前先做小样本试迁移。样本建议选单个项目或近三个月的附件，规模控制在可以在半天内完成并核验的程度。试迁移要验证三件事：映射表字段是否够用、附件能否在目标工作项中正常打开和下载、内嵌图片链接改写是否生效。样本通过后再扩大批次。
分批方式按项目或时间区间切分，每批容量以实测传输速率和窗口时长倒推。单批过大时失败重试成本高，单批过小时批次管理开销大，一般以单批可在迁移窗口内完成并留出核验时间为宜。每批执行前锁定该批的映射表快照，执行后按快照对账。
- 导出该批附件清单，生成映射表初始行，状态置为待迁。
- 按映射表逐条上传或导入附件，成功后回填新文件地址与校验值。
- 对失败条目记录错误码与原因，进入重试队列。
- 重试达到设定次数仍失败的条目转人工处理，登记补迁方式。
- 该批完成后执行数量对账，确认成功数、失败数、排除数与源清单一致。
迁移期间对源系统施加只读约束，避免用户在迁移过程中新增或修改附件导致清单漂移。如果业务无法完全停止写入，应记录迁移开始时间点，对该时间点之后的新增附件单独建批处理。并发控制方面，同一工作项的附件应串行处理，避免目标侧出现重复记录；不同批次之间可以并行，但要控制总并发数不超过目标系统的接口或存储承载能力。
失败处理记录建议包含：原附件ID、失败阶段、错误信息、重试次数、处理人、最终状态。这份记录既是补迁依据，也是后续分析迁移质量的输入。
核验与证据：怎么确认附件真的迁对了
核验分三层，逐层收紧。第一层是数量对账，确认没有遗漏和重复；第二层是完整性比对，确认文件内容一致；第三层是可用性抽查，确认文件在目标系统中能正常打开和下载。
数量对账以映射表为准，核对源附件数、成功数、失败数、排除数四项之和是否等于源清单总数。差异清单要逐条说明原因，挂起和占位对象处理的附件单独列出。完整性比对使用文件大小和哈希值，大小一致是基本条件，哈希一致才能确认内容未变。哈希比对发现集中不一致时，应暂停该批并排查传输环节，而不是逐条重试。
可用性抽查按文件类型分层抽样，覆盖文档、表格、图片、压缩包等类别，每种类型抽取一定数量，在目标工作项中实际打开并下载一次。内嵌图片要回到正文中确认显示正常。抽查比例和样本量写入核验方案，避免验收时口径不一。
| 核验层 | 核验内容 | 通过标准 |
|---|---|---|
| 数量对账 | 源附件数、成功数、失败数、排除数 | 四项之和与源清单一致，差异有说明 |
| 完整性比对 | 文件大小与哈希值 | 逐条一致，不一致条目已处理 |
| 可用性抽查 | 打开、下载、正文展示 | 抽样全部正常，内嵌图片显示正确 |
证据留存包括核验报告、差异清单和签字确认。核验报告应记录核验时间、核验人、样本范围、比对结果和遗留问题。差异清单作为报告附件，逐条标注处理结论。签字确认由业务方和技术方共同完成，作为切换的前置条件。
回退点与停止条件
回退点设在三个位置：试迁移通过后、全量迁移开始前、正式切换前。每个回退点都要确认源附件保持完整可读、目标侧已迁数据可以识别和清理、回退操作有明确责任人。试迁移通过后的回退点用于确认方法可行，全量前的回退点用于确认容量和配额充足，切换前的回退点用于确认业务方接受迁移结果。
停止条件需要提前量化。常见触发条件包括：单批失败率超过设定阈值、哈希不一致条目集中出现、目标存储配额接近上限、目标系统接口持续报错。阈值没有通用标准，应结合批次规模和业务容忍度设定，例如单批失败率超过百分之五即暂停该批并排查。阈值表要与范围清单中的总量估算对应，避免阈值形同虚设。
- 失败率超阈值：暂停当前批，排查后决定重试或回退
- 哈希集中不一致：暂停全量，检查传输与存储环节
- 配额不足：暂停后续批次，确认扩容或调整范围
- 接口持续异常：停止并发，降低速率后重试
回退操作的核心是保留源附件只读、清理目标侧已迁数据。源系统在切换后应保留一段只读期，保留期长度根据业务确认和合规要求确定，期间源附件可查可下载但不可修改。目标侧清理要按映射表逐条执行，先删文件再删关联记录，清理完成后重新对账，确认目标侧无残留。
切换完成后，源系统的保留策略要写入运维文档：保留多久、谁有权访问、到期后如何处理。附件迁移的完成标志不是文件传完，而是核验报告签字、回退窗口关闭、源系统进入约定的只读或归档状态。
常见问题
Jira 附件存放在对象存储或由插件托管，迁移取文件的方式有什么不同？
本地目录挂载可以直接按目录结构批量读取；对象存储需要通过接口或同步工具拉取；插件托管的附件要先确认插件是否提供导出入口。三种形态的盘点口径不同，范围清单里应注明每个 Jira 项目对应的存储形态，并据此确定取文件的手段和所需权限。
附件在目标系统中找不到对应工作项时，应该挂起还是直接排除？
三种处理方式各有适用场景：挂起适合目标对象稍后会同步生成的场景；挂到预先建立的占位对象适合需要保留附件可见性的场景；直接排除适合附件本身价值不高的场景。无论选哪种，都要在映射表状态字段中体现，并在核验时单独统计，避免差异清单说不清原因。
内嵌在描述和评论里的图片，迁移后正文显示不出来怎么办？
Jira 描述和评论中的图片通常以内部地址引用，迁移后这些地址会失效。处理方式是在映射表中记录原引用地址与新文件地址的对应关系，按规则批量改写正文链接，改写完成后抽样打开正文确认图片正常显示。如果内嵌图片被排除在迁移范围之外，正文中的图片位置需要做占位说明。
迁移过程中业务还在新增附件，清单对不上怎么处理？
迁移期间尽量对源系统施加只读约束。如果业务无法完全停止写入，应记录迁移开始时间点，对该时间点之后新增的附件单独建批处理，并在对账时把新增批次与原有批次分开统计。同一工作项的附件建议串行处理，避免目标侧出现重复记录。
选择 ONES 承接迁移后的工作项和附件，迁移范围覆盖哪些内容？
ONES 的 Jira 迁移方案围绕项目、工作项、状态、字段、流程、附件和历史记录进行迁移，问题数据迁移包括属性和属性值、附件、评论等信息，附件与工作项的关联可以在迁移过程中一并保留。附件大小上限、存储配额和校验机制等具体参数，需要在实施前与迁移服务方确认，再据此设定批次容量和核验方式。
