docs: add runtime runbook optimization design

2026-02-25 17:12:43 +08:00
parent 890de969cc
commit 36131cc001
1 changed files with 100 additions and 0 deletions
@@ -0,0 +1,100 @@
+# Runtime Runbook Optimization Design
+
+**Date:** 2026-02-25  
+**Audience:** 运维 / 后端值班同学
+
+## Goal
+
+将 `docs/runtime/runtime-runbook.md` 从“开发流程说明”升级为“运维可直接执行手册”，围绕上线、巡检、故障处置与回滚提供可操作步骤与判定标准，减少值班期间的判断成本与误操作风险。
+
+## Non-Goals
+
+- 不改动运行时代码行为。
+- 不新增部署工具，仅整理现有脚本和命令。
+- 不引入额外平台依赖。
+
+## Current Gaps
+
+- 结构偏开发说明，缺少运维分层（前置检查、门禁、验证、故障、回滚）。
+- 生产章节仍有占位内容（TODO），缺乏可执行流程。
+- 验证步骤有命令，但缺少“通过判定”与执行优先级。
+- 部分历史命名已变化（`dev-app-up` -> `app-up`），需要统一语义与历史记录。
+
+## Target Structure
+
+1. Scope & Preconditions
+2. Bootstrap Gate (Mandatory)
+3. Service Start/Stop (tmux)
+4. Operational Verification (L1/L2/L3)
+5. Incident Playbook
+6. Rollback Procedure
+7. Change Log
+
+## Design Principles
+
+- **Command-first**: 每一步先给命令，再给判定标准。
+- **Fail-fast**: 关键步骤失败即停止，禁止跳过门禁。
+- **Ops-centric**: 按值班动作组织，而非按模块组织。
+- **Consistency**: 统一 compose 与环境变量书写方式。
+
+## Section-Level Content Design
+
+### Scope & Preconditions
+
+- 说明手册适用场景：开发环境值班、发布前检查、生产排障参考。
+- 明确前置依赖：Docker、tmux、`uv`、`.env`。
+- 明确禁止动作：未完成 bootstrap gate 前禁止启动业务进程。
+
+### Bootstrap Gate
+
+- 固定顺序：
+  1) 启动基础设施  
+  2) 执行 bootstrap / init-job（带 `--build`）  
+  3) 校验版本与关键表状态
+- 对每一步给“成功判定”。
+
+### Service Start/Stop
+
+- 使用 `infra/scripts/app-up.sh` 作为唯一运维入口。
+- 标准化 tmux 管理命令（list / attach / kill）。
+- 给出日志文件映射，覆盖 web + 3 worker。
+
+### Operational Verification
+
+- 分层验证：
+  - **L1 必跑**：health、compose 状态、核心 API smoke。
+  - **L2 可选**：Auth/Profile 链路。
+  - **L3 可选**：Agent Chat 相关回归命令。
+- 每层包含通过判定。
+
+### Incident Playbook
+
+- 按故障模式给“症状 -> 定位 -> 修复”：
+  - 迁移未生效（镜像旧）
+  - worker 不消费
+  - JWT/模板配置异常
+  - agent-chat 依赖或迁移异常
+
+### Rollback Procedure
+
+- 给出回滚前检查、回滚执行、回滚后复核三段流程。
+- 标明数据风险提醒与必要确认点。
+
+## Validation Plan
+
+- 对照现有脚本与路径逐条校对命令可用性：
+  - `infra/scripts/app-up.sh`
+  - `infra/docker/docker-compose.yml`
+  - `backend/src/core/runtime/cli.py`
+- 至少执行 shell 语法检查与关键命令可达性检查。
+
+## Risks
+
+- 若未来启动脚本或 compose profile 变更，runbook 会过期。
+- 回滚流程依赖实际数据库策略，若策略变化需同步修订。
+
+## Acceptance Criteria
+
+- 手册不再包含 TODO 占位段。
+- 运维值班可按章节完成从启动到验证再到故障处置。
+- 所有命令路径与脚本名称与仓库现状一致。