# QAUP 系统 Docker 部署指南

## 概述

本文档详细介绍了如何在 Ubuntu 系统上使用 Docker 部署 QAUP 管理系统。该部署方案支持生产环境使用，包含完整的监控、日志管理和备份功能。

## 系统要求

### 硬件要求
- **CPU**: 最少 2 核，推荐 4 核或以上
- **内存**: 最少 4GB，推荐 8GB 或以上
- **磁盘**: 最少 20GB 可用空间，推荐 50GB 或以上
- **网络**: 稳定的网络连接（内网部署无需外网）

### 软件要求
- **操作系统**: Ubuntu 18.04 LTS 或更高版本
- **Docker**: 20.10 或更高版本
- **Docker Compose**: 1.29 或更高版本
- **其他工具**: curl, wget, unzip
- **Python环境**（可选，用于开发工具）: Python 3.6+, pip

## 安装 Docker 和 Docker Compose

### 安装 Docker

```bash
# 更新包索引
sudo apt update

# 安装必要的包
sudo apt install apt-transport-https ca-certificates curl gnupg lsb-release

# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 设置稳定版仓库
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker Engine
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io

# 将当前用户添加到 docker 组
sudo usermod -aG docker $USER

# 重新登录或运行以下命令
newgrp docker
```

### 安装 Docker Compose

```bash
# 下载 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 添加执行权限
sudo chmod +x /usr/local/bin/docker-compose

# 验证安装
docker-compose --version
```

## 项目结构说明

QAUP 系统采用了优化的部署结构，所有部署相关文件都集中在 `deploy` 目录下：

```
QAUP-Management/
├── deploy/                    # 部署目录（工作目录）
│   ├── deploy.sh             # 主部署脚本
│   ├── docker-compose.yml    # Docker Compose 配置
│   ├── docker-compose.prod.yml # 生产环境配置
│   ├── Dockerfile            # 应用镜像构建文件
│   ├── .env.template         # 环境变量模板
│   ├── docker/               # Docker 相关脚本和配置
│   │   ├── config-manager.sh # 配置管理脚本
│   │   ├── monitor.sh        # 监控脚本
│   │   ├── nginx/            # Nginx 配置
│   │   └── postgres/         # PostgreSQL 配置
│   └── docs/                 # 部署文档
├── qaup-admin/               # 后端主模块
├── qaup-ui/                  # 前端模块
└── 其他项目文件...
```

**离线部署包结构（更新后）：**
```
qaup-offline-deploy/
├── docker-compose.yml        # Docker Compose 配置（根目录）
├── docker-compose.prod.yml   # 生产环境配置（根目录）
├── .env.template             # 环境变量模板（根目录）
├── deploy.sh                 # 部署脚本
├── images/                   # Docker 镜像文件
├── scripts/                  # 部署脚本
└── README-离线部署.md        # 离线部署说明
```

**重要说明：**
- 所有部署操作都在 `deploy` 目录下进行
- Docker 构建上下文指向项目根目录，确保能正确访问所有源码文件
- 部署脚本会自动处理路径映射，无需手动调整

## 部署步骤

### 1. 获取部署包

#### 在线部署
```bash
# 克隆项目（如果有 Git 访问权限）
git clone <项目地址>
cd QAUP-Management/deploy
```

#### 离线部署
```bash
# 解压离线部署包
tar -xzf qaup-offline-deploy.tar.gz
cd QAUP-Management/deploy

# 导入 Docker 镜像
./docker/load-images.sh
```

### 2. 路径配置验证

```bash
# 运行路径配置测试（推荐）
./test-paths.sh
```

### 3. 环境验证

```bash
# 运行环境验证脚本
./docker/validate-environment.sh
```

如果验证失败，请根据提示修复问题。

### 4. 数据准备

根据部署场景选择合适的数据准备方式：

#### 场景1：全新部署（推荐新用户）
```bash
# 使用默认模板数据
./docker/postgres/db-manager.sh prepare-default
```

