# 若依框架 Docker 部署文档

本文档提供若依框架项目的完整Docker化部署方案，包括前后端分离架构的容器化部署、环境配置管理和故障排除指南。

## 📋 目录

- [项目概述](#项目概述)
- [快速开始](#快速开始)
- [环境要求](#环境要求)
- [目录结构](#目录结构)
- [详细部署步骤](#详细部署步骤)
- [环境配置](#环境配置)
- [服务管理](#服务管理)
- [监控和日志](#监控和日志)
- [故障排除](#故障排除)
- [性能优化](#性能优化)
- [安全配置](#安全配置)
- [常见问题](#常见问题)

## 🚀 项目概述

本部署方案将若依框架项目容器化，实现：
- **前后端分离**：Vue3前端 + Spring Boot后端独立部署
- **数据库容器化**：MySQL 8.0容器化部署
- **环境隔离**：支持开发、测试、生产环境配置
- **自动化部署**：一键构建、部署和管理脚本
- **服务监控**：健康检查和日志管理

### 架构图

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │    Backend      │    │    Database     │
│   (Vue3+Nginx)  │───▶│  (Spring Boot)  │───▶│     (MySQL)     │
│   Port: 80      │    │   Port: 8080    │    │   Port: 3306    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## ⚡ 快速开始

### 1. 环境准备

确保系统已安装必要的软件：

```bash
# 检查Docker版本
docker --version
docker-compose --version

# 检查系统资源
free -h
df -h
```

### 2. 配置环境

```bash
# 1. 进入Docker目录
cd docker

# 2. 复制环境配置文件
cp environments/.env.example environments/.env.development

# 3. 编辑配置文件（根据需要修改）
vim environments/.env.development
```

### 3. 一键部署

```bash
# 开发环境部署
./build.sh deploy -e development

# 或者分步执行
./build.sh build-all -e development    # 构建镜像
./deploy.sh start -e development       # 启动服务
```

### 4. 验证部署

```bash
# 检查服务状态
./deploy.sh status -e development

# 执行健康检查
./deploy.sh health -e development --wait

# 访问应用
# 前端: http://localhost:80
# 后端API: http://localhost:8080
```

## 🔧 环境要求

### 系统要求

| 组件 | 最低要求 | 推荐配置 |
|------|----------|----------|
| **操作系统** | Linux/macOS/Windows | Ubuntu 20.04+ / CentOS 8+ |
| **CPU** | 2核心 | 4核心+ |
| **内存** | 4GB | 8GB+ |
| **磁盘空间** | 10GB | 20GB+ |
| **网络** | 100Mbps | 1Gbps+ |

### 软件依赖

| 软件 | 版本要求 | 安装命令 |
|------|----------|----------|
| **Docker** | 20.10+ | `curl -fsSL https://get.docker.com \| sh` |
| **Docker Compose** | 2.0+ | 随Docker Desktop安装 |
| **Git** | 2.0+ | `apt install git` / `yum install git` |
| **Bash** | 4.0+ | 系统自带 |

### 端口要求

确保以下端口未被占用：

| 服务 | 默认端口 | 可配置 | 说明 |
|------|----------|--------|------|
| 前端服务 | 80 | ✅ | HTTP访问端口 |
| 后端服务 | 8080 | ✅ | API服务端口 |
| 数据库 | 3306 | ✅ | MySQL连接端口 |

## 📁 目录结构

```
docker/
├── README.md                    # 本文档
├── build.sh                     # 主构建脚本
├── deploy.sh                    # 部署管理脚本
├── docker-compose.yml           # 基础编排文件
├── docker-compose.*.yml         # 环境特定编排文件
├── validation-report.md         # 验证报告
│
├── frontend/                    # 前端容器配置
│   ├── Dockerfile              # 前端镜像构建文件
│   └── nginx.conf.*            # Nginx配置文件
│
├── backend/                     # 后端容器配置
│   ├── Dockerfile              # 后端镜像构建文件
│   └── startup.sh              # 启动脚本
│
├── database/                    # 数据库配置
│   ├── docker-compose.database.yml
│   ├── init/                   # 初始化脚本
│   └── README.md
│
├── environments/                # 环境配置
│   ├── .env.example            # 配置模板
│   ├── .env.development        # 开发环境
│   ├── .env.staging            # 测试环境
│   └── .env.production         # 生产环境
│
├── configs/                     # 配置文件模板
│   ├── nginx.conf.*            # Nginx配置模板
│   ├── application-docker.yml   # Spring Boot配置
│   └── my.cnf.*                # MySQL配置
│
├── scripts/                     # 辅助脚本
│   ├── env-config.sh           # 环境配置管理
│   ├── validate-*.sh           # 配置验证脚本
│   ├── backup.sh               # 数据备份脚本
│   └── setup-env.sh            # 环境初始化
│
└── data/                        # 数据目录（运行时创建）
    ├── mysql/                  # 数据库数据
    ├── logs/                   # 日志文件
    └── uploads/                # 上传文件
```

## 📖 详细部署步骤

### 步骤1：环境配置

#### 1.1 创建环境配置文件

```bash
# 复制配置模板
cp environments/.env.example environments/.env.development

# 编辑配置文件
vim environments/.env.development
```

#### 1.2 关键配置项说明

```bash
# 基础环境配置
ENVIRONMENT=development                    # 环境标识
COMPOSE_PROJECT_NAME=anxin                # Docker Compose项目名

# 数据库配置
DB_HOST=anxin-mysql                       # 数据库主机
DB_PORT=3306                              # 数据库端口
DB_NAME=anxin                             # 数据库名
DB_USER=anxin_user                        # 数据库用户
DB_PASSWORD=your_secure_password          # 数据库密码

# 服务端口配置
FRONTEND_PORT=80                          # 前端服务端口
BACKEND_PORT=8080                         # 后端服务端口

# 资源限制配置
BACKEND_MEMORY_LIMIT=1024                 # 后端内存限制(MB)
DATABASE_MEMORY_LIMIT=512                 # 数据库内存限制(MB)
```

### 步骤2：构建镜像

#### 2.1 构建所有镜像

```bash
# 构建所有镜像（开发环境）
./build.sh build-all -e development

# 构建特定组件
./build.sh build -c frontend -e development
./build.sh build -c backend -e development

# 强制重新构建（不使用缓存）
./build.sh build-all -e development --no-cache
```

#### 2.2 构建选项说明

| 选项 | 说明 | 示例 |
|------|------|------|
| `-e, --env` | 指定环境 | `-e production` |
| `-c, --component` | 指定组件 | `-c frontend` |
| `--pull` | 构建前拉取代码 | `--pull` |
| `--no-cache` | 不使用构建缓存 | `--no-cache` |
| `--clean` | 清理构建缓存 | `--clean` |
| `--verbose` | 显示详细日志 | `--verbose` |

### 步骤3：启动服务

#### 3.1 启动所有服务

```bash
# 启动所有服务
./deploy.sh start -e development

# 启动特定服务
./deploy.sh start mysql -e development
./deploy.sh start backend frontend -e development
```

#### 3.2 服务管理命令

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

# 重启服务
./deploy.sh restart -e development

# 停止服务
./deploy.sh stop -e development

# 完全清理（删除容器和网络）
./deploy.sh down -e development
```

### 步骤4：验证部署

#### 4.1 健康检查

```bash
# 执行健康检查
./deploy.sh health -e development

# 等待所有服务健康
./deploy.sh health -e development --wait --retry 10
```

#### 4.2 访问测试

```bash
# 测试前端访问
curl -I http://localhost:80

# 测试后端API
curl -I http://localhost:8080/actuator/health

# 测试数据库连接
mysql -h localhost -P 3306 -u anxin_user -p
```

## ⚙️ 环境配置

### 开发环境 (Development)

```bash
# 特点：启用调试模式，详细日志，热重载
ENVIRONMENT=development
LOG_LEVEL=DEBUG
SPRING_PROFILES_ACTIVE=docker,dev
```

### 测试环境 (Staging)

```bash
# 特点：接近生产配置，性能测试
ENVIRONMENT=staging
LOG_LEVEL=INFO
SPRING_PROFILES_ACTIVE=docker,staging
```

### 生产环境 (Production)

```bash
# 特点：优化性能，安全配置，监控
ENVIRONMENT=production
LOG_LEVEL=WARN
SPRING_PROFILES_ACTIVE=docker,prod
```

### 环境切换

```bash
# 切换到生产环境
./build.sh deploy -e production --pull

# 切换到开发环境
./deploy.sh restart -e development
```

## 🔄 服务管理

### 启动服务

```bash
# 启动所有服务
./deploy.sh start

# 启动特定服务
./deploy.sh start mysql
./deploy.sh start backend frontend

# 强制重新创建容器
./deploy.sh start --force
```

### 停止服务

```bash
# 停止所有服务
./deploy.sh stop

# 停止特定服务
./deploy.sh stop backend

# 设置停止超时时间
./deploy.sh stop -t 60
```

### 重启服务

```bash
# 重启所有服务
./deploy.sh restart

# 重启特定服务
./deploy.sh restart backend
```

### 服务状态

```bash
# 查看详细状态
./deploy.sh status

# 查看容器列表
./deploy.sh ps

# 查看网络和卷信息
docker network ls | grep anxin
docker volume ls | grep anxin
```

## 📊 监控和日志

### 日志查看

```bash
# 查看所有服务日志
./deploy.sh logs

# 查看特定服务日志
./deploy.sh logs backend

# 实时跟踪日志
./deploy.sh logs -f

# 查看最近100行日志
./deploy.sh logs --tail 100

# 查看最近1小时日志
./deploy.sh logs --since 1h
```

### 健康监控

```bash
# 执行健康检查
./deploy.sh health

# 持续监控（等待所有服务健康）
./deploy.sh health --wait --retry 20 --interval 30

# 查看服务详细信息
docker inspect anxin-backend-development
```

### 性能监控

```bash
# 查看容器资源使用
docker stats

# 查看特定容器资源使用
docker stats anxin-backend-development

# 查看系统资源
free -h
df -h
```

## 🔧 故障排除

### 常见问题诊断

#### 1. 服务启动失败

**症状**：容器无法启动或立即退出

**诊断步骤**：

```bash
# 1. 查看容器状态
./deploy.sh status

# 2. 查看容器日志
./deploy.sh logs [service_name]

# 3. 检查配置文件
cat environments/.env.development

# 4. 验证端口占用
netstat -tlnp | grep :80
netstat -tlnp | grep :8080
netstat -tlnp | grep :3306
```

**常见原因及解决方案**：

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 端口被占用 | 其他服务占用端口 | `sudo lsof -i :80` 查找并停止占用进程 |
| 内存不足 | 系统内存不够 | 增加系统内存或调整容器内存限制 |
| 配置错误 | 环境变量配置错误 | 检查并修正 `.env` 文件 |
| 镜像构建失败 | 依赖下载失败 | 检查网络连接，使用 `--no-cache` 重新构建 |

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

**症状**：后端无法连接数据库

**诊断步骤**：

```bash
# 1. 检查数据库容器状态
docker ps | grep mysql

# 2. 检查数据库日志
./deploy.sh logs mysql

# 3. 测试数据库连接
docker exec -it anxin-mysql-development mysql -u root -p

# 4. 检查网络连接
docker network inspect anxin-development_default
```

**解决方案**：

```bash
# 重启数据库服务
./deploy.sh restart mysql

# 检查数据库初始化
docker exec anxin-mysql-development mysql -u root -p -e "SHOW DATABASES;"

# 重新初始化数据库
./deploy.sh down
rm -rf data/development/mysql
./deploy.sh start
```

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

**症状**：前端页面加载但API调用失败

**诊断步骤**：

```bash
# 1. 检查后端服务状态
curl -I http://localhost:8080/actuator/health

# 2. 检查Nginx配置
docker exec anxin-frontend-development cat /etc/nginx/nginx.conf

# 3. 查看Nginx日志
./deploy.sh logs frontend

# 4. 检查网络连通性
docker exec anxin-frontend-development ping anxin-backend
```

**解决方案**：

```bash
# 重启前端服务
./deploy.sh restart frontend

# 检查API代理配置
# 编辑 configs/nginx.conf.development
# 确保 proxy_pass 指向正确的后端服务
```

#### 4. 镜像构建失败

**症状**：Docker镜像构建过程中出错

**诊断步骤**：

```bash
# 1. 查看构建日志
./build.sh build-all --verbose

# 2. 检查Dockerfile语法
docker run --rm -i hadolint/hadolint < frontend/Dockerfile

# 3. 手动构建测试
cd frontend
docker build -t test-frontend .
```

**解决方案**：

```bash
# 清理构建缓存
./build.sh clean

# 强制重新构建
./build.sh build-all --no-cache

# 检查网络连接
ping registry-1.docker.io
```

#### 5. 性能问题

**症状**：服务响应缓慢或资源使用过高

**诊断步骤**：

```bash
# 1. 查看资源使用情况
docker stats

# 2. 检查系统负载
top
htop
iostat -x 1

# 3. 分析日志
./deploy.sh logs --since 1h | grep -i error
./deploy.sh logs --since 1h | grep -i slow
```

**解决方案**：

```bash
# 调整资源限制
# 编辑 environments/.env.development
BACKEND_MEMORY_LIMIT=2048
DATABASE_MEMORY_LIMIT=1024

# 重启服务应用新配置
./deploy.sh restart
```

### 日志分析

#### 关键日志位置

```bash
# 容器日志
docker logs anxin-backend-development

# 应用日志（挂载到宿主机）
tail -f data/development/backend-logs/application.log
tail -f data/development/mysql-logs/error.log
tail -f data/development/nginx-logs/access.log
```

#### 日志级别说明

| 级别 | 说明 | 使用场景 |
|------|------|----------|
| ERROR | 错误信息 | 生产环境问题排查 |
| WARN | 警告信息 | 潜在问题识别 |
| INFO | 一般信息 | 正常运行监控 |
| DEBUG | 调试信息 | 开发环境调试 |

### 数据备份与恢复

#### 数据备份

```bash
# 使用内置备份脚本
./scripts/backup.sh -e development

# 手动备份数据库
docker exec anxin-mysql-development mysqldump -u root -p anxin > backup.sql

# 备份数据卷
docker run --rm -v anxin-development_mysql-data:/data -v $(pwd):/backup alpine tar czf /backup/mysql-data-backup.tar.gz /data
```

#### 数据恢复

```bash
# 恢复数据库
docker exec -i anxin-mysql-development mysql -u root -p anxin < backup.sql

# 恢复数据卷
docker run --rm -v anxin-development_mysql-data:/data -v $(pwd):/backup alpine tar xzf /backup/mysql-data-backup.tar.gz -C /
```

### 网络问题排查

#### 检查网络配置

```bash
# 查看Docker网络
docker network ls
docker network inspect anxin-development_default

# 检查容器网络连接
docker exec anxin-frontend-development ping anxin-backend
docker exec anxin-backend-development ping anxin-mysql

# 检查端口映射
docker port anxin-frontend-development
docker port anxin-backend-development
```

#### 解决网络问题

```bash
# 重新创建网络
./deploy.sh down
./deploy.sh start

# 检查防火墙设置
sudo ufw status
sudo iptables -L
```

## 🚀 性能优化

### 容器资源优化

#### 内存优化

```bash
# 调整JVM内存设置
JAVA_OPTS=-Xms512m -Xmx1024m -XX:+UseG1GC

# 调整MySQL内存设置
# 编辑 configs/my.cnf.production
innodb_buffer_pool_size = 256M
key_buffer_size = 64M
```

#### CPU优化

```bash
# 设置CPU限制
# 在 docker-compose.yml 中
deploy:
  resources:
    limits:
      cpus: '1.0'
      memory: 1024M
```

### 镜像优化

#### 减小镜像大小

```bash
# 使用多阶段构建
# 使用Alpine Linux基础镜像
# 清理不必要的文件和缓存

# 查看镜像大小
docker images | grep anxin
```

#### 构建缓存优化

```bash
# 合理安排Dockerfile层级
# 将变化频率低的操作放在前面
# 使用.dockerignore排除不必要文件
```

### 数据库优化

#### MySQL配置优化

```bash
# 编辑 configs/my.cnf.production
[mysqld]
innodb_buffer_pool_size = 512M
innodb_log_file_size = 128M
max_connections = 200
query_cache_size = 64M
```

#### 索引优化

```sql
-- 分析慢查询
SHOW PROCESSLIST;
SHOW FULL PROCESSLIST;

-- 查看索引使用情况
EXPLAIN SELECT * FROM your_table WHERE condition;
```

## 🔒 安全配置

### 容器安全

#### 用户权限

```bash
# 使用非root用户运行容器
# 在Dockerfile中添加
RUN addgroup -g 1001 appuser && adduser -u 1001 -G appuser -s /bin/sh -D appuser
USER appuser
```

#### 网络安全

```bash
# 限制容器网络访问
# 使用自定义网络
# 关闭不必要的端口映射
```

### 数据安全

#### 密码管理

```bash
# 使用强密码
# 定期更换密码
# 使用Docker secrets管理敏感信息

# 创建密码文件
echo "your_secure_password" | docker secret create db_password -
```

#### 数据加密

```bash
# 启用MySQL SSL
# 配置应用程序使用SSL连接
# 加密敏感数据字段
```

### 访问控制

#### 防火墙配置

```bash
# 配置iptables规则
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 3306 -s 172.20.0.0/16 -j ACCEPT
```

#### 反向代理

```bash
# 使用Nginx作为反向代理
# 配置SSL终止
# 实现负载均衡
```

## ❓ 常见问题

### Q1: 如何更新应用版本？

**A**: 

```bash
# 1. 拉取最新代码
./build.sh pull

# 2. 重新构建镜像
./build.sh build-all --no-cache

# 3. 重启服务
./deploy.sh restart
```

### Q2: 如何扩展服务实例？

**A**: 

```bash
# 编辑 docker-compose.yml
services:
  anxin-backend:
    deploy:
      replicas: 3

# 重新部署
./deploy.sh restart
```

### Q3: 如何迁移到其他服务器？

**A**: 

```bash
# 1. 备份数据
./scripts/backup.sh

# 2. 复制项目文件和备份到新服务器
rsync -av . user@newserver:/path/to/project

# 3. 在新服务器上恢复
./deploy.sh start
# 恢复数据库备份
```

### Q4: 如何配置SSL证书？

**A**: 

```bash
# 1. 获取SSL证书
# 2. 修改Nginx配置
# 3. 更新docker-compose.yml端口映射
# 4. 重启前端服务
```

### Q5: 如何监控服务健康状态？

**A**: 

```bash
# 使用内置健康检查
./deploy.sh health --wait

# 集成外部监控工具
# - Prometheus + Grafana
# - ELK Stack
# - Zabbix
```

### Q6: 如何处理数据库迁移？

**A**: 

```bash
# 1. 备份当前数据
./scripts/backup.sh

# 2. 停止服务
./deploy.sh stop

# 3. 更新数据库脚本
# 4. 重启服务（自动执行迁移）
./deploy.sh start
```

---

## 📞 技术支持

如果遇到问题，请按以下步骤获取帮助：

1. **查看日志**：`./deploy.sh logs -f`
2. **检查状态**：`./deploy.sh health`
3. **查阅文档**：参考本文档故障排除部分
4. **收集信息**：准备错误日志、配置文件、系统信息
5. **寻求帮助**：联系技术支持团队

### 信息收集脚本

```bash
#!/bin/bash
# 收集诊断信息
echo "=== 系统信息 ===" > diagnostic.log
uname -a >> diagnostic.log
docker --version >> diagnostic.log
docker-compose --version >> diagnostic.log

echo "=== 服务状态 ===" >> diagnostic.log
./deploy.sh status >> diagnostic.log

echo "=== 最近日志 ===" >> diagnostic.log
./deploy.sh logs --tail 100 >> diagnostic.log

echo "诊断信息已保存到 diagnostic.log"
```

---

**文档版本**: 1.0.0  
**最后更新**: $(date '+%Y-%m-%d')  
**维护团队**: 若依框架开发团队