241 lines
6.2 KiB
Markdown
241 lines
6.2 KiB
Markdown
# 企业微信回调配置完整步骤
|
||
|
||
## 当前状态检查
|
||
|
||
✅ 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. **验证安装**：
|
||
```powershell
|
||
cloudflared --version
|
||
```
|
||
应该显示版本号，例如：`cloudflared 2026.1.2`
|
||
|
||
### 方法 B：使用 Scoop（如果已安装）
|
||
|
||
```powershell
|
||
scoop install cloudflared
|
||
```
|
||
|
||
---
|
||
|
||
## 步骤 2：启动 Cloudflare Tunnel
|
||
|
||
### 2.1 启动 tunnel
|
||
|
||
在 PowerShell 中运行：
|
||
|
||
```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 窗口中运行：
|
||
|
||
```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 查看后端日志
|
||
|
||
在后端日志中应该看到：
|
||
|
||
**收到消息**：
|
||
```json
|
||
{
|
||
"level": "INFO",
|
||
"message": "wecom message received",
|
||
"trace_id": "...",
|
||
"external_userid": "wmxxxxx",
|
||
"msgid": "1234567890",
|
||
"msg_type": "text",
|
||
"content_summary": "你好，测试一下"
|
||
}
|
||
```
|
||
|
||
**发送回复**：
|
||
```json
|
||
{
|
||
"level": "INFO",
|
||
"message": "wecom reply sent",
|
||
"trace_id": "...",
|
||
"external_userid": "wmxxxxx",
|
||
"msgid": "1234567890",
|
||
"reply_summary": "已收到：你好，测试一下"
|
||
}
|
||
```
|
||
|
||
### 5.3 验证回复
|
||
|
||
在企业微信客户端中，应该收到回复：**`已收到：你好，测试一下`**
|
||
|
||
### 5.4 检查数据库
|
||
|
||
```powershell
|
||
# 查看会话
|
||
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: 收到消息但没有回复？
|
||
|
||
**检查**：
|
||
- 查看后端日志是否有错误
|
||
- 检查数据库连接是否正常
|
||
- 确认消息类型是否为文本消息
|
||
|
||
---
|
||
|
||
## 快速命令参考
|
||
|
||
```powershell
|
||
# 检查服务状态
|
||
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 匹配功能
|