#### 场景2：从现有系统迁移
```bash
# 设置数据库连接信息
export DB_HOST=your_db_host
export DB_USER=postgres
export DB_NAME=qaup

# 从现有数据库导出并准备数据
./docker/postgres/db-manager.sh prepare-export
```

#### 场景3：查看当前数据状态
```bash
# 查看当前数据文件状态
./docker/postgres/db-manager.sh prepare-status
```

### 6. 配置系统

```bash
# 初始化配置
./docker/config-manager.sh init

# 编辑环境配置文件
nano .env
```

**重要配置项说明：**

```bash
# 数据库配置
POSTGRES_DB=qaup
POSTGRES_USER=postgres
POSTGRES_PASSWORD=请设置强密码
APP_DB_USER=qaup_app
APP_DB_PASSWORD=请设置强密码

# Redis 配置
REDIS_PASSWORD=请设置密码或留空

# 应用配置
SPRING_PROFILES_ACTIVE=prod
APP_PORT=8080

# Nginx 配置
NGINX_PORT=80
SERVER_NAME=your-domain.com  # 替换为实际域名或IP
API_PREFIX=/prod-api

# 目录配置
DATA_DIR=./data
LOG_DIR=./logs
BACKUP_DIR=./backup
```

### 4. 一键部署

```bash
# 运行一键部署脚本
./deploy.sh install
```

部署脚本将自动执行以下步骤：
1. 检查系统要求
2. 初始化配置
3. 验证环境
4. 构建 Docker 镜像
5. 启动服务
6. 等待服务就绪
7. 运行健康检查

### 5. 验证部署

部署完成后，访问以下地址验证：

- **前端界面**: http://your-server-ip
- **API 健康检查**: http://your-server-ip/health
- **应用健康检查**: http://your-server-ip/prod-api/actuator/health

## 服务管理

### 基本操作

```bash
# 查看服务状态
./deploy.sh status

# 启动服务
./deploy.sh start

# 停止服务
./deploy.sh stop

# 重启服务
./deploy.sh restart

# 查看日志
./deploy.sh logs all          # 所有服务日志
./deploy.sh logs app          # 应用日志
./deploy.sh logs nginx        # Nginx 日志
```

### 高级管理

```bash
# 使用 Docker Compose 管理器
./docker/docker-compose-manager.sh prod start
./docker/docker-compose-manager.sh prod stop
./docker/docker-compose-manager.sh prod restart
./docker/docker-compose-manager.sh prod status

# 日志管理
./docker/log-manager.sh view app 100     # 查看应用最近100行日志
./docker/log-manager.sh monitor all      # 实时监控所有日志
./docker/log-manager.sh analyze          # 分析错误日志
./docker/log-manager.sh cleanup 30       # 清理30天前的日志

# 系统监控
./docker/monitor.sh status               # 检查系统状态
./docker/monitor.sh watch 60             # 每60秒监控一次
./docker/monitor.sh resources            # 查看资源使用
```

## 监控和告警

### 系统监控

```bash
# 实时监控
./docker/monitor.sh watch

# 生成监控报告
./docker/monitor.sh report

# 检查告警
./docker/alert-manager.sh check

# 持续告警监控
./docker/alert-manager.sh monitor 300    # 每5分钟检查一次
```

### 健康检查

系统提供多层次的健康检查：

1. **容器级健康检查**: Docker 内置健康检查
2. **服务级健康检查**: 应用程序健康端点
3. **系统级健康检查**: 资源使用监控

## 数据备份和恢复

### 数据库备份

```bash
# 手动备份
docker exec qaup-postgres /backup-db.sh

# 查看备份文件
ls -la ./backup/postgres/

# 恢复数据库
docker exec qaup-postgres /restore-db.sh /backup/qaup_backup_20241231_120000.sql.gz
```

### 配置备份

```bash
# 备份配置文件
./docker/config-manager.sh backup

# 查看备份
ls -la ./backup/config/
```

## 故障排除

### 常见问题

#### 1. 容器启动失败

