# Runtime Runbook

**Date:** 2026-02-24  
**Status:** Active

## 启动方式

### 一键启动 (推荐)

```bash
# 使用一键启动脚本
./infra/scripts/start.sh
```

或者手动执行:

```bash
# 1. 启动基础设施
docker compose --env-file .env -f infra/docker/docker-compose.yml up -d redis db

# 2. 运行迁移和初始化
docker compose --env-file .env -f infra/docker/docker-compose.yml run --rm init-job

# 3. 启动 Web 和 Worker
docker compose --env-file .env -f infra/docker/docker-compose.yml up -d web worker-critical worker-default worker-bulk
```

### 本地 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
```

## 服务说明

| 服务 | 说明 | 队列 |
|------|------|------|
| web | Web 服务 (gunicorn) | - |
| worker-critical | 关键任务 worker | critical |
| worker-default | 默认任务 worker | default |
| worker-bulk | 批量任务 worker | bulk |
| init-job | 数据库迁移和初始化 | - |

## 配置说明

### 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
curl -fsS http://127.0.0.1:8000/health
```

## 查看服务状态

```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 web
docker compose --env-file .env -f infra/docker/docker-compose.yml logs -f worker-critical
```

---

## 变更日志

| 日期 | 变更 |
|------|------|
| 2026-02-24 | 创建运行时手册，删除 legacy 脚本，统一使用 gunicorn |
| 2026-02-24 | 清理配置：合并 AppSettings 到 WebSettings，删除 Worker 旧配置 (enabled_queues/queues)，统一使用 SOCIAL_WEB__GUNICORN__* 命名 |