超大附件迁移失败时，先别急着重跑全量。更稳妥的顺序是先定位失败发生在读取源端、传输过程还是写入目标端，再按文件大小、版本数量、权限继承三条线索缩小到单文件复现，最后用小批量回放和抽样校验确认恢复。本文覆盖附件存在多版本、权限继承和超大文件的场景，只讨论迁移数据内容本身。
要点总览（TL;DR）
- 排查从定位失败层级开始：先看日志判断失败发生在读取源端、传输过程还是写入目标端，再缩小到单文件复现。
- 按文件大小分组复现找失败阈值，再分别抽取多版本附件和带继承权限的附件单独试迁移，三类问题可能叠加。
- 每条原因假设都要配验证证据：日志字段、错误码、单文件复现结果、源端与目标端配置比对，证据不足时保留为待验证。
- 处置后先小批量回放，以抽样通过率、失败清单清零、版本数与权限条目无差异三项作为恢复判定标准。
- 未确认原因前不做全量重跑；覆盖性操作前备份源端、在测试环境验证并设置停止点。
症状与范围：超大附件迁移失败通常表现为什么
“迁移失败”是一个笼统说法，落到附件上会呈现几种不同形态。先分清症状类型，才能判断后续该查哪一层。常见症状可以归为五类：整批任务中断、单文件被跳过、迁移后文件缺失、版本错乱、权限继承异常。前三种通常与文件体积和传输稳定性相关，后两种更多与映射规则和目标端模型相关。
| 症状 | 典型表现 | 优先怀疑方向 |
|---|---|---|
| 整批中断 | 迁移任务在某个时间点整体停止，后续文件未处理 | 传输通道超时、目标端连接中断、批次配置限制 |
| 单文件跳过 | 任务显示完成，但个别大文件不在目标端 | 单文件大小上限、分片未生效、读取源端失败 |
| 迁移后文件缺失 | 文件数量对不上，或文件名存在但内容为空 | 写入阶段失败、映射规则遗漏、存储配额不足 |
| 版本错乱 | 只保留最新版、版本顺序颠倒或版本数减少 | 版本链映射缺失、目标端版本保留策略限制 |
| 权限继承异常 | 继承权限变成显式授权，或部分人员失去访问权 | 继承关系被扁平化、目标端权限模型差异 |
需要把“超大文件失败”和“多版本、权限继承问题”分开记录。超大文件失败往往表现为单文件跳过或整批中断，多版本和权限继承问题则常在任务显示成功后才暴露。两类问题可能叠加：一个带多个版本的大文件，既可能因体积被跳过，也可能因版本映射不全而只迁了最新版。
记录症状时，至少采集以下最小信息，后续排查才有比对基础：
- 文件大小，精确到实际字节数，便于找出失败阈值；
- 版本数量，以及源端各版本的创建时间和大小；
- 源端与目标端系统及存储位置；
- 失败发生的时间点和所处批次；
- 错误码或日志片段，包含失败阶段的关键字段；
- 该附件是否带继承权限，继承自哪一级对象。
本文的范围限定在迁移数据内容本身。工作流与插件行为的迁移、迁移结果核验与切换管理的完整流程，属于另外的话题，这里不展开。
原因假设与排除证据：按层级缩小失败范围
排查中最容易犯的错误，是把第一个看起来合理的原因当成结论。更可靠的做法是先列出假设，再为每条假设找到能证实或排除它的证据。下面按层级整理常见假设与对应证据。
| 层级 | 原因假设 | 验证证据 |
|---|---|---|
| 源端读取 | 源端账号权限不足、文件被锁定、存储读取超时 | 源端访问日志、单文件下载测试结果、错误码中的读取阶段标识 |
| 传输通道 | 单文件大小上限、分片或断点续传未生效、超时设置过短 | 失败文件大小是否集中在同一阈值附近、传输日志中的超时记录、通道配置比对 |
| 目标端写入 | 存储配额不足、写入权限不足、目标端大小限制 | 目标端错误码、剩余空间、目标端配置中的大小与配额参数 |
| 映射规则 | 路径或字段映射不匹配、版本链映射缺失、权限继承被扁平化 | 映射配置与实际文件路径比对、迁移前后版本数比对、权限条目逐项比对 |
超大文件相关的假设要重点验证三点：单文件大小上限是否低于失败文件体积；分片或断点续传是否在该批次实际生效；超时设置是否短于大文件的正常传输耗时。验证方式是用同一文件在测试环境单独试迁移，观察失败是否稳定复现，以及日志中失败发生在哪个阶段。
多版本相关的假设，核心是版本链是否被完整映射。验证时抽取一个含三个以上版本的附件，迁移后逐版比对版本数量、版本顺序和每版内容大小。如果目标端存在版本保留策略，还要核对策略上限是否小于源端版本数。
权限继承相关的假设，重点看继承关系在迁移后是否保持。验证方法是选取一个从上级对象继承权限的附件，迁移前后分别导出权限条目，比对继承来源、授权对象和权限级别。若继承关系变成逐条显式授权，说明迁移过程对权限做了扁平化处理。
每条假设都应保留“待验证”状态，直到证据充分。日志字段、错误码、单文件复现结果、源端与目标端配置比对，这四类证据中缺少任何一类，都不足以把假设升级为结论。
排查顺序：从整批到单文件的分步定位
排查按“先定位失败层级、再缩小到单文件、最后验证恢复”推进。每一步都有明确的输入、动作和判断分支，通过则进入下一步，失败则记录证据并转入对应处置。
第一步，确认失败层级。查看迁移日志，判断失败发生在读取源端、传输过程还是写入目标端。输入是失败批次的完整日志；动作是定位第一条错误记录及其阶段标识；判断依据是错误码归属和日志中的阶段字段。如果日志无法区分阶段，先用一个中等大小的普通附件做对照迁移，观察正常流程各阶段的日志形态，再回头比对失败记录。
第二步，按文件大小分组复现。把失败清单按文件大小排序，找出失败是否集中在某个阈值以上。输入是失败文件清单及各自大小；动作是选取阈值上下各若干文件单独试迁移；判断依据是失败是否稳定出现在同一大小区间。若失败集中在阈值附近，优先怀疑单文件大小上限或分片策略。
第三步，抽取多版本附件单独试迁移。选择一个版本数较多的附件，单独执行迁移，观察版本链是否完整。输入是该附件的版本清单；动作是迁移后逐版比对数量、顺序和内容大小；判断依据是版本数是否一致、顺序是否保持。若只迁了最新版，转入版本映射处置。
第四步，抽取带继承权限的附件比对权限条目。输入是迁移前后的权限导出结果；动作是逐条比对继承来源和授权对象；判断依据是继承关系是否保留。若继承被扁平化，记录具体差异条目，转入权限规则处置。
第五步，核对映射规则与目标端限制配置。输入是映射配置文件和目标端的大小、配额、版本保留、权限模型参数；动作是逐项与源端实际情况比对；判断依据是是否存在不匹配项。这一步常能解释前几步中反复出现的失败。
涉及删除、覆盖或重新写入的操作前，先备份源端数据，在测试环境完成验证，并设置明确的停止点。未确认原因前不做全量重跑，避免重复写入或覆盖已有数据。
排查过程中会产生大量失败清单、复现记录和比对结果。这些记录如果散落在个人表格里，后续处置和验证容易脱节。在 ONES 中，可以把每个失败附件作为一条工作项记录，附上大小、版本数、失败阶段和证据片段，用状态区分“待复现、已定位、待处置、已验证”；迁移预检清单和映射比对结论则可以放在 Wiki 文档中，随排查进展更新。这样处置动作和验证结果能沿同一条记录追溯。
处置与恢复验证：修复后如何确认迁移成功
处置动作取决于已定位的原因，不同原因对应不同方向：
- 大小限制或分片问题：调整单文件大小限制、启用或修正分片与断点续传策略、适当延长超时；
- 版本映射缺失：补全版本链映射规则，确认目标端版本保留策略不低于源端版本数；
- 权限继承异常：修正继承规则，明确哪些权限保持继承、哪些需要转为显式授权；
- 映射规则不匹配：修正路径或字段映射，重新核对目标端配额与写入权限。
处置完成后，不要直接全量重跑。先做小批量回放：选取此前失败的样本文件，包含大文件、多版本附件和带继承权限的附件各若干，重新迁移并逐项核对。核对内容包括文件数量与大小、版本数与版本顺序、权限条目与继承来源。
恢复判定可以按以下标准执行：抽样通过率达到预设要求；失败清单清零，或剩余条目均有明确挂起原因和责任人；版本数和权限条目与源端比对无差异。三项同时满足，才可认为该批次恢复。
复发预防落在三个动作上：设置文件大小阈值告警，在迁移前识别超出目标端限制的文件；配置失败重试与断点续传，减少大文件因超时中断后的重复传输；建立迁移前预检清单，把大小分布、版本数量、权限继承情况作为必查项。ONES 的迁移方案把数据完整、业务连续和系统稳定作为目标，并建议在正式迁移前确认数据范围、功能匹配和系统适配，这与预检清单的思路一致。具体的大小上限、版本映射规则和权限继承粒度，需在迁移前与官方逐项确认，不能凭经验假设。
风险边界需要反复强调：未确认原因前不做全量重跑；任何覆盖性操作前先备份源端；在测试环境验证通过后再进入生产批次；每个批次设置停止点，出现异常立即暂停并保留现场日志。
常见问题
日志无法区分失败发生在读取、传输还是写入阶段，怎么办？
先用一个中等大小的普通附件做对照迁移，观察正常流程在读取、传输、写入各阶段分别留下什么日志形态，再回头比对失败记录。如果仍无法区分，用同一失败文件在测试环境单独试迁移，记录失败前后的日志时间点，通常能看出失败停在哪个阶段。这一步的结论会决定后续查源端、查通道还是查目标端。
超大文件失败后可以直接调大上限再全量重跑吗？
不建议。调大上限只是处置方向之一，前提是先确认失败确实由大小限制引起，而不是分片未生效、超时过短或目标端配额不足。未确认原因就全量重跑，可能重复写入或覆盖已有数据。稳妥做法是先在测试环境用阈值附近的样本文件验证调整是否生效，再小批量回放，最后才进入生产批次。
多版本附件只迁了最新版，是映射问题还是目标端策略问题？
两者都要查。先比对迁移前后的版本数量与顺序，确认源端版本链是否完整；再核对目标端的版本保留策略上限是否小于源端版本数。如果版本链映射缺失，需要补全映射规则；如果目标端保留策略上限偏低，需要调整策略或明确哪些历史版本需要保留。两类原因可能同时存在，处置后要用含三个以上版本的附件重新验证。
权限继承异常在迁移后多久能发现，怎么核对？
这类问题常在任务显示成功后才暴露，不会在迁移过程中报错。核对方法是选取一个从上级对象继承权限的附件，迁移前后分别导出权限条目，逐条比对继承来源、授权对象和权限级别。若继承关系变成逐条显式授权，说明迁移过程对权限做了扁平化处理，需要修正继承规则并重新核对差异条目。
排查记录用什么方式管理，才能让处置和验证不脱节？
关键是让失败清单、复现记录和验证结果沿同一条记录追溯。在 ONES 中可以把每个失败附件作为一条工作项，附上大小、版本数、失败阶段和证据片段，用状态区分“待复现、已定位、待处置、已验证”；迁移预检清单和映射比对结论放在 Wiki 文档中随进展更新。这样处置动作和恢复验证能对应到同一个对象，避免记录散落在个人表格里。
