Files

bujie9527 59275ed4dc Initial commit: 浼佷笟寰俊 AI 鏈哄櫒浜哄姪鐞?MVP

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-02-05 16:36:32 +08:00

6.2 KiB

Raw Blame History

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

当前状态检查

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

步骤 1：安装 cloudflared

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

下载安装包：
- 直接下载：https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.msi
- 或访问：https://github.com/cloudflare/cloudflared/releases 选择最新版本
安装：
- 双击下载的 cloudflared-windows-amd64.msi 文件
- 按照安装向导完成安装
- 安装完成后会自动添加到系统 PATH
验证安装：
```
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 进入应用设置

点击 应用管理
选择 自建应用
选择你的应用（AgentId: 1000003）
找到 接收消息 或 API接收
点击 设置 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校验失败"

如果失败，检查：

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

步骤 5：测试消息回调

5.1 发送测试消息

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

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;"

下一步

完成配置后，可以：

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

6.2 KiB Raw Blame History Unescape Escape