第二篇系统开发 on HappyRock

第四章系统整体架构设计

Fri, 03 Jul 2026 09:23:18 +0800

好的架构不是功能最多，而是每一层都知道自己应该做什么。

经过前面的需求分析和技术选型，我们已经确定了整个项目的技术路线。

但是，仅仅知道使用 FastAPI、OpenResty、DeepSeek 这些技术还远远不够。

真正决定一个项目是否能够长期维护、持续扩展的，是系统架构。

这一章，我们不会写一行业务代码，而是先搭建整个系统的骨架。

有了清晰的架构，后面的开发就会像搭积木一样自然。

4.1 整体架构设计原则

开始画架构图之前，我先给自己定下了五条原则。

第一原则：单一职责（Single Responsibility）

每一个模块，只负责一件事情。

例如：

OpenResty 负责 HTTPS、反向代理、安全控制
FastAPI 负责业务逻辑
AI Service 负责调用大模型
Tool Service 负责工具调用
Memory Service 负责上下文管理

任何模块，都不要"什么都做"。

职责越清晰，维护越简单。

第二原则：低耦合（Low Coupling）

模块之间尽量减少依赖。

例如：

AI Service 不应该知道企业微信。

它只应该知道：

输入：

用户消息

输出：

AI 回复

至于消息来自企业微信、飞书还是网页聊天室，

AI 根本不需要关心。

这样未来接入新的聊天平台时，

AI Service 可以完全不用修改。

第三原则：高内聚（High Cohesion）

同一类功能必须放在一起。

例如：

app/

    ai/

    wecom/

    tools/

    memory/

    config/

而不是：

utils.py

common.py

helper.py

tools.py

functions.py

随着项目越来越大，

“万能工具类"最终都会变成维护噩梦。

第四原则：配置与代码分离

所有配置必须放到配置文件。

例如：

API Key

企业微信 Token

AESKey

数据库密码

Redis 地址

模型名称

全部放到：

第五章：项目初始化与开发环境搭建

Fri, 03 Jul 2026 08:23:18 +0800

从这一章开始，我们正式开始搭建整个 wecom-bot 项目。

这一章我不会仅仅告诉大家如何安装几个软件，而是按照真实企业项目的方式，一步一步把整个开发环境搭好。

最终效果如下：

MacBook（开发）

├── VSCode
├── Cursor
├── Docker Desktop
├── Git
├── Python3.11
├── n8n
├── Ollama
├── Qdrant
└── 本地调试 wecom-bot


                │ Git Push

                ▼

GitHub



                │

                ▼

Ubuntu Server

├── OpenResty
├── Docker
├── Docker Compose
├── wecom-bot
├── HTTPS
├── 企业微信回调
├── DeepSeek API
└── 自动回复服务

整个项目采用：

本地开发 + Git 管理 + 服务器部署

而不是直接 SSH 到服务器写代码。

这是企业开发最标准的方式。

5.1 项目目录规划

首先建立整个项目。

mkdir wecom-bot
cd wecom-bot

项目最终目录如下：

第六章：企业微信回调接口完整实现（Webhook入口打通）

Fri, 03 Jul 2026 07:33:18 +0800

这一章是整个系统的第一个真实里程碑：

让企业微信成功“打通你的服务”，完成 URL 验证，并具备接收消息能力。

一旦这一章完成，你的系统就不再是“服务”，而是真正意义上的：

企业微信 AI 机器人入口系统

6.1 企业微信回调机制本质

企业微信回调不是普通 HTTP 请求，而是一个安全消息通道协议。

它包含三层机制：

HTTP层（请求入口）
   ↓
签名层（防伪造）
   ↓
加密层（AES消息内容）

📌 两种请求类型

① URL验证（GET）

用于首次绑定回调地址：

企业微信后台 → 验证回调URL

参数：

msg_signature
timestamp
nonce
echostr

② 消息推送（POST）

用户发送消息后：

企业微信 → POST → 你的服务

内容是：

<xml>
    <Encrypt>...</Encrypt>
    <MsgSignature>...</MsgSignature>
    <TimeStamp>...</TimeStamp>
    <Nonce>...</Nonce>
</xml>

6.2 项目结构准备（本章新增）

在 app/wecom/ 下新增模块：

app/wecom/
│
├── callback.py        # 回调入口
├── crypto.py          # 加解密
├── validator.py       # 签名验证
└── parser.py          # XML解析（本章新增）

6.3 FastAPI回调入口实现

📌 main.py 注册路由

from fastapi import FastAPI, Request
from app.wecom.callback import wecom_callback_router

app = FastAPI()

