企业微信 AI 自动回复系统实战排障记录（Docker + FastAPI + Redis）

这次问题排查覆盖了一个典型的“企业级 AI 消息链路系统”，从 Webhook → Redis 队列 → Worker → AI → 企业微信发送，全链路几乎都踩了一遍坑。

整套问题最终可以总结为一句话：

不是系统没跑，而是“多层结构 + 配置 + 缩进 + import + 启动方式”叠加导致链路断裂。

一、系统架构设计（目标状态）

整体系统设计如下：

企业微信消息
        ↓
FastAPI Webhook（wecom-bot）
        ↓
Redis Queue（解耦）
        ↓
Worker 消费队列
        ↓
DeepSeek / AI分析
        ↓
企业微信发送接口

二、初始现象

系统启动后出现以下问题：

❌ 企业微信收不到自动回复
❌ worker 容器频繁重启
❌ Redis 队列有数据但无反馈
❌ FastAPI 接口日志正常但无结果

三、问题排查全过程（关键坑点）

1️⃣ Worker 直接崩溃：缺少 Python 包

错误日志：

ModuleNotFoundError: No module named 'app'

原因：

Docker 中 Python 没有设置模块路径

修复：

environment:
  PYTHONPATH: /app

2️⃣ docker-compose build 结构错误

错误：

services.wecom-worker.build must be a string

原因：

旧版 Compose 不支持：

build:
  context: .
  dockerfile: Dockerfile

修复：

build: .

3️⃣ YAML 缩进灾难（最致命问题）

错误：

did not find expected '-' indicator

根因：

Tab + 空格混用
environment / command / depends_on 层级错位
worker 模块整体缩进破坏

4️⃣ worker 未执行发送逻辑

虽然 worker 能消费队列，但：

没有日志输出 send
没有企业微信响应

5️⃣ internal_reply 接口设计错误

问题：

token = get_access_token()

但函数未定义 → 直接 NameError

6️⃣ 架构混乱：双 worker 并存

系统中同时存在：

worker.py（正确）
worker_lead.py（旧逻辑）

导致：

消息路径不一致
发送链路混乱
调试困难

四、最终修复方案

✔ 统一 Worker

最终采用：

python app/worker.py

✔ docker-compose 标准化

wecom-worker:
  build: .
  container_name: wecom-worker
  restart: always

  working_dir: /app

  volumes:
    - ./app:/app/app

  environment:
    TZ: Asia/Shanghai
    REDIS_HOST: redis
    REDIS_PORT: 6379
    PYTHONUNBUFFERED: 1
    PYTHONPATH: /app

  command: python app/worker.py

  depends_on:
    - redis

✔ Redis 解耦结构确认

webhook 只负责入队
worker 负责处理
FastAPI 不做 AI 计算

五、最终运行状态

修复完成后系统进入稳定状态：

✔ webhook 正常接收
✔ Redis 队列正常流转
✔ worker 正常消费
✔ AI 正常返回
✔ 企业微信成功发送

日志示例：

processed: {'content': 'hello', 'intent': 'chat'}
🤖 reply: 收到，谢谢您的消息
📤 sent result: {"errcode":0}

六、关键经验总结（非常重要）

1️⃣ Docker 环境问题 > 代码问题

很多“代码 bug”，本质是：

PYTHONPATH
volume 覆盖
working_dir 不一致

2️⃣ YAML 是生产环境第一坑

80% compose 问题是缩进
Tab 永远是隐形炸弹

3️⃣ 多 worker 架构必须统一入口

否则：

消息路径分裂
debug 不可控
状态不可预测

4️⃣ FastAPI + Worker 必须职责分离

正确结构：

模块	职责
webhook	收消息
redis	解耦
worker	处理逻辑
sender	发消息

七、最终架构建议（升级方向）

如果要生产化，建议升级为：

worker 单入口
Redis stream（替代 list）
统一日志 trace_id
重试队列机制
dead letter queue

八、总结一句话

这次问题的本质不是“程序错了”，而是“系统在多个层（Docker + YAML + Python + 架构）同时发生小错误叠加，最终导致链路断裂”。

如果下一步想做升级版，可以直接做一个：

🚀 企业级 AI 获客系统 V2

n8n + Redis stream + FastAPI
自动线索评分
企业微信智能分发
可接 DeepSeek / Claude / OpenAI
带监控 + 重试 + 失败队列