ADR-006 v2.0: Sidecar V2 architecture revision based on review feedback

Incorporated feedback from 4 reviewers:
- 徐聪: AES key management, emergency channel, concurrency control, DDL indexes
- 陆怀瑾: P0 phase, schedule buffer, deployment topology, V1 compat checklist
- 严维序: SQLite backup, monitoring, cooldown persistence, port plan, rollback
- 沈路明: queue design, health check, per-model RPM decision, key validation, dashboard panels

Key additions:
+ Queue flow control design (FIFO + priority, capacity 500, REJECT overflow)
+ Provider health check (active probe + passive stats hybrid)
+ Per-model RPM decision (Provider-level V2, Model-level V3)
+ Key validation on add (test call with error feedback)
+ AES key management (SIDECAR_ENCRYPTION_KEY env var, backup SOP)
+ Emergency channel (10% RPM during full cooldown)
+ SQLite backup strategy (cron .backup, 7-day retention)
+ SQLite monitoring Prometheus metrics (db_size, wal_size, integrity)
+ Full DDL with indexes (ON CONFLICT, BEGIN IMMEDIATE patterns)
+ Dashboard panel list (5 panels: status, trends, history)
+ V1 compatibility checklist (13 items)
+ V1->V2 migration SOP with rollback plan
+ Deployment topology (systemd + Docker, port plan, firewall)
+ Log aggregation policy (logrotate: 10MB/30days)
+ Schedule revised: 71h/12days (added P0 + buffer)

Co-authored-by: multica-agent <github@multica.ai>
This commit is contained in:
2026-06-25 14:52:39 +08:00
parent 4fd89b038d
commit 82edded30c
7 changed files with 1429 additions and 0 deletions
+58
View File
@@ -0,0 +1,58 @@
sequenceDiagram
participant OC as OpenClaw
participant GW as API Gateway
participant LB as 负载均衡器
participant QM as 队列管理器
participant RL as Rate Limiter
participant P as Provider
participant CD as Cooldown Detector
participant ST as 统计引擎
OC->>GW: POST /v1/chat/completions
GW->>LB: 路由到目标池
Note over LB: Weighted RR 5-10s刷新<br/>weight=(max_rpm-current_rpm)/max_rpm
LB->>RL: BEGIN IMMEDIATE 事务 检查 RPM + 预占
alt RPM 不足
RL->>QM: 入队等待 超时30s
QM-->>RL: 令牌可用
end
RL-->>LB: 允许转发
LB->>P: 转发请求
P-->>LB: 响应
alt 200 OK
LB->>ST: INSERT ON CONFLICT 记录 usage_logs
LB-->>GW: 正常响应
else 429 Too Many Requests
LB->>CD: 上报429
CD->>P: 移入冷却池 cooldown_until=now+30s×2^n
LB->>LB: 重新选择 Provider B
alt Provider B 正常
LB->>P: 转发到 Provider B
P-->>LB: 200 OK
end
alt 主池全部冷却
Note over LB: 降级 Fallback 池<br/>检查即将恢复的Provider<br/>剩余<10s 等待
alt Fallback 可用
LB->>P: 转发 Fallback Provider
P-->>LB: 200 OK +降级标记
else Fallback 也全冷却
LB->>P: 紧急通道 1 Provider 10% RPM
alt 紧急通道成功
P-->>LB: 200 OK
else
LB-->>OC: 503 Service Unavailable
OC->>OC: OpenClaw 自身 fallback
end
end
end
end