wecom-ai-assistant/README_DEPLOY.md

部署指南

概述

本项目使用 Docker 容器化部署，镜像存储在私有 Registry：registry.667788.cool

镜像信息

• Backend: registry.667788.cool/wecom-backend:${TAG}
• Admin: registry.667788.cool/wecom-admin:${TAG}
• Nginx: registry.667788.cool/wecom-nginx:${TAG}

默认 TAG: latest

本地构建

构建并推送镜像

# 赋予脚本执行权限（首次运行）
chmod +x scripts/build_and_push.sh

# 使用默认标签 latest
./scripts/build_and_push.sh

# 或指定标签
./scripts/build_and_push.sh v1.0.0

手动构建

# 登录 Registry
docker login registry.667788.cool

# 设置标签
export TAG=v1.0.0

# 构建镜像
docker compose -f docker-compose.release.yml build

# 推送镜像
docker compose -f docker-compose.release.yml push

云端部署

准备工作

1. 服务器要求：

   • Linux 服务器（Ubuntu 20.04+ / CentOS 7+）
   • Docker 和 docker-compose 已安装
   • 开放端口：80、443（HTTP/HTTPS）

2. 上传部署文件：

   # 创建部署目录
   mkdir -p /opt/wecom-ai-assistant
   cd /opt/wecom-ai-assistant
   
   # 上传 deploy/ 目录下的所有文件
   # 或使用 Git 克隆项目后复制 deploy/ 目录
   

3. 配置环境变量：

   cd /opt/wecom-ai-assistant/deploy
   
   # 复制环境变量模板
   cp .env.prod.example .env.prod
   
   # 编辑配置文件
   nano .env.prod
   

   填写以下必需配置：

   • TAG: 镜像标签（默认 latest）
   • POSTGRES_PASSWORD: 数据库密码
   • DATABASE_URL: 数据库连接字符串
   • WECOM_*: 企业微信配置
   • JWT_SECRET: JWT 密钥

部署步骤

# 1. 进入部署目录
cd /opt/wecom-ai-assistant/deploy

# 2. 登录 Registry（如果需要认证）
docker login registry.667788.cool

# 3. 拉取最新镜像
docker compose -f docker-compose.prod.yml --env-file .env.prod pull

# 4. 启动服务
docker compose -f docker-compose.prod.yml --env-file .env.prod up -d

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

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

验证部署

# 健康检查
curl http://localhost/api/health

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

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

更新部署

更新到新版本

# 1. 更新环境变量中的 TAG
# 编辑 .env.prod，修改 TAG=v1.0.1

# 2. 拉取新镜像
docker compose -f docker-compose.prod.yml --env-file .env.prod pull

# 3. 重启服务
docker compose -f docker-compose.prod.yml --env-file .env.prod up -d

# 4. 验证
docker compose -f docker-compose.prod.yml ps

回滚到旧版本

# 1. 修改 .env.prod 中的 TAG 为旧版本
# TAG=v1.0.0

# 2. 拉取旧镜像
docker compose -f docker-compose.prod.yml --env-file .env.prod pull

# 3. 重启服务
docker compose -f docker-compose.prod.yml --env-file .env.prod up -d

停止和清理

# 停止服务
docker compose -f docker-compose.prod.yml --env-file .env.prod down

# 停止并删除数据卷（⚠️ 危险操作）
docker compose -f docker-compose.prod.yml --env-file .env.prod down -v

# 清理未使用的镜像
docker image prune -a

服务访问

部署成功后，服务可通过以下方式访问：

• 管理后台: http://your-server-ip/
• 后端 API: http://your-server-ip/api/
• 健康检查: http://your-server-ip/api/health

故障排查

问题：无法拉取镜像

解决方案：

# 检查 Registry 登录状态
docker login registry.667788.cool

# 手动拉取镜像测试
docker pull registry.667788.cool/wecom-backend:latest

问题：服务启动失败

检查项：

1. 环境变量配置是否正确
2. 数据库连接是否正常
3. 端口是否被占用
4. 查看服务日志：docker compose -f docker-compose.prod.yml logs

问题：Nginx 无法访问后端

解决方案：

1. 检查网络连接：docker network ls
2. 检查服务是否在同一网络：docker compose -f docker-compose.prod.yml ps
3. 检查 Nginx 配置：cat deploy/nginx.conf

相关文档

• 生产部署详细指南
• 宝塔面板部署指南
• Docker 镜像加速配置