WireGuard数据迁移不是复制文件，是在数据持续产生时换系统——本文给出分佣账本迁移前的4类基准线核验清单、并行期对账周期设计，以及3类迁移失败应急处理方案。
决定放弃WireGuard自建之后，大多数团队第一个动作是找新方案。
第二个动作，才想起来问：那些代理层级、历史分佣记录，怎么搬过去？
这个顺序本身就是问题的开始。选型是一次性决策，可以慢慢比对。数据迁移不是——它发生在系统仍在运行、数据仍在产生的窗口里。
先看这组数： 迁移前至少要核对代理层级、历史结算、在途分佣和异常记录四类基础数据。并行期不应按固定天数套用，而应根据数据规模、日增量、结算周期、差异收敛速度、核验资源和回退能力确定。
为什么迁移比选型更容易出问题
选型时算清楚的成本，迁移时反而容易出问题。为什么？
因为选型是一次性决策，你可以慢慢比、反复算，改主意的成本很低。迁移不是——它是一个持续过程，发生在数据仍在产生的窗口里。
分佣系统的数据不是静态的。新增下注每天在跑，结算每天在跑，分佣计算每天在跑。你不是在"复制一份文件"，你是在数据持续变动的情况下，切换承载这些数据的系统。
这就带出了迁移的核心矛盾：迁移窗口越长，新旧系统的数据差异会越大；窗口越短，核验就越不充分。两边都有代价，没有一个自动正确的答案。
选型阶段的失误，往往在决策之前就能被反复验证纠正。迁移阶段的失误，很多时候是数据已经产生了才发现——层级映射错了，一批分佣记录已经按错误比例结算出去了。这就是为什么迁移需要的不是"聪明的方案"，而是"扎实的核验流程"。
迁移前基准线核验清单：4类数据
机理讲清楚了，现在给清单。
迁移前必须核验的基准数据，分四类。如果你的历史数据分散在多个节点（比如原系统本身就是多个实例拼起来的），应当优先核验代理层级结构——这是最容易出现映射错误、且错误后果最严重的一类。
第一类，代理层级结构
谁在谁下面，分佣比例是多少。这是整个迁移最基础也最容易出错的部分。层级关系一旦映射错误，后续所有的分佣计算都会跟着错。
核验方法：导出原系统的完整层级树，逐层核对每一级的上下级关系和分佣比例设置，与业务侧（了解真实代理关系的运营或财务人员）交叉确认，不能只依赖系统数据单方面导出。
第二类，历史结算记录
已经完成结算的记录，和还在结算流程中的记录，边界在哪里。这个边界如果模糊，会导致同一笔分佣被重复计算，或者遗漏。
核验方法：明确一个"结算截止时间点"，这个时间点之前完成的记录标记为已结算，之后的记录进入待处理分佣核验流程。
第三类，待处理分佣
迁移当天，有没有"卡在中间"的分佣记录——已经产生下注、但分佣计算还没跑完的这批数据。这批数据是迁移过程中最容易被漏掉的一类，因为它既不在"已结算"里，也不在"新系统的起点"里。
核验方法：迁移前应确定业务截止点，并逐类定义在途状态由旧系统还是新系统承接。不能为了迁移而强行提前结算。每条在途记录应具有唯一标识、当前状态、责任系统、后续处理规则和复核证据。
第四类，异常/坏账记录
异常、争议和坏账记录不能被当作正常账目直接导入，也不能为了“账面干净”而删除。应保留原始记录、状态、金额、形成原因、处置责任和证据；尚未解决的项目可进入隔离账或待处理清单，并明确是否影响切换。带着未处理的异常记录进入新系统，等于把旧问题原样搬到新环境里，新系统的账本从第一天就是不干净的。
核验方法：迁移前先跑一轮异常记录扫描，把坏账和异常单独隔离出来，对异常记录建立隔离账或待处理清单，保留原始记录、金额、状态、处置责任和证据，并明确由哪套系统继续承接。不得通过删除或简单“不迁移”掩盖未决责任。
| 数据类型 | 核验方法 | 责任角色 | 最低证据要求 |
|---|---|---|---|
| 代理层级结构 | 导出完整层级树，并与业务侧交叉确认上下级和比例 | 运营、财务、技术 | 源文件、导出范围、确认记录、文件哈希 |
| 历史结算记录 | 确定结算截止点，核对已结算金额和状态分布 | 财务 | 结算单号、金额汇总、截止时间、复核记录 |
| 在途分佣 | 逐类定义责任系统、后续处理规则和唯一事件标识 | 技术、财务 | 状态清单、事件 ID、主处理系统、处理结果 |
| 异常与争议记录 | 隔离异常记录，保留原始状态和后续责任 | 财务、技术、内控 | 原始记录、原因、责任人、处置状态和证据 |
⚠️ 核验清单为通用框架，具体节点视自身系统架构调整。不同历史数据分散程度对应的核验重点不同，需结合自身情况判断优先级。基准线核验不是一次性动作，迁移过程中需持续复核。核验投入的人力和时间成本因数据规模差异较大，需提前评估资源投入。
「迁移不是搬家，是在数据持续产生的情况下换水管。」
并行期不是越长越安全
大多数团队的直觉是：并行期越长，越保险。多跑几天，多核对几遍，总不会错。
数据说的是另一件事。
并行期越长，需要核对的新增事件通常越多，但差异是否扩大以及扩大速度，取决于双写方式、事件顺序、数据模型、同步机制和对账频率。不能仅凭时间长短判断风险——新增数据在两个系统里各走各的路径，时间越长，需要人工核对的分歧点越多，核验的复杂度会明显加速上升，不是简单的"时间乘以工作量"。
在组合式示意场景中，如果两套系统长期同时写入且没有统一事件编号、截止点和差异处理机制，未决差异可能不断累积。因此并行期应以验收条件是否满足为结束依据，而不是无限延长或机械套用固定天数。
| 判断因素 | 需要确认的问题 | 对并行期的影响 |
|---|---|---|
| 数据规模和日增量 | 每天新增多少账本事件，历史数据是否分散 | 决定抽样范围、全量核验工作量和所需资源 |
| 结算周期 | 哪个时间点形成最终结算，是否存在跨期状态 | 决定截止点、观察范围和验收时点 |
| 同步方式 | 单写、影子核验还是受控双写 | 决定重复处理、事件顺序和冲突风险 |
| 差异收敛 | 差异能否解释，数量是否持续下降 | 决定是否具备切换、暂停或重新核验条件 |
| 核验资源 | 技术、财务和运营能否共同复核 | 决定可处理的数据量和异常响应速度 |
| 回退能力 | 旧系统能否恢复运行，增量能否回放 | 决定团队可以承受的切换风险 |
并行期可以设置计划窗口，但最终切换应以验收条件为准。窗口过短可能导致核验不足，窗口过长可能增加维护成本，不存在统一适用的固定天数。
「并行期是核验，不是保险——核验完就该切。」
窗口选多长，不取决于"越长越安心"的直觉，取决于你的核验团队能在多长时间内把该核对的都核对完。核对完了就切，别恋战。
迁移切换前的账本验收矩阵
| 数据集 | 源记录数 | 目标记录数 | 金额或数量合计 | 唯一标识 | 差异及原因 | 责任人 | 验收结论 |
|---|---|---|---|---|---|---|---|
| 代理层级 | 待填写 | 待填写 | 不适用或待填写 | 代理唯一 ID | 待填写 | 运营、技术 | 待验收 |
| 已结算记录 | 待填写 | 待填写 | 待填写 | 结算单号 | 待填写 | 财务 | 待验收 |
| 在途分佣 | 待填写 | 待填写 | 待填写 | 业务事件 ID | 待填写 | 财务、技术 | 待验收 |
| 异常与争议记录 | 待填写 | 待填写 | 待填写 | 异常记录 ID | 待填写 | 财务、内控 | 待验收 |
关键导出文件应记录生成时间、数据范围、文件哈希或其他完整性证明。切换前还应明确允许差异类型、未决差异处理方式、审批角色和回退触发条件。
3类迁移失败的应急处理
框架和清单都有了，说说万一出问题怎么办。
类型1：层级结构还原错误
代理层级关系对不上，分佣比例算错了。这类错误通常在迁移后的第一轮结算周期内暴露——数字和预期不一致。
应急处理：立即暂停新的结算写入并保全现场，由预先指定的责任人判断是继续修复、回退到可运行的旧系统，还是重新执行迁移。只读副本用于核查原始数据，不能作为继续结算的运行系统。重新核验层级映射表。不要在新系统里"边跑边改"，那样容易越改越乱，先回到干净的起点重新核对。
类型2：并行期数据差异超出预期
两套账本的差异越滚越大，超出了核验团队能覆盖的范围。
先暂停扩大写入范围并保全差异样本，确认差异来自映射、事件顺序、双写、重试还是状态模型。只有在差异已经可解释、验收条件明确且责任人批准后，才能决定缩短、延长、暂停或重新开始并行期；不能预设“尽快切换”一定更安全
类型3：坏账/异常记录带入新系统
账单层缺失的坑就是从这里开始的问题如果迁移前没处理干净，这类遗留问题就会原样出现在新系统里。
应急处理：迁移前必须识别并隔离异常记录，但不要求所有争议在切换前强行结案。未决项目应保留原始证据、责任人和后续处理规则，并明确是否影响切换。如果已经迁移完才发现坏账记录带进来了，需要在新系统里单独隔离标记，不能让它混在正常账本里继续计算，同时回头核查是否有其他关联记录也需要同步隔离。
⚠️ 应急处理方式为通用建议，具体执行需结合自身系统架构判断。3类失败类型可能同时出现，需综合判断优先处理顺序。应急预案应在迁移前预先制定，而非出现问题后临时应对。回退或重新核验涉及额外人力时间投入，需在迁移预算中预留缓冲。
迁移验收的标准，本质上就是这3类问题都排查过一遍且没有遗留——不是"新系统跑起来了"就算完成，是"跑起来且账对得上"才算完成。
账本迁完只是数据侧验收，旧系统的访问权限还需要单独收尾。如果原管理员、外包人员或旧设备仍保留私钥、PSK、节点配置或监控入口，数据已经切走也不代表旧环境已经安全退出。权限侧的验收可继续参考旧系统停用后，怎么确认Peer和人员权限都已真正退出。数据迁完以后，原团队职责如何重新归位？若还需要逐项完成旧 Peer 的删除、配置热重载和审计留痕，可参考〔旧环境退出前的 Peer 清理与审计步骤〕。
常见问题
Q1：迁移过程中代理还能正常提现吗？
迁移期间是否继续由原系统处理提现，应在方案设计阶段明确。常见方式包括原系统主写、新系统影子核验，受控双写，或短暂停写后切换。无论采用哪种方式，都必须保证同一笔提现或分佣只由一个确定的主处理系统负责，防止重复计算、重复结算或状态冲突。
这不只是技术问题，也是信任问题——代理层级下的用户对系统稳定性的敏感度很高，提现通道中断即便只是短暂的，也容易引发不必要的猜测。是否保持原通道，应根据主写系统、重复结算风险、业务连续性要求和已批准的迁移方案决定，不能仅以沟通成本作为判断依据。
Q2：历史分佣记录要保留多久？
建议至少保留完整的一个结算周期，加上审计所需时长。具体保留期限因地区法规差异较大，需以当地合规要求为准，不建议自行设定一个固定天数后一刀切清理。
Q3：迁移失败了能不能退回原系统？
能否回退取决于旧系统是否仍具备可恢复运行条件、增量数据是否可以回放，以及切换后由哪套系统继续承担写入。只读归档只能用于查证，不等于可以直接恢复业务处理。回退方案应提前定义触发条件、审批人、写入所有权、增量补录和重新对账步骤。这也是为什么不建议迁移当天就关停原系统——一旦关停，退回路径就没了，出问题只能硬扛。迁移验收完成前，应保留可核查的旧数据、可恢复运行条件和经过验证的回退方案。只读副本可用于查证，但不能单独承担业务回退。
如果你不确定核验清单是不是齐全
基准线核验清单、并行期窗口设计、3类应急处理——框架给完了。
但很多团队卡住的地方，不是不知道要核验什么，而是"核验到什么程度算够"这个判断本身没底。数据规模、团队能力、历史遗留问题的复杂程度，每个团队都不一样，同一份清单在不同团队手里，核验的深度会完全不同。
如果你已经决定迁移，但不确定基准线核验清单是不是齐全——WG.com官网可以帮你过一遍迁移前的核验框架，不替你接管迁移执行。