308 lines
7.0 KiB
Markdown
308 lines
7.0 KiB
Markdown
# Docker Compose 文件清理总结
|
||
|
||
## ✅ 清理完成
|
||
|
||
已成功将多个 docker-compose 文件整合为单一配置文件，使用 Docker Compose profiles 功能实现不同运行模式。
|
||
|
||
---
|
||
|
||
## 📦 清理前后对比
|
||
|
||
### 清理前（3个文件）
|
||
|
||
```
|
||
ocdp-go/
|
||
├── docker-compose.yml # 生产模式基础配置
|
||
├── docker-compose.dev.yml # 开发模式覆盖配置
|
||
└── docker-compose.mock.yml # Mock 测试模式配置
|
||
```
|
||
|
||
**问题**：
|
||
- ❌ 配置分散在多个文件
|
||
- ❌ 需要使用 `-f` 参数组合文件
|
||
- ❌ 维护困难，容易出现配置不一致
|
||
- ❌ 命令复杂：`docker compose -f docker-compose.yml -f docker-compose.dev.yml up`
|
||
|
||
### 清理后（1个文件）
|
||
|
||
```
|
||
ocdp-go/
|
||
└── docker-compose.yml # 统一配置（使用 profiles）
|
||
```
|
||
|
||
**优势**：
|
||
- ✅ 所有配置集中在一个文件
|
||
- ✅ 使用 Docker Compose profiles 特性
|
||
- ✅ 易于维护和理解
|
||
- ✅ 命令简洁：`docker compose --profile dev up`
|
||
|
||
---
|
||
|
||
## 🔧 技术实现
|
||
|
||
### Profiles 机制
|
||
|
||
使用 Docker Compose 的 `profiles` 功能，定义了三种运行模式：
|
||
|
||
| Profile | 服务 | 说明 |
|
||
|---------|------|------|
|
||
| `production` | postgres, redis, backend-prod, frontend-prod | 生产环境，真实数据库 |
|
||
| `dev` | backend-dev, frontend-dev | 开发环境，Mock 数据，热重载 |
|
||
| `mock` | backend-mock, frontend-mock | 独立测试，无外部依赖 |
|
||
| `tools` | pgadmin, swagger-ui | 可选管理工具 |
|
||
|
||
### 服务命名
|
||
|
||
为了避免冲突，不同模式下的服务使用不同名称：
|
||
|
||
- **生产模式**：`backend-prod`, `frontend-prod`
|
||
- **开发模式**：`backend-dev`, `frontend-dev`
|
||
- **Mock 模式**：`backend-mock`, `frontend-mock`
|
||
|
||
---
|
||
|
||
## 🚀 使用方式
|
||
|
||
### 旧方式（已弃用）
|
||
|
||
```bash
|
||
# 开发模式
|
||
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
|
||
|
||
# 生产模式
|
||
docker compose -f docker-compose.yml up
|
||
|
||
# Mock 模式
|
||
docker compose -f docker-compose.mock.yml up backend
|
||
```
|
||
|
||
### 新方式（推荐）
|
||
|
||
```bash
|
||
# 开发模式
|
||
docker compose --profile dev up
|
||
# 或
|
||
make docker-dev
|
||
|
||
# 生产模式
|
||
docker compose --profile production up
|
||
# 或
|
||
make docker-prod
|
||
|
||
# Mock 测试后端
|
||
docker compose --profile mock up backend-mock
|
||
# 或
|
||
make docker-test-backend
|
||
|
||
# Mock 测试前端
|
||
docker compose --profile mock up frontend-mock
|
||
# 或
|
||
make docker-test-frontend
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 改进效果
|
||
|
||
### 文件数量
|
||
|
||
| 项目 | 清理前 | 清理后 | 改进 |
|
||
|------|--------|--------|------|
|
||
| Docker Compose 文件 | 3 | 1 | ⬇️ 66% |
|
||
| 配置行数 | ~400 | ~260 | ⬇️ 35% |
|
||
| 维护复杂度 | 高 | 低 | ⬇️ 显著降低 |
|
||
|
||
### 命令简化
|
||
|
||
| 操作 | 清理前 | 清理后 |
|
||
|------|--------|--------|
|
||
| 启动开发环境 | `docker compose -f docker-compose.yml -f docker-compose.dev.yml up` | `docker compose --profile dev up` |
|
||
| 启动生产环境 | `docker compose -f docker-compose.yml up` | `docker compose --profile production up` |
|
||
| 测试后端 | `docker compose -f docker-compose.mock.yml up backend` | `docker compose --profile mock up backend-mock` |
|
||
|
||
---
|
||
|
||
## 📝 配置文件结构
|
||
|
||
新的 `docker-compose.yml` 结构：
|
||
|
||
```yaml
|
||
services:
|
||
# 数据库服务（生产模式）
|
||
postgres:
|
||
profiles: [production]
|
||
|
||
redis:
|
||
profiles: [production]
|
||
|
||
# 后端服务（三种模式）
|
||
backend-prod:
|
||
profiles: [production]
|
||
|
||
backend-dev:
|
||
profiles: [dev]
|
||
|
||
backend-mock:
|
||
profiles: [mock]
|
||
|
||
# 前端服务（三种模式）
|
||
frontend-prod:
|
||
profiles: [production]
|
||
|
||
frontend-dev:
|
||
profiles: [dev]
|
||
|
||
frontend-mock:
|
||
profiles: [mock]
|
||
|
||
# 可选工具
|
||
pgadmin:
|
||
profiles: [tools]
|
||
|
||
swagger-ui:
|
||
profiles: [tools]
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 迁移指南
|
||
|
||
### 如果您有自定义配置
|
||
|
||
如果您之前有自定义的 docker-compose 配置：
|
||
|
||
1. **备份旧文件**（如果需要）
|
||
2. **更新环境变量**到新的 `docker-compose.yml`
|
||
3. **测试每个模式**确保工作正常
|
||
4. **更新 CI/CD** 脚本使用新的命令
|
||
|
||
### Make 命令保持不变
|
||
|
||
所有 Makefile 命令保持不变，无需修改工作流程：
|
||
|
||
```bash
|
||
make docker-dev # 仍然有效
|
||
make docker-prod # 仍然有效
|
||
make docker-test-backend # 仍然有效
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 更新的文档
|
||
|
||
已更新以下文档以反映新的配置：
|
||
|
||
- ✅ `README.md` - 更新项目结构说明
|
||
- ✅ `USAGE_GUIDE.md` - 新增统一配置使用指南
|
||
- ✅ `Makefile` - 更新 Docker 命令使用 profiles
|
||
- ✅ `CLEANUP_SUMMARY.md` - 本文档
|
||
|
||
### 推荐阅读顺序
|
||
|
||
1. 📖 [README.md](./README.md) - 项目概述
|
||
2. 📋 [USAGE_GUIDE.md](./USAGE_GUIDE.md) - 统一配置详细说明 ⭐
|
||
3. 🚀 [QUICK_START.md](./QUICK_START.md) - 快速开始
|
||
4. 💡 [COMMANDS_CHEATSHEET.md](./COMMANDS_CHEATSHEET.md) - 命令速查
|
||
|
||
---
|
||
|
||
## ✨ 优势总结
|
||
|
||
### 对开发者
|
||
|
||
- ✅ **更简单**：只需记住一个文件
|
||
- ✅ **更清晰**：所有服务定义集中
|
||
- ✅ **更灵活**：轻松切换不同模式
|
||
- ✅ **更快速**：命令更短，输入更少
|
||
|
||
### 对运维
|
||
|
||
- ✅ **易维护**：单一配置来源
|
||
- ✅ **易理解**：profiles 语义清晰
|
||
- ✅ **易扩展**：添加新模式很简单
|
||
- ✅ **易调试**：配置集中便于排查问题
|
||
|
||
### 对项目
|
||
|
||
- ✅ **更规范**：使用 Docker Compose 标准特性
|
||
- ✅ **更现代**：符合最佳实践
|
||
- ✅ **更专业**：配置简洁清晰
|
||
- ✅ **更可靠**：减少配置错误的可能
|
||
|
||
---
|
||
|
||
## 🎓 Docker Compose Profiles 说明
|
||
|
||
Docker Compose profiles 是 Docker Compose 1.28+ 引入的特性，用于：
|
||
|
||
1. **条件性服务启动**：只启动特定 profile 的服务
|
||
2. **环境隔离**：不同环境使用不同 profiles
|
||
3. **配置复用**：共享基础配置，profile 区分差异
|
||
|
||
### 基本用法
|
||
|
||
```bash
|
||
# 启动特定 profile
|
||
docker compose --profile dev up
|
||
|
||
# 启动多个 profiles
|
||
docker compose --profile production --profile tools up
|
||
|
||
# 查看所有 profiles
|
||
docker compose config --profiles
|
||
|
||
# 查看特定 profile 的配置
|
||
docker compose --profile dev config
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 回滚方案
|
||
|
||
如果需要回滚到旧的多文件方式（不推荐）：
|
||
|
||
```bash
|
||
# 1. 恢复旧的配置文件（从 git 历史）
|
||
git log --all --full-history -- docker-compose.*.yml
|
||
git checkout <commit-hash> -- docker-compose.dev.yml
|
||
git checkout <commit-hash> -- docker-compose.mock.yml
|
||
|
||
# 2. 恢复旧的 Makefile 命令
|
||
git checkout <commit-hash> -- Makefile
|
||
```
|
||
|
||
但我们**强烈建议使用新的单文件方式**，它更符合现代 Docker Compose 最佳实践。
|
||
|
||
---
|
||
|
||
## 📞 需要帮助？
|
||
|
||
如果遇到问题：
|
||
|
||
1. 查看 [USAGE_GUIDE.md](./USAGE_GUIDE.md) 详细说明
|
||
2. 查看 [COMMANDS_CHEATSHEET.md](./COMMANDS_CHEATSHEET.md) 命令参考
|
||
3. 提交 [GitHub Issue](https://github.com/your-repo/issues)
|
||
|
||
---
|
||
|
||
## 🎉 总结
|
||
|
||
通过将 3 个 docker-compose 文件整合为 1 个：
|
||
|
||
- ✅ **简化了项目结构**
|
||
- ✅ **降低了维护成本**
|
||
- ✅ **提升了配置清晰度**
|
||
- ✅ **保持了所有功能**
|
||
- ✅ **兼容了现有工作流**
|
||
|
||
**配置更少，效率更高！** 🚀
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
<sub>清理完成于 2025-11-09</sub>
|
||
<br/>
|
||
<sub>单一配置文件，多种运行模式</sub>
|
||
</div>
|
||
|