131 lines
4.0 KiB
Markdown
131 lines
4.0 KiB
Markdown
# 云端最小回调壳快速部署指南
|
||
|
||
## 一、前置条件检查清单
|
||
|
||
- [ ] 备案域名（例如：`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`
|