Jira 附件迁移要先把附件当作有归属的数据来管理，再按“范围界定—前置输入—映射—试迁移—核验—切换回退”六步推进。每一步都产出可核对的表格或记录，用试迁移结果决定批次和取舍，并保留源端只读窗口作为回退点。整个过程以证据验收，不承诺零丢失或一键完成。
要点总览（TL;DR）
- 先写清迁移边界：源端 Jira 实例、目标替代系统、纳入的问题附件与评论内联附件、排除的头像和图标，首批按项目、时间、大小、类型收窄。
- 动手前备齐四类输入：冻结版本的附件清单、目标端单文件与批量限制、账号与权限映射关系、导出与传输条件，缺失项写明卡在哪一步。
- 映射以问题键为主关联键，建立源问题键到目标工作项 ID 的对照表，再定文件名冲突规则、附件归属位置和受限附件的可见范围。
- 用覆盖大文件、特殊字符文件名、受限权限附件、评论内联附件的样本试迁移，按结果调整批次；核验以数量、大小、可用性、归属与权限四类证据为准。
- 切换前设定失败率、关键附件缺失、权限错配等停止阈值，保留源端只读窗口作为回退点，回退以批次为单位。
迁移范围：哪些附件要迁、迁到哪里
附件迁移的第一步是写清迁移边界。源端是正在使用的 Jira 实例及其附件存储，目标端是已经选定的替代系统或新建实例，迁移方向固定为 Jira 到目标，不假设目标端数据会反向回流。范围界定表要把这些内容逐项写下来，作为后续盘点和验收的共同依据。
附件对象范围需要逐类确认。问题附件是主体；评论中的内联附件要单独确认是否随评论一起迁移；头像、项目图标、仪表盘配图这类装饰性文件通常可以排除，但要在表里写明排除理由，避免验收时被当成遗漏。首批范围建议按项目、时间、大小、类型四个维度收窄，例如先选一个附件量中等、业务仍在活跃使用的项目，时间上限定近两年，类型上排除超大视频文件。
| 范围项 | 填写内容 | 示例 |
|---|---|---|
| 源系统 | Jira 实例地址、附件存储方式 | Jira Software 实例，附件存于本地目录 |
| 目标系统 | 替代系统名称与目标空间 | 目标系统项目空间 A |
| 纳入对象 | 问题附件、评论内联附件 | 问题附件全量，评论附件随评论迁移 |
| 排除对象 | 头像、项目图标、仪表盘配图 | 装饰性图片不迁移 |
| 首批项目 | 项目键与附件数量 | 项目 A，约 3000 个附件 |
范围表确定后，后续的盘点、映射和核验都围绕这张表展开，范围之外的文件不进入迁移清单，也不计入验收数量。
动手前的输入清单与依赖确认
迁移卡住的原因多数出在输入不齐，而不是工具本身。动手前需要拿到四类输入：附件清单、目标端限制、账号与权限映射关系、存储与网络条件。清单逐项标注“已具备、待确认、缺失”，缺失项要写明会卡住哪一步。
附件清单至少包含附件 ID、所属问题键、文件名、文件大小、创建时间、上传人。这份清单是后续数量对账的基准，导出后要冻结版本，迁移期间源端新增的附件单独记录，避免总数对不上。目标端限制包括单文件大小上限、单次批量上限、总容量和允许的文件类型，这些数值直接决定批次怎么切、大文件是否需要单独处理。账号与权限映射要覆盖源端上传人和可见范围如何对应到目标端用户与项目角色，受限附件尤其需要提前确认对应关系。存储与网络条件决定导出方式：能直接访问附件存储目录时可以批量导出，只能通过接口获取时需要分批下载再上传，传输通道的带宽和稳定性也要评估。
- 附件清单已导出并冻结版本，记录导出时间点。
- 目标端单文件上限、批量上限、总容量已确认，形成书面记录。
- 源端用户、用户组与目标端账号的对应关系已列出。
- 受限附件的可见范围规则已明确由谁确认。
- 导出与传输方式已确定，大文件是否有单独通道。
目标端的具体限制数值需要以目标系统文档或实施方确认为准，没有确认前不要按经验值划分批次。
附件与字段的映射方法
映射解决的是两端对应关系：一个附件在源端挂在哪个问题、哪个位置、谁能看，到目标端要落到哪个工作项、哪个字段、哪个权限范围。主关联键用问题键，先建立源问题键到目标工作项 ID 的对照表，附件再通过问题键挂接，这样附件归属不依赖文件名或上传顺序。
文件名冲突和非法字符要提前定规则。常见做法是保留原始文件名作为可追溯字段，实际存储名在冲突时追加问题键或序号；非法字符按目标系统允许的字符集替换，替换记录写入映射表。附件归属位置要区分工作项附件区和评论内联位置：评论中的附件应随评论落到对应评论下，直接挂到工作项附件区会丢失上下文。权限继承按源端可见范围映射到目标端项目角色或工作项权限，源端受限附件在目标端仍应受限，映射结果由业务负责人确认。无法映射的附件单独登记，标注原因，进入人工复核或暂缓迁移，不混在成功清单里。
| 映射项 | 源端 | 目标端 | 冲突处理 |
|---|---|---|---|
| 归属主键 | 问题键 | 目标工作项 ID | 对照表逐条登记 |
| 文件名 | 原始文件名 | 存储名 + 原始名保留字段 | 重名追加问题键或序号 |
| 归属位置 | 问题附件区 / 评论内联 | 工作项附件区 / 对应评论 | 按来源位置分别导入 |
| 可见范围 | 问题或评论权限 | 项目角色或工作项权限 | 受限附件逐条确认 |
| 无法映射 | — | 单独清单 | 人工复核或暂缓 |
如果目标系统是 ONES，附件迁移属于 Jira 数据迁移的一部分，官方方案中问题数据的迁移范围包括属性和属性值、附件、评论等信息，用户、用户组以及问题类型、工作流、字段配置、权限配置等系统配置也在迁移范围内。这意味着映射表里的权限和字段对应关系可以借助配置迁移结果来核对，但附件级的可见范围仍要在试迁移中逐类验证。ONES 的迁移方案把迁移工具、原厂服务和分阶段切换结合，正式迁移前确认数据范围、功能匹配和系统适配，这与前面先盘点、再映射的做法一致。
试迁移：小批量跑通再放大
试迁移的目的是用受控样本验证映射规则和工具链路，而不是提前迁完全部数据。样本要覆盖四类情况：大文件、特殊字符文件名、受限权限附件、评论内联附件。每类选若干条，数量不必多，但要能暴露规则边界。
执行顺序按导出、传输、导入、抽查四步走，每一步记录开始时间、处理条数和异常。导出环节确认文件能完整取出，传输环节确认字节数没有变化，导入环节确认附件挂到了正确的工作项和位置，抽查环节打开文件确认内容可读。试迁移记录表按样本类别填写成功、失败、需人工处理三种结果，失败项写明错误信息。
- 大文件样本：验证是否触发单文件上限，是否需要拆分或单独通道。
- 特殊字符文件名：验证替换规则是否生效，原始名是否可追溯。
- 受限权限附件：验证目标端可见范围是否与源端一致。
- 评论内联附件：验证是否落在对应评论下，上下文是否完整。
试迁移结果直接决定正式批次：失败集中在某一类文件时，先修规则再放大；单批处理稳定后再提高并发数，并发提高后要重新观察失败率。批次大小以单批可核对、可回退为原则，不追求一次跑完。
核验与证据：怎么判断附件迁对了
核验用四类证据说话：数量、大小、可用性、归属与权限。数量核验把源端附件总数与目标端导入数、失败数、跳过数对账，三者相加应等于源端总数，差额要能逐条解释。大小核验对抽样文件比对字节数或哈希值，大文件和特殊字符文件优先抽样。可用性核验随机打开文件，确认内容完整、可预览或下载。归属与权限核验检查附件是否挂在正确工作项、评论附件是否在对应评论下、受限附件是否仍然受限。
| 核验项 | 方法 | 抽样比例 | 结果 | 责任人 |
|---|---|---|---|---|
| 数量对账 | 源端总数 = 导入数 + 失败数 + 跳过数 | 全量 | — | — |
| 文件大小 | 比对字节数或哈希值 | 大文件全量，其余抽样 | — | — |
| 可打开性 | 随机打开预览或下载 | 按批次抽样 | — | — |
| 归属正确 | 抽查附件与工作项、评论的对应 | 按批次抽样 | — | — |
| 权限一致 | 用受限账号访问受限附件 | 受限附件全量 | — | — |
核验记录要留存，作为验收依据和后续问题追溯的凭据。抽样发现的问题按类别汇总，同类问题重复出现时扩大抽样或暂停该批次。ONES 方案把“数据完整、业务连续和系统稳定”作为迁移目标，实际是否达成仍以项目验收记录为准，核验表就是这份记录的组成部分。
切换节奏与回退、停止条件
切换方式有两种：全量一次性切换和按项目分批切换。附件总量小、试迁移失败率低、业务允许短时间停写时，可以全量切换；附件量大、项目之间依赖少时，按项目分批切换更稳，每批完成核验后再启动下一批。两种方式都要保留源端只读窗口，窗口时长覆盖切换和首批核验，用途是让用户仍能查阅旧附件、处理旧链接，也为回退留出空间。
停止条件要提前写成阈值，例如单批失败率超过约定比例、关键项目附件缺失、受限附件出现权限错配，任一条件触发就暂停导入，查明原因再决定继续或回退。回退动作包括暂停当前批次导入、保持源端可访问、按批次撤销已导入附件，回退范围以批次为单位，不做跨批次混合回滚。切换完成后处理收尾：通知用户新位置和旧链接的处理方式，把遗留附件清单交接给业务负责人，未迁移的排除项和暂缓项逐条说明。
- 停止阈值：失败率、关键附件缺失、权限错配三类条件写入方案，明确判定人和决策人。
- 回退点：源端只读窗口的起止时间、可访问范围、关闭条件。
- 收尾交接：遗留附件清单、旧链接处理结果、用户通知记录。
切换与回退方案要和核验表配套使用，每批切换的核验结果决定下一批是否启动，回退记录同样留档，便于复盘批次划分是否合理。
常见问题
Jira 附件迁移能不能做到零丢失、一键完成？
不建议按零丢失或一键完成来设定预期。附件迁移涉及导出、传输、导入、权限映射多个环节，文件名冲突、超大文件、受限附件都可能需要人工处理。可行的做法是把目标定为“可核对、可回退”：数量对账能解释每一处差额，失败和跳过项有单独清单，切换期间保留源端只读窗口。验收时以核验表记录为准，而不是以“全部迁完”作为唯一标准。
评论里的附件和问题附件要分开处理吗？
要分开。问题附件直接挂在工作项附件区，评论中的内联附件应随评论落到对应评论下，这样上下文才完整。如果统一挂到工作项附件区，用户回看评论时会发现附件位置错乱。映射表里把“归属位置”单独列一列，试迁移样本中专门选几条评论内联附件验证落点，核验时抽查附件与评论的对应关系。
源端受限附件迁到目标系统后，权限怎么保证一致？
先确认源端每个受限附件的可见范围由哪个用户组或项目角色控制，再在目标端找到对应的角色或工作项权限设置，逐条登记到映射表。目标端权限模型与 Jira 不完全相同，映射结果需要业务负责人确认。核验时用受限账号实际访问受限附件，确认仍然受限；受限附件建议全量核验，不只抽样。试迁移阶段就应覆盖这一类样本，提前暴露权限错配。
迁移过程中源端还在新增附件，数量对不上怎么办？
导出附件清单后立即冻结版本并记录导出时间点，这份清单作为数量对账的基准。迁移期间源端新增的附件单独记录，不混入基准清单。切换前再做一次增量盘点，把新增附件按同一套映射规则补迁，或者明确列入遗留清单交接给业务负责人。数量核验时用“基准总数 = 导入数 + 失败数 + 跳过数”对账，增量部分单独核对，避免总数反复变动导致验收无法收敛。
什么情况下应该暂停迁移或回退？
提前把停止条件写成阈值，常见的有三类：单批失败率超过约定比例、关键项目出现附件缺失、受限附件出现权限错配。任一条件触发就暂停当前批次导入，查明原因后再决定继续还是回退。回退以批次为单位，动作包括暂停导入、保持源端可访问、撤销该批已导入附件，不做跨批次混合回滚。停止阈值、判定人和决策人要写进切换方案，避免现场临时争论。
