wecom-ai-assistant/docs/deploy-quickstart.md

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

一、前置条件检查清单

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

二、5 分钟快速部署

步骤 1：克隆项目

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

步骤 2：配置环境变量

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

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

步骤 3：部署最小回调壳

# 方式 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）

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：验证

# 查看日志
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