更新
This commit is contained in:
1 parent
628bbe14a8
commit
04664c8d42
2 files changed
+827
No files matched your search
@@ -327,6 +327,332 @@ upstream gateway_pool {
|
||||
|
||||
---
|
||||
|
||||
## 六-A、方案 C 在 Docker 容器内的详细实施指南
|
||||
|
||||
> **目标**:在不引入新依赖、不动业务代码、不拆容器的前提下,让 AI 写作走专门的单 worker 进程,其它业务继续走多 worker。
|
||||
>
|
||||
> **基础设施**:本项目镜像基于 `python:3.12-slim-bookworm`,用 `uv` 管理依赖,Dockerfile 位于 `offline-backend-20260512/backend/Dockerfile`,默认入口是
|
||||
>
|
||||
> ```
|
||||
> CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run --no-sync uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]
|
||||
> ```
|
||||
|
||||
### 总览:单容器双 uvicorn 进程
|
||||
|
||||
```
|
||||
┌─────────────── nginx (容器外或前置) ───────────────┐
|
||||
│ │
|
||||
/api/ai-writing/ ──┼──► container:8002 (uvicorn --workers 1) ───► AI 写作专用
|
||||
其余 /api/* ──┼──► container:8001 (uvicorn --workers N) ───► 其他业务
|
||||
└────────────────────────────────────────────────────┘
|
||||
▲
|
||||
│ (两个进程跑在同一个容器里,共享 .deer-flow 卷
|
||||
│ /同一个 MySQL /同一个 sqlite checkpoints.db)
|
||||
```
|
||||
|
||||
两进程都用 **同一个 `app.gateway.app:app`**,区别只在:
|
||||
- `8002` 单 worker,专门接 `/api/ai-writing/*`
|
||||
- `8001` 多 worker,接其他所有路由
|
||||
- 容器内用 `supervisord` 同时托管这两个 uvicorn
|
||||
|
||||
### 步骤 1:在镜像里加 supervisord
|
||||
|
||||
编辑 `offline-backend-20260512/backend/Dockerfile`,给 **runtime stage**(第 67 行 `FROM python:3.12-slim-bookworm` 之后)补一段:
|
||||
|
||||
```dockerfile
|
||||
# 安装 supervisord(约 4 MB,纯 Python,无需编译)
|
||||
RUN apt-get update \
|
||||
&& apt-get install -y --no-install-recommends supervisor \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
```
|
||||
|
||||
如果内网无法访问 debian 源,可用现有的 `APT_MIRROR` build-arg:
|
||||
|
||||
```bash
|
||||
docker build \
|
||||
--build-arg APT_MIRROR=mirrors.aliyun.com \
|
||||
-f offline-backend-20260512/backend/Dockerfile \
|
||||
-t deerflow-gateway:dual .
|
||||
```
|
||||
|
||||
### 步骤 2:写 supervisord 配置
|
||||
|
||||
新建 `offline-backend-20260512/backend/deploy/supervisord.conf`:
|
||||
|
||||
```ini
|
||||
[supervisord]
|
||||
nodaemon=true ; 容器主进程,必须前台
|
||||
user=root
|
||||
logfile=/dev/null ; 让子进程日志直接走 stdout/stderr,由 docker logs 接管
|
||||
logfile_maxbytes=0
|
||||
pidfile=/tmp/supervisord.pid
|
||||
|
||||
; ─── 主 Gateway:多 worker,处理除 ai-writing 以外的所有业务 ───
|
||||
[program:gateway-main]
|
||||
command=uv run --no-sync uvicorn app.gateway.app:app
|
||||
--host 0.0.0.0 --port 8001
|
||||
--workers %(ENV_GATEWAY_MAIN_WORKERS)s
|
||||
--proxy-headers --forwarded-allow-ips=*
|
||||
directory=/app/backend
|
||||
environment=PYTHONPATH=".",AI_WRITING_DEDICATED_PORT="8002"
|
||||
autostart=true
|
||||
autorestart=true
|
||||
stopasgroup=true
|
||||
killasgroup=true
|
||||
stopsignal=TERM
|
||||
stopwaitsecs=35 ; 给 lifespan 的 30s drain 留点余量
|
||||
stdout_logfile=/dev/stdout
|
||||
stdout_logfile_maxbytes=0
|
||||
stderr_logfile=/dev/stderr
|
||||
stderr_logfile_maxbytes=0
|
||||
|
||||
; ─── AI 写作专用:单 worker,处理 /api/ai-writing/* ───
|
||||
[program:gateway-aiwriting]
|
||||
command=uv run --no-sync uvicorn app.gateway.app:app
|
||||
--host 0.0.0.0 --port 8002
|
||||
--workers 1
|
||||
--proxy-headers --forwarded-allow-ips=*
|
||||
directory=/app/backend
|
||||
environment=PYTHONPATH=".",DEER_FLOW_ROLE="ai-writing"
|
||||
autostart=true
|
||||
autorestart=true
|
||||
stopasgroup=true
|
||||
killasgroup=true
|
||||
stopsignal=TERM
|
||||
stopwaitsecs=35
|
||||
stdout_logfile=/dev/stdout
|
||||
stdout_logfile_maxbytes=0
|
||||
stderr_logfile=/dev/stderr
|
||||
stderr_logfile_maxbytes=0
|
||||
```
|
||||
|
||||
**几个关键点**:
|
||||
- `nodaemon=true` 让 supervisord 自己变成 PID 1,docker stop 发的 SIGTERM 才能正确传给它,它再传给两个 uvicorn 子进程
|
||||
- `stopasgroup=true` + `killasgroup=true` 确保 uvicorn 多 worker 模式下所有子进程一起退
|
||||
- `stopwaitsecs=35` 必须大于 lifespan 的 30s drain 超时,否则 in-flight 写作会被 SIGKILL
|
||||
- `%(ENV_GATEWAY_MAIN_WORKERS)s` 让主进程 worker 数走环境变量,下面会传
|
||||
|
||||
把这个配置文件 COPY 进镜像(在 Dockerfile runtime stage `COPY --from=builder /app/backend ./backend` 之后加):
|
||||
|
||||
```dockerfile
|
||||
COPY backend/deploy/supervisord.conf /etc/supervisor/conf.d/deerflow.conf
|
||||
```
|
||||
|
||||
### 步骤 3:把 Dockerfile 入口换成 supervisord
|
||||
|
||||
把 Dockerfile **runtime stage 最后一行** 改成:
|
||||
|
||||
```dockerfile
|
||||
# 之前
|
||||
CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run --no-sync uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]
|
||||
|
||||
# 之后
|
||||
EXPOSE 8001 8002 2024
|
||||
CMD ["supervisord", "-c", "/etc/supervisor/conf.d/deerflow.conf"]
|
||||
```
|
||||
|
||||
> **`dev` stage 不用改**:开发环境本来就是单 worker、reload 模式,方案 C 是为生产准备的,dev stage 维持原 CMD。
|
||||
|
||||
### 步骤 4:暴露端口 / 挂卷 / 环境变量
|
||||
|
||||
启动容器时:
|
||||
|
||||
```bash
|
||||
docker run -d --name deerflow-gateway \
|
||||
-p 8001:8001 \
|
||||
-p 8002:8002 \
|
||||
-e GATEWAY_MAIN_WORKERS=4 \
|
||||
-e DEER_FLOW_CONFIG_PATH=/app/config.yaml \
|
||||
-v /your/host/path/.deer-flow:/app/.deer-flow \
|
||||
-v /your/host/path/config.yaml:/app/config.yaml:ro \
|
||||
-v /your/host/path/extensions_config.json:/app/extensions_config.json:ro \
|
||||
deerflow-gateway:dual
|
||||
```
|
||||
|
||||
**两个进程必须共享 `.deer-flow` 卷** —— 因为 `checkpoints.db` 在里面(`offline-backend-20260512/config.yaml` 里配的是相对路径 `.deer-flow/data/checkpoints.db`)。两个进程跑在同一个容器内,天然共享文件系统,**这一步不用做任何额外配置**,只要确认数据卷挂出去就行。
|
||||
|
||||
> ⚠️ 即便 8002 是单 worker,仍然推荐把 checkpointer 持久化到磁盘,因为:① 容器重启会重建进程;② 如果哪天临时改回多容器/多 worker,数据不丢;③ 跟主 gateway 共享 checkpoint,未来想做读副本也方便。
|
||||
|
||||
### 步骤 5:nginx 路由
|
||||
|
||||
如果你前面已经有 nginx(容器外或者另一个容器),把 AI 写作的路由独立出来:
|
||||
|
||||
```nginx
|
||||
upstream gateway_main { server gateway-host:8001; }
|
||||
upstream gateway_aiwriting { server gateway-host:8002; }
|
||||
|
||||
server {
|
||||
listen 80;
|
||||
server_name deerflow.example.com;
|
||||
|
||||
# SSE 长连接必须关 buffering
|
||||
proxy_buffering off;
|
||||
proxy_request_buffering off;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Connection "";
|
||||
|
||||
# AI 写作 → 单 worker 后端
|
||||
location /api/ai-writing/ {
|
||||
proxy_pass http://gateway_aiwriting;
|
||||
proxy_read_timeout 3600s; # graph 跑得久,给足时间
|
||||
proxy_send_timeout 3600s;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
|
||||
# 其它一切 API → 多 worker 后端
|
||||
location /api/ {
|
||||
proxy_pass http://gateway_main;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
|
||||
# 前端静态资源不变
|
||||
location / {
|
||||
proxy_pass http://frontend:5174;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**`proxy_buffering off` 是必须的** —— 不关 buffering,nginx 会把 SSE 流缓冲到响应结束才一次性吐给前端,等于把流式写作变成「等几分钟啥都看不到 → 一下吐一整篇」。
|
||||
|
||||
如果前端是 Vite 直连后端(开发态没走 nginx),就只需要把 `frontend-web` 里 AI 写作相关的 `fetch`/`EventSource` 改成 `:8002`,但更推荐 **始终走 nginx**,对前端透明。
|
||||
|
||||
### 步骤 6:如果你用 docker-compose
|
||||
|
||||
完整 compose 示例:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
gateway:
|
||||
image: deerflow-gateway:dual
|
||||
container_name: deerflow-gateway
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
GATEWAY_MAIN_WORKERS: "4"
|
||||
DEER_FLOW_CONFIG_PATH: /app/config.yaml
|
||||
ports:
|
||||
- "8001:8001"
|
||||
- "8002:8002" # 如果有外层 nginx,且 nginx 跟 gateway 同网段,可去掉这行只走内网
|
||||
volumes:
|
||||
- ./data/deer-flow:/app/.deer-flow
|
||||
- ./config.yaml:/app/config.yaml:ro
|
||||
- ./extensions_config.json:/app/extensions_config.json:ro
|
||||
healthcheck:
|
||||
test: ["CMD", "sh", "-c", "curl -fsS http://localhost:8001/health && curl -fsS http://localhost:8002/health"]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
retries: 3
|
||||
start_period: 30s
|
||||
stop_grace_period: 45s # 给 supervisord 的 35s + 余量,让两路 drain 跑完
|
||||
|
||||
nginx:
|
||||
image: nginx:1.27-alpine
|
||||
depends_on: [gateway]
|
||||
ports: ["80:80"]
|
||||
volumes:
|
||||
- ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
|
||||
```
|
||||
|
||||
`stop_grace_period: 45s` 这一行很关键 —— docker-compose 默认只给 10s,到点直接 SIGKILL,in-flight 写作会全部丢。设到 45s 等于 supervisord 的 35s + 10s 余量。
|
||||
|
||||
### 步骤 7:验证(按这个清单逐项过)
|
||||
|
||||
```bash
|
||||
# 1) 两个进程都起来了
|
||||
docker exec deerflow-gateway sh -c 'ps -ef | grep -E "uvicorn|supervisord" | grep -v grep'
|
||||
# 期望看到:
|
||||
# 1 root supervisord -c /etc/supervisor/conf.d/deerflow.conf
|
||||
# N root uvicorn app.gateway.app:app --port 8001 --workers 4
|
||||
# M root uvicorn app.gateway.app:app --port 8002 --workers 1
|
||||
# (8001 那一行会有 N 个 worker 子进程,8002 那一行只有 1 个)
|
||||
|
||||
# 2) 8002 只有 1 个 worker(这是方案 C 的命脉)
|
||||
docker exec deerflow-gateway sh -c 'pgrep -f "port 8002" | wc -l'
|
||||
# 期望 = 2(1 个 master + 1 个 worker);如果 > 2,单 worker 没生效
|
||||
|
||||
# 3) 8001 不再警告多 worker
|
||||
docker logs deerflow-gateway 2>&1 | grep -i 'WEB_CONCURRENCY'
|
||||
# 期望:没有 ERROR 警告(因为 8001 走的是其他业务,8002 走的是单 worker)
|
||||
|
||||
# 4) 8002 进程能看到 ai_writing 持久化日志
|
||||
docker logs deerflow-gateway 2>&1 | grep 'AsyncSqliteSaver'
|
||||
# 期望至少 1 行:ai_writing: 使用 AsyncSqliteSaver (...)
|
||||
|
||||
# 5) /api/ai-writing/* 走 8002,其他走 8001
|
||||
curl -sI http://deerflow.example.com/api/ai-writing/health # 看 nginx access log 落到 gateway_aiwriting
|
||||
curl -sI http://deerflow.example.com/api/models # 看落到 gateway_main
|
||||
|
||||
# 6) 真跑一次 AI 写作,确认全程没有「resume 404 / 进度断流」
|
||||
```
|
||||
|
||||
### 步骤 8:监控两个进程的健康
|
||||
|
||||
supervisord 自带 `unix_http_server` + `supervisorctl`,但对容器化场景更直接的是看 docker logs:
|
||||
|
||||
```bash
|
||||
# 实时看两个进程的日志
|
||||
docker logs -f deerflow-gateway 2>&1 | grep -E '(gateway-main|gateway-aiwriting)'
|
||||
|
||||
# 进程级状态
|
||||
docker exec deerflow-gateway supervisorctl -c /etc/supervisor/conf.d/deerflow.conf status
|
||||
# 期望:
|
||||
# gateway-main RUNNING pid 7, uptime 0:05:12
|
||||
# gateway-aiwriting RUNNING pid 18, uptime 0:05:12
|
||||
|
||||
# 单独重启 AI 写作进程(不影响主业务,前端只是 AI 写作页几秒不可用)
|
||||
docker exec deerflow-gateway supervisorctl -c /etc/supervisor/conf.d/deerflow.conf restart gateway-aiwriting
|
||||
```
|
||||
|
||||
### 资源开销(实测预估)
|
||||
|
||||
| 项 | 单 worker 镜像 | 双进程镜像 | 增量 |
|
||||
|---|---|---|---|
|
||||
| 镜像大小 | 基线 | +约 5 MB | supervisord 依赖 |
|
||||
| 启动时 RSS | ~250 MB | ~450 MB | 多一份 Python runtime + 模型客户端预加载 |
|
||||
| 稳态 RSS | 视业务而定 | +约 200 MB | 第二个 worker 的常驻内存 |
|
||||
| CPU | 不变 | 不变 | 单 worker 进程空闲基本不占 CPU |
|
||||
|
||||
**结论**:内存额外占用约 200 MB,对 4 GB 以上的部署机基本无压力。
|
||||
|
||||
### 常见坑位
|
||||
|
||||
1. **`stop_grace_period` 没改大 → 重启时 in-flight 写作被秒杀**
|
||||
表现:每次 `docker compose restart` 都有用户报告「写到一半没了」。修复见步骤 6。
|
||||
|
||||
2. **8002 没暴露 / nginx 没改 → 所有请求还是落 8001**
|
||||
表现:症状跟没做方案 C 一样。验证步骤 5 的 curl 即可发现。
|
||||
|
||||
3. **两路用了不同的 `config.yaml`**
|
||||
表现:8001 跟 8002 行为不一致。务必让两个进程**只读同一个文件**(在 compose 里只挂一次卷)。
|
||||
|
||||
4. **`.deer-flow` 卷没挂 → 8002 重启后会话全丢**
|
||||
表现:用户刷新页面,AI 写作历史空白。修复:步骤 4 的 `-v` 必须有。
|
||||
|
||||
5. **AI 写作进程崩溃后 supervisord 反复重启 → 日志爆炸**
|
||||
表现:`gateway-aiwriting` 状态在 RUNNING/EXITED/BACKOFF 间反复。
|
||||
修复:先 `supervisorctl tail gateway-aiwriting stderr` 看真正原因(多半是 sqlite 权限或配置文件路径),再修,**别盲目调 `autorestart=false`**。
|
||||
|
||||
6. **想做 K8s 部署但还想用方案 C**
|
||||
不要把两个进程塞一个 Pod,应该直接拆成两个 Deployment、共享 PVC(checkpoints.db)。这种情况下方案 C 已经变形成方案 F 的子集,建议直接走方案 F。
|
||||
|
||||
### 回滚方案
|
||||
|
||||
如果上线后发现问题,回滚只需要 1 步:
|
||||
|
||||
```bash
|
||||
# 把 Dockerfile 最后一行换回原来的 CMD,重新 build + 重启
|
||||
CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run --no-sync uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]
|
||||
```
|
||||
|
||||
数据完全兼容(checkpoints.db、MySQL 表结构都跟单进程模式一致),**不会丢任何用户数据**,只是回到「resume 偶发 404、SSE 断断续续」的旧体验。
|
||||
|
||||
---
|
||||
|
||||
## 七、运维操作清单
|
||||
|
||||
### 部署前验证
|
||||
|
||||
Reference in new issue
Block a user