qzl
101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
# 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 占位段。
|
||
- 运维值班可按章节完成从启动到验证再到故障处置。
|
||
- 所有命令路径与脚本名称与仓库现状一致。
|