Files

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

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

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

14 KiB

Raw Permalink Blame History

企业微信回调功能测试详细流程

一、前置准备

1.1 检查服务状态

# 检查所有服务是否运行
docker compose ps

# 应该看到：
# - ai-db-1 (Running)
# - ai-backend-1 (Running)
# - ai-admin-1 (Running，可选)

1.2 检查后端日志

# 查看后端最新日志，确认无错误
docker compose logs backend --tail 50

# 应该看到：
# INFO: Uvicorn running on http://0.0.0.0:8000
# INFO: Application startup complete.

1.3 配置环境变量

编辑 .env 文件，确保以下企业微信相关配置已填写：

# 企业微信配置（必须）
WECOM_CORP_ID=你的企业ID                    # 从"我的企业 → 企业信息"获取
WECOM_AGENT_ID=你的应用AgentId              # 从"自建应用 → 应用详情"获取
WECOM_SECRET=你的应用Secret                 # 从"自建应用 → 应用详情"获取（可选，用于主动发送消息）
WECOM_TOKEN=你的Token                       # 自定义字符串，需与企微后台一致
WECOM_ENCODING_AES_KEY=你的43位密钥         # 从企微后台获取，43位Base64编码
WECOM_API_BASE=https://qyapi.weixin.qq.com
WECOM_API_TIMEOUT=10
WECOM_API_RETRIES=2

重要提示：

WECOM_TOKEN 和 WECOM_ENCODING_AES_KEY 必须与企微后台配置完全一致
WECOM_ENCODING_AES_KEY 是 43 位 Base64 编码字符串（不含等号）

1.4 重启后端服务（如果修改了 .env）

# 重启后端以加载新的环境变量
docker compose restart backend

# 等待几秒后检查日志
docker compose logs backend --tail 20

二、企业微信后台配置

2.1 获取必要参数

登录企业微信管理后台：https://work.weixin.qq.com
获取企业 ID (CorpId)：
- 进入 我的企业 → 企业信息
- 复制 企业 ID，填入 .env 的 WECOM_CORP_ID
获取应用信息：
- 进入 应用管理 → 自建应用 → 选择你的应用
- 在 应用详情 中获取：
  - AgentId：填入 .env 的 WECOM_AGENT_ID
  - Secret：填入 .env 的 WECOM_SECRET（可选）

2.2 配置回调 URL（关键步骤）

进入接收消息设置：
- 在应用详情页面，找到 接收消息 或 API接收
- 点击 设置 API 接收 或 配置回调URL
填写回调配置：
- 接收消息服务器 URL：https://你的公网域名/api/wecom/callback
  - 本地测试：使用 ngrok 等工具暴露本地服务（见下方）
  - 生产环境：使用你的实际域名
- Token：填写一个自定义字符串（例如：my_wecom_token_2025）
  - 重要：这个 Token 必须与 .env 中的 WECOM_TOKEN 完全一致
- EncodingAESKey：
  - 点击 随机获取 或手动输入 43 位 Base64 编码字符串
  - 重要：这个密钥必须与 .env 中的 WECOM_ENCODING_AES_KEY 完全一致
- 消息加解密方式：选择 安全模式（推荐）或 明文模式（仅测试）
保存配置：
- 点击保存按钮
- 企业微信会立即发送 GET 请求到你的回调 URL 进行校验
- 如果配置正确，会显示 保存成功 ✅

三、本地测试方法

方法 1：使用 Cloudflare Tunnel（推荐 ⭐⭐⭐⭐⭐）

Cloudflare Tunnel (cloudflared) 提供免费的固定域名，比 ngrok 更稳定。

3.1 安装 cloudflared

Windows（使用 Scoop）：

# 安装 Scoop（如果还没有）
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

# 安装 cloudflared
scoop install cloudflared

或使用 Chocolatey：

choco install cloudflared

或手动下载：

访问：https://github.com/cloudflare/cloudflared/releases
下载 cloudflared-windows-amd64.exe，重命名为 cloudflared.exe

3.2 启动 cloudflared

# 在项目根目录运行（暴露本地 8000 端口）
cloudflared tunnel --url http://localhost:8000

输出示例：

2025-02-05T10:00:00Z INF +--------------------------------------------------------------------------------------------+
2025-02-05T10:00:00Z INF |  Your quick Tunnel has been created! Visit it at:                                        |
2025-02-05T10:00:00Z INF |  https://abc123-def456-ghi789.trycloudflare.com                                           |
2025-02-05T10:00:00Z INF +--------------------------------------------------------------------------------------------+

3.3 获取公网 URL

从输出中复制 https://xxx.trycloudflare.com，这就是你的公网 URL。

注意：

这个 URL 在本次运行期间是固定的
关闭 cloudflared 后，URL 会失效
如需固定域名，请登录 Cloudflare 创建命名 tunnel（见 docs/cloudflared-setup.md）

3.4 配置企微后台

在企微后台的回调 URL 中填写：https://你的cloudflared域名.trycloudflare.com/api/wecom/callback

