wecom-ai-assistant/docs/deploy-quick-reference.md

生产部署快速参考

一、首次部署（5 分钟）

# 1. 克隆项目
git clone https://github.com/your-org/wecom-ai-assistant.git
cd wecom-ai-assistant

# 2. 配置环境变量
cp .env.prod.example .env.prod
nano .env.prod  # 填写必需变量

# 3. 启动服务
chmod +x deploy/scripts/*.sh
./deploy/scripts/start.sh

# 4. 配置 HTTPS（Let's Encrypt）
export DOMAIN=your-domain.com
export EMAIL=your-email@example.com
sudo certbot certonly --nginx -d $DOMAIN --email $EMAIL --agree-tos --non-interactive

# 5. 更新 Nginx 配置（使用实际域名替换 nginx.conf 中的 _）
# 然后重启: docker-compose -f docker-compose.prod.yml restart nginx

二、常用命令

# 启动服务
./deploy/scripts/start.sh

# 停止服务
./deploy/scripts/stop.sh

# 更新服务
./deploy/scripts/update.sh latest

# 查看日志
docker-compose -f docker-compose.prod.yml logs -f backend

# 查看服务状态
docker-compose -f docker-compose.prod.yml ps

# 健康检查
curl https://your-domain.com/api/health

三、GitHub Actions 自动部署

配置 Secrets

在 GitHub 仓库设置中添加：

• PROD_HOST: 服务器 IP
• PROD_USER: SSH 用户名
• PROD_SSH_KEY: SSH 私钥
• PROD_DOMAIN: 生产域名
• PROD_APP_PATH: 应用路径（可选）

部署流程

1. 推送代码到 main 分支
2. GitHub Actions 自动构建并部署
3. 查看部署日志：https://github.com/your-org/wecom-ai-assistant/actions

四、关键文件

文件	说明
.env.prod	生产环境变量（不提交到 Git）
docker-compose.prod.yml	生产环境 Docker Compose 配置
deploy/docker/backend.Dockerfile	Backend 生产镜像构建文件
deploy/docker/nginx.conf	Nginx 生产配置
deploy/scripts/start.sh	启动脚本
deploy/scripts/update.sh	更新脚本
.github/workflows/deploy.yml	GitHub Actions 部署 workflow

五、故障排查

# 查看服务日志
docker-compose -f docker-compose.prod.yml logs backend

# 检查服务状态
docker-compose -f docker-compose.prod.yml ps

# 检查环境变量
docker-compose -f docker-compose.prod.yml config

# 检查 SSL 证书
sudo certbot certificates

# 测试健康检查
curl -v https://your-domain.com/api/health

六、回滚

# 回滚到指定版本
export IMAGE_TAG=v0.9.0
docker-compose -f docker-compose.prod.yml --env-file .env.prod pull
docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d

详细文档：参见 docs/deploy.md