# Design Document: Docker Deployment

## Overview

本设计文档描述了若依框架项目的前后端分离Docker部署方案。该方案将Vue3前端应用、Spring Boot后端应用和MySQL数据库分别容器化，通过Docker Compose进行统一编排和管理。

系统采用微服务架构，前端通过Nginx提供静态文件服务并代理API请求到后端服务，后端连接到独立的数据库容器，实现完全的容器化部署。

## Architecture

### 整体架构图

```mermaid
graph TB
    subgraph "Docker Host"
        subgraph "Frontend Container"
            A[Nginx + Vue3 Static Files]
        end
        
        subgraph "Backend Container"
            B[Spring Boot Application]
        end
        
        subgraph "Database Container"
            C[MySQL Database]
        end
        
        subgraph "Volumes"
            D[Database Data Volume]
            E[Log Volume]
            F[Config Volume]
        end
    end
    
    G[External Users] --> A
    A --> B
    B --> C
    C --> D
    B --> E
    A --> F
    B --> F
```

### 网络架构

```mermaid
graph LR
    subgraph "External Network"
        U[Users]
    end
    
    subgraph "Docker Network: anxin-network"
        F[Frontend:80]
        B[Backend:8080]
        D[Database:3306]
    end
    
    U -->|HTTP:80| F
    F -->|API Proxy| B
    B -->|MySQL Connection| D
```

## Components and Interfaces

### 1. Frontend Container (anxin-frontend)

**基础镜像**: nginx:alpine
**构建方式**: 多阶段构建

**第一阶段 - 构建阶段**:
- 基础镜像: node:18-alpine
- 工作目录: /app
- 复制源码并执行npm构建
- 输出: dist目录包含构建后的静态文件

**第二阶段 - 运行阶段**:
- 基础镜像: nginx:alpine
- 复制构建产物到nginx默认目录
- 配置nginx.conf用于静态文件服务和API代理
- 暴露端口: 80

**Nginx配置要点**:
```nginx
server {
    listen 80;
    server_name localhost;
    
    # 静态文件服务
    location / {
        root /usr/share/nginx/html;
        try_files $uri $uri/ /index.html;
    }
    
    # API代理
    location /prod-api/ {
        proxy_pass http://anxin-backend:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### 2. Backend Container (anxin-backend)

**基础镜像**: openjdk:8-jre-alpine
**构建方式**: 多阶段构建

**第一阶段 - 构建阶段**:
- 基础镜像: maven:3.8-openjdk-8
- 工作目录: /app
- 复制pom.xml和源码
- 执行Maven构建: mvn clean package -DskipTests
- 输出: target目录包含JAR文件

**第二阶段 - 运行阶段**:
- 基础镜像: openjdk:8-jre-alpine
- 复制JAR文件到容器
- 设置启动命令
- 暴露端口: 8080

**环境变量配置**:
- `SPRING_PROFILES_ACTIVE`: 激活的配置文件
- `SPRING_DATASOURCE_URL`: 数据库连接URL
- `SPRING_DATASOURCE_USERNAME`: 数据库用户名
- `SPRING_DATASOURCE_PASSWORD`: 数据库密码

### 3. Database Container (anxin-mysql)

**基础镜像**: mysql:8.0
**配置要点**:
- 数据持久化: 挂载数据卷到/var/lib/mysql
- 初始化脚本: 挂载SQL文件到/docker-entrypoint-initdb.d/
- 字符集配置: utf8mb4
- 暴露端口: 3306

**环境变量**:
- `MYSQL_ROOT_PASSWORD`: root用户密码
- `MYSQL_DATABASE`: 默认数据库名
- `MYSQL_USER`: 应用用户名
- `MYSQL_PASSWORD`: 应用用户密码

### 4. Docker Compose编排

**服务依赖关系**:
```yaml
services:
  anxin-mysql:
    # 数据库服务，最先启动
    
  anxin-backend:
    depends_on:
      - anxin-mysql
    # 后端服务，依赖数据库
    
  anxin-frontend:
    depends_on:
      - anxin-backend
    # 前端服务，依赖后端
```

**网络配置**:
- 创建自定义网络: anxin-network
- 所有服务连接到同一网络
- 服务间通过服务名进行通信

**卷挂载**:
- 数据库数据卷: mysql-data
- 日志卷: logs
- 配置文件卷: configs

## Data Models

### 容器配置模型

```yaml
# Docker Compose配置结构
version: '3.8'
services:
  service_name:
    build:
      context: string
      dockerfile: string
    image: string
    container_name: string
    ports:
      - "host_port:container_port"
    environment:
      - KEY=VALUE
    volumes:
      - volume_name:container_path
    networks:
      - network_name
    depends_on:
      - dependency_service
