超大附件迁移失败往往不是单一原因：单文件体积超限或传输超时先触发中断，多版本附件映射、权限继承和存储配额问题再叠加出现。本文按“症状分类—体积与传输—版本映射—权限继承—存储配额—重跑验证”的顺序给出排查路径，每一步用日志、抽样对比或失败样本复现确认原因，再进入处置。内容聚焦迁移数据本身，流程与插件行为、迁移结果核验与切换管理不在本文展开。
要点总览（TL;DR）
- 先按整批中断、单文件失败、文件缺失、版本错乱、权限异常五类症状归类，再决定从哪一步开始查，避免一上来翻全部日志。
- 排查顺序为：失败清单与单文件体积、传输超时和断点续传→多版本附件映射→权限继承→目标存储配额与并发限制，每一步用日志或抽样比对确认后再进入下一步。
- 处置按原因分类：体积超时类分批迁移并保留断点记录，版本类先对样本重跑，权限类先导出源端权限清单再改，存储类扩容或清理前先备份。
- 涉及删除、覆盖或改权限的操作须先备份并设停止点，样本重跑不符合预期立即停止扩大范围。
- 验证以抽样比对文件数量、大小、版本数和权限可见范围为准，失败清单归零或剩余项有明确原因才算恢复，本次失败样本留作回归用例。
先看失败症状：超大附件迁移失败有哪些表现
排查的起点是把笼统的“迁移失败”拆成可观察的症状。不同症状指向不同的原因层，先归类能缩小排查范围，避免一上来就翻全部日志。建议从迁移工具的任务报告、失败清单和抽样结果中提取三类信息：失败发生在哪个阶段、影响的是整批还是个别文件、目标端数据与源端是否一致。
| 症状类型 | 典型表现 | 影响范围 | 优先排查方向 |
|---|---|---|---|
| 整批中断 | 迁移任务在中途停止，后续文件全部未处理 | 整个批次或某个迁移阶段 | 传输链路、超时设置、并发与存储余量 |
| 单文件失败 | 失败清单中列出个别文件，其余文件正常完成 | 单个或少量超大文件 | 单文件体积上限、传输耗时、断点续传 |
| 文件缺失 | 任务显示完成，但目标端找不到对应附件 | 特定目录、特定类型或特定版本 | 映射规则、过滤条件、失败清单是否被忽略 |
| 版本错乱 | 附件存在，但版本数量不对或版本顺序颠倒 | 多版本附件所在的工作项或页面 | 版本映射规则、版本号对应关系 |
| 权限异常 | 目标端部分用户看不到附件，或可见范围比源端更大 | 继承权限的目录、空间或页面 | 继承权限展开策略、目标端继承支持 |
症状与原因层的对应关系是排查的假设来源，不是结论。例如“单文件失败”既可能是体积超限，也可能是链路在传输大文件时超时；“权限异常”既可能是源端继承权限未被展开，也可能是目标端对继承的处理方式不同。每一类症状都需要在后续步骤中用证据确认。若失败集中在多版本附件且伴随权限异常，可以从版本映射和权限继承两步并行取证，但处置仍按确认顺序推进。
按顺序定位原因：从体积与传输到版本、权限和存储
排查顺序遵循“先排除最直接、最容易验证的原因，再处理依赖映射和权限配置的原因”。每一步都先形成假设，再找验证证据，证据不足时不进入处置。下面四步按顺序执行，前一步排除后再进入下一步；若证据指向多个原因并存，分别记录，处置时逐项处理。
第一步：核对失败清单与单文件体积、传输超时和断点续传
先看失败清单中失败文件的体积分布。如果失败项集中在超过某一数值的文件上，体积上限是首要假设；如果失败文件的体积分布分散、失败时间点集中，更可能是传输超时或链路中断。验证证据包括：失败清单中的文件大小字段、任务日志中的开始与结束时间、断点续传记录是否存在且可恢复。排除条件是：体积在限制内的文件同样失败，且日志显示连接中断而非大小拒绝，此时转向链路与超时配置。
第二步：核对多版本附件的版本映射规则与版本号对应关系
多版本附件是版本错乱的高发场景。取若干源端有多个版本的附件作为样本，逐一比对源端与目标端的版本数量、版本顺序和版本号。验证证据是样本比对表：源端版本数、目标端版本数、最新版本内容是否一致、历史版本是否可追溯。若目标端只保留了最新版本，说明映射规则按“仅迁当前版本”执行；若版本顺序颠倒，说明版本号未按原顺序对应。排除条件是样本比对完全一致，此时版本层不是本次失败原因。
第三步：核对权限继承：源端继承权限是否被展开、目标端是否支持同等继承
权限异常的定位要分两头看。源端一侧，确认附件的可见范围是直接授权还是从上级目录、空间继承而来；继承权限在迁移时是否被展开为具体授权记录。目标端一侧，确认目标系统对继承权限的支持方式，以及迁移后继承关系是否保留。验证证据包括：选取若干继承权限的样本，比对源端与目标端的可见用户列表；检查迁移日志中权限处理相关记录。排除条件是样本的可见范围在两端一致，且没有出现权限放大或丢失。
第四步：核对目标存储配额、单文件大小限制和并发限制
前三步排除后，检查目标端的存储余量是否足以容纳本批附件总量，目标端是否存在低于源端的单文件大小限制，以及迁移任务的并发数是否超过目标端承受能力。验证证据是目标端存储使用量与剩余配额、失败时间点与配额告警的时间对应关系、并发调高后失败率是否上升。排除条件是配额充足、单文件限制不低于失败文件体积、降低并发后失败不再复现。
处置动作：针对已定位原因的处理与风险边界
处置的前提是原因已被证据确认。未确认的原因不进入处置，避免用调整参数掩盖真实问题。以下按原因类型给出动作，涉及删除、覆盖或修改权限的操作，执行前须完成备份并设定停止点：一旦样本重跑结果不符合预期，立即停止扩大范围。
| 原因类型 | 处置动作 | 前置条件 | 风险提示与停止点 |
|---|---|---|---|
| 体积或超时 | 按体积分批迁移，调整单批大小，保留断点记录以便续传 | 已确认失败与体积或超时相关 | 分批后需重新核对批次边界，避免遗漏；断点记录被覆盖前先导出留存 |
| 版本映射 | 修正映射规则，先对多版本样本重跑，确认版本数量和顺序后再扩大范围 | 样本比对已定位映射偏差 | 重跑可能覆盖目标端已有版本，覆盖前备份目标端现状；样本不符预期即停止 |
| 权限继承 | 明确继承展开策略，按样本验证目标端可见范围后再全量执行 | 已确认源端继承方式与目标端支持范围 | 避免权限放大或丢失；修改权限前导出源端权限清单，发现放大立即回退 |
| 存储与配额 | 扩容或清理目标端存储后重跑，保留原始失败记录 | 已确认配额或限制是直接原因 | 清理操作须确认不删除已迁移成功的数据；清理前做备份 |
分批迁移时，批次划分建议以单文件体积和总传输量为依据，而不是简单按文件数量均分，否则大文件仍会集中在某一批。版本类处置的关键是先小范围重跑：选覆盖单版本、多版本、历史版本被引用等几种情况的样本，确认版本顺序和内容一致后再扩大。权限类处置要把“展开继承”和“保留继承”两种策略的适用条件写清楚，同一批数据内保持策略一致，避免部分目录展开、部分保留造成核对困难。存储类处置完成后，原始失败记录应保留到验证通过为止，作为回归比对的基线。
验证恢复与防复发：如何确认迁移结果可信
处置完成后，验证的目标是确认迁移结果与源端一致，并且失败清单中的每一项都有明确去向。验证不只看任务状态显示成功，还要用抽样比对确认数据内容。
恢复验证检查表
- 文件数量：按目录或工作项抽样，比对源端与目标端的附件数量。
- 文件大小：抽样比对文件大小，重点覆盖此前失败的超大文件。
- 版本数与版本顺序：对多版本样本逐一核对版本数量和最新版本内容。
- 权限继承结果：抽取继承权限样本，比对两端可见用户范围，确认无放大、无丢失。
- 失败清单：确认归零；若有剩余项，每项标注明确原因和处理结论。
防复发检查项
把本次排查中确认的约束固化为迁移前检查项，可以减少同类失败重复出现：
- 体积上限：迁移前统计待迁附件的体积分布，识别超过目标端限制的文件并提前分批。
- 版本规则：迁移前明确多版本附件的映射规则，并用样本预演验证。
- 权限策略：迁移前确认源端继承权限的展开方式与目标端支持范围，形成书面策略。
- 存储余量：迁移前核对目标端配额与单文件限制，预留余量应对峰值。
- 回归用例：把本次失败样本记录为回归用例，下次迁移或工具升级后优先重跑。
在 ONES 的迁移方案中，Jira 迁移覆盖项目、工作项、状态、字段、流程、附件和历史记录，Confluence 迁移可将空间、页面、附件和权限结构迁入 ONES Wiki，并迁移用户、用户组、空间权限与页面权限。这些能力说明附件与权限结构属于迁移范围；具体到超大附件的体积上限、版本映射规则、继承权限展开方式和迁移日志字段，需以实际迁移工具和实施文档为准。排查时可把上述通用步骤与实施方确认的参数对照使用，把每次确认的阈值和规则补充进迁移前检查项，让下一次迁移的排查起点更明确。
常见问题
失败清单里既有超大文件也有小文件，应该先查哪一类？
先按体积分布把失败项分成两组。若失败集中在超过某一数值的文件上，优先核对单文件体积上限和传输超时；若小文件同样失败且失败时间点集中，更可能是链路中断、并发过高或目标端配额不足。两组证据分别记录，处置时先处理能解释多数失败的那一类，再回头验证另一组是否随之消失。
多版本附件迁移后只剩最新版本，是映射规则问题还是迁移工具不支持？
先用样本比对确认现象：取若干源端有多个版本的附件，核对目标端的版本数量和版本顺序。若目标端只保留最新版本，通常是映射规则按“仅迁当前版本”执行，需要与实施方确认规则配置；若版本数量正确但顺序颠倒，则是版本号对应关系的问题。在规则确认前，不宜直接判定工具能力边界。
权限继承异常时，先改源端还是先改目标端？
先取证再动手。源端一侧确认附件的可见范围是直接授权还是继承而来，继承权限在迁移时是否被展开为具体授权记录；目标端一侧确认继承关系的保留情况。两侧证据齐备后再定策略：需要展开继承的，先导出源端权限清单作为基线，按样本验证目标端可见范围，确认无放大、无丢失后再全量执行。修改权限前完成备份并设停止点。
分批迁移后仍然出现个别超大文件失败，下一步查什么？
先看这批失败文件的体积是否仍超过目标端单文件限制，再核对失败时间点是否与并发峰值或存储告警重合。若体积在限制内仍失败，检查断点续传记录是否完整、传输链路是否在中途断开。可以把失败文件单独组成一个小批次重跑，观察是否稳定复现，复现结果作为判断是体积问题还是链路问题的依据。
迁移任务显示成功，还需要做哪些验证？
任务状态成功只说明流程走完，数据一致性要靠抽样比对。按目录或工作项抽取样本，核对附件数量、文件大小、多版本附件的版本数与顺序，以及继承权限样本在两端可见用户范围是否一致。失败清单要确认归零，若有剩余项，每项标注明确原因和处理结论。本次失败样本建议记录为回归用例，下次迁移或工具升级后优先重跑。
