项目概述
本文档详细说明如何使用Docker Compose部署和管理Next.js应用。项目使用MySQL 8.0作为数据库,Next.js 15作为应用框架,通过Docker Compose实现容器化部署。
一、Docker Compose配置文件详解
1. docker-compose.yml(开发/测试环境)
主要配置文件包含以下服务:
MySQL服务配置:
- 镜像:mysql:8.0
- 端口映射:3306(可通过环境变量配置)
- 数据持久化:使用命名卷mysql-data
- 字符集:utf8mb4(支持emoji和完整Unicode)
- 健康检查:确保数据库就绪后再启动应用
- 优化配置:max_connections=100, innodb_buffer_pool_size=640M
应用服务配置:
- 构建:使用项目根目录的Dockerfile
- 端口:3000(可通过环境变量配置)
- 环境变量:从.env文件读取
- 依赖:等待MySQL健康检查通过
- 健康检查:检查/api/health端点
网络配置:
- 使用自定义bridge网络space-helper-network
- 支持容器名解析(服务发现)
- 容器间可通过服务名直接通信
数据卷配置:
- mysql-data:MySQL数据持久化
- 即使容器删除,数据也不会丢失
2. docker-compose.prod.yml(生产环境)
生产环境配置特点:
- 不暴露MySQL端口到宿主机(仅容器间访问)
- 添加资源限制(CPU、内存)
- 配置日志轮转
- 更严格的健康检查
- 更高的MySQL性能配置(max_connections=200, innodb_buffer_pool_size=1G)
二、环境变量配置
必需环境变量
| 变量名 | 说明 | 示例 |
|---|---|---|
| MYSQL_ROOT_PASSWORD | MySQL root用户密码 | SecureRootPass123! |
| MYSQL_DATABASE | 应用数据库名 | space_helper |
| MYSQL_USER | 应用数据库用户 | spaceuser |
| MYSQL_PASSWORD | 应用数据库密码 | SecureUserPass123! |
| NEXTAUTH_URL | NextAuth回调URL | http://localhost:3000 |
| NEXTAUTH_SECRET | NextAuth加密密钥 | 使用openssl rand -base64 32生成 |
可选环境变量
- APP_PORT:应用端口(默认3000)
- MYSQL_PORT:MySQL端口(默认3306)
- GITHUB_CLIENT_ID/SECRET:GitHub OAuth配置
- GITLAB_CLIENT_ID/SECRET:GitLab OAuth配置
- OPENAI_BASE_URL/API_KEY:OpenAI API配置
生成NEXTAUTH_SECRET
# Linux/macOS
openssl rand -base64 32
# Windows PowerShell
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })
三、快速开始
1. 创建环境变量文件
在项目根目录创建.env文件,配置所有必需的环境变量。
2. 启动所有服务
# 构建镜像并启动所有服务(后台运行)
docker-compose up -d
# 查看服务状态
docker-compose ps
# 查看日志
docker-compose logs -f
3. 验证服务运行
- 检查容器状态:docker-compose ps
- 测试应用访问:http://localhost:3000
- 测试数据库连接:docker-compose exec app sh
4. 初始化数据库
docker-compose exec app npm run init-db
四、常用操作命令
服务管理
- 启动:docker-compose up -d
- 停止:docker-compose stop
- 重启:docker-compose restart
- 删除:docker-compose down
- 查看状态:docker-compose ps
构建和更新
- 构建镜像:docker-compose build
- 重新构建并启动:docker-compose up -d --build
- 强制重新构建:docker-compose build --no-cache
查看日志
- 查看所有日志:docker-compose logs -f
- 查看指定服务:docker-compose logs -f app
- 查看最近100行:docker-compose logs --tail=100
执行命令
- 进入容器:docker-compose exec app sh
- 执行一次性命令:docker-compose exec app npm run init-db
五、服务管理
MySQL服务管理
连接MySQL:
docker-compose exec mysql mysql -u root -p
备份数据库:
docker-compose exec mysql mysqldump -u root -p${MYSQL_ROOT_PASSWORD} space_helper > backup_$(date +%Y%m%d_%H%M%S).sql
恢复数据库:
docker-compose exec -T mysql mysql -u root -p${MYSQL_ROOT_PASSWORD} space_helper < backup.sql
应用服务管理
- 查看日志:docker-compose logs -f app
- 重启应用:docker-compose restart app
- 进入容器:docker-compose exec app sh
六、数据持久化
数据卷说明
Docker Compose使用命名卷来持久化数据:
- mysql-data:MySQL数据文件
- redis-data(如果启用):Redis数据文件
备份数据卷
docker run --rm \
-v space-helper-mysql-data:/source:ro \
-v $(pwd):/backup \
alpine tar czf /backup/mysql-data-$(date +%Y%m%d).tar.gz -C /source .
恢复数据卷
# 停止服务
docker-compose down
# 恢复数据卷
docker run --rm \
-v space-helper-mysql-data:/target \
-v $(pwd):/backup \
alpine tar xzf /backup/mysql-data-20240101.tar.gz -C /target
# 启动服务
docker-compose up -d
七、网络配置
网络架构
所有服务通过自定义bridge网络space-helper-network连接,支持容器名解析和容器间安全通信。
容器间通信
容器可以通过服务名直接通信:
- 在应用容器中访问MySQL:mysql://mysql:3306/space_helper
- 在应用代码中:const dbUrl =
mysql://${user}:${pass}@mysql:3306/${db}
网络隔离
生产环境建议使用网络隔离,将前端和后端服务分离到不同网络。
八、健康检查
MySQL健康检查
- interval:每10秒检查一次
- timeout:超时时间5秒
- retries:失败重试5次
- start_period:启动后30秒内不判定为失败
应用健康检查
- 检查端点:/api/health
- interval:每30秒检查一次
- timeout:超时时间10秒
- retries:失败重试3次
九、故障排查
常见问题
问题1:容器无法启动
- 查看日志:docker-compose logs app
- 检查环境变量:docker-compose config
- 检查端口占用:netstat -an | grep 3000
问题2:数据库连接失败
- 检查MySQL是否运行:docker-compose ps mysql
- 检查MySQL日志:docker-compose logs mysql
- 测试数据库连接:docker-compose exec app sh
- 检查环境变量:docker-compose exec app env | grep DATA_SOURCE_URL
- 检查网络连接:docker-compose exec app ping mysql
问题3:端口冲突
- 修改.env文件中的端口配置
- 或停止占用端口的服务
问题4:数据丢失
- 使用数据卷备份恢复
- 或从数据库备份恢复
调试技巧
- 进入容器调试:docker-compose exec app sh
- 查看详细日志:docker-compose logs --tail=100 -f
- 检查配置:docker-compose config
十、生产环境部署
使用生产配置
docker-compose -f docker-compose.prod.yml up -d
生产环境检查清单
- 修改所有默认密码
- 使用强密码(至少16位)
- 配置HTTPS(使用Nginx反向代理)
- 不暴露MySQL端口到宿主机
- 配置资源限制(CPU、内存)
- 配置日志轮转
- 设置自动备份
- 配置监控和告警
- 使用环境变量文件(.env.production)
- 定期更新镜像和依赖
安全加固
- 使用非root用户运行容器
- 限制网络访问(不暴露数据库端口)
- 使用密钥管理(Docker Secrets或外部密钥管理服务)
监控和日志
- 配置日志驱动:json-file,max-size: 10m,max-file: 3
- 集成监控工具:Prometheus + Grafana、ELK Stack、Sentry
十一、安全最佳实践
密码安全
- 使用强密码(至少16位)
- 定期更换密码
- 不在代码中硬编码密码
- 使用环境变量或密钥管理服务
网络安全
- 使用自定义网络隔离服务
- 不暴露数据库端口到公网
- 使用防火墙规则限制访问
- 配置HTTPS/TLS
镜像安全
- 使用官方基础镜像
- 定期更新镜像和依赖
- 扫描镜像漏洞:docker scan space-helper:latest
- 使用最小化镜像(Alpine)
数据安全
- 定期备份数据
- 加密敏感数据
- 使用数据卷权限控制
- 配置数据保留策略
十二、性能优化
MySQL优化
- 调整配置参数:innodb_buffer_pool_size=1G, max_connections=200
- 使用连接池:连接池大小50,队列限制100,空闲超时60秒
应用优化
- 启用Next.js缓存:NODE_ENV=production, NEXT_TELEMETRY_DISABLED=1
- 配置资源限制:CPU 2核,内存2G
网络优化
- 使用host网络模式(高性能场景,但会失去容器网络隔离)
存储优化
- 使用SSD存储
- 配置数据卷优化
总结
本文档详细介绍了Docker Compose的配置和使用方法,包括:
- 完整的docker-compose.yml配置文件
- 生产环境配置文件docker-compose.prod.yml
- 详细的环境变量配置说明
- 快速开始指南
- 常用操作命令
- 服务管理方法
- 数据持久化方案
- 网络配置和容器间通信
- 健康检查配置
- 故障排查指南
- 生产环境部署最佳实践
- 安全最佳实践
- 性能优化建议
通过遵循本指南,可以快速部署space-helper应用,管理多容器服务,配置数据持久化,实现服务间通信,进行故障排查,并安全地部署到生产环境。