app.include_router(wecom_callback_router, prefix="/wecom")

📌 callback.py（核心入口）

from fastapi import APIRouter, Request
from app.wecom.crypto import WeComCrypto
from app.wecom.validator import verify_url

router = APIRouter()

crypto = WeComCrypto()


@router.get("/callback")
async def verify_callback(
    msg_signature: str,
    timestamp: str,
    nonce: str,
    echostr: str
):
    """
    企业微信URL验证
    """
    result = verify_url(
        msg_signature=msg_signature,
        timestamp=timestamp,
        nonce=nonce,
        echostr=echostr,
        crypto=crypto
    )

    return result

6.4 URL验证逻辑（第一关）

📌 verify_url.py

from app.wecom.crypto import WeComCrypto


def verify_url(msg_signature, timestamp, nonce, echostr, crypto: WeComCrypto):
    """
    企业微信URL验证逻辑
    """

    decrypted = crypto.decrypt_echo_str(
        msg_signature=msg_signature,
        timestamp=timestamp,
        nonce=nonce,
        echostr=echostr
    )

    return decrypted

📌 验证逻辑本质

企业微信发送加密 echostr
        ↓
服务端解密
        ↓
原样返回
        ↓
验证成功

6.5 企业微信加解密核心（crypto.py）

📌 WeComCrypto实现

from wechatpy.crypto import WeChatCrypto
import os


class WeComCrypto:
    def __init__(self):
        self.token = os.getenv("WECOM_TOKEN")
        self.aes_key = os.getenv("WECOM_AES_KEY")
        self.corp_id = os.getenv("WECOM_CORP_ID")

        self.crypto = WeChatCrypto(
            self.token,
            self.aes_key,
            self.corp_id
        )

    def decrypt_echo_str(self, msg_signature, timestamp, nonce, echostr):
        """
        URL验证解密
        """
        return self.crypto.check_signature(
            msg_signature,
            timestamp,
            nonce,
            echostr
        )

⚠️ 注意点（非常关键）

企业微信这里最容易错：

第七章：企业微信消息解密与完整回调链路打通

Fri, 03 Jul 2026 05:33:18 +0800

这一章是从“能收到请求”到“能理解消息”的关键跃迁。

上一章我们已经做到：

企业微信消息可以进入 FastAPI

但目前系统仍然是：

✔ 收到了请求
❌ 看不懂内容
❌ 没有解密
❌ 没有业务分发

这一章结束后，你的系统会变成：

企业微信 → 解析 → 解密 → 识别消息 → 分发处理

7.1 企业微信加密消息的真实结构

企业微信 POST 请求的核心内容如下：

<xml>
    <ToUserName><![CDATA[wwxxxxx]]></ToUserName>
    <Encrypt><![CDATA[encrypted_message]]></Encrypt>
</xml>

同时 HTTP 参数还有：

msg_signature=xxx
timestamp=xxx
nonce=xxx

📌 本质结构

HTTP层参数（签名）
   ↓
XML外壳
   ↓
Encrypt（真正消息体）
   ↓
AES解密
   ↓
明文XML

7.2 完整处理流程设计

本章完成后的标准链路：

POST /wecom/callback
        ↓
1. 解析XML
        ↓
2. 提取 Encrypt
        ↓
3. 校验 msg_signature
        ↓
4. AES解密
        ↓
5. 得到明文XML
        ↓
6. 解析消息内容
        ↓
7. 进入Dispatcher

7.3 更新 wecom_crypto（核心升级）

📌 crypto.py（完整实现）

from wechatpy.crypto import WeChatCrypto
import os


class WeComCrypto:
    def __init__(self):
        self.token = os.getenv("WECOM_TOKEN")
        self.aes_key = os.getenv("WECOM_AES_KEY")
        self.corp_id = os.getenv("WECOM_CORP_ID")

        self.crypto = WeChatCrypto(
            self.token,
            self.aes_key,
            self.corp_id
        )

    def verify_signature(self, msg_signature, timestamp, nonce, data):
        """
        校验签名
        """
        return self.crypto.check_signature(
            msg_signature,
            timestamp,
            nonce,
            data
        )

    def decrypt_message(self, msg_signature, timestamp, nonce, xml):
        """
        解密企业微信消息
        """
        return self.crypto.decrypt_message(
            xml,
            msg_signature,
            timestamp,
            nonce
        )

7.4 XML解析增强

📌 parser.py（升级版）

import xml.etree.ElementTree as ET


def parse_encrypt_xml(xml_str: str):
    """
    解析外层XML（带Encrypt）
    """
    root = ET.fromstring(xml_str)

    data = {}

    for child in root:
        data[child.tag] = child.text

    return data


