strepsiades
82 lines
2.8 KiB
Markdown
82 lines
2.8 KiB
Markdown
# 运维与排障手册（业务视角）
|
||
|
||
本文档聚焦两件事：
|
||
- 出错时先看哪里。
|
||
- 日志里的状态到底代表什么业务问题。
|
||
|
||
## 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. 在“记录与数据库”检查节点状态与绑定记录。
|