baodan/docs/企微回调配置指南.md

企微回调服务器配置指南

一、问题现象

在企微后台设置接收消息服务器时，保存配置提示：

"openapi回调地址请求不通过"

二、问题原因

1. AES解密未实现 - 回调验证需要解密echostr，原代码只返回了原始密文
2. 环境变量未配置 - Docker容器中缺少企微配置
3. 回调地址不可访问 - 服务器无法访问配置的URL

三、配置步骤

步骤1：获取企微配置信息

登录 企业微信管理后台，进入：

应用管理 → 接收消息 → 设置接收消息服务器

你需要获取以下信息：

配置项	说明	示例
企业ID (CorpID)	企业微信后台 → 我的企业 → 企业信息	ww1234567890abcdef
应用Secret	应用管理 → 自建应用 → Secret	a1b2c3d4e5f6...
回调Token	自定义，用于验证请求	my_callback_token_123456
消息加密密钥	43位字符，系统自动生成	abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG

步骤2：配置Docker环境变量

在服务器上创建 .env 文件：

cd /path/to/baodanagent/deploy-package/baodanagent
cp .env.example .env

编辑 .env 文件，填入真实配置：

# 企微配置
WECOM_CORP_ID=ww1234567890abcdef
WECOM_SECRET=a1b2c3d4e5f6...
WECOM_TOKEN=my_callback_token_123456
WECOM_AES_KEY=abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG

步骤3：确保回调地址可访问

方案A：使用HTTPS（推荐，生产环境）

1. 配置域名和SSL证书
2. 设置Nginx反向代理

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:5001/api/;
        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;
    }
}

方案B：使用内网穿透（开发测试环境）

使用 ngrok、frp 等工具：

# 使用 ngrok
ngrok http 8080

# 获取公网地址，如：https://xxxx.ngrok.io

步骤4：重启Docker服务

cd /path/to/baodanagent/deploy-package/baodanagent

# 停止服务
docker compose down

# 重新构建（代码有改动时需要）
docker compose build baodanagent-api

# 启动服务
docker compose up -d

# 查看日志，确认启动成功
docker compose logs -f baodanagent-api

步骤5：在企微后台配置回调地址

1. 进入 企业微信管理后台 → 应用管理 → 接收消息

2. 点击 设置接收消息服务器

3. 填写配置：

   配置项	值
   URL	https://your-domain.com/api/wecom/callback
   Token	你在 .env 中设置的 WECOM_TOKEN
   EncodingAESKey	你在 .env 中设置的 WECOM_AES_KEY

4. 点击 保存

四、验证配置

1. 检查服务是否正常运行

# 检查API服务
curl http://localhost:5001/api/health

# 检查前端
curl http://localhost:8080

2. 手动测试回调接口

# 测试GET验证接口
curl "https://your-domain.com/api/wecom/callback?msg_signature=test&timestamp=1234567890&nonce=test&echostr=test"

# 应该返回：Invalid signature（说明服务正常，只是参数不对）

3. 查看Docker日志

docker compose logs -f baodanagent-api | grep -i wecom

五、常见问题

问题1：仍然提示"回调地址请求不通过"

排查步骤：

1. 检查URL是否正确（注意路径是 /api/wecom/callback，不是 /wecom/callback）
2. 检查防火墙是否开放了443端口
3. 检查SSL证书是否有效
4. 查看Docker日志：docker compose logs baodanagent-api

问题2：返回"Invalid signature"

原因： Token配置不一致

解决： 确保企微后台配置的Token与 .env 中的 WECOM_TOKEN 完全一致

问题3：返回"Invalid echostr"

原因： AES密钥配置不一致

解决： 确保企微后台配置的EncodingAESKey与 .env 中的 WECOM_AES_KEY 完全一致

问题4：5秒内未返回success

原因： 服务器响应太慢

解决： 检查服务器性能，优化网络延迟

六、完整配置示例

.env 文件

# 数据库
DB_PASSWORD=your_secure_password

# JWT
JWT_SECRET=your_jwt_secret_key

# 企微配置
WECOM_CORP_ID=ww1234567890abcdef
WECOM_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
WECOM_TOKEN=my_callback_token_2024
WECOM_AES_KEY=abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG

企微后台配置

配置项	值
URL	https://example.com/api/wecom/callback
Token	my_callback_token_2024
EncodingAESKey	abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG

七、安全建议

1. Token和AES密钥：使用随机生成的强字符串
2. HTTPS：生产环境必须使用HTTPS
3. IP白名单：在企微后台配置IP白名单
4. 日志监控：定期检查回调日志，发现异常及时处理