ecm_sync_system/docs/operations.md

运维与排障手册（业务视角）

本文档聚焦两件事：

• 出错时先看哪里。
• 日志里的状态到底代表什么业务问题。

1. 先看什么（快速定位）

1. 看运行日志（sync_log）：
   • 重点关注 状态机流转、reason=、depends=[...]。
2. 看持久化数据库：
   • 重点字段：binding_status、action、status、error。
3. 对照状态机文档：
   • docs/state_machine.md
   • docs/node_state_definition.md

2. 阶段化排障

2.1 bind 阶段

常见表现：节点停在 S03/S04/S05/S13。

• S03(ABNORMAL)：节点数据损坏或核心绑定异常。
• S04(WARNING)：自动绑定关闭、键缺失、歧义等不可自动处理情况。
• S05(DEPENDENCY_ERROR)：依赖节点不存在或依赖状态不正常。
• S13(PEER_CREATING)：对侧创建进行中，尚未提交完成。

典型日志：

• reason=依赖项不满足 | depends=[company_id status=peer_creating -> not_normal]

业务解释：

• 上游依赖还没进入 NORMAL，下游业务会被严格阻断。

2.2 create 阶段

常见表现：节点长时间停在 S13 或 S10C。

• S13：已判定需要创建，但创建提交未完成。
• S10C：CREATE 异步执行中。
• S12C：CREATE 失败。

优先检查：

• API 侧是否返回任务 ID 与成功回执。
• 轮询参数（poll_max_retries / poll_interval）是否过小。

2.3 update 阶段

常见表现：节点进入 S08 或 S12U。

• S08(PRECONDITION_FAILED)：前置条件失败（如缺 data_id、依赖 ID 解析失败）。
• S12U：UPDATE 调用失败。
• S14：UPDATE 被 handler 降级为 NONE 并跳过。

优先检查：

• update_direction 是否符合预期。
• 目标节点是否具备 data_id。

3. 常见配置误区与症状

• auto_bind=false
  • 症状：MISSING 节点更容易进入 WARNING，不会走自动创建识别。
• local_orphan_action=none + remote_orphan_action=none + update_direction=none
  • 症状：该类型会被整体跳过，常被误以为“配置没生效”。
• load_mode=persisted_only
  • 症状：数据只来自持久化，不主动拉取新数据。
• update_direction=none
  • 症状：不做 update，即使有差异也不会提交更新。

4. 推荐操作顺序

1. 先用 run_profiles/preset/jsonl_to_jsonl.default.yaml 跑通基线。
2. 再切到 run_profiles/*.local.yaml 做最小覆盖。
3. 每次只改一类字段（比如只改 project 的依赖策略）。
4. 改完看一次 sync_log，确认状态流转与预期一致。

5. UI 排障（可选）

1. 启动：python -m ui.main --host 127.0.0.1 --port 8765
2. 打开：http://127.0.0.1:8765
3. 在“运行与日志”查看实时状态变化。
4. 在“记录与数据库”检查节点状态与绑定记录。