例如：https://abc123-def456-ghi789.trycloudflare.com/api/wecom/callback

3.5 保存并验证

点击保存
观察后端日志：
```
docker compose logs backend -f
```

应该看到：

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

企微后台应显示 保存成功

详细文档：参见 docs/cloudflared-setup.md

方法 2：使用 ngrok 暴露本地服务

2.1 安装 ngrok

Windows：下载 https://ngrok.com/download，解压到任意目录
或使用包管理器：choco install ngrok 或 scoop install ngrok

2.2 启动 ngrok

# 在终端中运行（暴露本地 8000 端口）
ngrok http 8000

# 输出示例：
# Forwarding  https://abc123.ngrok.io -> http://localhost:8000

2.3 获取公网 URL

从 ngrok 输出中复制 https://xxx.ngrok.io，这就是你的公网 URL。

注意：免费版 ngrok 每次重启 URL 都会变化，需要重新配置企微后台。

2.4 配置企微后台

在企微后台的回调 URL 中填写：https://你的ngrok域名.ngrok.io/api/wecom/callback

例如：https://abc123.ngrok.io/api/wecom/callback

2.5 保存并验证

点击保存
观察后端日志：
```
docker compose logs backend -f
```

应该看到：

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

企微后台应显示 保存成功

方法 2：使用企业微信官方测试工具

在企业微信管理后台，进入 自建应用 → 接收消息 → 调试工具
输入测试参数，生成测试请求
使用 curl 或 Postman 发送请求到本地服务

四、测试消息回调

4.1 发送测试消息

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

4.2 查看后端日志

# 实时查看日志
docker compose logs backend -f

# 应该看到以下日志：

收到消息日志：

{
  "timestamp": "2025-02-05T10:00:00Z",
  "level": "INFO",
  "message": "wecom message received",
  "trace_id": "abc123-def456",
  "external_userid": "wmxxxxx",
  "msgid": "1234567890",
  "msg_type": "text",
  "content_summary": "你好，测试一下"
}

发送回复日志：

{
  "timestamp": "2025-02-05T10:00:01Z",
  "level": "INFO",
  "message": "wecom reply sent",
  "trace_id": "abc123-def456",
  "external_userid": "wmxxxxx",
  "msgid": "1234567890",
  "reply_summary": "已收到：你好，测试一下"
}

4.3 验证回复消息

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

4.4 检查数据库

# 进入数据库容器
docker compose exec db psql -U wecom -d wecom_ai

# 查询会话
SELECT id, external_user_id, external_name, status, created_at 
FROM chat_sessions 
ORDER BY created_at DESC 
LIMIT 5;

# 查询消息
SELECT id, session_id, role, content, created_at 
FROM messages 
ORDER BY created_at DESC 
LIMIT 10;

# 应该看到：
# - 一条会话记录（external_user_id 为你的企微用户ID）
# - 两条消息记录（一条 user，一条 assistant）

五、完整测试检查清单

5.1 配置检查

.env 文件中所有企业微信配置已填写
WECOM_TOKEN 与企微后台一致
WECOM_ENCODING_AES_KEY 与企微后台一致（43位）
WECOM_CORP_ID 已填写
后端服务正常运行

5.2 GET 校验测试

在企微后台点击保存配置
后端日志显示 wecom verify success
企微后台显示 保存成功

5.3 POST 回调测试

在企业微信中发送文本消息
后端日志显示 wecom message received
后端日志显示 wecom reply sent
企业微信中收到回复消息
数据库中创建了会话记录
数据库中创建了消息记录（user + assistant）

六、常见问题排查

问题 1：GET 校验失败

症状：企微后台显示"保存失败"或"URL校验失败"

排查步骤：

检查 Token：

# 查看 .env 中的 WECOM_TOKEN
cat .env | grep WECOM_TOKEN

# 确保与企微后台完全一致（包括大小写、空格等）

检查 EncodingAESKey：

# 查看 .env 中的 WECOM_ENCODING_AES_KEY
cat .env | grep WECOM_ENCODING_AES_KEY

# 确保是 43 位 Base64 编码（不含等号）
# 确保与企微后台完全一致

检查后端日志：

docker compose logs backend | grep "wecom verify"

# 如果看到 "wecom verify failed"，检查签名或解密错误

检查回调 URL：
- 确保 URL 可公网访问（使用 ngrok 等工具）
- 确保 URL 格式正确：https://域名/api/wecom/callback
- 确保后端服务正常运行

解决方案：

重新检查并同步 Token 和 EncodingAESKey
确保回调 URL 可访问
重启后端服务：docker compose restart backend

问题 2：POST 回调失败

症状：发送消息后没有收到回复，或后端日志显示错误

排查步骤：

检查后端日志：

docker compose logs backend | grep -E "wecom|error|Error"

检查解密错误：
- 如果看到 wecom decrypt error，检查 WECOM_ENCODING_AES_KEY 是否正确
- 如果看到 wecom xml parse failed，检查 XML 格式

