工具链同步失败时，排查过程往往散落在聊天记录、日志截图和个人记忆里，换人接手就要从头问起。这份模板把一次同步故障从发现到复盘所需的记录收进一张表，覆盖故障基本信息、同步任务与对象、失败现象与复现条件、排查过程与证据、根因判定、处置与恢复验证、影响与复盘七组字段。它适用于代码仓库、制品库、需求或缺陷系统之间的定时与触发式同步，目标是先让问题可复现、可跟踪，再支撑后续复盘。
要点总览（TL;DR）
- 模板以一张可复制的空白表为核心，覆盖故障基本信息、同步任务与对象、失败现象与复现条件、排查过程与证据、根因判定、处置与恢复验证、影响与复盘七组字段。
- 必填项围绕可复现、可跟踪、可复盘设置：记录编号、发现时间与发现人、同步任务与对接对象、失败现象与首次失败时间、排查时间线与关键证据、根因与恢复验证结果。
- 填写时对接对象写到具体实例和仓库层级，错误码原样抄录，复现结果明确标注稳定复现、偶发或未能复现，证据以附件路径存放。
- 模板可按同步链路数量裁剪或拆分字段，新增字段优先保留能帮助复现与定位的信息，并在文件头部标注版本号与生效日期。
- 排查记录需要多人协作与状态跟踪时，可承载为可跟踪的工作项，让字段成为可筛选、可统计的结构化信息。
可复制空白排查记录表
下表可直接复制到文档或表格工具中使用。填写时按分区顺序推进：前四组在排查阶段边查边填，根因与处置在定位后补齐，影响与复盘在恢复后完成。表格中的“对接对象”一栏用于写明同步两端的系统与仓库，例如 GitLab 项目与需求管理工具之间的单向同步，或 SVN 仓库与构建系统之间的变更拉取。
| 分区 | 字段 | 填写内容 |
|---|---|---|
| 一、故障基本信息 | 记录编号 | |
| 发现时间 / 发现人 | ||
| 发现途径 | ||
| 故障等级 | ||
| 当前状态 | ||
| 关联工单 / 事件链接 | ||
| 二、同步任务与对象 | 同步任务名称 / ID | |
| 对接对象（源系统与目标系统） | ||
| 同步方向 | ||
| 触发方式与周期 | ||
| 同步范围 | ||
| 最近一次成功时间 | ||
| 三、失败现象与复现条件 | 失败现象描述 | |
| 错误码 / 错误信息 | ||
| 首次失败时间点 | ||
| 复现步骤 | ||
| 复现结果（是否稳定复现） | ||
| 四、排查过程与证据 | 排查时间线 | |
| 已排除的方向 | ||
| 关键日志片段 | ||
| 请求标识 / 批次号 | ||
| 证据附件位置 | ||
| 五、根因判定 | 根因描述 | |
| 判定依据 | ||
| 根因类别 | ||
| 六、处置与恢复验证 | 临时处置动作 | |
| 根治处置动作 | ||
| 处置执行人与时间 | ||
| 恢复验证方式与结果 | ||
| 数据一致性核对结果 | ||
| 七、影响与复盘 | 影响范围 | |
| 影响时长 | ||
| 改进项与责任人 | ||
| 复盘结论与日期 |
表格保留“证据附件位置”一栏，用于放置日志文件、截图或抓包文件的存放路径，避免把大段日志直接粘进记录正文。若一次故障涉及多个同步任务，建议每个任务单独建一条记录，再用“关联工单”字段互相引用。
字段说明：每个栏位记录什么
字段说明的作用是让不同的人填出同一口径的记录。下面按七个分区逐项解释，重点放在容易写偏的栏位。
故障基本信息
记录编号建议采用“日期+序号”的格式，便于检索。发现途径写明是监控告警、使用方反馈还是例行巡检发现，这决定了后续是否需要补充监控覆盖。故障等级按团队既有分级填写，没有分级标准的团队可先按“阻断业务 / 影响部分数据 / 仅告警”三档粗略标注。当前状态用“排查中、已定位、已恢复、已复盘”四个值，方便快速筛选未闭环记录。
同步任务与对象
对接对象要写到具体实例和仓库层级，例如“GitLab 某项目仓库 → 需求管理系统的需求条目”，或“SVN 某目录 → 构建系统的变更记录”。同步方向写明单向还是双向，双向同步的故障往往需要分别记录两个方向的失败情况。触发方式区分定时、事件触发和手动触发，定时任务还要写周期。同步范围说明是全量还是增量、涉及哪些分支或目录。最近一次成功时间用于界定故障窗口，是判断影响时长的基准。
失败现象与复现条件
失败现象描述写可观察的事实，例如“目标系统未出现新提交记录”“同步任务状态停留在运行中”。错误码和错误信息原样抄录，不要改写或概括。复现步骤写成可执行的动作序列，注明使用的测试数据或提交，复现结果明确写“稳定复现”“偶发”或“未能复现”，偶发问题要补充出现频率。
排查过程与证据
排查时间线按“时间点—动作—观察结果”逐条记录，保留走过的弯路，这对复盘同样有价值。已排除的方向写明排除依据，避免后来者重复验证。关键日志片段只摘录与失败直接相关的若干行，并标注日志来源与时间戳。请求标识或批次号是串联两端日志的关键，GitLab 侧的提交哈希、SVN 侧的版本号、同步任务自身的批次号都应记录。证据附件位置写清存放路径或链接。
根因判定、处置与复盘
根因描述要落到具体机制，例如“源端分支保护规则变更导致同步账号无读取权限”，判定依据写支撑该结论的证据。根因类别可按权限、网络、配置、数据格式、目标端限流等归类，便于统计。处置分临时与根治两栏：临时处置用于先恢复同步，根治处置解决根因。恢复验证要写清验证方式，例如“手动触发一次增量同步并核对目标端记录数”，数据一致性核对结果记录两端条数或关键字段的比对结论。影响范围写受影响的业务对象与使用方，改进项要带责任人和预期完成时间。
必填与选填：哪些字段不能空
必填项的设计目标是保证记录可复现、可跟踪、可复盘。以下字段在记录创建时就应填写，缺失会导致记录无法支撑后续工作。
| 类别 | 字段 | 作用 |
|---|---|---|
| 必填 | 记录编号、发现时间、发现人、当前状态 | 建立记录身份与跟踪入口 |
| 必填 | 同步任务名称 / ID、对接对象、同步方向 | 定位故障发生在哪条链路的哪个方向 |
| 必填 | 失败现象描述、首次失败时间点 | 界定故障窗口，支撑影响评估 |
| 必填 | 排查时间线、关键日志片段或错误码 | 保留证据，支持他人接手 |
| 必填 | 根因描述、处置动作、恢复验证结果 | 闭环判定，防止未恢复即关闭 |
| 选填 | 故障等级、关联工单 | 有分级制度或工单系统时填写 |
| 选填 | 触发方式与周期、同步范围、最近一次成功时间 | 定时任务和增量同步场景建议填写 |
| 选填 | 复现步骤与复现结果 | 偶发问题或需他人复现时必填 |
| 选填 | 已排除方向、请求标识 / 批次号 | 多端联查或排查周期较长时填写 |
| 选填 | 影响范围、影响时长、改进项、复盘结论 | 达到复盘条件的事件填写 |
字段缺失时的处理约定建议写进模板说明：必填项暂时无法获取的，先填“待补充”并注明获取途径和责任人，不允许留空；选填项不适用的填“不适用”，与“未填写”区分开。记录关闭前由处理人自查必填项是否齐全，复盘环节再核对选填项是否补齐。
填写示例：一次同步失败记录的完整样例
以下为演示情景，用于说明各字段的填写粒度，不对应真实系统事件。
| 分区 | 字段 | 示例内容 |
|---|---|---|
| 一、故障基本信息 | 记录编号 | SYNC-20240612-03 |
| 发现时间 / 发现人 | 2024-06-12 09:20 / 值班同学 A | |
| 发现途径 | 监控告警：同步任务连续 3 次失败 | |
| 故障等级 | 影响部分数据 | |
| 当前状态 | 已复盘 | |
| 关联工单 | OPS-1842 | |
| 二、同步任务与对象 | 同步任务名称 / ID | gitlab-to-req-sync / job-217 |
| 对接对象 | GitLab 项目 web-console 的 main 分支 → 需求管理系统“研发需求”条目 | |
| 同步方向 | 单向：GitLab → 需求管理系统 | |
| 触发方式与周期 | 定时，每 15 分钟一次 | |
| 同步范围 | 增量，按提交时间拉取 | |
| 最近一次成功时间 | 2024-06-12 08:45 | |
| 三、失败现象与复现条件 | 失败现象描述 | 任务状态为失败，目标端未出现 08:45 之后的提交记录 |
| 错误码 / 错误信息 | HTTP 403，提示同步账号无权访问该仓库 | |
| 首次失败时间点 | 2024-06-12 09:00 批次 | |
| 复现步骤 | 使用同步账号调用仓库读取接口，观察返回码 | |
| 复现结果 | 稳定复现，均返回 403 | |
| 四、排查过程与证据 | 排查时间线 | 09:25 查看任务日志，确认 403；09:40 核对同步账号权限，发现账号已不在项目成员列表；09:55 查询审计记录，确认 08:50 有成员权限调整操作 |
| 已排除的方向 | 网络连通性正常；目标端服务状态正常；任务配置未变更 | |
| 关键日志片段 | 09:00:03 ERROR sync job-217 fetch repo failed: 403 Forbidden | |
| 请求标识 / 批次号 | 批次 batch-20240612-0900；提交哈希 a1b2c3d | |
| 证据附件位置 | 共享文档 /sync/20240612/ 下日志与审计截图 | |
| 五、根因判定 | 根因描述 | 项目成员权限调整时移除了同步账号，导致读取仓库被拒 |
| 判定依据 | 审计记录显示 08:50 权限变更，与首次失败时间吻合；恢复权限后接口返回正常 | |
| 根因类别 | 权限配置 | |
| 六、处置与恢复验证 | 临时处置动作 | 将同步账号重新加入项目成员，赋予只读权限 |
| 根治处置动作 | 在权限变更检查项中加入同步账号核对；为同步账号设置独立服务账号并纳入变更通知 | |
| 处置执行人与时间 | 同学 B，2024-06-12 10:10 | |
| 恢复验证方式与结果 | 手动触发增量同步，10:20 批次成功，目标端出现对应提交记录 | |
| 数据一致性核对结果 | 核对 08:45 至 10:20 的提交数，源端 7 条、目标端 7 条，一致 | |
| 七、影响与复盘 | 影响范围 | 该项目的需求条目关联信息延迟约 80 分钟 |
| 影响时长 | 08:45 至 10:20 | |
| 改进项与责任人 | 权限变更检查项补充，责任人同学 B，6 月 20 日前完成 | |
| 复盘结论与日期 | 同步账号应作为服务账号单独管理，2024-06-13 复盘确认 |
样例中每个字段与空白模板一一对应，可直接作为填表参照。SVN 场景的写法相同，只需把提交哈希换成版本号，把分支换成目录路径。
调整与维护：让模板适配不同团队
模板长期可用的前提是随同步链路变化同步调整。裁剪时先看同步对象数量：只维护一两条链路的团队，可以把“同步范围”“触发方式与周期”合并为一栏；对接对象多、方向复杂的团队，则建议把“对接对象”拆成源系统、目标系统、仓库或目录三栏，并增加“同步账号”字段。团队规模影响的是记录承载方式，多人轮值排查时，记录需要放在大家都能访问的位置，并保留修改痕迹。
新增字段遵循两条取舍原则：能帮助复现或定位的字段优先保留，例如请求标识、批次号；只服务单次事件的描述性内容放到附件，不占表格栏位。删除字段前确认它是否被复盘统计使用，影响范围、根因类别这类用于汇总分析的字段建议长期保留。
版本维护上，建议在模板文件头部标注版本号和生效日期，字段增删时同步更新字段说明，避免说明与表格脱节。历史记录按季度归档，归档时保留原始字段结构，不随新版本回改。每半年抽查若干条已关闭记录，检查必填项完整率和根因分类的一致性，据此决定下一版调整方向。
当排查记录需要多人协作、与工单联动并保留处理状态时，可以把这张表承载为可跟踪的工作项：记录创建后进入待处理状态，排查过程以评论和时间线补充，处置完成后附上恢复验证结果再关闭。ONES 的工作项与文档能力可以承担这类记录与流转，让模板中的字段成为可筛选、可统计的结构化信息，复盘时按根因类别和影响范围汇总，减少人工翻找。
常见问题
同步失败只是偶发、无法稳定复现时，记录该怎么填？
复现结果一栏如实写“偶发”或“未能复现”，并在复现步骤中补充出现频率和已观察到的触发条件，例如特定时间段、特定提交量或特定分支。关键日志片段和请求标识、批次号要尽量多留几条，便于后续比对。偶发问题不建议在未定位根因时直接关闭记录，可先转为观察状态，约定观察周期后再判定。
一次故障涉及多条同步链路，是合并成一条记录还是分开建？
建议每个同步任务单独建一条记录，用“关联工单”字段互相引用。合并记录会让对接对象、同步方向和恢复验证混在一起，影响时长和影响范围也难以分别界定。如果多条链路的失败由同一根因引起，可在各条记录的根因描述中引用主记录编号，复盘时再合并统计。
必填项在记录创建时拿不到，能不能先留空？
不建议留空。模板约定必填项暂时无法获取时填“待补充”，并注明获取途径和责任人；选填项不适用时填“不适用”，与“未填写”区分开。记录关闭前由处理人自查必填项是否齐全，复盘环节再核对选填项是否补齐，这样记录状态始终可判断。
SVN 场景使用这份模板需要改哪些字段？
表格结构不用改，只需调整填写口径：请求标识一栏用 SVN 版本号替代提交哈希，同步范围用目录路径替代分支，对接对象写到具体仓库与目录层级。若团队只维护少量 SVN 链路，可把“触发方式与周期”和“同步范围”合并为一栏，减少填写负担。
模板用了一段时间后，怎么判断哪些字段该删、哪些该加？
先看字段是否被实际使用：长期填“不适用”或空白的选填项可以考虑删除；排查中反复需要临时补充的信息，例如同步账号、目标端限流状态，可以升级为正式字段。影响范围、根因类别这类用于汇总分析的字段建议长期保留。调整后同步更新字段说明并标注版本号，历史记录按原结构归档，不回改。
