增量迁移出现重复数据，先要分清是同一记录被多次写入，还是同一业务对象被识别成多条。前者多与重试、断点重放、幂等有关，后者多与增量识别口径、主键映射有关。排查按“界定症状—核对增量识别—检查幂等规则—核对断点续传—处置验证”的顺序推进，每一步用可复现的证据确认假设，避免直接改配置掩盖问题。
要点总览（TL;DR）
- 先界定重复形态：同一记录被多次写入多与重试、断点重放、幂等有关，同一业务对象被识别成多条多与增量识别口径、主键映射有关。
- 增量识别重点核对时间戳边界（大于与大于等于）、同一时间戳多条记录、变更标记复位、分页游标唯一性与排序稳定性，用源端与目标端记录数对比和批次捕获清单验证。
- 幂等规则失效常出在键设计、写入语义和并发边界三处，检查键是否稳定唯一、upsert 判定条件是否过严、并发与重试时是否有唯一约束兜底。
- 断点续传先看提交与断点更新的先后顺序，再看断点粒度是否与提交时机匹配、重试范围是否整批重跑、多分片是否共享断点导致位置回退。
- 处置按停止重复写入、备份后清理重复数据、修正配置的顺序推进，修复后用重放批次、记录数与主键集合对比、断点续跑结果确认不再复发。
重复数据长什么样：先界定症状与影响范围
“重复”在迁移结果里表现为两种不同形态，排查方向也不同。第一种是同一记录被多次写入：目标端出现主键相同或业务键相同的多行，字段值基本一致，差异可能只在创建时间、批次号或自增ID。第二种是同一业务对象被识别成多条：目标端主键不同，但业务含义指向同一条源数据，常见于源系统ID映射缺失、复合键拼接错误或大小写、空格处理不一致。两种形态对应的原因假设不同，先分类再排查能减少无效动作。
界定症状时，需要把以下信息记录成清单，作为后续排查的基线：
- 时间窗口：重复数据集中在哪个迁移批次、哪个时间段产生，是否与某次失败重试、配置变更或源端批量操作时间吻合。
- 数据对象类型：集中在哪类对象上，例如工作项、附件、评论、状态历史，不同类型对象的写入路径和键设计往往不同。
- 批次范围：重复只出现在个别批次，还是跨批次普遍存在；同一批次内重复，还是相邻批次之间重复。
- 伴随异常：是否同时出现字段缺失、状态错乱、关联关系断裂（如评论挂错工作项、附件指向错误记录）。伴随异常往往指向写入顺序或映射问题，而不只是重复写入。
- 影响边界：仅新增数据重复、仅更新数据重复，还是全量重跑后出现；是否影响下游统计、通知或权限关联。
这份清单的作用是缩小假设空间。例如重复只出现在中断续跑之后的批次，应优先怀疑断点与重试；重复集中在同一时间戳附近的记录，应优先怀疑增量识别边界。症状清单确认之前，不建议直接删除目标端数据或调整迁移配置。
增量识别环节的常见原因与排除证据
增量识别负责判断“哪些源数据需要被捕获”，条件设置不当会让同一条记录被多次判定为新增或变更。下面按假设、验证证据和判定标准列出常见原因，建议按表中顺序排查，因为识别环节的问题会同时放大后续幂等与断点的压力。
| 原因假设 | 典型表现 | 验证证据 | 结论判定 |
|---|---|---|---|
| 时间戳边界使用“大于等于” | 每次增量都重复捕获上一批次末尾同一时间点的记录 | 取相邻两批次的捕获清单，比对边界时间点的记录是否两批都出现 | 边界记录在两批中重复出现，且源端该记录只变更一次，可判定为边界条件问题 |
| 同一时间戳存在多条记录 | 按时间戳分页时，同一时刻的多条记录被拆分到不同批次或被重复读取 | 统计源端同一时间戳的记录数，核对目标端对应记录的写入次数 | 重复记录集中在同一时间戳，且该时间戳记录数大于单批处理量 |
| 源端与迁移端时钟偏差 | 记录更新时间落在水位线附近，被反复判定为新增 | 对比源端数据库时间与迁移任务服务器时间，抽样检查边界记录的实际更新时间 | 时间差稳定存在且重复记录集中在边界附近 |
| 变更标记未复位或状态回退 | 已同步记录被再次标记为待同步，或状态从已处理回退 | 检查源端变更标记字段的复位逻辑，抽样查看重复记录的标记值变化 | 重复记录的标记在同步后仍为待处理状态 |
| 分页排序不稳定或游标字段不唯一 | 跨页出现重复，重复记录分布在相邻页边界 | 用相同查询条件多次执行分页，比对每页返回的主键集合 | 不同次执行的分页结果在主键集合上有交集 |
| 更新事件被当作新增处理 | 源端更新后目标端新增一条而非更新原记录 | 抽样比对源端更新记录与目标端记录，检查目标端是否存在同业务键的多条记录 | 目标端同业务键记录数大于源端，且多出的记录对应更新操作 |
| 软删除记录被重复带入 | 已删除或已归档记录在后续增量中再次出现 | 核对源端删除标记与增量查询条件，检查重复记录在源端的删除状态 | 重复记录在源端已标记删除，但增量条件未排除 |
验证时建议同时做两组对比：一是源端与目标端的记录数对比，按对象类型和时间窗口分别统计；二是抽样比对主键与更新时间，选取重复记录及其相邻记录，确认源端实际变更次数。如果源端只变更一次而目标端写入多次，问题更可能出在写入端或断点重放；如果源端本身被多次判定为变更，问题在识别条件。按批次核对捕获清单能把范围定位到具体批次，避免在全部数据上反复扫描。
幂等规则为什么没拦住：写入端检查要点
幂等规则的作用是让同一记录重复到达时，目标端结果保持一致。规则失效通常不在“有没有做去重”，而在键的选择、写入语义和并发边界三处。
键设计是否稳定唯一
去重键常用业务主键、源系统ID或复合键。检查时确认三点：键在源端是否唯一且不随业务变化；迁移过程中是否对键做了截断、大小写转换或空格处理，导致同一记录生成不同键值；复合键的拼接顺序和分隔符是否在所有批次中一致。键不稳定时，重复记录会以不同键值写入，唯一约束无法拦截。
写入语义是否与预期一致
插入与更新（upsert）的判定条件决定了重复到达时的行为。需要核对：判定依据是主键、业务键还是版本号与更新时间；版本号比较是否包含相等情况；重复写入时选择覆盖、跳过还是新增，与业务预期是否一致。常见问题是更新判定条件过严，记录被判定为“新记录”而执行插入；或者版本号未随源端更新递增，导致旧数据覆盖新数据。
并发与重试下的幂等边界
同一记录在并发批次中同时到达时，先查后写的逻辑可能同时判定为“不存在”而各自插入。批次重试时，如果重试范围包含已成功写入的记录，而写入端没有唯一约束兜底，也会产生重复。验证方法是构造重复批次重放：将同一批次数据重复提交一次，观察目标端记录数是否变化；检查目标端唯一约束是否真实存在并生效；核对更新前后关键字段值，确认覆盖方向正确。
幂等检查清单可以按“键—语义—并发—验证”四步执行：确认键稳定唯一，确认写入语义与业务预期一致，确认并发与重试场景下有约束兜底，最后用重放批次和记录数对比验证规则实际生效，而不是只检查配置项是否存在。
断点续传配置排查：断点记录与重试边界
断点续传让迁移任务在中断后从上次位置继续，配置不当会把已提交的批次再写一遍。排查集中在断点粒度、提交顺序、重试范围和分片并发四个方面。
| 核对项 | 需要确认的内容 | 风险表现 | 验证方式 |
|---|---|---|---|
| 断点记录粒度 | 按批次、按记录还是按游标位置记录；粒度与数据提交时机是否匹配 | 按批次记录但批次内部分提交，续跑时整批重放 | 模拟中断后续跑，对比断点前后批次的记录写入结果 |
| 提交与断点更新顺序 | 先提交数据后更新断点，还是先更新断点后提交数据 | 先更新断点再提交，失败时数据丢失；先提交后更新断点，失败时批次重放 | 在提交与断点更新之间制造中断，观察续跑行为 |
| 失败重试策略 | 重试次数、重试范围是单条、单批还是整批重跑 | 整批重跑且写入端无幂等兜底，产生重复 | 触发一次可控失败，核对重跑批次与已成功批次的交集 |
| 并发与分片 | 多分片是否共享同一断点；分片重启后位置是否回退 | 分片间断点互相覆盖，重启后从更早位置开始 | 并行运行多分片，重启其中一个，检查其起始位置与已写入记录 |
排查顺序建议先看提交与断点更新顺序，因为它决定失败时是丢数据还是重放；再看断点粒度是否与提交时机匹配；然后核对重试范围；最后检查分片并发。验证时用模拟中断的方式复现：在已知批次位置中断任务，续跑后对比断点前后批次的记录，确认重跑批次是否与已提交批次重叠，以及重叠部分的写入结果是否符合幂等预期。断点配置的核对结论应记录到具体批次和具体分片，便于后续回归。
处置与验证：修复后如何确认不再复发
处置按风险排序推进：先停止重复写入，再清理已产生的重复数据，最后修正配置。顺序颠倒会让清理过程中继续产生新重复，或让配置修正掩盖尚未定位的原因。
停止重复写入
暂停相关迁移任务或增量调度，保留现场：当前断点位置、最近批次清单、失败重试记录。停止点应选在批次边界，避免中断正在提交的批次造成半批数据。停止后确认没有其他并行任务或分片仍在写入同一对象。
清理重复数据
清理前完成备份，明确去重规则：保留哪一条（通常保留最早写入或字段最完整的一条）、按什么键判定重复、关联数据（评论、附件、状态历史）如何处理。删除或合并时注意关联关系，避免删除主记录后留下孤立关联；审计记录和通知记录是否需要同步处理，应提前确认。清理脚本先在副本环境验证，再在生产执行，并记录清理前后的记录数。
修复后的验证
验证用重放和对比两种方式：重放同一批次，确认目标端记录数不增加、关键字段值正确；对比源端与目标端记录数与主键集合，确认差异在预期范围内；检查断点续跑结果，确认续跑起点与已提交批次不重叠。验证记录应包含批次号、对象类型、修复前后记录数和结论。
复发预防
把本次排查中确认的原因转成回归用例：增量识别条件的边界用例（同一时间戳多条记录、边界时间点、软删除记录）、幂等规则的重放用例、断点与重试的中断续跑用例。对增量任务的捕获数量、目标端记录数变化、断点位置推进设置监控告警，出现异常批次时能定位到具体对象和时间窗口。
在迁移任务与验证结果的跟踪上，可以用 ONES 承载迁移相关的工作项与缺陷记录：把每个重复数据问题登记为工作项，关联对应批次、对象类型和验证结论，修复动作与回归用例挂在同一处，便于在后续批次中复查。ONES 的 Jira 迁移方案覆盖项目、工作项、状态、字段、流程、附件和历史记录的迁移，并把数据完整与业务连续作为迁移目标；这些能力用于承载迁移过程的管理与记录，增量识别与幂等规则的具体实现仍需以实际迁移工具和源端配置为准。
常见问题
源端只变更了一次，目标端却出现多条记录，问题更可能出在哪一环？
这种情况更可能出在写入端或断点重放，而不是增量识别。判断方法是抽样比对重复记录及其相邻记录，确认源端实际变更次数：源端只变更一次而目标端写入多次，说明同一份数据被重复投递，应重点检查幂等规则是否生效、断点续跑是否重放了已提交批次。反过来，如果源端本身被多次判定为变更，问题就在增量识别条件上。
增量任务中断后续跑，发现重复只出现在续跑后的批次，应优先查什么？
优先查断点续传配置。先确认提交与断点更新的先后顺序：先提交数据后更新断点，失败时批次会重放；先更新断点后提交数据，则可能丢数据。再核对断点粒度是否与提交时机匹配，例如按批次记录断点但批次内部分提交，续跑时整批重放。最后检查重试范围是否包含已成功写入的记录，以及多分片是否共享同一断点导致位置回退。
目标端已经加了唯一约束，为什么重复数据还是写进去了？
常见原因是去重键不稳定，唯一约束拦不住。检查迁移过程中是否对键做了截断、大小写转换或空格处理，导致同一记录生成不同键值；复合键的拼接顺序和分隔符是否在所有批次中一致；键本身在源端是否唯一且不随业务变化。键值不一致时，重复记录以不同键值写入，唯一约束自然无法生效。验证方法是将同一批次数据重复提交一次，观察目标端记录数是否变化。
清理已产生的重复数据时，关联数据应该怎么处理？
清理前先完成备份，并明确去重规则：保留哪一条（通常保留最早写入或字段最完整的一条）、按什么键判定重复。删除或合并主记录时同步处理关联数据，例如评论、附件、状态历史，避免删除主记录后留下孤立关联；审计记录和通知记录是否需要同步处理，应提前确认。清理脚本先在副本环境验证，再在生产执行，并记录清理前后的记录数，便于事后核对。
修复配置后，怎样确认重复数据不再产生？
用重放和对比两种方式验证：重放同一批次，确认目标端记录数不增加、关键字段值正确；对比源端与目标端的记录数和主键集合，确认差异在预期范围内；检查断点续跑结果，确认续跑起点与已提交批次不重叠。验证记录应包含批次号、对象类型、修复前后记录数和结论。同时把本次确认的原因转成回归用例，覆盖增量识别边界、幂等重放和断点续跑场景。
