135 lines
8.3 KiB
Markdown
135 lines
8.3 KiB
Markdown
# SAGA 分布式事务设计汇报
|
||
|
||
> 基于 `gvsdsdk/msync` + `gvsds/apps/msync` 源码分析（2026-08-10）。
|
||
> 涉及文件：`gvsds/apps/msync/transaction.py`、`gvsds/apps/msync/models.py`、`gvsds/apps/msync/local_tx.py`、`gvsdsdk/msync/local_tx.py`、`gvsds/apps/msync/MSYNC.md`。
|
||
|
||
---
|
||
|
||
## 1. 架构定位：双包三层
|
||
|
||
```
|
||
┌────────────────────────────── 主服务器（账本服务器）──────────────────────────────┐
|
||
│ gvsds/apps/msync/transaction.py TransactionManager（Saga 编排引擎） │
|
||
│ gvsds/apps/msync/models.py DistributedTransaction / TransactionStep │
|
||
│ │ 正向: POST {domain}/api/msync/local/execute/ {StepName, payload} │
|
||
│ │ 反向: POST {domain}/api/msync/local/compensate/ {StepName, payload, │
|
||
│ │ ActionResult} │
|
||
└────────┼───────────────────────────────┬─────────────────────────────────────────┘
|
||
▼ ▼
|
||
┌────────────────────────┐ ┌────────────────────────┐
|
||
│ gvsdsdk/msync/ │ │ gvsdsdk/msync/ │
|
||
│ local_tx.py │ │ transaction.py │
|
||
│ LocalTransactionManager│ │ 薄封装 → 转发 gvsds 原生层│
|
||
│ （工作服务本地执行端） │ │ （仅主服务器可用） │
|
||
└────────────────────────┘ └────────────────────────┘
|
||
```
|
||
|
||
关键事实：
|
||
|
||
- **编排端在主服务器，执行端在每个工作服务**，通过账本（`ServiceNode.ServiceDomain`）发现参与服务域名，HTTP 调用本地端点。
|
||
- **SDK 薄封装**：`gvsdsdk/msync/transaction.py` 与 `ogm.py` 仅转发 gvsds 原生层，子服务器无 gvsds 依赖时抛 ImportError；`local_tx.py` 是**真实实现**，子服务器可直接注册步骤处理器。
|
||
- **主服务器本身也当工作服务**：`gvsds/apps/msync/local_tx.py` 从 gvsdsdk 导入 `LocalTransactionManager`，主服务器同样可以参与 Saga 步骤。
|
||
- 双包环形依赖：gvsdsdk（SDK）→ gvsds（主服务器）→ gvsdsdk（local_tx），靠惰性加载（PEP 562）避免初始化时序问题。
|
||
|
||
## 2. 状态机
|
||
|
||
### 事务 7 态（`DistributedTransaction`）
|
||
|
||
```
|
||
Pending(0) ──▶ Running(1) ──▶ Committed(2) （全部步骤成功）
|
||
│
|
||
├─▶ Failed(5) ──▶ Compensating(3) ──▶ Compensated(4)
|
||
│
|
||
└─▶ TimedOut(6) ──▶ Compensating(3) ──▶ Compensated(4)
|
||
```
|
||
|
||
终态集合（`IsTerminal`）= Committed / Compensated / Failed / TimedOut。
|
||
|
||
### 步骤 7 态（`TransactionStep`）
|
||
|
||
```
|
||
Pending(0) ──▶ Running(1) ──▶ Completed(2)
|
||
│
|
||
├─▶ Compensating(3) ──▶ Compensated(4)
|
||
└─▶ Failed(5)（正向失败）/ Skipped(6)（事务取消跳过）
|
||
```
|
||
|
||
### 关键属性
|
||
|
||
- `IsTimedOut`：`CreateTime + TimeoutSeconds`（默认 300s）判定，已终态恒 False。
|
||
- `CanRetry`：`RetryCount < MaxRetries`（默认 MaxRetries=3）。
|
||
|
||
## 3. 核心流程
|
||
|
||
### 3.1 正向执行（`Execute`）
|
||
|
||
1. `select_for_update()` 锁行（防并发推进同一事务）。
|
||
2. 校验状态 ∈ {Pending, Running}；超时则标记 TimedOut 并 `on_commit` 补偿。
|
||
3. 置 Running → 按 `StepIndex` 逐步骤执行：
|
||
- 已 Completed 步骤跳过（断点续跑语义）；
|
||
- `_execute_step`：标记步骤 Running → POST 参与服务 execute 端点 → 返回结果 → 标记 Completed + 保存 StepResult；
|
||
- 任一失败：步骤标记 Failed，记录错误快照，`on_commit` 触发 `Compensate`。
|
||
4. 全部完成 → 事务 Committed。
|
||
|
||
### 3.2 反向补偿（`Compensate`）
|
||
|
||
1. `select_for_update()` 锁行；已 Compensated 直接返回（幂等）。
|
||
2. 事务置 Compensating → **逆序**遍历 `StepStatus=Completed` 的步骤。
|
||
3. 每步 `_compensate_step`：把该步骤原始 `StepResult` 作为 `ActionResult` 随请求传回 → 业务补偿函数可据此幂等回滚。
|
||
4. 补偿成功 → 步骤 Compensated；补偿失败 → 记录 `compensate_error`（**步骤状态停留在 Compensating**）。
|
||
5. 若存在仍在 Compensating 的步骤 → 事务 Failed；否则 Compensated。
|
||
|
||
### 3.3 超时与兜底
|
||
|
||
- 双保险：执行中逐步骤检测 `IsTimedOut`（`on_commit` 补偿）+ `CheckTimeouts()` 轮询兜底（需 Celery 定时任务触发）。
|
||
|
||
### 3.4 重试
|
||
|
||
- **手动重试**：`RetryStep(transaction_code, step_index)` 仅允许 Failed/Pending 步骤，校验 `CanRetry`，重跑 action。
|
||
- **注意**：Execute 正向流程中**没有自动重试**逻辑——步骤失败直接进入补偿，`MaxRetries` 仅约束手动重试次数。
|
||
|
||
## 4. 传输层设计
|
||
|
||
| 项 | 配置 |
|
||
|---|---|
|
||
| 会话 | 模块级 `requests.Session`，连接池 10 |
|
||
| TLS | 显式 `verify=True`，支持 `REQUESTS_CA_BUNDLE` 环境变量自定义 CA |
|
||
| 重试 | 502/503/504 自动重试 3 次，backoff 0.5s，仅 POST |
|
||
| 超时 | 单次请求 30s |
|
||
| 鉴权 | `Authorization: Service <AccessToken>`（HMAC 验权签发，2h 有效） |
|
||
| 响应契约 | 兼容 `{code:200, data}`（DRF）与 `{success, result, error}`（本地管理器） |
|
||
|
||
## 5. 设计亮点
|
||
|
||
1. **远程编排 + 本地执行彻底解耦**：子服务器仅依赖 SDK `local_tx` 注册处理器即可接入，无需理解编排。
|
||
2. **补偿带回 ActionResult**：补偿函数拿到原始执行结果，可精确、幂等地回滚（如按返回的 user_uuid 删除）。
|
||
3. **行锁防并发**：Execute / Compensate 均 `select_for_update`。
|
||
4. **on_commit 补偿**：补偿在主事务提交后触发，避免"正向已回滚却补偿"的错乱。
|
||
5. **断点续跑**：Execute 跳过已完成步骤，支持中途失败后整体重跑推进。
|
||
6. **协议双兼容**：`_call_service` 同时解析两套响应契约。
|
||
|
||
## 6. 缺陷与风险
|
||
|
||
| 等级 | 问题 | 位置 | 说明 |
|
||
|---|---|---|---|
|
||
| 高 | 响应非 JSON 时事务卡死 | `_call_service`（transaction.py L538-566） | `resp.json()` 解析失败抛 JSONDecodeError 未捕获 → Execute 中断 → 事务永久停 Running，不触发补偿，需等 300s 超时 |
|
||
| 高 | 补偿失败后无法重试补偿 | `Compensate`（L256-314） | 补偿异常时步骤状态停在 Compensating（非 Completed），再次 Compensate 查不到它 → 永远补不回来，事务 Failed 只能人工处理，无 re-compensate 入口 |
|
||
| 中 | MaxRetries 无自动重试 | `Execute`（L211-244） | 失败直接补偿，`CanRetry` 只在手动 RetryStep 生效；RetryStep 无 `select_for_update`，并发重试有竞态 |
|
||
| 中 | 无步骤间数据流 | `Execute`/`_execute_step` | `StepResult` 不注入后续步骤 payload；TransactionPayload 创建后不参与执行。无法表达"A 步骤输出是 B 步骤输入"的链式场景 |
|
||
| 中 | 超时以 CreateTime 起算 | `models.py IsTimedOut` | 非"最近活动空闲超时"，10 步慢事务总预算仅 300s，无活动推进重置机制 |
|
||
| 低 | TransactionResult 恒空 | `Execute`/`Compensate` | 模型有字段但从不写入，`GetDetail().Result` 永远 null |
|
||
| 低 | 幂等依赖业务自觉 | `_call_service` | 无全局幂等键，崩溃窗口内重复执行 action 的副作用靠业务方补偿兜底 |
|
||
|
||
## 7. 改进建议（按优先级）
|
||
|
||
1. `_call_service` 捕获 JSON 解析/异常 → 统一转 `StepExecutionError`，保证失败必进补偿链路。
|
||
2. 补偿失败步骤状态改为 Failed 并提供 `RetryCompensate` 入口（复用 RetryStep 骨架 + 行锁）。
|
||
3. `RetryStep` 补 `select_for_update`；若需自动重试，在 Execute 循环内按 `CanRetry` 内联重试。
|
||
4. 支持步骤结果注入下一步 ActionPayload（可选项，向后兼容）。
|
||
5. 超时改为基于 `UpdateTime` 的空闲判定或提供事务级 heartbeat。
|
||
6. Execute/Compensate 末尾统一写入 `TransactionResult` 汇总。
|
||
|
||
---
|
||
|
||
*汇报人：TraeCode（2026-08-10）*
|