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`

## 本地构建

### 构建并推送镜像

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

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

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

### 手动构建

```bash
# 登录 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. **上传部署文件**：
   ```bash
   # 创建部署目录
   mkdir -p /opt/wecom-ai-assistant
   cd /opt/wecom-ai-assistant
   
   # 上传 deploy/ 目录下的所有文件
   # 或使用 Git 克隆项目后复制 deploy/ 目录
   ```

3. **配置环境变量**：
   ```bash
   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 密钥

### 部署步骤

```bash
# 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
```

### 验证部署

```bash
# 健康检查
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
```

## 更新部署

### 更新到新版本

```bash
# 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
```

### 回滚到旧版本

```bash
# 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
```

## 停止和清理

```bash
# 停止服务
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

## 故障排查

### 问题：无法拉取镜像

**解决方案**：
```bash
# 检查 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`

## 相关文档

- [生产部署详细指南](./docs/deploy.md)
- [宝塔面板部署指南](./docs/baota-docker-setup.md)
- [Docker 镜像加速配置](./docs/docker-mirror.md)