# AI 写作 — 故障排查与解决方案说明 > **本文档目的**:完整记录 AI 写作子系统在内网 Docker 部署后出现的问题、根因、已落地的修复、剩余风险、以及未来的解决方案路径。 > > **适用读者**:维护 AI 写作功能的前端/后端开发者、内网部署运维。 > > **更新日期**:2026-05-20 --- ## 一、问题背景 ### 起因 内网 Docker 部署后,AI 写作出现两类报错: | 接口 | 报错 | 频率 | |---|---|---| | `PUT /api/ai-writing/sessions/{id}/transcript` | HTTP 500 | 经常 | | `POST /api/ai-writing/{id}/resume` | HTTP 4xx(用户记忆为 400,实际可能是 404) | 经常,且没有 Docker 重启时也发生 | ### 这两个接口的作用 #### 1. `PUT /sessions/{id}/transcript` — 对话时间线持久化 - **职责**:保存前端组装的完整对话时间线(progressEvents + completedInterventions)到 MySQL - **调用时机**:前端在写作过程中**反复 PUT**(事件累计、干预完成、草稿生成等节点全量覆盖) - **存到哪**:MySQL 的 `ai_writing_sessions.transcript` 列(LONGTEXT) - **用途**:用户**关闭页面后再回来 / 刷新 / 看历史会话**时,从 DB 拉回这段时间线,UI 上回显出「跟实时一样的对话历史」 - **定位**:**纯锦上添花** — 失败了用户当下写作完全不受影响,只是历史回显会缺失/不完整 #### 2. `POST /{id}/resume` — 写作流程的核心控制接口 - **职责**:提交用户在干预点的决策,让 LangGraph 从挂起的 interrupt 点继续推进 - **调用时机**:用户在 4 个 interrupt 点(素材确认 / 大纲确认 / 草稿确认 / 审核确认)做出决定后 - **传什么**:用户的决策内容(确认的素材 id、修改后的大纲、用户的修订意见、章节求助决策…) - **定位**:**流程主干** — 它失败,用户就**真的卡死**在干预点 --- ## 二、根因分析 ### 根因 1:`transcript` 列容量不足 + 路由层无兜底 - MySQL `TEXT` 列上限 64 KB - 用户写作过程中累计 `progressEvents`(含每个流式 chunk)+ `completedInterventions` 后,JSON blob 经常超过 64 KB - `session.commit()` 抛 `DataError: Data too long for column 'transcript'` - 原路由没有 try/except,异常直接冒泡成 HTTP 500 ### 根因 2:内存中的会话状态在多 worker 部署下隔离 后端用了大量模块级 dict 维护会话状态: ```python _event_queues: dict[str, asyncio.Queue] # SSE 事件队列 _session_pending_pause: dict[str, tuple] # 挂起的 await_user 事件 _session_model_names: dict[str, str] # 用户选的模型 _session_interventions: dict[str, list] # 累计干预历史 _session_repos: dict[str, repo] # DB 仓库引用 _session_user_ids: dict[str, str] # 用户 id _session_article_types: dict[str, list] # 文章类型列表 ``` **uvicorn / gunicorn 多 worker 是多进程共享 socket**,OS 内核决定哪个 worker 接到请求,应用层和 nginx 都管不着。所以: ``` T0: POST /start → worker A 创建 _event_queues[sid] = QueueA graph 推进任务跑在 worker A T1: GET /stream → 落 worker B,没有 QueueA 的引用 → 触发 _recover_session,从 sqlite 重建 QueueB → SSE 推 QueueB 但事件都在 QueueA 里 T2: POST /resume → 落 worker C,同样无法看到 A/B 的状态 ``` **结果**:SSE 时断时续、resume 偶发 404「会话状态已丢失」。 ### 根因 3:Graph 用了内存 checkpointer 原代码: ```python # ai_writing/graph.py checkpointer = MemorySaver() ``` 进程内的 `MemorySaver` 重启即丢,**容器重启或单 worker 进程被回收**后所有进行中会话都拿不到。 ### 根因 4:路径配错 `config.yaml` 里 sqlite 路径写成了 Windows 绝对路径 `D:\cursor-work\...`,Linux 容器里根本无法解析。 --- ## 三、已落地的修复(已合入 dhk-1 分支) ### 修复 1:`transcript` 列改 LONGTEXT + 路由兜底 | 文件 | 改动 | |---|---| | `packages/harness/deerflow/persistence/types.py` | 新增 `PortableLongText` 类型(MySQL→LONGTEXT,SQLite/PG→TEXT) | | `packages/harness/deerflow/persistence/ai_writing_sessions/model.py` | `transcript` 列改成 `PortableLongText` | | `packages/harness/deerflow/persistence/migrations/versions/20260519_02_ai_writing_transcript_longtext.py` | Alembic 迁移:MySQL 上 `ALTER ... type_=LONGTEXT()` | | `app/gateway/routers/ai_writing.py` | `save_transcript` 整段 try/except 包裹,**任何异常都返回 `{success: false, reason}`,永远不抛 5xx** | **结果**:transcript 500 永远不会再发生。前端已经做了 fire-and-forget 容错,失败只 `console.warn`,写作流程不阻断。 ### 修复 2:Checkpointer 改为持久化 SQLite | 文件 | 改动 | |---|---| | `packages/harness/deerflow/agents/ai_writing/graph.py` | `MemorySaver()` → 懒加载 `AsyncSqliteSaver` | | 同上 | 新增 `get_ai_writing_graph()` / `get_ai_writing_checkpointer()` / `shutdown_ai_writing_graph()` | | `offline-backend-20260512/config.yaml` | sqlite 路径改成相对路径 `.deer-flow/data/checkpoints.db` | **关键容错**:sqlite 初始化失败(磁盘满 / 权限 / aiosqlite 未装 / 损坏)会**自动降级 InMemorySaver**,写作流程能跑完,但跨重启不可恢复。 ### 修复 3:跨 worker / 进程重启会话恢复 | 文件 | 改动 | |---|---| | `app/gateway/routers/ai_writing.py` | 新增 `_recover_session(session_id, request)` | 当 worker 内存里没有该 session 时,从 sqlite checkpointer 读快照,重建 `_event_queues`、重新注入 `await_user` 事件。 **效果**:worker B 收到的 resume 请求,能从 sqlite 找到 worker A 写下的 checkpoint,**resume 接口本身能跑通**(但 SSE 事件流仍隔离 — 见下文剩余风险)。 ### 修复 4:多层失败兜底,保证写作流程能继续 | 改动 | 作用 | |---|---| | `_sse(event, data)` 加 `default=str` + notice 帧降级 | JSON 序列化失败不会让 SSE 断开 | | 所有 DB 写入(草稿/审核/干预/status)已包 try/except | DB 异常吞掉,graph 继续推 | | 文章类型加载失败 → 退回 `[]` | intent_parser 仍能跑 | | `/start` 加 503 兜底 | graph 构建失败时给前端可读错误而不是 500 | ### 修复 5:定期清理 + admin 触发接口 | 文件 | 改动 | |---|---| | `app/gateway/ai_writing_cleanup.py` | 新文件:cron 调度 + 联动清理(MySQL 行 + sqlite checkpointer thread) | | `packages/harness/deerflow/persistence/ai_writing_sessions/sql.py` | 新增 `list_older_than()` / `delete_by_ids()` | | `app/gateway/app.py` | lifespan 启动/停止清理任务 | | `app/gateway/routers/ai_writing.py` | 新增 `POST /api/ai-writing/admin/cleanup` 手动触发接口(admin only) | | `config.yaml` | 新增 `ai_writing.cleanup` 段(默认每天凌晨 3 点跑,保留 7 天) | **关键安全机制**:清理永远跳过 `_event_queues` 里仍在跑的会话(**活跃保护**),即使 admin 手动传 `retention_days: 0` 也不会秒杀正在写作的用户。 ### 修复 6:优雅关闭 — In-flight Drain | 文件 | 改动 | |---|---| | `app/gateway/routers/ai_writing.py` | 新增 `_inflight_graph_tasks` + `_spawn_graph_task()` + `wait_for_inflight_graph_tasks(timeout)` | | `app/gateway/app.py` | lifespan shutdown 顺序:取消清理 → **等 in-flight 写作 task 收尾(30s 超时)** → 关 checkpointer connection | 容器收到 SIGTERM 时,给正在跑的写作 30 秒窗口跑到下一个 interrupt / END,已生成的 checkpoint 都安全落盘。 ### 修复 7:多 worker 配置陷阱检测 | 文件 | 改动 | |---|---| | `app/gateway/app.py` | lifespan startup 检测 `WEB_CONCURRENCY > 1` 或 `/proc` 里同名 uvicorn 进程数 > 1 → 打 ERROR 日志 | 下次启动容器看 docker logs 第一屏就能看到强提醒。 --- ## 四、当前状态评估 ### transcript 500 ✅ **彻底修复**,跟 worker 数无关。LONGTEXT 列 + 路由兜底双保险。 ### resume 报错 ⚠️ **大幅缓解**: - 接口本身(在 worker > 1 下)能跑通 - sqlite 共享让 worker B 也能恢复 worker A 创建的 session ❌ **未彻底解决**: - SSE 事件流仍 per-worker 隔离 - 用户可能看到「进度时有时无、需要刷新页面才能看到草稿」 - 但**草稿、审核结果**都落到 MySQL,刷新 `/sessions/{id}` 总能看到最终成品 ### 「写作流程能不能跑完」 ✅ **能**。最坏情况下: - 用户感受:进度断断续续,需要刷新几次 - 数据保证:草稿和审核都落 MySQL,**写出来的内容不会丢** --- ## 五、剩余风险 ### 风险 A:多 worker 下 SSE 事件流隔离 ⚠️ 最重要 **症状**:用户 SSE 长连接绑在 worker B,但 graph 推进任务跑在 worker A,事件 put 进 A 的 queue → SSE 收不到。 **为什么不能用 `--workers 1` 解决**:业务团队反馈其他业务功能需要多 worker。 **解决方案见第六章**。 ### 风险 B:容器优雅关闭时 in-flight 写作进度 **当前缓解**:30 秒 drain timeout 让 graph 跑到下一个 checkpoint。 **完美方案**(如有需求):无法 100% 防护,只能尽量缩短「未落 checkpoint」窗口。 ### 风险 C:节点级别 LLM 抽风 某个写作节点调用 LLM 时网络抖动 / 限流 → astream 抛错 → session 结束。 **当前缓解**:astream level 已 try/except,推 error 事件。用户从 checkpoint 重试。 **改进方向**(不在本次修复范围): - 给节点加 `tenacity.retry` 重试装饰器 - 节点抛错时把已生成的部分塞进 progress_events ### 风险 D:跨 worker 恢复时降级丢失 worker B 从 sqlite 恢复 worker A 的 session 时,以下数据回退到默认: | 数据 | 默认值 | 影响 | |---|---|---| | `_session_model_names` | `""` | 退回默认模型 | | `_session_interventions` | `[]` | 本次 resume 之前的干预历史从内存里丢(MySQL 里有副本,但内存累计不全) | | `_session_article_types` | `[]` | 没影响(graph 早过了 intent_parser) | **改进方向**:恢复时从 MySQL 反向填充内存元数据(约 20 行代码)。 --- ## 六、Worker > 1 限制下的解决方案路径 ### 三条路径对比 | 方案 | 是否引入新依赖 | 代码改动 | 运维改动 | 适用场景 | |---|---|---|---|---| | **B. Redis Pub/Sub 共享状态** | ⚠️ 需 Redis | ~150 行 | docker-compose 加 redis | 已有 Redis 或愿意上 | | **C. AI 写作独立单 worker 进程** | 无 | ~30 行 | docker-compose 加一个容器 / 进程 + nginx 转发 | 不想上 Redis | | **F. 多容器单 worker + nginx sticky** | 无 | ~5 行(nginx config) | 把 1 个多 worker 容器拆成 N 个单 worker 容器 | 已经在做容器编排 | ### 方案 B:Redis Pub/Sub(最彻底) **改造点**: ``` 之前(per-worker memory dict) 之后(Redis 共享) ───────────────────────── ───────────────────── _event_queues[sid] = asyncio.Queue() → Redis Pub/Sub channel "ai_writing:events:{sid}" _session_pending_pause → Redis Hash "ai_writing:pause" _session_model_names → Redis Hash "ai_writing:meta:model" _session_interventions → Redis Hash + JSON _session_repos / _session_user_ids → Redis Hash ``` **关键设计**: 1. `/start` 在 worker A:graph 推进任务跑在 A,事件 publish 到 Redis channel 2. `/stream` 在 worker B:subscribe Redis channel,把消息转 SSE 推前端 3. `/resume` 在 worker C:用 Redis 分布式锁保证「同一 session 同时只有一个 worker 驱动 graph」 **优点**:根治。任何 worker 数、任何部署形态都能跑。 **缺点**: - 引入 Redis 依赖(运维负担) - 代码改动较大(约 150 行) - 需要处理 Redis 断连 / 分布式锁释放等边缘情况 ### 方案 C:AI 写作独立服务(次推荐) **做法**:在同一个容器里多起一个 uvicorn 进程,专门处理 `/api/ai-writing/*`,**显式 `--workers 1`**。 ```bash # 主 gateway(多 worker,处理其他业务) uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --workers 4 # AI 写作专用单 worker uvicorn app.gateway.app:app --host 0.0.0.0 --port 8002 --workers 1 ``` nginx 配置: ```nginx location /api/ai-writing/ { proxy_pass http://localhost:8002; proxy_buffering off; proxy_read_timeout 3600s; } location / { proxy_pass http://localhost:8001; } ``` **优点**: - 零代码改动 - 不引入新依赖 - AI 写作彻底单 worker,问题根除 **缺点**: - 容器内多一个进程 - 内存占用 +1 份 Python runtime(约 200 MB) ### 方案 F:多容器单 worker + nginx sticky **做法**:把当前 1 个 4 worker 容器,拆成 4 个 1 worker 容器,nginx 用 `ip_hash` 做 sticky。 ```yaml # docker-compose.yml services: gateway-1: { ports: ["8001:8001"], command: ["...", "--workers", "1"] } gateway-2: { ports: ["8002:8001"], command: ["...", "--workers", "1"] } gateway-3: { ports: ["8003:8001"], command: ["...", "--workers", "1"] } gateway-4: { ports: ["8004:8001"], command: ["...", "--workers", "1"] } nginx: # upstream 配 ip_hash,让同一个客户端粘到同一个容器 ``` ```nginx upstream gateway_pool { ip_hash; server gateway-1:8001; server gateway-2:8001; server gateway-3:8001; server gateway-4:8001; } ``` **优点**:零代码改动,标准做法 **缺点**: - 改动 docker-compose - 客户端 IP 不均匀时负载不均衡(但 AI 写作低并发场景影响小) ### 推荐顺序 1. **方案 C(AI 写作独立单 worker 进程)** — 改动最小、风险最低、立刻可上 2. **方案 F(多容器 sticky)** — 如果你们已经在做多容器编排 3. **方案 B(Redis)** — 长期方案,等真正需要水平扩容时再上 --- ## 六-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 断断续续」的旧体验。 --- ## 七、运维操作清单 ### 部署前验证 ```bash # 1) 确认 .deer-flow 数据卷挂出来了(持久化的命脉) docker exec ls -la /app/.deer-flow/data/ # 应该能看到 checkpoints.db 文件(首次启动后会自动创建) # 2) 确认 alembic 迁移跑完了 docker exec sh -c "cd /app/backend && PYTHONPATH=. uv run alembic current" # 应该看到包含 20260519_02 的 head # 3) 确认 transcript 列已扩容 docker exec mysql -uroot -p deerflow -e \ "SHOW COLUMNS FROM ai_writing_sessions LIKE 'transcript';" # Type 列应该是 longtext # 4) 查 worker 数 docker exec ps -ef | grep -E 'uvicorn|gunicorn' # 如果 > 1,且没做任何方案 C/F/B,启动日志会打 ERROR 警告 ``` ### 启动时关注的日志 ```bash docker logs 2>&1 | head -100 | grep -iE 'ai_writing|checkpointer|worker' ``` 期望看到: - `ai_writing: 使用 AsyncSqliteSaver (xxx.db)` — 持久化生效 - `ai_writing_cleanup: 已启动 cron=...` — 清理任务起来了 警告: - `⚠ 检测到 WEB_CONCURRENCY=N` — 多 worker 配置警告 - `ai_writing: 持久化 checkpointer 不可用,退回 InMemorySaver` — sqlite 初始化失败,需立刻排查 ### 用户报告「会话丢失」时的排查 ```bash # 1) 查 sqlite 里这个 session 的快照 docker exec sh -c "sqlite3 /app/.deer-flow/data/checkpoints.db \ \"SELECT thread_id, checkpoint_ns FROM checkpoints WHERE thread_id='' LIMIT 5;\"" # 2) 查 MySQL 里这条会话 docker exec mysql -uroot -p deerflow -e \ "SELECT id, status, draft_title, updated_at FROM ai_writing_sessions WHERE id='';" # 3) 看 gateway 日志里这个 session 的活动轨迹 docker logs 2>&1 | grep '' | tail -50 # 4) 看是否有 recover_session 调用 docker logs 2>&1 | grep 'ai_writing: recovered' | tail -20 # 5) 看是否有节点异常 docker logs 2>&1 | grep -E 'ai_writing graph segment failed|ai_writing.*error' | tail -20 ``` ### 手动触发清理(admin only) ```bash # 用 admin 账号登录后,取 cookie,调清理接口 curl -X POST 'http:///api/ai-writing/admin/cleanup' \ -H 'Content-Type: application/json' \ -H 'Cookie: ' \ -d '{"retention_days": 7}' ``` 返回: ```json { "deleted_db": 12, "deleted_checkpoints": 12, "skipped_active": 1, "elapsed_seconds": 0.234, "params": { "retention_days": 7, "only_finished": false, "batch_size": 500 } } ``` `skipped_active` > 0 表示有正在跑的会话被活跃保护拦下来,不会被误删。 --- ## 八、相关文件索引 ### 后端 - `offline-backend-20260512/backend/app/gateway/routers/ai_writing.py` — 路由 + 内存状态字典 + drain - `offline-backend-20260512/backend/app/gateway/ai_writing_cleanup.py` — 定期清理 - `offline-backend-20260512/backend/app/gateway/app.py` — lifespan / 多 worker 检测 - `offline-backend-20260512/backend/packages/harness/deerflow/agents/ai_writing/graph.py` — Graph 定义 + 持久化 checkpointer - `offline-backend-20260512/backend/packages/harness/deerflow/persistence/ai_writing_sessions/` — MySQL repo - `offline-backend-20260512/backend/packages/harness/deerflow/persistence/types.py` — `PortableLongText` - `offline-backend-20260512/backend/packages/harness/deerflow/persistence/migrations/versions/20260519_02_*.py` — LONGTEXT 迁移 - `offline-backend-20260512/config.yaml` — `checkpointer:` + `ai_writing.cleanup:` 配置 ### 前端 - `frontend-web/src/open-canvas/pages/AIWritingPage.tsx` — 页面顶部有快速排查注释 - `frontend-web/src/open-canvas/api/ai-writing-sessions.ts` — transcript 保存(已做 fire-and-forget 容错) - `frontend-web/src/open-canvas/api/ai-writing.ts` — resume / stream ### 测试 - `tests/test_ai_writing_cleanup.py` — 清理 + drain + checkpointer 降级 + SSE 序列化(21 个测试) - `tests/test_ai_writing_session_recovery.py` — 跨 worker 会话恢复(8 个测试) - `tests/test_ai_writing_session_repo.py` — Repo(7 个测试) - `tests/test_ai_writing_transcript_endpoint.py` — transcript 兜底(5 个测试) - `tests/test_portable_long_text.py` — LONGTEXT 列类型(5 个测试) 总测试:**51 个,全过**。 --- ## 九、变更历史 | 日期 | Commit | 内容 | |---|---|---| | 2026-05-19 | c3d0c82 | 报错兜底(transcript LONGTEXT 迁移 + 路由 try/except + session 恢复) | | 2026-05-20 | (本次) | checkpointer 持久化 + 定期清理 + admin 接口 + 多层兜底 + drain + 多 worker 检测 | --- ## 十、决策摘要(给未来的你/同事) > **如果你现在第一次接手这个问题**,按这个清单往下走: > > 1. ✅ **transcript 500 不用管** — 已彻底修复 > 2. ⚠️ **resume 报错的根因是多 worker** — sqlite 持久化已减轻,但 SSE 事件流仍隔离 > 3. ⚠️ **写作能跑完,但用户体验断断续续** — 草稿数据安全,刷新就能看到 > 4. 🎯 **要彻底解决,从方案 C / F / B 选一个**(建议从 C 开始) > 5. 🚨 **务必确认 `.deer-flow` 数据卷挂出来了** — 否则 sqlite 持久化白做 > 6. 📊 **关注的日志关键字**:`ai_writing:`、`checkpointer`、`AsyncSqliteSaver`、`WEB_CONCURRENCY` 如有疑问,先看本文件的「七、运维操作清单」做基础排查,再问当前维护者。