第四章 系统整体架构设计

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

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

但是，仅仅知道使用 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 地址

模型名称

全部放到：

.env

或者：

config.py

以后迁移服务器，

几乎不用修改代码。

---

第五原则：模块可替换

整个系统必须做到：

任何一个模块，

都可以随时替换。

例如：

DeepSeek

↓

OpenAI

或者：

Qwen

↓

Claude

业务代码不应该发生变化。

---

4.2 系统整体架构图

整个系统可以划分为六层。

                    ┌────────────────────────────┐
                    │        企业微信客户端        │
                    └────────────┬───────────────┘
                                 │
                           HTTPS 回调
                                 │
                    ┌────────────▼───────────────┐
                    │        OpenResty           │
                    │ SSL / Nginx / ReverseProxy │
                    └────────────┬───────────────┘
                                 │
                    ┌────────────▼───────────────┐
                    │       FastAPI Gateway      │
                    │ 企业微信消息入口            │
                    └────────────┬───────────────┘
                                 │
      ┌──────────────┬───────────┴──────────────┬─────────────┐
      │              │                          │             │
      ▼              ▼                          ▼             ▼
 消息解析        Session管理              AI Service      Tool Manager
 XML解析         上下文缓存               DeepSeek         ERP
 AES解密         Redis                  OpenAI          数据库
 签名校验        Memory                 Claude          天气API
      │              │                          │             │
      └──────────────┴──────────────┬───────────┘
                                     ▼
                             回复企业微信消息

整个架构非常简单。

真正复杂的只有消息处理这一层。

其它模块几乎都是标准的软件架构。

---

4.3 消息流转过程

下面来看一次完整的消息处理流程。

例如：

用户发送：

今天北京天气怎么样？

整个系统会经历以下步骤。

企业微信

↓

HTTPS

↓

OpenResty

↓

FastAPI

↓

验证签名

↓

AES 解密

↓

XML 转 JSON

↓

Session 查询

↓

调用 DeepSeek

↓

获得回复

↓

XML 加密

↓

返回企业微信

↓

用户收到回复

整个过程，

用户通常感觉不到。

耗时一般在：

1~3 秒

这就是一个完整的请求生命周期（Request Lifecycle）。

---

4.4 模块划分

为了方便维护，

我把整个项目拆分成多个模块。

app/

├── api/
│
├── wecom/
│
├── ai/
│
├── tools/
│
├── memory/
│
├── models/
│
├── services/
│
├── config/
│
└── utils/

下面分别介绍每个模块。

---

api/

负责：

所有 HTTP 接口。

例如：

/wecom/callback

/health

/version

它只负责：

接收请求。

绝不写业务逻辑。

---

wecom/

企业微信专用模块。

里面包括：

消息解密

消息加密

XML解析

签名验证

Reply封装

以后如果接飞书。

这里基本不用修改。

新增：

feishu/

即可。

---

ai/

负责所有 AI。

例如：

DeepSeek

OpenAI

Claude

Gemini

统一提供：

chat()

stream()

embedding()

业务层永远不要直接调用 SDK。

---

memory/

负责上下文。

例如：

Redis

SQLite

PostgreSQL

向量数据库

以后升级，

这里只需要替换实现。

其它模块不需要改。

---

tools/

负责所有工具。

例如：

天气

数据库

ERP

CRM

邮件

Excel

知识库

未来 Tool Calling，

全部从这里管理。

---

services/

真正业务逻辑。

例如：

聊天流程

Agent

工作流

消息处理

Prompt拼接

这里，

才是整个系统的大脑。

---

4.5 请求生命周期（Request Lifecycle）

下面画一个更加完整的数据流。

用户

↓

企业微信

↓

HTTPS

↓

OpenResty

↓

FastAPI

↓

WeCom Handler

↓

Decrypt

↓

Parse XML

↓

Session

↓

Prompt Builder

↓

AI Model

↓

Tool Calling

↓

AI Result

↓

Encrypt XML

↓

HTTP Response

↓

企业微信

↓

用户

可以发现。

真正调用 AI，

其实只是整个流程中的一步。

很多初学者，

把所有代码都写在：

main.py

里面。

几十行还可以。

几百行以后，

整个项目就无法维护了。

因此：

模块拆分非常重要。

---

4.6 为什么采用 Gateway 模式？

很多教程直接这样写：

企业微信

↓

FastAPI

↓

AI

看起来很简单。

但是以后：

增加：

公众号

飞书

钉钉

Telegram

Slack

怎么办？

于是，

我们增加一层：

Gateway

变成：

企业微信

↓

Gateway

↓

AI

Gateway 的职责只有三个。

第一：

统一入口。

第二：

统一认证。

第三：

统一消息格式。

这样：

AI 永远只处理：

UserMessage

而不是：

XML

JSON

Webhook

HTTP

这就是 Gateway 的意义。

---

4.7 部署架构

整个部署也尽量简单。

                    Internet
                        │
                  443 HTTPS
                        │
               OpenResty(Nginx)
                        │
                127.0.0.1:8000
                        │
                   FastAPI
                        │
         ┌──────────────┴──────────────┐
         │                             │
     DeepSeek API                  Redis
         │                             │
         └──────────────┬──────────────┘
                        │
                    PostgreSQL

以后增加：

Qdrant

Milvus

MinIO

RabbitMQ

都不会影响整体架构。

---

4.8 日志系统设计

很多项目上线以后，

最怕的一句话就是：

“程序好像坏了。”

为什么坏了？

没人知道。

所以，

日志一定要提前设计。

建议分四类。

access.log

error.log

ai.log

wecom.log

其中：

OpenResty 负责：

access.log

error.log

FastAPI 负责：

application.log

AI 调用单独：

ai.log

以后排查问题，

速度会快很多。

---

4.9 为什么这样设计？

很多读者可能会觉得：

这个架构是不是有点复杂？

其实恰恰相反。

复杂的不是架构。

而是未来业务。

好的架构，

应该让业务越来越复杂，

而代码依然保持整洁。

随着系统不断成长，

你可以继续增加：

• MCP Server
• Agent Router
• Workflow Engine
• RAG
• Knowledge Base
• Multi-Agent
• Scheduler
• Message Queue

而不用推倒重来。

这，

才是真正的软件架构。

---

本章小结

这一章，我们没有编写任何业务代码，而是完成了整个系统的架构设计。

我们明确了五大设计原则：单一职责、低耦合、高内聚、配置分离、模块可替换，并围绕这些原则构建了企业微信 AI 助手的整体框架。

整个系统采用了典型的分层架构：

• OpenResty：统一 HTTPS 入口和安全控制。
• FastAPI Gateway：统一处理企业微信回调请求。
• WeCom 模块：完成消息解密、签名校验和 XML 解析。
• AI Service：统一封装大模型调用能力。
• Tool Manager：负责所有外部工具和业务能力。
• Memory Service：负责会话上下文和长期记忆。
• Service Layer：承载业务逻辑和 Agent 流程。

同时，我们还规划了完整的请求生命周期、项目目录结构、部署拓扑和日志体系。

至此，一个能够长期维护、易于扩展、支持多模型、多平台接入的 AI 助手基础架构已经搭建完成。

下一章开始，我们将正式进入开发阶段，从零开始搭建开发环境，并创建整个项目的工程骨架。