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

从这一章开始，我们正式开始搭建整个 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

项目最终目录如下：

wecom-bot
│
├── app/
│   ├── main.py
│   ├── config.py
│   ├── wecom_crypto.py
│   ├── handlers.py
│   ├── reply.py
│   ├── llm.py
│   ├── logger.py
│   └── utils.py
│
├── prompts/
│   └── system.md
│
├── logs/
│
├── tests/
│
├── requirements.txt
│
├── Dockerfile
│
├── docker-compose.yml
│
├── .env
│
├── .gitignore
│
└── README.md

这是后面所有章节都会一直使用的目录结构。

5.2 为什么这样划分目录？

很多教程喜欢把所有代码写在：

main.py

一千多行。

这种方式：

  • 无法维护
  • 无法测试
  • 无法多人协作

因此我们采用职责拆分。

例如：

main.py

只负责：

  • FastAPI启动
  • 注册路由
  • 生命周期管理

绝不会写业务。

config.py

负责：

读取环境变量

API KEY

企业微信配置

日志配置

URL配置

任何配置都放这里。

以后更换模型：

DeepSeek

↓

OpenAI

↓

Claude

都不用改业务代码。

wecom_crypto.py

整个企业微信最重要的文件。

负责：

URL验证

AES解密

AES加密

签名验证

回复加密

这一层完全对应：

企业微信安全协议层

这一章后面会详细实现。

handlers.py

负责：

收到消息以后：

↓

解析XML

↓

判断消息类型

↓

调用对应处理函数

例如：

文本

图片

语音

文件

事件

全部在这里分发。

这就是经典：

Dispatcher

reply.py

这里只负责：

生成最终回复

例如：

你好

↓

调用LLM

↓

返回答案

以后：

RAG

Function Call

MCP

Agent

知识库

全部也是这里扩展。

llm.py

所有大模型调用全部封装。

例如：

DeepSeek

OpenAI

Claude

Gemini

Qwen

统一接口：

chat()

以后换模型：

其它地方一行不用改。

logger.py

统一日志。

以后：

INFO

WARNING

ERROR

DEBUG

全部集中。

日志千万不要：

print()

utils.py

公共函数。

例如：

UUID

时间

XML解析

JSON处理

字符串

签名计算

5.3 Python 虚拟环境

为什么一定要使用虚拟环境？

假设你的电脑：

Python 3.11

Python 3.12

Python 3.13

安装：

pip install fastapi

可能装到另一个 Python。

所以企业开发统一：

venv

创建：

python3.11 -m venv venv

Mac：

source venv/bin/activate

Ubuntu：

source venv/bin/activate

Windows：

venv\Scripts\activate

看到：

(venv)

说明进入成功。

5.4 requirements.txt

建议一开始只安装真正需要的依赖，而不是一次性安装几十个库。

fastapi
uvicorn[standard]

wechatpy

httpx

python-dotenv

loguru

lxml

pydantic

pydantic-settings

安装：

pip install -r requirements.txt

查看：

pip list

5.5 为什么选择 FastAPI？

很多人问：

为什么不用 Flask？

因为企业微信机器人：

每天只有：

HTTP POST

↓

处理

↓

返回

FastAPI 更适合：

  • 高性能
  • 异步
  • 自动类型检查
  • 自动生成接口文档
  • 更好的并发能力

以后增加：

REST API

Webhook

管理后台

健康检查

都非常方便。

5.6 Docker 化开发

开发完成后，最终不会直接运行：

python main.py

而是统一容器化。

Dockerfile：

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD [
    "uvicorn",
    "app.main:app",
    "--host",
    "0.0.0.0",
    "--port",
    "8000"
]

整个服务任何地方：

Mac

↓

Windows

↓

Ubuntu

↓

云服务器

运行效果完全一致。

5.7 Git 初始化

创建 Git 仓库：

git init

配置 .gitignore：

venv/
__pycache__/
*.pyc
.env
logs/
.idea/
.vscode/

首次提交：

git add .

git commit -m "Initial project structure"

建议从项目第一天开始就坚持小步提交，每完成一个功能就提交一次，便于回溯和排查问题。

5.8 环境变量管理

不要把敏感信息直接写进代码。

创建 .env：

# 企业微信
WECOM_CORP_ID=wwxxxxxxxxxxxxxxxx
WECOM_AGENT_ID=1000002
WECOM_TOKEN=your_token
WECOM_AES_KEY=your_encoding_aes_key

# DeepSeek
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx

# 服务
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO

通过配置模块统一读取，避免在多个文件中重复获取环境变量，也方便不同环境（开发、测试、生产）切换。

5.9 本章小结

完成本章后，我们已经拥有了一个符合企业开发规范的项目骨架，包括：

  • 清晰的目录结构与职责划分
  • Python 虚拟环境
  • 基础依赖管理
  • FastAPI 作为 Web 框架
  • Docker 容器化基础
  • Git 版本管理
  • .env 配置管理

这些内容虽然不会直接实现机器人功能，但它们决定了项目是否具备长期维护和持续迭代的能力。

下一章预告

第六章：《FastAPI 服务搭建与企业微信回调接口实现》

这一章将开始真正编写代码，内容包括：

  1. 创建第一个 FastAPI 服务。
  2. 实现 /wecom/callback 回调接口。
  3. 完成企业微信 URL 验证（GET 请求）。
  4. 集成消息加解密与签名校验。
  5. 实现接收消息并返回加密响应。
  6. 在企业微信管理后台完成回调验证，让整个 wecom-bot 首次成功与企业微信建立通信。

从这一章开始，电子书将进入完整的实战开发阶段，每一章都会配套完整、可运行的代码，并与我们前面实际调试过的架构保持一致。