```bash
# 查看容器状态
docker ps -a

# 查看容器日志
docker logs qaup-app
docker logs qaup-postgres
docker logs qaup-redis
docker logs qaup-nginx

# 检查资源使用
docker stats
```

#### 2. 数据库连接失败

```bash
# 检查数据库容器状态
docker exec qaup-postgres pg_isready -h localhost -p 5432 -U postgres

# 检查数据库日志
docker logs qaup-postgres

# 测试数据库连接
docker exec qaup-postgres psql -U postgres -d qaup -c "SELECT version();"
```

#### 3. 前端无法访问

```bash
# 检查 Nginx 状态
curl -I http://localhost/health

# 检查 Nginx 配置
docker exec qaup-nginx nginx -t

# 查看 Nginx 日志
docker logs qaup-nginx
```

#### 4. 应用响应慢

```bash
# 检查应用健康状态
curl http://localhost:8080/actuator/health

# 查看应用日志
docker logs qaup-app | grep -i "error\|exception"

# 检查资源使用
docker stats qaup-app
```

### 日志分析

```bash
# 分析错误日志
./docker/log-manager.sh analyze

# 查看特定时间段的日志
docker logs qaup-app --since "2024-01-01T00:00:00" --until "2024-01-01T23:59:59"

# 搜索特定错误
docker logs qaup-app | grep -i "OutOfMemoryError"
```

## 性能优化

### JVM 调优

编辑 `.env` 文件中的 JVM 参数：

```bash
# 生产环境 JVM 配置
JVM_OPTS=-Dname=qaup-admin.jar -Duser.timezone=Asia/Shanghai -server -Xms2g -Xmx4g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m -XX:+UseG1GC -XX:G1HeapRegionSize=16m
```

### 数据库优化

编辑 `docker/postgres/postgresql.conf`：

```bash
# 根据服务器配置调整
shared_buffers = 512MB          # 25% of RAM
effective_cache_size = 2GB      # 75% of RAM
work_mem = 8MB
maintenance_work_mem = 128MB
```

### Nginx 优化

编辑 `docker/nginx/nginx.conf`：

```bash
worker_processes auto;
worker_connections 2048;
keepalive_timeout 65;
client_max_body_size 50M;
```

## 安全配置

### 防火墙设置

```bash
# 只开放必要端口
sudo ufw allow 22/tcp          # SSH
sudo ufw allow 80/tcp          # HTTP
sudo ufw allow 443/tcp         # HTTPS
sudo ufw enable
```

### SSL/TLS 配置

1. 获取 SSL 证书（Let's Encrypt 或商业证书）
2. 将证书文件放置在 `./ssl/` 目录
3. 更新 Nginx 配置启用 HTTPS

### 密码安全

```bash
# 生成强密码
./docker/secrets-manager.sh generate

# 检查密码强度
./docker/secrets-manager.sh check
```

## 更新和维护

### 系统更新

```bash
# 备份当前部署
./docker/config-manager.sh backup

# 更新部署
./deploy.sh update

# 验证更新
./deploy.sh status
```

### 定期维护

建议定期执行以下维护任务：

```bash
# 每日
./docker/alert-manager.sh check
./docker/monitor.sh status

# 每周
./docker/log-manager.sh cleanup 30
./docker/log-manager.sh compress

# 每月
docker system prune -f
./docker/config-manager.sh backup
```

## 可选工具安装

### Python 开发工具（可选）

如果需要使用项目中的Python开发工具（如mock server），可以安装Python环境：

```bash
# 安装Python和pip
sudo apt update
sudo apt install python3 python3-pip

# 安装Flask（用于mock server）
pip3 install flask

# 运行mock server（开发测试用）
cd tools
python3 mock_server.py
```

## 联系支持

如果遇到无法解决的问题，请提供以下信息：

1. 系统信息：`uname -a`
2. Docker 版本：`docker --version`
3. 容器状态：`docker ps -a`
4. 错误日志：相关服务的日志文件
5. 配置文件：`.env` 文件（隐藏敏感信息）

---

**注意**: 本文档会根据系统更新持续维护，请定期查看最新版本。