Jira附件迁移后出现附件问题，先别急着归因于迁移失败。附件列表为空、数量少于源端，属于“丢失”；附件条目还在但下载失败、文件损坏、预览空白或提示无权限，属于“打不开”。两类症状的排查起点不同。本文按“记录是否存在—附件记录是否迁移—文件实体是否落盘—访问链路是否可用”四层推进，每层用清单比对、日志和下载测试留下可复现证据，再决定处置动作。
要点总览（TL;DR）
- 先区分两类症状：附件列表为空或数量少于源端属于“丢失”，附件条目在但下载失败、文件损坏、预览空白或提示无权限属于“打不开”，两类症状的排查起点不同。
- 按“记录是否存在—附件记录是否迁移—文件实体是否落盘—访问链路是否可用”四层推进，每层先提原因假设，再用清单比对、日志和下载测试留下可复现证据。
- 处置前先备份目标端现有附件并明确回滚方式；重跑附件迁移先挑3到5条做小批量验证，数量、文件名、大小三项一致后再扩大到全量。
- 恢复验证同时做数量与大小比对、可下载率统计和按文件类型抽测，把比对报告纳入迁移验收清单，并明确责任人与复核时点。
先分清是附件丢失还是附件打不开
排查的第一步是把症状说清楚，而不是马上重跑迁移。附件“丢失”和“打不开”在数据链路上处于不同位置：前者通常指向记录没有生成或迁移范围遗漏，后者通常指向文件实体、存储或访问环节。把两者混在一起，容易出现“附件明明在列表里，却被当作丢失重新导入”的重复操作。
可以按下面的口径做症状分类，并把每类症状的影响面一并记录：
| 症状类型 | 典型表现 | 优先怀疑的层级 |
|---|---|---|
| 附件丢失 | 问题条目存在，但附件列表为空；或附件数量少于源端 | 第一层记录、第二层附件记录 |
| 附件打不开 | 附件条目在列表中，但下载失败、文件损坏、预览空白、提示无权限 | 第三层文件实体、第四层访问链路 |
影响面决定排查层级。只有单条问题缺附件，优先检查该条目的迁移范围和字段映射；某个项目下批量缺附件，优先核对项目级过滤条件和附件类型限制；全量附件都异常，则应先停下逐条修复，回到迁移任务本身核对导出清单与执行日志。范围越大，越要先确认迁移范围，而不是在目标端手工补文件。
无论哪类症状，都需要先准备一份源端导出清单作为比对基准。清单至少包含：问题键、附件文件名、文件大小、附件数量、创建时间。没有这份基准，“数量对不对”“文件是不是原文件”都只能靠印象判断。建议把清单与症状记录整理成一张表，字段包括问题键、症状类型、影响范围、源端附件数、目标端附件数、首次发现时间、发现人，后续排查和验收都围绕这张表推进。
按四层链路列出原因假设与验证证据
四层排查的核心原则是：每一层先提出原因假设，再用可复现的证据判定，未验证前只作假设，不写成结论。下面按链路顺序给出每层的验证动作和判定证据。
| 层级 | 原因假设 | 验证动作 | 判定证据 |
|---|---|---|---|
| 第一层：条目与附件记录 | 问题条目未迁移；附件记录未生成；迁移范围过滤掉了该条目 | 在目标系统按问题键检索条目，打开详情查看附件区；对照迁移任务的过滤条件与执行日志 | 条目存在且附件区有记录，进入第二层；条目缺失或附件区为空，记录为记录层问题 |
| 第二层：附件记录一致性 | 附件数量少于源端；文件名被截断或改写；大小为0或明显偏小 | 用源端导出清单逐条比对目标端附件数量、文件名、大小 | 数量、名称、大小一致则进入第三层；存在差异则记录差异条目和差异类型 |
| 第三层：文件实体 | 文件未完整上传至存储；传输中断导致截断；存储空间不足或写入失败 | 下载目标端附件，核对文件大小与源端是否一致；检查迁移日志中的上传失败、超时、重试记录 | 大小一致且可正常打开，进入第四层；大小不一致、零字节或下载报错，记录为实体层问题 |
| 第四层：访问链路 | 下载权限未继承；链接地址指向旧域名；文件名编码异常；预览组件不支持该格式 | 用不同角色账号测试下载；检查附件链接地址；用特殊字符文件名做测试；换用下载方式而非预览打开 | 换账号或换下载方式后正常，说明是权限或链路问题；仍失败则回到第三层复核实体 |
第一层要回答的是“记录在不在”。在目标系统检索问题键时，注意区分“条目不存在”和“条目存在但附件区为空”，前者是条目迁移范围问题，后者才进入附件记录排查。迁移日志里通常能看到条目级和附件级的处理结果，先看日志再动手补数据，能避免重复导入。
第二层要回答的是“记录对不对”。数量比对之外，文件名和大小同样重要。文件名被截断、特殊字符被替换、大小显示为0，都是后续“打不开”的常见前兆。比对时以源端导出清单为准，逐条标记一致、缺失、异常三类状态。
第三层要回答的是“文件在不在、全不全”。附件记录存在不代表文件实体完整落盘。实际下载一次，比对文件大小，是最直接的验证方式。如果迁移日志中出现上传超时、重试失败或存储写入错误，应优先复核对应批次的文件实体，而不是继续在访问层找原因。
第四层要回答的是“能不能访问”。权限继承、链接域名、文件名编码和预览组件是四个常见检查点。用有权限的账号直接下载，可以区分“文件本身有问题”和“当前账号看不到”；用下载代替预览，可以区分“文件损坏”和“预览组件不支持该格式”。这一层的结论要写成“某账号在某入口下载某文件的结果”，而不是笼统的“打不开”。
按症状执行的处置步骤
处置动作要跟着已定位的层级走。下面按症状给出对应步骤，涉及重跑、覆盖、删除的操作，都先备份目标端现有附件，并明确回滚方式和停止条件。
记录缺失：核对迁移范围与过滤条件，补迁对应条目。先对照迁移任务的过滤条件，确认缺失条目是否被状态、项目、时间范围或字段条件排除。确认属于范围遗漏后，调整过滤条件补迁对应条目，补迁前记录当前目标端该条目的状态，补迁后复核条目和附件是否同时到位。
数量不一致：按清单重跑附件迁移，先小批量验证。从差异清单中挑3到5条代表性条目做小批量重跑，比对数量、文件名、大小三项都一致后，再扩大到全量。重跑前备份目标端已有附件，避免覆盖后无法对照；重跑过程中记录批次号和失败条目，出现失败率上升时暂停，先查日志再继续。
文件损坏或零字节：从源端重新导出并校验。对大小不一致或零字节的附件，从源端重新导出单个文件，核对导出后的大小与源端记录是否一致，再重新上传或补迁。校验时至少比对文件大小，条件允许时补充哈希比对。若同一批次多个文件出现截断，应检查迁移过程中的网络与存储写入日志，而不是逐个重传了事。
打不开：检查权限继承、链接域名、文件名编码与预览支持格式。先用有管理权限的账号直接下载，确认文件实体是否正常；再检查附件链接是否仍指向旧域名或旧路径；文件名含特殊字符时，测试重命名后能否正常下载；预览空白时，改用下载方式打开，确认是否为预览组件不支持该格式。四项检查按顺序做，每项记录测试账号、入口和结果。
需要明确停止条件：补迁或重跑过程中，如果失败条目持续增加、目标端出现重复附件、或备份无法完成，应暂停操作，保留现场日志后再分析。破坏性操作前没有可用备份、没有明确回滚方式时，不执行覆盖式重跑。
在ONES承接Jira迁移的场景中，附件属于迁移范围的一部分，迁移问题数据包括属性和属性值、附件、评论等信息。排查过程中产生的问题条目、差异清单和处置记录，可以落到ONES的工作项或文档中，按“待核查—已定位—已处置—已验证”推进状态，让迁移负责人和业务方看到同一份进度，避免口头同步造成遗漏。
恢复验证与复发预防
处置完成不等于问题解决，恢复验证要拿数据说话。建议同时做数量比对和可用性抽测，并把结果整理成比对报告。
- 数量与大小比对：按源端导出清单逐条核对目标端附件数量、文件名和大小，统计一致率，差异条目单独列出并说明处置结果。
- 可下载率统计：对问题条目全量下载测试，记录成功、失败和超时数量，失败项回到四层链路重新定位。
- 按文件类型抽测：从文档、表格、图片、压缩包等类型中各抽取若干附件，分别测试下载和预览，确认打开方式与内容正常。
- 权限复核：用普通成员账号抽测附件下载，确认权限继承符合预期，避免只有管理员能打开的情况被漏掉。
把上述检查纳入迁移验收清单，作为附件迁移完成的判定依据：数量一致率、可下载率、抽测通过率达到约定标准，才算验收通过。比对报告随迁移记录归档，保留源端清单、目标端比对结果和处置日志，后续出现争议时有据可查。
复发预防落在机制上。迁移前确认数据范围和附件类型，迁移中保留批次日志和失败清单，迁移后按清单做完整性与可用性校验，三个阶段各设一名责任人和一个复核时点。正式切换前用分阶段方式验证附件链路，先小范围试用再全量开放。ONES的Jira迁移方案围绕项目、工作项、状态、字段、流程、附件和历史记录进行迁移，并把数据完整和业务连续作为目标；具体到附件完整性校验、权限继承和重跑回滚的细节，以实际迁移服务约定和迁移工具的实际表现为准，验收时用本文的比对方法逐项确认。
常见问题
源端导出清单没有提前准备，还能排查附件数量是否一致吗？
可以补做，但结论的可信度会下降。优先从源端系统重新导出问题条目的附件列表，至少拿到问题键、文件名、大小和数量四项；如果源端已无法访问，只能以迁移任务日志中的附件处理记录作为替代基准，并在比对报告里注明基准来源和获取时间。缺少基准时，建议把排查重点放在“文件实体是否可下载、可打开”上，数量一致性作为待确认项保留，不写成已核实。
只有个别用户反馈附件打不开，其他人正常，应该先查哪一层？
这种情况优先查第四层访问链路。用反馈问题的账号和有管理权限的账号分别下载同一附件，对比结果：管理员能下载而普通账号不能，重点检查权限继承和附件所在条目的可见范围；两个账号都失败，回到第三层复核文件实体。链接域名指向旧地址、文件名含特殊字符、预览组件不支持该格式，也常表现为“部分人打不开”。每次测试记录账号、入口和结果，避免把权限问题误判为文件损坏。
重跑附件迁移时，目标端已经存在的附件会被覆盖吗？
取决于迁移任务的配置和工具行为，执行前需要确认清楚。稳妥做法是先备份目标端现有附件，再挑少量条目试跑，观察重跑后是新增副本、覆盖原文件还是跳过已存在项，确认行为符合预期后再扩大范围。出现重复附件、失败条目持续增加或备份无法完成时暂停操作，保留日志后再分析。没有可用备份和明确回滚方式时，不执行覆盖式重跑。
附件能下载但预览是空白，算迁移失败吗？
不一定。先用下载方式打开同一文件，确认文件实体是否完整：下载后能正常打开，说明文件本身没问题，问题出在预览环节，重点检查预览组件是否支持该格式、文件名编码是否影响预览加载；下载后同样打不开或文件损坏，才回到第三层排查文件实体。把“下载结果”和“预览结果”分开记录，能避免把预览限制当成迁移失败处理。
迁移验收时，附件完整性要核对到什么程度才算通过？
建议至少覆盖三项：按源端清单核对附件数量、文件名和大小的一致率；对问题条目做全量下载测试并统计可下载率；按文档、表格、图片、压缩包等类型抽测下载与预览。三项达到迁移前约定的标准才算验收通过，比对报告随迁移记录归档。在ONES承接Jira迁移的场景中，迁移问题数据包括属性和属性值、附件、评论等信息，具体校验口径和重跑回滚细节以实际迁移服务约定为准。
