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