# 云端最小回调壳快速部署指南

## 一、前置条件检查清单

- [ ] 备案域名（例如：`api.yourdomain.com`）
- [ ] Linux 服务器（Ubuntu 20.04+ / CentOS 7+）
- [ ] 公网 IP，开放 80/443 端口
- [ ] Docker 和 docker-compose 已安装
- [ ] 企业微信管理后台访问权限

## 二、5 分钟快速部署

### 步骤 1：克隆项目

```bash
git clone https://github.com/your-org/wecom-ai-assistant.git
cd wecom-ai-assistant
```

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

```bash
# 复制模板
cp .env.example .env

# 编辑 .env，填写以下必需变量：
# - WECOM_TOKEN（从企微后台获取）
# - WECOM_ENCODING_AES_KEY（从企微后台获取，43位）
# - WECOM_CORP_ID（从企微后台获取）
# - WECOM_AGENT_ID（从企微后台获取）
```

### 步骤 3：部署最小回调壳

```bash
# 方式 A：使用 docker-compose
docker-compose -f docker-compose.minimal.yml up -d

# 方式 B：使用部署脚本
chmod +x deploy/scripts/deploy-minimal.sh
export DOMAIN=your-domain.com
bash deploy/scripts/deploy-minimal.sh
```

### 步骤 4：配置 HTTPS（Let's Encrypt）

```bash
export DOMAIN=your-domain.com
export SSL_EMAIL=your-email@example.com
chmod +x deploy/scripts/setup-ssl.sh
bash deploy/scripts/setup-ssl.sh
```

### 步骤 5：配置企业微信回调

1. 登录企业微信管理后台：https://work.weixin.qq.com
2. 进入：应用管理 → 自建应用 → 选择你的应用
3. 配置回调：
   - **接收消息服务器 URL**：`https://your-domain.com/api/wecom/callback`
   - **Token**：与 `.env` 中的 `WECOM_TOKEN` **完全一致**
   - **EncodingAESKey**：与 `.env` 中的 `WECOM_ENCODING_AES_KEY` **完全一致**
   - **消息加解密方式**：**安全模式**
4. 点击 **保存**

### 步骤 6：验证

```bash
# 查看日志
docker-compose logs -f backend

# 应该看到：
# INFO: wecom verify success {"trace_id": "...", "echostr_length": 43}
```

## 三、关键环境变量

| 变量 | 说明 | 来源 |
|------|------|------|
| `WECOM_TOKEN` | 企业微信回调 Token | 企微后台 → 应用 → 接收消息 → Token |
| `WECOM_ENCODING_AES_KEY` | 43 位 Base64 编码密钥 | 企微后台 → 应用 → 接收消息 → EncodingAESKey |
| `WECOM_CORP_ID` | 企业 ID | 企微后台 → 我的企业 → 企业信息 |
| `WECOM_AGENT_ID` | 应用 AgentId | 企微后台 → 应用管理 → 自建应用 → 应用详情 |

## 四、验证清单

- [ ] 服务启动：`docker-compose ps` 显示 backend 和 nginx 运行中
- [ ] 健康检查：`curl http://localhost:8000/health` 返回 200
- [ ] HTTPS 访问：`curl https://your-domain.com/api/health` 返回 200
- [ ] 企业微信 GET 校验：保存回调配置后，日志显示 `wecom verify success`
- [ ] 企业微信 POST 回调：发送测试消息后，日志显示 `wecom message received` 和 `wecom reply sent`

## 五、常见问题

### 5.1 GET 校验失败

**症状**：企微后台保存失败，日志显示 `wecom verify failed`

**解决**：
1. 检查 `.env` 中的 `WECOM_TOKEN` 和 `WECOM_ENCODING_AES_KEY`
2. 确保与企微后台配置**完全一致**（包括大小写、空格）
3. 重启后端：`docker-compose restart backend`

### 5.2 HTTPS 证书问题

**症状**：浏览器显示"不安全连接"

**解决**：
1. 检查证书：`sudo certbot certificates`
2. 更新 Nginx 配置，使用正确的证书路径
3. 重启 Nginx：`docker-compose restart nginx`

### 5.3 域名无法访问

**症状**：`curl https://your-domain.com/api/health` 超时

**解决**：
1. 检查 DNS：`nslookup your-domain.com`
2. 检查防火墙：`sudo ufw status`（Ubuntu）或 `sudo firewall-cmd --list-all`（CentOS）
3. 检查端口：`netstat -tlnp | grep -E '80|443'`

## 六、下一步

完成最小回调壳部署后：

1. ✅ **最小回调壳**（当前阶段）
2. ⏭️ **数据库接入**（会话与消息入库）
3. ⏭️ **Admin 后台**（会话列表、工单、知识库）
4. ⏭️ **FAQ/RAG**（智能回复）

**详细文档**：参见 `docs/deploy-cloud-minimal.md`