```

### 构建脚本配置模型

```bash
# 环境配置结构
ENVIRONMENT=production|staging|development
DB_HOST=string
DB_PORT=number
DB_NAME=string
DB_USER=string
DB_PASSWORD=string
BACKEND_PORT=number
FRONTEND_PORT=number
```

## Correctness Properties

*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*

### Property 1: Container Build Verification
*For any* Docker container build process, the resulting container should contain all required application artifacts (static files for frontend, JAR files for backend)
**Validates: Requirements 1.1, 2.1**

### Property 2: Service Connectivity
*For any* multi-container deployment, when all containers are started, each service should be able to communicate with its dependencies (frontend to backend, backend to database)
**Validates: Requirements 1.2, 1.3, 2.2**

### Property 3: Port Configuration
*For any* container configuration, the specified ports should be correctly exposed and accessible from the host system
**Validates: Requirements 1.5, 2.3, 3.4**

### Property 4: Build Process Execution
*For any* build script execution, the script should successfully complete all build steps (npm build for frontend, Maven build for backend) without errors
**Validates: Requirements 1.4, 2.4**

### Property 5: Database Initialization
*For any* database container startup, the container should successfully initialize the database schema and execute all provided SQL scripts
**Validates: Requirements 3.2, 3.5**

### Property 6: Data Persistence
*For any* database container restart, previously stored data should remain intact through volume mounting
**Validates: Requirements 3.3**

### Property 7: Service Orchestration
*For any* Docker Compose deployment, services should start in the correct dependency order and establish proper network communication
**Validates: Requirements 4.1, 4.2, 4.3, 4.5**

### Property 8: Volume Configuration
*For any* Docker Compose configuration, all specified volumes should be correctly mounted and accessible to their respective containers
**Validates: Requirements 4.4**

### Property 9: Build Script Functionality
*For any* deployment script execution, the script should successfully build all images, pull latest code, and verify service availability
**Validates: Requirements 5.1, 5.2, 5.5**

### Property 10: Environment Configuration Management
*For any* environment parameter change, the build script should correctly apply the new configuration and load the appropriate configuration files
**Validates: Requirements 5.3, 6.1, 6.2, 6.3, 6.4, 6.5**

### Property 11: Logging and Monitoring
*For any* script execution, sufficient logging information should be provided to enable troubleshooting and monitoring
**Validates: Requirements 5.4**

## Error Handling

### 容器启动失败处理
- **数据库连接失败**: 后端容器应实现重试机制，等待数据库容器完全启动
- **端口冲突**: 提供清晰的错误信息并建议解决方案
- **镜像构建失败**: 详细记录构建日志，便于问题定位

### 网络连接问题
- **服务间通信失败**: 验证网络配置和服务发现机制
- **外部访问问题**: 检查端口映射和防火墙配置
- **DNS解析问题**: 确保容器间能够通过服务名正确解析

### 数据持久化问题
- **卷挂载失败**: 验证宿主机目录权限和路径存在性
- **数据丢失**: 实现数据备份和恢复机制
- **存储空间不足**: 监控磁盘使用情况并提供告警

### 构建脚本错误处理
- **依赖下载失败**: 配置镜像源和重试机制
- **权限问题**: 提供明确的权限要求说明
- **环境变量缺失**: 验证必需的环境变量并提供默认值

## Testing Strategy

### 单元测试方法
- **Dockerfile语法验证**: 使用hadolint等工具验证Dockerfile语法
- **配置文件验证**: 验证nginx.conf、docker-compose.yml等配置文件的正确性
- **脚本语法检查**: 使用shellcheck验证shell脚本语法

### 集成测试方法
- **容器构建测试**: 验证每个容器能够成功构建
- **服务启动测试**: 验证所有服务能够正确启动并建立连接
- **端到端测试**: 从外部访问验证整个系统的功能完整性

### 属性测试配置
使用Docker和shell脚本进行属性测试，每个属性测试运行最少100次迭代：

- **测试框架**: 使用Bash测试框架（如bats-core）
- **测试环境**: 在隔离的Docker环境中运行测试
- **测试数据**: 使用不同的环境配置和数据集进行测试
- **测试标签格式**: **Feature: docker-deployment, Property {number}: {property_text}**

### 性能测试
- **容器启动时间**: 测量各容器的启动时间
- **资源使用情况**: 监控CPU、内存、磁盘使用情况
- **并发访问测试**: 测试系统在高并发情况下的表现

### 安全测试
- **镜像安全扫描**: 使用工具扫描镜像中的安全漏洞
- **网络安全**: 验证容器间网络隔离和访问控制
- **敏感信息保护**: 确保密码等敏感信息不会暴露在镜像中