wecom-ai-assistant/docs/setup-steps.md

企业微信回调配置完整步骤

当前状态检查

✅ Docker 服务运行正常 ✅ 后端服务正常（http://localhost:8000） ✅ .env 文件已配置企业微信参数

---

步骤 1：安装 cloudflared

方法 A：使用 MSI 安装包（推荐，最简单）

1. 下载安装包：

   • 直接下载：https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.msi
   • 或访问：https://github.com/cloudflare/cloudflared/releases 选择最新版本

2. 安装：

   • 双击下载的 cloudflared-windows-amd64.msi 文件
   • 按照安装向导完成安装
   • 安装完成后会自动添加到系统 PATH

3. 验证安装：

   cloudflared --version
   

   应该显示版本号，例如：cloudflared 2026.1.2

方法 B：使用 Scoop（如果已安装）

scoop install cloudflared

---

步骤 2：启动 Cloudflare Tunnel

2.1 启动 tunnel

在 PowerShell 中运行：

cloudflared tunnel --url http://localhost:8000

2.2 复制公网 URL

启动后会显示类似这样的输出：

+--------------------------------------------------------------------------------------------+
|  Your quick Tunnel has been created! Visit it at:                                        |
|  https://abc123-def456-ghi789.trycloudflare.com                                           |
+--------------------------------------------------------------------------------------------+

重要：复制这个 URL（例如：https://abc123-def456-ghi789.trycloudflare.com）

2.3 保持窗口运行

重要：不要关闭这个 PowerShell 窗口，保持 cloudflared 运行。

---

步骤 3：配置企业微信后台

3.1 登录企业微信管理后台

访问：https://work.weixin.qq.com

3.2 进入应用设置

1. 点击 应用管理
2. 选择 自建应用
3. 选择你的应用（AgentId: 1000003）
4. 找到 接收消息 或 API接收
5. 点击 设置 API 接收 或 配置回调URL

3.3 填写回调配置

根据你的 .env 文件，填写以下信息：

配置项	值	说明
接收消息服务器 URL	https://你的cloudflared域名.trycloudflare.com/api/wecom/callback	将 你的cloudflared域名 替换为步骤 2.2 中复制的域名
Token	tuqA13S8A9L2	与 .env 中的 WECOM_TOKEN 一致
EncodingAESKey	VjrVc9NuGr1pikvwKLjr2OpB6gh1wDlBaUMKeUHAlKw	与 .env 中的 WECOM_ENCODING_AES_KEY 一致
消息加解密方式	安全模式	推荐选择安全模式

示例：

• 如果 cloudflared URL 是：https://abc123-def456-ghi789.trycloudflare.com
• 那么回调 URL 应该是：https://abc123-def456-ghi789.trycloudflare.com/api/wecom/callback

3.4 保存配置

点击 保存 按钮。

---

步骤 4：验证配置

4.1 查看后端日志

在另一个 PowerShell 窗口中运行：

docker compose logs backend -f

4.2 检查验证结果

保存配置后，企业微信会立即发送 GET 请求进行校验。

成功标志：

• 后端日志中应该看到：

  INFO: wecom verify success {"trace_id": "...", "echostr_length": 43}
  

• 企业微信后台应显示 保存成功 ✅

失败标志：

• 后端日志显示 wecom verify failed
• 企业微信后台显示"URL校验失败"

如果失败，检查：

1. Token 是否与 .env 中的 WECOM_TOKEN 完全一致
2. EncodingAESKey 是否与 .env 中的 WECOM_ENCODING_AES_KEY 完全一致（43位，不含等号）
3. 回调 URL 是否正确（包含 /api/wecom/callback）
4. cloudflared 是否仍在运行

---

步骤 5：测试消息回调

5.1 发送测试消息

1. 打开企业微信客户端
2. 找到你配置的应用
3. 发送一条文本消息，例如：你好，测试一下

5.2 查看后端日志

在后端日志中应该看到：

收到消息：

{
  "level": "INFO",
  "message": "wecom message received",
  "trace_id": "...",
  "external_userid": "wmxxxxx",
  "msgid": "1234567890",
  "msg_type": "text",
  "content_summary": "你好，测试一下"
}

发送回复：

{
  "level": "INFO",
  "message": "wecom reply sent",
  "trace_id": "...",
  "external_userid": "wmxxxxx",
  "msgid": "1234567890",
  "reply_summary": "已收到：你好，测试一下"
}

5.3 验证回复

在企业微信客户端中，应该收到回复：已收到：你好，测试一下

5.4 检查数据库

# 查看会话
docker compose exec db psql -U wecom -d wecom_ai -c "SELECT id, external_user_id, status, created_at FROM chat_sessions ORDER BY created_at DESC LIMIT 5;"

# 查看消息
docker compose exec db psql -U wecom -d wecom_ai -c "SELECT id, session_id, role, content, created_at FROM messages ORDER BY created_at DESC LIMIT 10;"

---

常见问题

Q1: cloudflared 命令找不到？

解决：

• 如果使用 MSI 安装，重启 PowerShell 窗口
• 或使用完整路径运行：C:\Program Files\Cloudflare\cloudflared.exe tunnel --url http://localhost:8000

Q2: GET 校验失败？

检查清单：

• Token 是否与 .env 中的 WECOM_TOKEN 完全一致（包括大小写、空格）
• EncodingAESKey 是否与 .env 中的 WECOM_ENCODING_AES_KEY 完全一致（43位）
• 回调 URL 是否正确（格式：https://域名.trycloudflare.com/api/wecom/callback）
• cloudflared 是否仍在运行
• 后端服务是否正常运行

Q3: 收到消息但没有回复？

检查：

• 查看后端日志是否有错误
• 检查数据库连接是否正常
• 确认消息类型是否为文本消息

---

快速命令参考

# 检查服务状态
docker compose ps

# 查看后端日志
docker compose logs backend -f

# 测试本地服务
curl http://localhost:8000/api/health

# 启动 cloudflared
cloudflared tunnel --url http://localhost:8000

# 检查数据库
docker compose exec db psql -U wecom -d wecom_ai -c "SELECT * FROM chat_sessions;"

---

下一步

完成配置后，可以：

1. 测试不同类型的消息（文本、图片等）
2. 查看管理后台的会话列表和消息记录
3. 继续开发阶段 5：FAQ 匹配功能