merge: combine local dev updates into dev
This commit is contained in:
qzl
@@ -1,115 +1,77 @@
|
||||
# Runtime Runbook
|
||||
|
||||
**Date:** 2026-02-24
|
||||
**Date:** 2026-02-25
|
||||
**Status:** Active
|
||||
|
||||
## 启动方式
|
||||
## 开发环境启动
|
||||
|
||||
### 一键启动 (推荐)
|
||||
### 一键启动
|
||||
|
||||
```bash
|
||||
# 前提：基础设施已手动启动（redis + supabase）
|
||||
# docker compose --env-file .env -f infra/docker/docker-compose.yml up -d
|
||||
# 1. 首次或 schema 变更后，执行 bootstrap
|
||||
docker compose --env-file .env -f infra/docker/docker-compose.yml run --rm init-job bootstrap
|
||||
|
||||
# 一键执行 bootstrap + 拉起 web/worker（tmux）
|
||||
bash infra/scripts/dev-app-up.sh
|
||||
# 2. 日常启动服务（tmux）
|
||||
bash infra/scripts/app-up.sh
|
||||
|
||||
# 查看窗口
|
||||
# 查看 tmux 窗口
|
||||
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 --build init-job
|
||||
|
||||
# 3. 一键执行应用层启动（bootstrap + web + workers）
|
||||
bash infra/scripts/dev-app-up.sh
|
||||
```
|
||||
|
||||
### 生产环境迁移防遗漏（必读）
|
||||
|
||||
- 生产发布前必须先通过 bootstrap gate，再启动业务进程；禁止绕过 gate 直接起服务。
|
||||
- 使用容器执行迁移时必须带 `--build`，确保最新 Alembic 迁移已进入镜像。
|
||||
- 建议在迁移后做一次版本核对，确认已到预期 head。
|
||||
|
||||
```bash
|
||||
# 1) 先执行 bootstrap gate
|
||||
make runtime-bootstrap-gate
|
||||
|
||||
# 2) 如采用 init-job 单跑，必须带 --build
|
||||
docker compose --env-file .env -f infra/docker/docker-compose.yml --profile job run --rm --build init-job
|
||||
|
||||
# 3) 核对 Alembic 版本
|
||||
docker compose --env-file .env -f infra/docker/docker-compose.yml exec -T db \
|
||||
psql -U postgres -d postgres -c "SELECT version_num FROM public.alembic_version;"
|
||||
```
|
||||
|
||||
### 本地 CLI (开发调试)
|
||||
|
||||
> 适用于本地开发调试，不依赖 Docker。
|
||||
> 开发调试阶段推荐直接使用本地一次性迁移脚本，不通过 Docker 触发数据库迁移，避免反复重建镜像。
|
||||
|
||||
```bash
|
||||
# 推荐：一次性迁移（开发调试）
|
||||
PYTHONPATH=backend/src uv run python -m core.runtime.cli migrate
|
||||
|
||||
# 需要初始化数据时再执行
|
||||
PYTHONPATH=backend/src uv run python -m core.runtime.cli init-data
|
||||
|
||||
# 或一键执行（migrate + init-data）
|
||||
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
|
||||
```
|
||||
|
||||
### 日志文件
|
||||
|
||||
每个服务自动生成独立日志文件：
|
||||
|
||||
| 服务 | 日志文件 |
|
||||
|------|---------|
|
||||
| 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: 待补充
|
||||
|
||||
```bash
|
||||
# TBD
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 服务说明
|
||||
|
||||
| 服务 | 说明 | 备注 |
|
||||
|------|------|------|
|
||||
| redis | 缓存与 Celery broker | docker-compose 编排 |
|
||||
| supabase-* | 认证与数据库相关服务 | docker-compose 编排 |
|
||||
| init-job | 数据库迁移和初始化 | docker-compose 按需 run |
|
||||
| web | Web 服务 (gunicorn) | 本地 CLI 启动 |
|
||||
| worker-* | Celery worker | 本地 CLI 启动 |
|
||||
| 服务 | 说明 |
|
||||
|------|------|
|
||||
| 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 | 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 |
|
||||
| 环境变量 | 说明 | 默认值 |
|
||||
|----------|------|--------|
|
||||
| `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 队列路由
|
||||
|
||||
@@ -191,7 +153,6 @@ curl -sS -X POST http://127.0.0.1:8000/api/v1/agent-chat/run \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"message":"hello"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 变更日志
|
||||
@@ -206,3 +167,4 @@ curl -sS -X POST http://127.0.0.1:8000/api/v1/agent-chat/run \
|
||||
| 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 与服务启动 |
|
||||
|
||||
Reference in New Issue
Block a user