第十三章：系统日志、TraceID与可观测性设计
这一章开始，系统从：
“能运行的分布式系统”
升级为：
“可观测、可追踪、可定位问题的生产级系统”
13.1 当前系统的真实问题
虽然我们已经具备：
企业微信 → FastAPI → Redis → Worker → AI → 回复
但在生产环境中会出现一个核心问题：
❌ 系统“黑盒化”
典型问题
用户说：为什么没回复？
你无法快速回答：
- 消息在哪一步卡住？
- 是 Webhook 问题？
- Redis 问题？
- Worker 问题？
- AI超时？
- 还是发送失败？
❌ 日志分散
FastAPI日志一份
Worker日志一份
AI调用日志一份
Redis日志一份
无法串联。
❌ 无法追踪单条消息
一条用户消息 → 多个系统组件
但没有统一ID
13.2 本章目标
构建一套完整的：
✔ TraceID贯穿全链路
✔ 结构化日志
✔ 请求级追踪
✔ Worker可观测
✔ AI调用可记录
13.3 TraceID设计（核心思想）
📌 什么是 TraceID？
一条消息在系统中的“身份证”
📌 贯穿链路
企业微信消息
↓ trace_id=abc123
FastAPI
↓
Redis Queue
↓
Worker
↓
LLM
↓
Send API
13.4 TraceID生成规则
📌 建议方案
trace_id = uuid4().hex
📌 utils/id.py
import uuid
def generate_trace_id():
return uuid.uuid4().hex
13.5 日志系统设计（Loguru）
📌 选择 Loguru
原因：
- ✔ 无需复杂配置
- ✔ 支持结构化日志
- ✔ 支持文件分割
- ✔ 支持上下文绑定
13.6 logger.py（核心实现）
from loguru import logger
import sys
logger.remove()
logger.add(
sys.stdout,
format="{time} | {level} | {extra[trace_id]} | {message}",
level="INFO"
)
13.7 TraceID绑定机制
📌 核心思想
每条请求绑定一个上下文变量
📌 utils/context.py
from contextvars import ContextVar
trace_id_var = ContextVar("trace_id", default=None)
def set_trace_id(trace_id: str):
trace_id_var.set(trace_id)
def get_trace_id():
return trace_id_var.get()
13.8 Logger增强（自动注入TraceID）
📌 logger升级
from loguru import logger
from app.utils.context import get_trace_id
def log(message: str):
trace_id = get_trace_id()
logger.bind(trace_id=trace_id).info(message)
13.9 FastAPI接入TraceID
📌 callback入口改造
from app.utils.id import generate_trace_id
from app.utils.context import set_trace_id
from app.logger import log
@router.post("/callback")
async def callback(request: Request):
trace_id = generate_trace_id()
set_trace_id(trace_id)
log("收到企业微信请求")
body = await request.body()
log("开始解析XML")
...
13.10 Worker接入TraceID
📌 worker改造
from app.utils.context import set_trace_id
from app.logger import log
async def process(message: dict):
trace_id = message.get("trace_id")
set_trace_id(trace_id)
log(f"开始处理消息: {message.get('Content')}")
13.11 Redis消息结构升级
📌 必须携带 trace_id
{
"trace_id": "abc123",
"FromUserName": "user1",
"Content": "你好",
"MsgId": "xxx"
}
13.12 全链路日志效果
📌 示例输出
2026-07-03 09:40:12 | INFO | abc123 | 收到企业微信请求
2026-07-03 09:40:12 | INFO | abc123 | 解密成功
2026-07-03 09:40:12 | INFO | abc123 | 写入Redis队列
2026-07-03 09:40:13 | INFO | abc123 | Worker开始处理
2026-07-03 09:40:15 | INFO | abc123 | AI返回成功
13.13 可观测性能力提升
✔ 改造前
❌ 只能看日志文件
❌ 无法关联请求
❌ 无法定位问题
✔ 改造后
✔ 一条消息全链路可追踪
✔ 每一步都有日志
✔ 可定位任意节点问题
13.14 Worker错误定位能力
现在可以精确回答：
“这条消息为什么没回复？”
答案：
trace_id = abc123
卡在：
→ LLM超时（15s）
13.15 系统架构升级（可观测版）
企业微信
↓
FastAPI (trace_id)
↓
Redis Queue (trace_id)
↓
Worker (trace_id)
↓
LLM (trace_id)
↓
WeCom Send (trace_id)
↓
Log System（统一输出）
13.16 本章核心价值
这一章完成后：
👉 系统从“可运行”
升级为
👉 “可观测系统”
13.17 当前系统能力总结
✅ 已完成能力
✔ AI对话系统
✔ 异步队列
✔ Worker架构
✔ Token管理
✔ 幂等机制
✔ 重试机制
✔ 死信队列
✔ TraceID追踪
✔ 结构化日志
🚀 下一章预告（第十四章）
第十四章：系统性能优化与限流设计（企业级稳定性）
下一章我们将进入：
✔ 并发控制
✔ Redis限流
✔ AI请求保护
✔ Worker负载均衡
✔ 系统抗压能力设计
👉 到这一章结束：
系统将具备真正的：
“高并发企业级 AI 服务能力”