def parse_plain_xml(xml_str: str):
    """
    解析解密后的XML
    """
    root = ET.fromstring(xml_str)

    data = {}

    for child in root:
        data[child.tag] = child.text

    return data

7.5 callback.py（完整版本）

📌 POST入口升级

from fastapi import APIRouter, Request
from app.wecom.crypto import WeComCrypto
from app.wecom.parser import parse_encrypt_xml, parse_plain_xml

router = APIRouter()
crypto = WeComCrypto()


@router.post("/callback")
async def callback(request: Request):
    """
    企业微信消息入口
    """

    # 1️⃣ 获取URL参数
    params = dict(request.query_params)

    msg_signature = params.get("msg_signature")
    timestamp = params.get("timestamp")
    nonce = params.get("nonce")

    # 2️⃣ 读取XML
    body = await request.body()
    xml_str = body.decode("utf-8")

    # 3️⃣ 解析外层XML
    outer = parse_encrypt_xml(xml_str)
    encrypt = outer.get("Encrypt")

    print("收到Encrypt:", encrypt)

    # 4️⃣ 校验签名
    crypto.verify_signature(
        msg_signature,
        timestamp,
        nonce,
        encrypt
    )

    # 5️⃣ 解密消息
    plain_xml = crypto.decrypt_message(
        msg_signature,
        timestamp,
        nonce,
        xml_str
    )

    print("解密后XML:", plain_xml)

    # 6️⃣ 解析明文
    message = parse_plain_xml(plain_xml)

    print("结构化消息:", message)

    return "success"

7.6 明文消息结构

解密后通常是：

第八章：消息分发与 Dispatcher 设计（系统进入可扩展阶段）

Fri, 03 Jul 2026 03:33:18 +0800

这一章是整个系统从“能解析消息”到“能处理业务逻辑”的分水岭。

上一章结束时，我们已经做到：

企业微信 → 解密 → 明文XML → Python对象

但目前的问题是：

所有消息都堆在 callback 里处理

这在工程上是不可接受的。

8.1 为什么必须要 Dispatcher

如果不做分发，会变成这样：

if text:
    do_text()

elif event:
    do_event()

elif image:
    do_image()

问题：

❌ 代码越来越臃肿
❌ 无法扩展新消息类型
❌ AI逻辑混入入口层
❌ 不可测试
❌ 不可拆分部署

✔ 正确做法：Dispatcher模式

核心思想：

“入口只负责接收，处理交给不同模块”

8.2 系统分层设计

本章完成后的结构：

callback.py
    ↓
dispatcher.py
    ↓
handler/
    ├── text.py
    ├── event.py
    ├── image.py
    └── file.py

8.3 Dispatcher设计

📌 dispatcher.py（核心）

from app.handlers.text import handle_text
from app.handlers.event import handle_event
from app.handlers.image import handle_image


class Dispatcher:

    def dispatch(self, message: dict):
        msg_type = message.get("MsgType")

        if msg_type == "text":
            return handle_text(message)

        elif msg_type == "event":
            return handle_event(message)

        elif msg_type == "image":
            return handle_image(message)

        else:
            return self.handle_unknown(message)

    def handle_unknown(self, message):
        print("未知消息类型:", message)
        return None

8.4 Handler设计原则

每个 handler 必须满足：

第九章：接入 Redis 消息队列（异步架构设计）

Fri, 03 Jul 2026 02:33:18 +0800

这一章开始，系统从“能处理消息”升级为：

能承载并发、可扩展、不会被AI阻塞的企业级架构

9.1 为什么必须引入异步队列

在上一章的架构中：

企业微信 → FastAPI → Dispatcher → AI → 返回

问题非常明显：

❌ 同步架构的致命问题

1️⃣ AI调用阻塞

用户发消息
   ↓
等待 DeepSeek
   ↓
接口卡住

2️⃣ 企业微信超时限制

企业微信要求：

5秒内必须返回 success

否则：

❌ 重试
❌ 重复消息
❌ 回调失败

3️⃣ 无法抗并发

10个用户 → OK
1000个用户 → 崩

✔ 正确架构：异步解耦

引入 Redis Queue：

企业微信
   ↓
FastAPI（只接收）
   ↓
Redis Queue（缓存消息）
   ↓
Worker（异步处理）
   ↓
AI（DeepSeek）
   ↓
发送回复

9.2 新架构设计

📌 完整链路

企业微信
   ↓
Webhook (FastAPI)
   ↓
Dispatcher
   ↓
Redis LPUSH（入队）
   ↓
