19 KiB
19 KiB
若依框架 Docker 部署文档
本文档提供若依框架项目的完整Docker化部署方案，包括前后端分离架构的容器化部署、环境配置管理和故障排除指南。
📋 目录
🚀 项目概述
本部署方案将若依框架项目容器化，实现：
- 前后端分离：Vue3前端 + Spring Boot后端独立部署
- 数据库容器化：MySQL 8.0容器化部署
- 环境隔离：支持开发、测试、生产环境配置
- 自动化部署：一键构建、部署和管理脚本
- 服务监控：健康检查和日志管理
架构图
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ Backend │ │ Database │
│ (Vue3+Nginx) │───▶│ (Spring Boot) │───▶│ (MySQL) │
│ Port: 80 │ │ Port: 8080 │ │ Port: 3306 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
⚡ 快速开始
1. 环境准备
确保系统已安装必要的软件：
# 检查Docker版本
docker --version
docker-compose --version
# 检查系统资源
free -h
df -h
2. 配置环境
# 1. 进入Docker目录
cd docker
# 2. 复制环境配置文件
cp environments/.env.example environments/.env.development
# 3. 编辑配置文件（根据需要修改）
vim environments/.env.development
3. 一键部署
# 开发环境部署
./build.sh deploy -e development
# 或者分步执行
./build.sh build-all -e development # 构建镜像
./deploy.sh start -e development # 启动服务
4. 验证部署
# 检查服务状态
./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 创建环境配置文件
# 复制配置模板
cp environments/.env.example environments/.env.development
# 编辑配置文件
vim environments/.env.development
1.2 关键配置项说明
# 基础环境配置
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 构建所有镜像
# 构建所有镜像（开发环境）
./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 启动所有服务
# 启动所有服务
./deploy.sh start -e development
# 启动特定服务
./deploy.sh start mysql -e development
./deploy.sh start backend frontend -e development
3.2 服务管理命令
# 查看服务状态
./deploy.sh status -e development
# 重启服务
./deploy.sh restart -e development
# 停止服务
./deploy.sh stop -e development
# 完全清理（删除容器和网络）
./deploy.sh down -e development
步骤4：验证部署
4.1 健康检查
# 执行健康检查
./deploy.sh health -e development
# 等待所有服务健康
./deploy.sh health -e development --wait --retry 10
4.2 访问测试
# 测试前端访问
curl -I http://localhost:80
# 测试后端API
curl -I http://localhost:8080/actuator/health
# 测试数据库连接
mysql -h localhost -P 3306 -u anxin_user -p
⚙️ 环境配置
开发环境 (Development)
# 特点：启用调试模式，详细日志，热重载
ENVIRONMENT=development
LOG_LEVEL=DEBUG
SPRING_PROFILES_ACTIVE=docker,dev
测试环境 (Staging)
# 特点：接近生产配置，性能测试
ENVIRONMENT=staging
LOG_LEVEL=INFO
SPRING_PROFILES_ACTIVE=docker,staging
生产环境 (Production)
# 特点：优化性能，安全配置，监控
ENVIRONMENT=production
LOG_LEVEL=WARN
SPRING_PROFILES_ACTIVE=docker,prod
环境切换
# 切换到生产环境
./build.sh deploy -e production --pull
# 切换到开发环境
./deploy.sh restart -e development
🔄 服务管理
启动服务
# 启动所有服务
./deploy.sh start
# 启动特定服务
./deploy.sh start mysql
./deploy.sh start backend frontend
# 强制重新创建容器
./deploy.sh start --force
停止服务
# 停止所有服务
./deploy.sh stop
# 停止特定服务
./deploy.sh stop backend
# 设置停止超时时间
./deploy.sh stop -t 60
重启服务
# 重启所有服务
./deploy.sh restart
# 重启特定服务
./deploy.sh restart backend
服务状态
# 查看详细状态
./deploy.sh status
# 查看容器列表
./deploy.sh ps
# 查看网络和卷信息
docker network ls | grep anxin
docker volume ls | grep anxin
📊 监控和日志
日志查看
# 查看所有服务日志
./deploy.sh logs
# 查看特定服务日志
./deploy.sh logs backend
# 实时跟踪日志
./deploy.sh logs -f
# 查看最近100行日志
./deploy.sh logs --tail 100
# 查看最近1小时日志
./deploy.sh logs --since 1h
健康监控
# 执行健康检查
./deploy.sh health
# 持续监控（等待所有服务健康）
./deploy.sh health --wait --retry 20 --interval 30
# 查看服务详细信息
docker inspect anxin-backend-development
性能监控
# 查看容器资源使用
docker stats
# 查看特定容器资源使用
docker stats anxin-backend-development
# 查看系统资源
free -h
df -h
🔧 故障排除
常见问题诊断
1. 服务启动失败
症状：容器无法启动或立即退出
诊断步骤：
# 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. 数据库连接失败
症状：后端无法连接数据库
诊断步骤：
# 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
解决方案：
# 重启数据库服务
./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调用失败
诊断步骤：
# 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
解决方案：
# 重启前端服务
./deploy.sh restart frontend
# 检查API代理配置
# 编辑 configs/nginx.conf.development
# 确保 proxy_pass 指向正确的后端服务
4. 镜像构建失败
症状：Docker镜像构建过程中出错
诊断步骤：
# 1. 查看构建日志
./build.sh build-all --verbose
# 2. 检查Dockerfile语法
docker run --rm -i hadolint/hadolint < frontend/Dockerfile
# 3. 手动构建测试
cd frontend
docker build -t test-frontend .
解决方案：
# 清理构建缓存
./build.sh clean
# 强制重新构建
./build.sh build-all --no-cache
# 检查网络连接
ping registry-1.docker.io
5. 性能问题
症状：服务响应缓慢或资源使用过高
诊断步骤：
# 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
解决方案：
# 调整资源限制
# 编辑 environments/.env.development
BACKEND_MEMORY_LIMIT=2048
DATABASE_MEMORY_LIMIT=1024
# 重启服务应用新配置
./deploy.sh restart
日志分析
关键日志位置
# 容器日志
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 | 调试信息 | 开发环境调试 |
数据备份与恢复
数据备份
# 使用内置备份脚本
./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
数据恢复
# 恢复数据库
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 /
网络问题排查
检查网络配置
# 查看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
解决网络问题
# 重新创建网络
./deploy.sh down
./deploy.sh start
# 检查防火墙设置
sudo ufw status
sudo iptables -L
🚀 性能优化
容器资源优化
内存优化
# 调整JVM内存设置
JAVA_OPTS=-Xms512m -Xmx1024m -XX:+UseG1GC
# 调整MySQL内存设置
# 编辑 configs/my.cnf.production
innodb_buffer_pool_size = 256M
key_buffer_size = 64M
CPU优化
# 设置CPU限制
# 在 docker-compose.yml 中
deploy:
resources:
limits:
cpus: '1.0'
memory: 1024M
镜像优化
减小镜像大小
# 使用多阶段构建
# 使用Alpine Linux基础镜像
# 清理不必要的文件和缓存
# 查看镜像大小
docker images | grep anxin
构建缓存优化
# 合理安排Dockerfile层级
# 将变化频率低的操作放在前面
# 使用.dockerignore排除不必要文件
数据库优化
MySQL配置优化
# 编辑 configs/my.cnf.production
[mysqld]
innodb_buffer_pool_size = 512M
innodb_log_file_size = 128M
max_connections = 200
query_cache_size = 64M
索引优化
-- 分析慢查询
SHOW PROCESSLIST;
SHOW FULL PROCESSLIST;
-- 查看索引使用情况
EXPLAIN SELECT * FROM your_table WHERE condition;
🔒 安全配置
容器安全
用户权限
# 使用非root用户运行容器
# 在Dockerfile中添加
RUN addgroup -g 1001 appuser && adduser -u 1001 -G appuser -s /bin/sh -D appuser
USER appuser
网络安全
# 限制容器网络访问
# 使用自定义网络
# 关闭不必要的端口映射
数据安全
密码管理
# 使用强密码
# 定期更换密码
# 使用Docker secrets管理敏感信息
# 创建密码文件
echo "your_secure_password" | docker secret create db_password -
数据加密
# 启用MySQL SSL
# 配置应用程序使用SSL连接
# 加密敏感数据字段
访问控制
防火墙配置
# 配置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
反向代理
# 使用Nginx作为反向代理
# 配置SSL终止
# 实现负载均衡
❓ 常见问题
Q1: 如何更新应用版本？
A:
# 1. 拉取最新代码
./build.sh pull
# 2. 重新构建镜像
./build.sh build-all --no-cache
# 3. 重启服务
./deploy.sh restart
Q2: 如何扩展服务实例？
A:
# 编辑 docker-compose.yml
services:
anxin-backend:
deploy:
replicas: 3
# 重新部署
./deploy.sh restart
Q3: 如何迁移到其他服务器？
A:
# 1. 备份数据
./scripts/backup.sh
# 2. 复制项目文件和备份到新服务器
rsync -av . user@newserver:/path/to/project
# 3. 在新服务器上恢复
./deploy.sh start
# 恢复数据库备份
Q4: 如何配置SSL证书？
A:
# 1. 获取SSL证书
# 2. 修改Nginx配置
# 3. 更新docker-compose.yml端口映射
# 4. 重启前端服务
Q5: 如何监控服务健康状态？
A:
# 使用内置健康检查
./deploy.sh health --wait
# 集成外部监控工具
# - Prometheus + Grafana
# - ELK Stack
# - Zabbix
Q6: 如何处理数据库迁移？
A:
# 1. 备份当前数据
./scripts/backup.sh
# 2. 停止服务
./deploy.sh stop
# 3. 更新数据库脚本
# 4. 重启服务（自动执行迁移）
./deploy.sh start
📞 技术支持
如果遇到问题，请按以下步骤获取帮助：
- 查看日志：
./deploy.sh logs -f - 检查状态：
./deploy.sh health - 查阅文档：参考本文档故障排除部分
- 收集信息：准备错误日志、配置文件、系统信息
- 寻求帮助：联系技术支持团队
信息收集脚本
#!/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')
维护团队: 若依框架开发团队