taiyi/baodan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
8253867913
baodan/docs/企业微信接入指南.md

381 lines
9.5 KiB
Markdown
Raw Normal View History

第一次提交。可以使用企微群消息
2026-07-02 23:13:23 +08:00
# 企业微信接入指南
本文档详细说明如何将保险智能客服系统接入企业微信，包括自建应用、机器人消息和 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&timestamp=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.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&timestamp=xxx&nonce=xxx&echostr=xxx
```
**说明**: 企微服务器验证回调地址有效性。
### 6.4 消息回调（消息接收）
```
POST /insurance/wecom/callback?msg_signature=xxx&timestamp=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)
Reference in New Issue Copy Permalink