social-app/docs/runtime/runtime-runbook.md

Runtime Runbook

Date: 2026-02-25
Status: Active

开发环境启动

一键启动

# 1. 首次或 schema 变更后，执行 bootstrap
docker compose --env-file .env -f infra/docker/docker-compose.yml run --rm init-job bootstrap

# 2. 日常启动服务（tmux）
bash infra/scripts/app-up.sh

# 查看 tmux 窗口
tmux list-windows -t social-dev

# 进入会话观察日志
tmux attach -t social-dev

tmux 会话管理

# 杀掉会话（停止 web/workers）
tmux kill-session -t social-dev

日志文件

每个服务自动生成独立日志文件：

服务	日志文件
Web	logs/web.log, logs/web.error.log
Worker Critical	logs/worker-critical.log, logs/worker-critical.error.log
Worker Default	logs/worker-default.log, logs/worker-default.error.log
Worker Bulk	logs/worker-bulk.log, logs/worker-bulk.error.log

---

生产环境启动

TODO: 待补充

# TBD

---

服务说明

服务	说明
redis	缓存与 Celery broker
supabase-*	认证与数据库相关服务
init-job	数据库迁移和初始化（一次性）
web	Web 服务 (gunicorn)
worker-*	Celery worker (3 个队列)

配置说明

Web 服务器配置

环境变量	说明	默认值
SOCIAL_WEB__HOST	监听地址	0.0.0.0
SOCIAL_WEB__PORT	监听端口	8000
SOCIAL_WEB__GUNICORN__WORKERS	Gunicorn 工作进程数	2
SOCIAL_WEB__GUNICORN__WORKER_CLASS	Gunicorn worker 类	uvicorn.workers.UvicornWorker
SOCIAL_WEB__GUNICORN__TIMEOUT	请求超时秒数	60

Celery 队列路由

任务前缀	队列
tasks.critical.*	critical
tasks.bulk.*	bulk
其他	default

健康检查

# Supabase 网关
curl -fsS http://127.0.0.1:${SOCIAL_SUPABASE__KONG_HTTP_PORT:-8000}/health

# 数据库迁移与初始化
docker compose --env-file .env -f infra/docker/docker-compose.yml --profile job run --rm --build init-job

查看服务状态

docker compose --env-file .env -f infra/docker/docker-compose.yml ps
docker compose --env-file .env -f infra/docker/docker-compose.yml logs -f db

# init-job 为一次性任务（run --rm），如需查看日志请重跑：
docker compose --env-file .env -f infra/docker/docker-compose.yml --profile job run --rm --build init-job

Auth/Profile 验证

# 注意：默认模板地址 http://mail-templates/* 仅在 Docker Compose 内网可用。
# 生产环境请替换为 gotrue 可访问的模板 URL。

# signup start: username + email + password（发送验证码）
curl -sS -X POST http://127.0.0.1:8000/api/v1/auth/signup/start \
  -H 'Content-Type: application/json' \
  -d '{"username":"demo","email":"demo@example.com","password":"secret123"}'

# signup verify: email + token（6位验证码）
curl -sS -X POST http://127.0.0.1:8000/api/v1/auth/signup/verify \
  -H 'Content-Type: application/json' \
  -d '{"email":"demo@example.com","token":"123456"}'

# signup resend: email（重发验证码）
curl -sS -X POST http://127.0.0.1:8000/api/v1/auth/signup/resend \
  -H 'Content-Type: application/json' \
  -d '{"email":"demo@example.com"}'

# login: email + password
curl -sS -X POST http://127.0.0.1:8000/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"demo@example.com","password":"secret123"}'

# by-email lookup
curl -sS "http://127.0.0.1:8000/api/v1/auth/users/by-email?email=demo@example.com"

# patch profile: username/avatar_url/bio only
curl -sS -X PATCH http://127.0.0.1:8000/api/v1/profile/me \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer <access_token>" \
  -d '{"username":"demo2","bio":"hello"}'

Agent Chat 验证

# 1) 基础门禁（迁移 + init-data）
make runtime-bootstrap-gate

# 2) 运行 agent_chat 相关单测/集成/E2E
PYTHONPATH=backend/src uv run pytest backend/tests/unit/core/agent_chat -v
PYTHONPATH=backend/src uv run pytest backend/tests/integration -k agent_chat -v
PYTHONPATH=backend/src uv run pytest backend/tests/e2e/test_agent_chat_flow.py backend/tests/e2e/test_agent_chat_recent_session_home.py -v

# 3) 核心接口 smoke
curl -sS -X POST http://127.0.0.1:8000/api/v1/agent-chat/run \
  -H 'Content-Type: application/json' \
  -d '{"message":"hello"}'

---

变更日志

日期	变更
2026-02-24	创建运行时手册，删除 legacy 脚本，统一使用 gunicorn
2026-02-24	清理配置：合并 AppSettings 到 WebSettings，删除 Worker 旧配置 (enabled_queues/queues)，统一使用 SOCIAL_WEB__GUNICORN__* 命名
2026-02-24	开发阶段 compose 暂不编排 web/worker，仅保留 redis/supabase 与 init-job
2026-02-24	新增 dev-app-up 脚本：手动基础设施后，一键 bootstrap + tmux 拉起 web/worker
2026-02-25	补充迁移防遗漏规则：容器迁移命令统一追加 --build；开发调试优先使用本地 CLI 一次性迁移脚本
2026-02-25	Auth 注册切换为 OTP 三段式：signup/start、signup/verify、signup/resend；邮件模板改为纯验证码展示
2026-02-25	清理未使用配置类：删除 WebSettings/GunicornSettings/WorkerSettings/WorkerGroupSettings（脚本仍使用环境变量启动服务）
2026-02-25	新增 Agent Chat 验证章节：bootstrap gate、分层测试命令与 run 接口 smoke 示例
2026-02-25	简化启动方式：dev-app-up → app-up，分离 bootstrap 与服务启动