qzl
128 lines
4.1 KiB
Markdown
128 lines
4.1 KiB
Markdown
# Runtime Runbook
|
||
|
||
**Date:** 2026-02-24
|
||
**Status:** Active
|
||
|
||
## 启动方式
|
||
|
||
### 一键启动 (推荐)
|
||
|
||
```bash
|
||
# 前提：基础设施已手动启动（redis + supabase）
|
||
# docker compose --env-file .env -f infra/docker/docker-compose.yml up -d
|
||
|
||
# 一键执行 bootstrap + 拉起 web/worker（tmux）
|
||
bash infra/scripts/dev-app-up.sh
|
||
|
||
# 查看窗口
|
||
tmux list-windows -t social-dev
|
||
|
||
# 进入会话观察日志
|
||
tmux attach -t social-dev
|
||
```
|
||
|
||
或者手动执行:
|
||
|
||
```bash
|
||
# 1. 启动基础设施（当前编排不包含 web/worker）
|
||
docker compose --env-file .env -f infra/docker/docker-compose.yml up -d
|
||
|
||
# 2. 运行迁移和初始化
|
||
docker compose --env-file .env -f infra/docker/docker-compose.yml --profile job run --rm init-job
|
||
|
||
# 3. 一键执行应用层启动（bootstrap + web + workers）
|
||
bash infra/scripts/dev-app-up.sh
|
||
```
|
||
|
||
### 本地 CLI (开发调试)
|
||
|
||
> 适用于本地开发调试，不依赖 Docker。
|
||
|
||
```bash
|
||
# 初始化/迁移
|
||
PYTHONPATH=backend/src uv run python -m core.runtime.cli bootstrap
|
||
|
||
# 启动 Web (gunicorn)
|
||
PYTHONPATH=backend/src uv run gunicorn app:app --bind 0.0.0.0:8000 --workers 2 --worker-class uvicorn.workers.UvicornWorker
|
||
|
||
# 启动 Worker (按队列分组)
|
||
PYTHONPATH=backend/src uv run celery -A core.celery.app worker --loglevel=info --queues=critical --concurrency=2
|
||
PYTHONPATH=backend/src uv run celery -A core.celery.app worker --loglevel=info --queues=default --concurrency=2
|
||
PYTHONPATH=backend/src uv run celery -A core.celery.app worker --loglevel=info --queues=bulk --concurrency=1
|
||
```
|
||
|
||
### tmux 会话管理
|
||
|
||
```bash
|
||
# 进入会话
|
||
tmux attach -t social-dev
|
||
|
||
# 杀掉会话（停止 web/workers）
|
||
tmux kill-session -t social-dev
|
||
```
|
||
|
||
## 服务说明
|
||
|
||
| 服务 | 说明 | 备注 |
|
||
|------|------|------|
|
||
| redis | 缓存与 Celery broker | docker-compose 编排 |
|
||
| supabase-* | 认证与数据库相关服务 | docker-compose 编排 |
|
||
| init-job | 数据库迁移和初始化 | docker-compose 按需 run |
|
||
| web | Web 服务 (gunicorn) | 本地 CLI 启动 |
|
||
| worker-* | Celery worker | 本地 CLI 启动 |
|
||
|
||
## 配置说明
|
||
|
||
### Web 服务器配置
|
||
|
||
| 环境变量 | 说明 | 默认值 | 有效范围 |
|
||
|----------|------|--------|----------|
|
||
| `SOCIAL_WEB__SERVER` | Web 服务器类型 | gunicorn | uvicorn/gunicorn |
|
||
| `SOCIAL_WEB__HOST` | 监听地址 | 0.0.0.0 | - |
|
||
| `SOCIAL_WEB__PORT` | 监听端口 | 8000 | 1-65535 |
|
||
| `SOCIAL_WEB__RELOAD` | 开发模式热重载 | false | true/false |
|
||
| `SOCIAL_WEB__GUNICORN__WORKERS` | Gunicorn 工作进程数 | 2 | 1-64 |
|
||
| `SOCIAL_WEB__GUNICORN__WORKER_CLASS` | Gunicorn worker 类 | uvicorn.workers.UvicornWorker | Python import path |
|
||
| `SOCIAL_WEB__GUNICORN__TIMEOUT` | 请求超时秒数 | 60 | 1-600 |
|
||
| `SOCIAL_WEB__GUNICORN__KEEPALIVE` | Keep-alive 秒数 | 5 | 1-120 |
|
||
| `SOCIAL_WEB__LOG_LEVEL` | 日志级别 | info | debug/info/warning/error/critical |
|
||
|
||
### Celery 队列路由
|
||
|
||
| 任务前缀 | 队列 |
|
||
|----------|------|
|
||
| tasks.critical.* | critical |
|
||
| tasks.bulk.* | bulk |
|
||
| 其他 | default |
|
||
|
||
## 健康检查
|
||
|
||
```bash
|
||
# 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 init-job
|
||
```
|
||
|
||
## 查看服务状态
|
||
|
||
```bash
|
||
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 init-job
|
||
```
|
||
|
||
---
|
||
|
||
## 变更日志
|
||
|
||
| 日期 | 变更 |
|
||
|------|------|
|
||
| 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 |
|