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

# 企微回调服务器配置指南

## 一、问题现象

在企微后台设置接收消息服务器时，保存配置提示：
> "openapi回调地址请求不通过"

## 二、问题原因

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

## 三、配置步骤

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

登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)，进入：

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

你需要获取以下信息：

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

### 步骤2：配置Docker环境变量

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

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

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

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

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

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

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

```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 等工具：

```bash
# 使用 ngrok
ngrok http 8080

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

### 步骤4：重启Docker服务

```bash
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. 检查服务是否正常运行

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

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

### 2. 手动测试回调接口

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

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

### 3. 查看Docker日志

```bash
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 文件

```bash
# 数据库
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. **日志监控**：定期检查回调日志，发现异常及时处理