Initial commit: 浼佷笟寰俊 AI 鏈哄櫒浜哄姪鐞?MVP

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/deploy-quickstart.md

@@ -0,0 +1,130 @@
+# 云端最小回调壳快速部署指南
+
+## 一、前置条件检查清单
+
+- [ ] 备案域名（例如：`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`