检查企业 ID：

# 确保 WECOM_CORP_ID 正确
cat .env | grep WECOM_CORP_ID

检查数据库连接：

# 确保数据库服务正常运行
docker compose ps db

# 检查数据库连接
docker compose exec backend python -c "from app.database import engine; print('DB OK')"

解决方案：

检查并修复配置错误
重启后端服务
检查数据库连接

问题 3：收到消息但没有回复

症状：后端日志显示收到消息，但企业微信中没有收到回复

排查步骤：

检查回复日志：

docker compose logs backend | grep "wecom reply sent"

# 如果没有这条日志，说明回复构造或加密失败

检查回复 XML 格式：
- 查看后端代码中的 build_reply_xml 函数
- 确保 XML 格式符合企业微信规范
检查加密：
- 确保 WECOM_ENCODING_AES_KEY 正确
- 确保 WECOM_CORP_ID 正确（用于加密验证）

解决方案：

检查回复 XML 构造逻辑
检查加密函数
查看完整错误日志

问题 4：URL 变化问题

症状：每次重启内网穿透工具，URL 都会变化

解决方案：

使用 Cloudflare Tunnel：登录后可以创建固定域名的 tunnel（推荐）
使用 ngrok：每次重启后需要重新在企微后台更新回调 URL
使用 ngrok 付费版：可以设置固定域名
其他工具：frp、localtunnel 等（参见 docs/cloudflared-setup.md）

七、高级测试

7.1 测试不同类型的消息

文本消息：发送普通文本
图片消息：发送图片（当前实现可能只回复"收到"）
事件消息：测试关注/取消关注等事件

7.2 测试并发消息

同时发送多条消息
检查数据库是否正确记录所有消息
检查回复是否正确

7.3 测试错误处理

发送格式错误的消息
检查错误日志
确保服务不会崩溃

八、测试完成后

8.1 验证数据完整性

# 检查会话和消息数据
docker compose exec db psql -U wecom -d wecom_ai -c "
SELECT 
  cs.id as session_id,
  cs.external_user_id,
  cs.external_name,
  COUNT(m.id) as message_count,
  MAX(m.created_at) as last_message_time
FROM chat_sessions cs
LEFT JOIN messages m ON cs.id = m.session_id
GROUP BY cs.id
ORDER BY cs.created_at DESC;
"

8.2 清理测试数据（可选）

# 删除测试数据
docker compose exec db psql -U wecom -d wecom_ai -c "
DELETE FROM messages;
DELETE FROM chat_sessions;
"

九、下一步

完成阶段 4 测试后，可以继续：

阶段 5：接入 FAQ 匹配
阶段 6：接入 RAG 检索
阶段 7：实现工单转人工流程

十、快速测试命令汇总

# 1. 检查服务状态
docker compose ps

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

# 3. 检查环境变量
docker compose exec backend env | grep WECOM

# 4. 启动 Cloudflare Tunnel（推荐）
cloudflared tunnel --url http://localhost:8000

# 5. 测试本地健康检查
curl http://localhost:8000/api/health

# 6. 测试公网健康检查（替换为你的 cloudflared URL）
curl https://你的域名.trycloudflare.com/api/health

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

# 8. 重启服务
docker compose restart backend

详细 Cloudflare Tunnel 配置：参见 docs/cloudflared-setup.md

提示：如果遇到问题，请先查看后端日志，大多数问题都会在日志中显示错误信息。

14 KiB Raw Permalink Blame History Unescape Escape

企业微信回调功能测试详细流程

一、前置准备

1.1 检查服务状态

1.2 检查后端日志

1.3 配置环境变量

1.4 重启后端服务（如果修改了 .env）

二、企业微信后台配置

2.1 获取必要参数

2.2 配置回调 URL（关键步骤）

三、本地测试方法

方法 1：使用 Cloudflare Tunnel（推荐 ⭐⭐⭐⭐⭐）

3.1 安装 cloudflared

3.2 启动 cloudflared

3.3 获取公网 URL

3.4 配置企微后台

3.5 保存并验证

方法 2：使用 ngrok 暴露本地服务

2.1 安装 ngrok

2.2 启动 ngrok

2.3 获取公网 URL

2.4 配置企微后台

2.5 保存并验证

方法 2：使用企业微信官方测试工具

四、测试消息回调

4.1 发送测试消息

4.2 查看后端日志

4.3 验证回复消息

4.4 检查数据库

五、完整测试检查清单

5.1 配置检查

5.2 GET 校验测试

5.3 POST 回调测试

六、常见问题排查

问题 1：GET 校验失败

问题 2：POST 回调失败

问题 3：收到消息但没有回复

问题 4：URL 变化问题

七、高级测试

7.1 测试不同类型的消息

7.2 测试并发消息

7.3 测试错误处理

八、测试完成后

8.1 验证数据完整性

8.2 清理测试数据（可选）

九、下一步

十、快速测试命令汇总

14 KiB

Raw Permalink Blame History