增量迁移出现重复数据，排查时先别急着删记录。重复通常来自三条线索：增量识别口径把已迁移记录再次选中、写入端缺少幂等键导致重复落库、断点续传或失败重跑时水位线与批次状态不一致。本文按“先界定范围、再逐条验证原因、最后处置与验证”的顺序展开，覆盖研发数据内容层面的重复问题，工作流与插件行为迁移、整体验收切换不在讨论范围内。
要点总览（TL;DR）
- 先界定重复的形态与范围：区分整条记录重复、同一业务对象多条记录、字段级重复，统计发生批次、对象类型与占比，并确认是否已被下游引用。
- 按三条主线逐条验证：增量识别口径（识别字段与水位线）、写入端幂等（幂等键与唯一约束）、断点续传与重跑（断点粒度、恢复起点、并发与补跑）。
- 用数量对比区分原因：目标端新增数明显多于源端变更数且与上一批重合，多为识别口径重判；幂等键相同、内容一致且源端仅一次变更，多为写入端问题。
- 处置按顺序设停止点：冻结增量任务、标记而非直接删除、修正配置、单批次小范围重放验证，清理前完成备份并明确回滚方式。
- 修复后按批次核对记录数与唯一键，连续观察若干增量批次，并把幂等键、水位线提交时机、断点粒度纳入迁移前配置检查项。
重复数据的症状与影响范围
排查的第一步是把“重复”描述成可统计的事实。同样是重复，整条记录重复、同一业务对象多条记录、字段级重复，指向的原因往往不同，混在一起看容易误判。
常见的三种形态可以这样区分：整条记录重复，指源端一条记录在目标端出现两条及以上，字段值基本一致；同一业务对象多条记录，指一个需求或缺陷在目标端被拆成多条，可能字段各有缺失或新旧版本并存；字段级重复，指记录本身唯一，但某个多值字段（如评论、附件、标签）被重复追加。第三种最容易被忽略，因为按记录数统计时看不出异常。
接着确认重复集中在哪次增量批次、哪些对象类型。研发数据里需求、缺陷、任务、评论的写入路径可能不同，如果重复只出现在评论上，排查重点应放在评论的追加逻辑；如果需求、缺陷、任务同时成批重复，更可能是批次级问题。统计重复数量与占比，能帮助判断性质：少量偶发通常与单次失败重试有关，成批出现则更像水位线回退或整批重放。
最后明确影响边界：重复数据是否已写入目标系统并被下游引用，比如是否已进入报表、是否已被其他工作项关联、是否已触发通知。这一步决定后续处置能否直接清理。建议先产出一份范围清单，至少包含重复类型、发生批次、对象类型、数量与占比、下游引用情况五项，后续每个原因假设都用这份清单去对照。
增量识别口径的排查与证据
增量识别负责回答“这次该迁哪些数据”。如果识别条件把已迁移记录再次纳入，写入端再严谨也会产生重复。排查时先确认识别依据是什么，再核对水位线，最后用数字对比验证。
常见的识别依据有四类，各自的失效方式不同：按更新时间识别，源端批量更新、状态回刷、时区或精度差异都可能让旧记录的时间戳变新，被重新选中；按自增ID识别，源端数据回灌或ID不连续时容易漏判或重判；按版本号识别，版本号回退或多系统写入同一对象时判断失准；按变更日志识别，日志保留窗口不足或消费位点记录错误会导致重复消费。先确认实际用的是哪一种，再针对性地找证据。
水位线是排查的核心证据。需要找到水位线记录在哪里（配置文件、数据库表、任务状态存储），核对它的值是否与上一批实际处理到的位置一致。重点看三种情况：水位线在批次成功前就被提交，失败重跑时从更靠前的位置开始；水位线被人工修改或回退；多实例各自持有水位线，互相覆盖。
用同一时间窗口做数量对比是最直接的验证：取源端该窗口内的变更记录数，与目标端该批次新增记录数比较。两者接近说明识别口径基本正常，重复更可能出在写入端；目标端明显多于源端，且多出的部分与上一批记录重合，则识别口径重判的可能性较大。核对表建议记录识别字段、水位线值、源端变更数、目标端新增数四列，按批次逐行填写。
幂等规则与写入端去重检查
写入端的问题表现为“同一份数据被写了两次”。判断方法是看目标端是否具备幂等能力，以及幂等键是否选得合理。
幂等键要稳定且唯一。源系统唯一ID通常最可靠；业务编号在跨项目或历史数据中可能重复；组合键（如项目ID加业务编号）能提高唯一性，但要求各字段在迁移中不被改写。检查时抽取若干重复记录，看它们的幂等键是否相同：键相同却产生两条记录，说明幂等逻辑未生效；键不同，说明键的选取或生成规则有问题。
目标端的唯一约束或去重逻辑是否启用，决定了冲突时的行为。需要确认冲突处理方式是覆盖、跳过还是新增。如果配置为新增，重试就会直接产生重复；如果配置为覆盖，还要确认覆盖的字段范围，避免旧值覆盖新值。
批量写入失败后的重试行为是高频原因。整批重放时，批次中已成功的记录会被再次写入，而失败点之前的记录没有回滚。排查时查看失败批次的日志，确认重试是从批次开头还是从失败记录开始。同一对象多次更新被拆成多条记录的情况，则要检查合并策略：是按幂等键合并保留最新，还是逐条追加。
区分识别口径问题与写入端问题，可以用一个简单判据：如果重复记录的幂等键相同、内容一致，且源端该窗口只有一次变更，问题在写入端；如果重复记录对应源端两次变更或本不该被选中的旧记录，问题在识别口径。两者同时存在时，先修识别口径，再补幂等，否则重复会持续产生。
断点续传与重跑配置的排查
断点续传和重跑造成的重复，特征是重复集中在任务中断点附近，或出现在调度时间重叠的批次里。
断点记录粒度决定重复风险。按批次记录断点，恢复时整批重来，批次内已写入的记录会重复；按对象记录，重复范围缩小到一个对象；按单条记录，重复风险最低，但状态管理成本更高。排查时确认断点粒度，并核对中断后恢复的起点是否回退到了批次开头。
并发与调度重叠同样会产生重复。同一任务多实例并发执行时，两个实例可能处理同一批数据；定时任务执行时间超过调度间隔，前后两次触发重叠，也会造成同一窗口被处理两次。手工补跑与自动调度同时运行是常见场景：补跑任务未暂停调度，两个流程各自读取水位线并写入。核查记录应包含断点粒度、恢复起点、是否存在并发实例、补跑与调度的时间关系。
三类原因的对照可以整理成下表，便于按症状快速定位：
| 原因类别 | 典型症状 | 验证证据 | 处置方向 |
|---|---|---|---|
| 增量识别口径 | 重复记录与上一批重合，成批出现 | 水位线值异常、源端变更数少于目标端新增数 | 修正识别条件，提交水位线的时机后移到批次成功后 |
| 写入端幂等 | 同一幂等键出现多条记录，内容一致 | 幂等键相同、唯一约束未启用、冲突策略为新增 | 启用唯一约束，明确覆盖或跳过策略，重试改为从失败点继续 |
| 断点与重跑 | 重复集中在中断点附近或调度重叠时段 | 断点粒度为批次、恢复起点回退、存在并发实例 | 细化断点粒度，恢复前校验已写入范围，补跑时暂停调度 |
处置步骤与风险边界
确认原因后按顺序处置，每一步都设停止点，避免在排查未完成时扩大影响。
- 冻结增量任务。暂停相关增量任务和定时调度，记录暂停时的水位线与批次号，防止重复继续累积。
- 标记而非直接删除。对已产生的重复数据打标记（如添加标签、写入排查记录表），保留原始记录和批次信息，作为回溯依据。
- 修正识别条件或水位线。根据前两节的结论修改识别字段、水位线提交时机或幂等配置，修改内容留档。
- 小范围重放验证。选一个单批次、数据量可控的范围重放，对比源端与目标端记录数和唯一键，确认不再产生重复后再放开全量。
- 清理重复数据。清理前完成备份，明确删除范围（按批次、按对象类型或按标记）、保留哪一条（通常保留最新或最早写入的一条，需与业务确认），并写明回滚方式。
- 评估下游影响。重复数据若已被报表、关联工作项或通知引用，先评估关联影响，必要时同步修正下游引用，再执行清理。
需要特别注意的是，删除操作不可逆，备份与回滚方案必须在执行前就绪；涉及目标端已有下游引用时，清理顺序应先处理引用关系，再删除记录。
在迁移任务的组织层面，可以把批次号、水位线、重放记录和复核结论放在同一处跟踪，让处置过程可追溯。ONES 的 Jira 迁移方案围绕项目、工作项、状态、字段、流程、附件和历史记录进行迁移，并把数据完整、业务连续和系统稳定作为迁移目标，建议在正式迁移前确认数据范围与系统适配。排查和处置阶段产生的批次记录、复核结论，可以借助工作项或文档留痕，供后续复盘使用；增量识别与断点机制的具体配置，以实际迁移工具的能力为准。
修复后的验证与复发预防
修复是否有效，要用数据说话，而不是看单次重放没有报错。
验证分三层：第一层是对比源端与目标端记录数，按对象类型分别统计，差异应能逐条解释；第二层是抽样核对唯一键，从重复高发批次中抽取记录，确认幂等键在目标端唯一；第三层是检查重复率，修复后新增批次的重复记录数应为零，若不为零需回到对应环节重新排查。验证结果建议按批次记录，包含批次号、源端记录数、目标端新增数、重复数、结论五项。
单批验证通过后，连续观察若干增量批次的重复情况，覆盖正常增量、失败重试、调度重叠等场景，确认修复在异常路径下同样有效。
复发预防落在配置检查项上，迁移前逐项确认：
- 幂等键已选定并验证唯一性，目标端唯一约束已启用，冲突处理策略明确；
- 水位线在批次成功后才提交，存储位置单一，避免多实例各自维护；
- 断点粒度与恢复起点规则已确认，恢复前校验已写入范围；
- 补跑流程要求先暂停自动调度，避免并发；
- 迁移监控中加入重复率与批次记录数异常告警，设定阈值和通知对象。
把这些检查项纳入迁移前的配置核对清单，并在每次调整识别条件或调度配置后重新过一遍，可以把重复问题控制在发生之前。
常见问题
增量迁移中，怎么快速判断重复是识别口径问题还是写入端问题？
取重复记录做两项核对即可初步分流。第一，看重复记录对应的源端变更次数：如果源端在该时间窗口只有一次变更，而目标端出现两条及以上记录，问题更可能在写入端；如果重复记录对应源端两次变更，或包含本不该被选中的旧记录，问题更可能在识别口径。
第二，看幂等键：重复记录的幂等键相同且内容一致，说明写入端幂等未生效；幂等键不同，说明键的选取或生成规则有问题。两者同时存在时，先修识别口径再补幂等，否则重复会持续产生。
水位线在批次成功前就提交，会带来什么后果？
水位线提前提交，意味着任务记录的“已处理位置”比实际写入位置更靠前。一旦该批次中途失败并重跑，恢复起点会落在实际未完成的位置之后，造成部分记录漏迁；如果重跑逻辑改为从批次开头重放，则已成功写入的记录会被再次写入，形成重复。
排查时核对水位线值与上一批实际处理到的位置是否一致，并把提交时机后移到批次成功之后，同时确认水位线只有一个存储位置，避免多实例各自维护、互相覆盖。
手工补跑和定时调度同时运行，为什么容易产生重复？
补跑任务和自动调度各自读取水位线、各自写入目标端，两个流程处理同一时间窗口时，同一批数据会被写入两次；如果写入端没有启用唯一约束或幂等逻辑，重复会直接落库。
处置上要求补跑前先暂停自动调度，补跑完成并核对已写入范围后再恢复调度。同时在迁移监控中关注同一窗口的批次记录数，出现异常增量时及时告警。
重复数据已经被报表或关联工作项引用，还能直接清理吗？
不建议直接清理。先评估关联影响：确认哪些报表、工作项关联或通知引用了重复记录，明确保留哪一条（通常保留最新或最早写入的一条，需与业务确认），再处理引用关系，最后删除多余记录。
清理前完成备份，明确删除范围（按批次、按对象类型或按标记）与回滚方式。删除操作不可逆，备份与回滚方案必须在执行前就绪。
修复后只重放一个批次没有报错，可以认为问题解决了吗？
单批重放通过只是第一层验证。还需要按对象类型对比源端与目标端记录数，差异应能逐条解释；从重复高发批次抽样核对幂等键在目标端唯一；确认修复后新增批次的重复记录数为零。
之后连续观察若干增量批次，覆盖正常增量、失败重试、调度重叠等场景，确认修复在异常路径下同样有效，再把相关配置纳入迁移前的检查清单。