立即返回 success
   ↓
Worker BRPOP（消费）
   ↓
LLM处理
   ↓
发送企业微信消息

9.3 Redis设计模型

我们采用最简单可靠模型：

第十章：Worker 接入 DeepSeek（AI核心引擎）

Fri, 03 Jul 2026 01:33:18 +0800

这一章开始，系统正式从：

“能处理消息的架构系统”

升级为：

“真正具备智能回复能力的 AI 系统”

10.1 当前系统状态回顾

在上一章结束时，我们已经有：

企业微信
   ↓
FastAPI（Webhook）
   ↓
Dispatcher
   ↓
Redis Queue
   ↓
Worker（但只是打印 + 假处理）

但此时 Worker 还没有“脑子”。

❌ 当前 Worker 的问题

只能：
✔ 接收消息
✔ 打印内容

不能：
❌ 理解语义
❌ 生成回复
❌ 具备AI能力

10.2 本章目标

本章完成后：

Worker
   ↓
DeepSeek API
   ↓
Prompt处理
   ↓
生成回复
   ↓
返回企业微信

10.3 AI调用架构设计

📌 新增核心模块

app/core/
    ├── llm.py
    ├── prompt.py
    └── client.py

10.4 DeepSeek API设计

我们统一封装LLM调用层：

第十一章：AccessToken 管理与企业微信稳定发送机制

Fri, 03 Jul 2026 00:38:18 +0800

这一章开始，我们从“能跑的系统”进入：

生产级系统必须解决的稳定性问题

11.1 当前系统的隐患

在上一章，我们实现了：

Worker → DeepSeek → 企业微信发送

但有一个非常严重的问题：

❌ 现有 AccessToken 方案问题

当前实现是：

每次发送消息都调用 gettoken

问题如下：

1️⃣ 性能浪费

每条消息 → 请求一次微信API

2️⃣ 容易触发限流

企业微信限制：

频繁调用 gettoken 会被限制

3️⃣ 不稳定

网络抖动 → token 获取失败 → 全链路失败

11.2 正确方案：Token缓存机制

📌 架构设计

WeCom API
   ↓
Token Manager
   ↓
Redis缓存
   ↓
Worker发送消息

11.3 Token生命周期规则

企业微信 Token：

有效期：7200秒（2小时）

但实际必须：

提前10分钟刷新

11.4 Redis Token结构设计

Key:
wecom:access_token

Value:
{
  "token": "...",
  "expire_at": 1234567890
}

11.5 Token Manager设计

📌 新增模块

app/core/token_manager.py

📌 完整实现

import time
import json
import httpx
import os
from app.queue.redis_client import redis_client


class TokenManager:

    def __init__(self):
        self.corp_id = os.getenv("WECOM_CORP_ID")
        self.secret = os.getenv("WECOM_SECRET")

        self.redis_key = "wecom:access_token"

    async def get_token(self):

        # 1️⃣ 先查Redis
        cached = redis_client.get(self.redis_key)

        if cached:
            data = json.loads(cached)

            # 未过期直接返回
            if data["expire_at"] > time.time():
                return data["token"]

        # 2️⃣ 重新获取
        token = await self.fetch_token()

        return token

    async def fetch_token(self):

        url = "https://qyapi.weixin.qq.com/cgi-bin/gettoken"

        params = {
            "corpid": self.corp_id,
            "corpsecret": self.secret
        }

        async with httpx.AsyncClient() as client:
            resp = await client.get(url, params=params)
            data = resp.json()

        token = data["access_token"]
        expires_in = data.get("expires_in", 7200)

        expire_at = time.time() + expires_in - 600  # 提前10分钟刷新

        # 存Redis
        redis_client.set(
            self.redis_key,
            json.dumps({
                "token": token,
                "expire_at": expire_at
            })
        )

        return token

11.6 企业微信发送服务升级

📌 wecom_service.py（改造版）

import httpx
import os
from app.core.token_manager import TokenManager


class WeComService:

    def __init__(self):
        self.agent_id = os.getenv("WECOM_AGENT_ID")
        self.token_manager = TokenManager()

    async def send_message(self, user: str, content: str):

        token = await self.token_manager.get_token()

        url = f"https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token={token}"

        payload = {
            "touser": user,
            "msgtype": "text",
            "agentid": self.agent_id,
            "text": {
                "content": content
            }
        }

        async with httpx.AsyncClient() as client:
            resp = await client.post(url, json=payload)
            return resp.json()

11.7 Worker接入优化

Worker无需改逻辑，只保持调用：

第二篇 系统开发 on HappyRock

第四章 系统整体架构设计