baodan/docs/企业微信接入指南.md

企业微信接入指南

本文档详细说明如何将保险智能客服系统接入企业微信，包括自建应用、机器人消息和 OAuth 登录。

---

目录

• 前置条件
• 第一步：创建自建应用
• 第二步：配置机器人消息接收
• 第三步：配置 OAuth 登录
• 第四步：配置环境变量
• 第五步：验证接入
• 部署注意事项
• 常见问题排查

---

前置条件

• 已注册企业微信（注册地址）
• 拥有企业微信管理员权限
• 服务器已部署并配置 HTTPS（企微回调要求）
• 域名已备案（生产环境必须）

---

第一步：创建自建应用

1.1 登录管理后台

访问 企业微信管理后台，使用管理员账号登录。

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 文件：

# ===== 企业微信配置 =====

# 企业 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 启动服务

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 健康检查

# 检查服务是否正常
curl http://localhost:5001/api/health

# 检查企微回调接口
curl http://localhost:5001/insurance/wecom/callback

---

部署注意事项

5.5 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 是否与代码一致

# 手动测试回调接口
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: 企微后台提示「回调地址请求不通过」

现象: 保存配置时提示 openapi回调地址请求不通过

常见原因:

1. AES 解密未正确实现 — 回调验证需要解密 echostr，代码只返回了原始密文
2. 环境变量未配置 — Docker 容器中缺少企微配置
3. Token/AES Key 不一致 — 企微后台配置与 .env 中的值不匹配
4. SSL 证书问题 — 自签名证书不被企微信任

排查步骤:

1. 手动测试回调接口：

   curl "https://your-domain.com/insurance/wecom/callback?msg_signature=test&timestamp=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，需要使用内网穿透工具：

# 使用 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&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 登录流程
• 测试机器人消息接收
• 测试消息回复功能
• 检查服务器日志正常

---

参考链接

• 企业微信官方文档
• 自建应用开发指南
• 消息接收说明
• OAuth 说明