social-app/docs/plans/2026-02-25-runtime-runbook-optimization-design.md

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