309 lines
9.4 KiB
Markdown
309 lines
9.4 KiB
Markdown
# 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、内存、磁盘使用情况
|
||
- **并发访问测试**: 测试系统在高并发情况下的表现
|
||
|
||
### 安全测试
|
||
- **镜像安全扫描**: 使用工具扫描镜像中的安全漏洞
|
||
- **网络安全**: 验证容器间网络隔离和访问控制
|
||
- **敏感信息保护**: 确保密码等敏感信息不会暴露在镜像中 |