424 lines
11 KiB
Markdown
424 lines
11 KiB
Markdown
# 企业微信接入指南
|
||
|
||
本文档详细说明如何将保险智能客服系统接入企业微信，包括自建应用、机器人消息和 OAuth 登录。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [前置条件](#前置条件)
|
||
- [第一步：创建自建应用](#第一步创建自建应用)
|
||
- [第二步：配置机器人消息接收](#第二步配置机器人消息接收)
|
||
- [第三步：配置 OAuth 登录](#第三步配置-oauth-登录)
|
||
- [第四步：配置环境变量](#第四步配置环境变量)
|
||
- [第五步：验证接入](#第五步验证接入)
|
||
- [部署注意事项](#部署注意事项)
|
||
- [常见问题排查](#常见问题排查)
|
||
|
||
---
|
||
|
||
## 前置条件
|
||
|
||
- 已注册企业微信（[注册地址](https://work.weixin.qq.com/)）
|
||
- 拥有企业微信管理员权限
|
||
- 服务器已部署并配置 HTTPS（企微回调要求）
|
||
- 域名已备案（生产环境必须）
|
||
|
||
---
|
||
|
||
## 第一步：创建自建应用
|
||
|
||
### 1.1 登录管理后台
|
||
|
||
访问 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)，使用管理员账号登录。
|
||
|
||
### 1.2 创建应用
|
||
|
||
1. 左侧菜单 → **应用管理** → **自建**
|
||
2. 点击 **创建应用**
|
||
3. 填写应用信息：
|
||
- **应用名称**: 保险智能客服
|
||
- **应用 Logo**: 上传图标
|
||
- **应用介绍**: 保险行业智能客服系统
|
||
- **可见范围**: 选择需要使用的部门/成员
|
||
|
||
### 1.3 记录关键信息
|
||
|
||
创建完成后，进入应用详情页，记录以下信息：
|
||
|
||
| 配置项 | 位置 | 示例 |
|
||
|--------|------|------|
|
||
| **企业 ID** | 我的企业 → 企业信息 | `ww1234567890abcdef` |
|
||
| **AgentId** | 应用详情 → 基础信息 | `1000002` |
|
||
| **Secret** | 应用详情 → 基础信息 → Secret | `xxxxxxxxxxxxxxxxxxxxxxxx` |
|
||
|
||
> ⚠️ **Secret 点击查看后要立即保存**，关闭后无法再次查看。
|
||
|
||
---
|
||
|
||
## 第二步：配置机器人消息接收
|
||
|
||
### 2.1 启用机器人能力
|
||
|
||
1. 进入自建应用详情
|
||
2. 左侧菜单 → **机器人**
|
||
3. 点击 **启用** 按钮
|
||
|
||
### 2.2 配置消息接收 API
|
||
|
||
1. 进入应用详情 → **接收消息** → **设置 API 接收**
|
||
2. 填写以下信息：
|
||
|
||
| 配置项 | 值 | 说明 |
|
||
|--------|-----|------|
|
||
| **URL** | `https://your-domain.com/insurance/wecom/callback` | 企微回调地址 |
|
||
| **Token** | 自定义随机字符串 | 用于验证请求来源 |
|
||
| **EncodingAESKey** | 点击随机获取 | 43位加密密钥 |
|
||
|
||
3. 点击 **保存**，企微会向该 URL 发送验证请求
|
||
|
||
### 2.3 服务器验证要求
|
||
|
||
- 必须支持 HTTPS（443 端口）
|
||
- 必须在 **5 秒内** 响应验证请求
|
||
- 响应内容必须是明文的 `echostr`
|
||
|
||
### 2.4 记录配置信息
|
||
|
||
| 配置项 | 位置 | 长度 |
|
||
|--------|------|------|
|
||
| **Token** | 应用 → 接收消息 | 自定义，建议 32 位随机字符串 |
|
||
| **EncodingAESKey** | 应用 → 接收消息 | 43 位（自动生成） |
|
||
|
||
---
|
||
|
||
## 第三步：配置 OAuth 登录
|
||
|
||
### 3.1 开启授权登录
|
||
|
||
1. 进入自建应用详情
|
||
2. 左侧菜单 → **企业微信授权登录**
|
||
3. 点击 **设置授权回调域**
|
||
|
||
### 3.2 配置回调域名
|
||
|
||
根据部署环境配置：
|
||
|
||
| 环境 | 回调域名 | 说明 |
|
||
|------|----------|------|
|
||
| 开发环境 | `localhost` | 本地开发测试 |
|
||
| 测试环境 | `test.your-domain.com` | 测试服务器 |
|
||
| 生产环境 | `your-domain.com` | 正式环境 |
|
||
|
||
> ⚠️ 回调域名只填写域名，不要带 `https://` 和端口号。
|
||
|
||
### 3.3 权限配置
|
||
|
||
如需获取用户敏感信息（手机号等），需要在应用详情中申请相应权限：
|
||
|
||
- **基础信息**: 默认开启
|
||
- **通讯录权限**: 根据需要申请
|
||
- **成员信息**: 申请 `读取成员` 权限
|
||
|
||
---
|
||
|
||
## 第四步：配置环境变量
|
||
|
||
### 4.1 创建 .env 文件
|
||
|
||
在项目根目录（`baodan-main/`）创建 `.env` 文件：
|
||
|
||
```bash
|
||
# ===== 企业微信配置 =====
|
||
|
||
# 企业 ID（必填）
|
||
WECOM_CORP_ID=ww1234567890abcdef
|
||
|
||
# 自建应用 AgentId（必填）
|
||
WECOM_AGENT_ID=1000002
|
||
|
||
# 自建应用 Secret（必填）
|
||
WECOM_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||
|
||
# 消息校验 Token（必填，与企微后台配置一致）
|
||
WECOM_TOKEN=your_random_token_32_chars
|
||
|
||
# 消息加密 Key（必填，43位，与企微后台配置一致）
|
||
WECOM_ENCODING_AES_KEY=your_43_char_encoding_aes_key
|
||
```
|
||
|
||
### 4.2 配置说明
|
||
|
||
| 环境变量 | 是否必填 | 说明 |
|
||
|----------|:--------:|------|
|
||
| `WECOM_CORP_ID` | ✅ | 企业唯一标识，从「我的企业」获取 |
|
||
| `WECOM_AGENT_ID` | ✅ | 自建应用 ID |
|
||
| `WECOM_SECRET` | ✅ | 应用密钥，点击查看后立即保存 |
|
||
| `WECOM_TOKEN` | ✅ | 消息校验 Token，需与后台一致 |
|
||
| `WECOM_ENCODING_AES_KEY` | ✅ | 43位加密密钥，需与后台一致 |
|
||
|
||
---
|
||
|
||
## 第五步：验证接入
|
||
|
||
### 5.1 启动服务
|
||
|
||
```bash
|
||
cd baodan-main
|
||
|
||
# 安装依赖
|
||
./dev/setup
|
||
|
||
# 启动后端
|
||
./dev/start-api
|
||
```
|
||
|
||
### 5.2 测试 OAuth 登录
|
||
|
||
浏览器访问：
|
||
|
||
```
|
||
http://localhost:5001/insurance/wecom/oauth
|
||
```
|
||
|
||
预期行为：
|
||
1. 重定向到企业微信授权页面
|
||
2. 扫码或确认登录后
|
||
3. 重定向回系统并携带用户信息
|
||
|
||
### 5.3 测试机器人消息
|
||
|
||
1. 在企业微信客户端，搜索「保险智能客服」应用
|
||
2. 向机器人发送消息
|
||
3. 检查服务器日志是否收到消息
|
||
|
||
### 5.4 API 健康检查
|
||
|
||
```bash
|
||
# 检查服务是否正常
|
||
curl http://localhost:5001/api/health
|
||
|
||
# 检查企微回调接口
|
||
curl http://localhost:5001/insurance/wecom/callback
|
||
```
|
||
|
||
---
|
||
|
||
## 部署注意事项
|
||
|
||
### 5.5 Nginx 配置
|
||
|
||
确保 Nginx 正确代理企微回调接口：
|
||
|
||
```nginx
|
||
server {
|
||
listen 443 ssl;
|
||
server_name your-domain.com;
|
||
|
||
# SSL 证书配置
|
||
ssl_certificate /path/to/cert.pem;
|
||
ssl_certificate_key /path/to/key.pem;
|
||
|
||
# 企微回调接口
|
||
location /insurance/wecom/ {
|
||
proxy_pass http://127.0.0.1:5001;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
}
|
||
|
||
# 其他接口...
|
||
}
|
||
```
|
||
|
||
### 5.6 防火墙配置
|
||
|
||
确保服务器开放以下端口：
|
||
|
||
| 端口 | 协议 | 用途 |
|
||
|------|------|------|
|
||
| 443 | TCP | HTTPS 访问（企微回调） |
|
||
| 80 | TCP | HTTP 访问（重定向到 HTTPS） |
|
||
|
||
### 5.7 域名要求
|
||
|
||
- 必须使用已备案域名（生产环境）
|
||
- 必须配置 SSL 证书（企微要求 HTTPS）
|
||
- 域名需加入企微后台的「可信域名」白名单
|
||
|
||
---
|
||
|
||
## 常见问题排查
|
||
|
||
### 问题 1: URL 验证失败
|
||
|
||
**现象**: 企微后台保存回调地址时提示「URL 验证失败」
|
||
|
||
**排查步骤**:
|
||
1. 检查服务器是否正常运行
|
||
2. 检查 Nginx 是否正确代理 `/insurance/wecom/callback`
|
||
3. 检查 SSL 证书是否有效
|
||
4. 检查 `Token` 和 `EncodingAESKey` 是否与代码一致
|
||
|
||
```bash
|
||
# 手动测试回调接口
|
||
curl -v "https://your-domain.com/insurance/wecom/callback?msg_signature=xxx×tamp=xxx&nonce=xxx&echostr=xxx"
|
||
```
|
||
|
||
### 问题 2: 消息接收不到
|
||
|
||
**现象**: 用户发送消息后，服务器没有收到回调
|
||
|
||
**排查步骤**:
|
||
1. 确认机器人能力已启用
|
||
2. 确认消息接收 API 已配置
|
||
3. 检查服务器日志是否有请求记录
|
||
4. 检查消息是否在 5 秒内处理（企微要求）
|
||
|
||
### 问题 3: OAuth 登录失败
|
||
|
||
**现象**: 点击登录后提示「授权失败」
|
||
|
||
**排查步骤**:
|
||
1. 确认「企业微信授权登录」已开启
|
||
2. 确认回调域名配置正确
|
||
3. 检查 `WECOM_CORP_ID` 环境变量是否正确
|
||
4. 检查应用可见范围是否包含测试用户
|
||
|
||
### 问题 4: 用户信息获取失败
|
||
|
||
**现象**: 登录成功但无法获取用户详细信息
|
||
|
||
**排查步骤**:
|
||
1. 确认应用已申请「读取成员」权限
|
||
2. 确认用户在应用可见范围内
|
||
3. 检查 `WECOM_AGENT_ID` 和 `WECOM_SECRET` 是否正确
|
||
|
||
### 问题 5: 企微后台提示「回调地址不可达」
|
||
|
||
**现象**: 保存配置时提示网络不可达
|
||
|
||
**排查步骤**:
|
||
1. 确认域名已备案
|
||
2. 确认 SSL 证书有效（非自签名）
|
||
3. 确认防火墙已开放 443 端口
|
||
4. 使用在线工具检测 SSL：https://www.ssllabs.com/ssltest/
|
||
|
||
### 问题 6: 企微后台提示「回调地址请求不通过」
|
||
|
||
**现象**: 保存配置时提示 `openapi回调地址请求不通过`
|
||
|
||
**常见原因**:
|
||
1. AES 解密未正确实现 — 回调验证需要解密 echostr，代码只返回了原始密文
|
||
2. 环境变量未配置 — Docker 容器中缺少企微配置
|
||
3. Token/AES Key 不一致 — 企微后台配置与 `.env` 中的值不匹配
|
||
4. SSL 证书问题 — 自签名证书不被企微信任
|
||
|
||
**排查步骤**:
|
||
1. 手动测试回调接口：
|
||
```bash
|
||
curl "https://your-domain.com/insurance/wecom/callback?msg_signature=test×tamp=1234567890&nonce=test&echostr=test"
|
||
# 应返回：Invalid signature（说明服务正常，只是参数不对）
|
||
```
|
||
2. 检查 Docker 日志：`docker compose logs baodanagent-api | grep -i wecom`
|
||
3. 确认 Token 和 AES Key 与企微后台完全一致
|
||
4. 确认 SSL 证书有效（非自签名）
|
||
|
||
### 问题 7: 5 秒内未返回 success
|
||
|
||
**现象**: 企微日志显示超时
|
||
|
||
**原因**: 服务器响应太慢
|
||
|
||
**解决**: 检查服务器性能、网络延迟，确保回调处理在 5 秒内完成
|
||
|
||
### 开发环境调试（内网穿透）
|
||
|
||
本地开发时，企微无法访问 localhost，需要使用内网穿透工具：
|
||
|
||
```bash
|
||
# 使用 ngrok
|
||
ngrok http 8080
|
||
# 获取公网地址，如：https://xxxx.ngrok.io
|
||
|
||
# 使用 frp（自建服务器）
|
||
# 配置 frpc.ini 指向本地 8080 端口
|
||
```
|
||
|
||
将获取到的公网地址配置到企微后台的回调 URL 中。
|
||
|
||
---
|
||
|
||
## 接口说明
|
||
|
||
### 6.1 OAuth 登录入口
|
||
|
||
```
|
||
GET /insurance/wecom/oauth
|
||
```
|
||
|
||
**说明**: 重定向到企微授权页面，用户确认后回调。
|
||
|
||
### 6.2 OAuth 回调
|
||
|
||
```
|
||
GET /insurance/wecom/oauth/callback?code=xxx&state=state
|
||
```
|
||
|
||
**说明**: 企微授权回调，自动完成登录并重定向到系统首页。
|
||
|
||
### 6.3 消息回调（URL 验证）
|
||
|
||
```
|
||
GET /insurance/wecom/callback?msg_signature=xxx×tamp=xxx&nonce=xxx&echostr=xxx
|
||
```
|
||
|
||
**说明**: 企微服务器验证回调地址有效性。
|
||
|
||
### 6.4 消息回调（消息接收）
|
||
|
||
```
|
||
POST /insurance/wecom/callback?msg_signature=xxx×tamp=xxx&nonce=xxx
|
||
```
|
||
|
||
**说明**: 接收用户发送给机器人的消息，5 秒内响应 `success`。
|
||
|
||
---
|
||
|
||
## 附录：配置清单
|
||
|
||
### 企业微信后台配置
|
||
|
||
- [ ] 创建自建应用
|
||
- [ ] 记录企业 ID、AgentId、Secret
|
||
- [ ] 启用机器人能力
|
||
- [ ] 配置消息接收 API（URL、Token、EncodingAESKey）
|
||
- [ ] 开启企业微信授权登录
|
||
- [ ] 配置授权回调域名
|
||
- [ ] 设置应用可见范围
|
||
|
||
### 服务器配置
|
||
|
||
- [ ] 配置 SSL 证书
|
||
- [ ] 配置 Nginx 代理
|
||
- [ ] 开放 443 端口
|
||
- [ ] 创建 `.env` 文件并填写配置
|
||
- [ ] 启动服务并测试
|
||
|
||
### 验证测试
|
||
|
||
- [ ] 测试 OAuth 登录流程
|
||
- [ ] 测试机器人消息接收
|
||
- [ ] 测试消息回复功能
|
||
- [ ] 检查服务器日志正常
|
||
|
||
---
|
||
|
||
## 参考链接
|
||
|
||
- [企业微信官方文档](https://developer.work.weixin.qq.com/document/path/90556)
|
||
- [自建应用开发指南](https://developer.work.weixin.qq.com/document/path/90537)
|
||
- [消息接收说明](https://developer.work.weixin.qq.com/document/path/90930)
|
||
- [OAuth 说明](https://developer.work.weixin.qq.com/document/path/91022)
|