# 设计文档

## 概述

本设计文档描述了 QAUP 项目的 Docker 容器化部署架构。该方案将整个项目打包为多个 Docker 容器，包括后端应用、前端应用、数据库和缓存服务，适用于在客户的 Ubuntu 系统上进行生产环境部署。

## 架构

### 整体架构图

```mermaid
graph TB
    subgraph "Docker Host (Ubuntu)"
        subgraph "qaup-network"
            nginx[Nginx容器<br/>端口: 80, 443]
            app[QAUP应用容器<br/>端口: 8080]
            postgres[(PostgreSQL容器<br/>端口: 5432)]
            redis[(Redis容器<br/>端口: 6379)]
        end
        
        subgraph "Docker Volumes"
            db_data[数据库数据卷]
            app_logs[应用日志卷]
            upload_files[文件上传卷]
            nginx_conf[Nginx配置卷]
        end
    end
    
    Client[客户端浏览器] --> nginx
    nginx --> app
    app --> postgres
    app --> redis
    
    postgres -.-> db_data
    app -.-> app_logs
    app -.-> upload_files
    nginx -.-> nginx_conf
```

### 容器组件

1. **Nginx 容器**: 反向代理和静态文件服务
2. **QAUP 应用容器**: Spring Boot 应用（包含所有模块）
3. **PostgreSQL 容器**: 数据库服务（包含 PostGIS 扩展）
4. **Redis 容器**: 缓存和会话存储

## 组件和接口

### 1. QAUP 应用容器

**基础镜像**: `openjdk:17-jre-slim`

**功能**:
- 运行 qaup-admin.jar（包含所有模块）
- 提供 REST API 服务
- 处理定时任务
- 管理文件上传

**配置**:
- JVM 参数优化
- 环境变量配置
- 健康检查端点

### 2. Nginx 容器

**基础镜像**: `nginx:alpine`

**功能**:
- 反向代理到后端应用
- 服务前端静态文件
- SSL 终止（可选）
- 负载均衡（单实例时作为代理）

**配置**:
- 自定义 nginx.conf
- 前端构建文件挂载
- 日志配置

### 3. PostgreSQL 容器

**基础镜像**: `postgis/postgis:15-3.3`

**功能**:
- 数据持久化存储
- 空间数据支持（PostGIS）
- 数据库初始化脚本

**配置**:
- 数据库初始化
- 性能参数调优
- 数据卷挂载

### 4. Redis 容器

**基础镜像**: `redis:7-alpine`

**功能**:
- 缓存存储
- 会话管理
- 数据持久化

**配置**:
- Redis 配置文件
- 持久化策略
- 内存限制

## 数据模型

### Docker Compose 配置结构

```yaml
version: '3.8'
services:
  qaup-app:
    # 应用服务配置
  qaup-nginx:
    # Nginx 服务配置
  qaup-postgres:
    # PostgreSQL 服务配置
  qaup-redis:
    # Redis 服务配置

volumes:
  # 数据卷定义

networks:
  # 网络定义
```

### 环境变量配置

**应用配置**:
- `SPRING_PROFILES_ACTIVE`: 激活的配置文件
- `DB_HOST`, `DB_PORT`, `DB_NAME`: 数据库连接
- `REDIS_HOST`, `REDIS_PORT`: Redis 连接
- `UPLOAD_PATH`: 文件上传路径

**数据库配置**:
- `POSTGRES_DB`: 数据库名称
- `POSTGRES_USER`: 数据库用户
- `POSTGRES_PASSWORD`: 数据库密码

## 错误处理

### 容器故障处理

1. **自动重启策略**
   - 所有服务配置 `restart: unless-stopped`
   - 健康检查失败时自动重启

2. **数据恢复**
   - 数据库数据通过卷持久化
   - 应用日志和上传文件持久化

3. **网络故障处理**
   - 容器间通信通过内部网络
   - 外部访问通过 Nginx 代理

### 监控和告警

1. **健康检查**
   - 应用: `/actuator/health`
   - 数据库: `pg_isready`
   - Redis: `redis-cli ping`

2. **日志管理**
   - 应用日志通过卷挂载
   - 容器日志通过 Docker 日志驱动
   - 日志轮转配置

## 测试策略

### 部署测试

1. **容器启动测试**
   - 验证所有容器正常启动
   - 检查容器间网络连通性

2. **功能测试**
   - API 接口可访问性
   - 前端页面加载
   - 数据库连接正常

3. **持久化测试**
   - 容器重启后数据保持
   - 文件上传功能正常

### 性能测试

1. **资源使用测试**
   - 内存使用监控
   - CPU 使用监控
   - 磁盘 I/O 监控

2. **并发测试**
   - 多用户同时访问
   - 数据库连接池测试

## 安全考虑

### 网络安全

1. **网络隔离**
   - 使用自定义 Docker 网络
   - 仅暴露必要端口

2. **访问控制**
   - 数据库仅允许应用容器访问
   - Redis 仅允许内部网络访问

### 数据安全

1. **敏感信息管理**
   - 使用环境变量或 Docker secrets
   - 数据库密码加密存储

2. **文件权限**
   - 容器内使用非 root 用户
   - 挂载卷设置适当权限

## 部署流程

### 离线部署准备阶段（在有网络环境中进行）

1. **Docker 镜像准备**
   - 构建所有自定义镜像
   - 拉取所有基础镜像
   - 导出镜像为 tar 文件

2. **应用构建**
   - Maven 构建 JAR 包
   - 创建应用 Docker 镜像

3. **前端构建**
   - npm 构建前端资源
   - 准备 Nginx 静态文件

4. **部署包打包**
   - 打包所有 Docker 镜像文件
   - 打包配置文件和脚本
   - 创建离线安装包

### 现场部署阶段（在客户内网环境中进行）

1. **环境准备**
   - 安装 Docker 和 Docker Compose
   - 创建必要目录和权限

2. **镜像导入**
   - 导入所有 Docker 镜像
   - 验证镜像完整性

3. **服务启动**
   - 启动数据库和缓存服务
   - 初始化数据库架构
   - 启动应用和 Nginx 服务

4. **验证部署**
   - 健康检查验证
   - 功能测试验证