5步实现Earthworm开发环境零配置部署：Docker容器化解决方案

环境部署痛点分析

作为开发者，我们都经历过环境配置的"马拉松"——PostgreSQL版本冲突导致数据导入失败，Redis配置参数不匹配引发缓存异常，Logto认证服务部署需要手动配置多个依赖。这些问题往往耗费数小时甚至一整天，最终却只是重复别人踩过的坑。更糟的是，"在我电脑上能运行"成为团队协作的最大障碍。Earthworm项目通过容器化方案将这一过程压缩到10分钟内，让开发者专注于功能实现而非环境调试。

容器化解决方案的3大核心优势

1. 环境一致性保障

容器化技术（将应用及其依赖打包成标准化单元）确保了开发、测试和生产环境的一致性，彻底消除"环境差异"导致的问题。Earthworm的Docker配置文件经过严格测试，可在任何支持Docker的系统上稳定运行。

2. 服务隔离与快速启停

采用多容器架构设计，将数据库、缓存、认证服务等组件完全隔离，避免服务间的端口冲突和依赖干扰。通过简单命令即可启动或停止整个服务集群，比传统部署方式节省80%的操作时间。

3. 简化配置管理

所有服务参数通过环境变量和配置文件集中管理，无需手动修改系统级配置。预置的初始化脚本和数据让新开发者无需了解复杂的服务配置细节，即可快速上手开发。

1/3 环境准备：极简依赖清单

必备工具检查

确保系统已安装以下工具（建议版本）：

• Docker 24.0.0+（容器化运行环境）
• Node.js v20+（JavaScript运行时）
• pnpm 8+（包管理工具）

验证命令：

docker --version  # 输出Docker版本
node --version    # 输出Node.js版本
pnpm -v           # 输出pnpm版本

硬件配置建议

• 内存：≥8GB（Docker容器同时运行时需约4GB内存）
• 磁盘空间：预留10GB以上（含镜像、数据库文件及项目依赖）
• CPU：双核以上处理器（推荐4核以获得流畅体验）

2/3 模块化实施流程

模块1：代码获取与依赖安装

git clone https://gitcode.com/GitHub_Trending/ea/earthworm
cd earthworm
corepack enable  # 确保pnpm可用
pnpm install      # 安装所有工作区依赖

模块2：环境变量配置

# 后端环境配置
cp ./apps/api/.env.example ./apps/api/.env

# 前端环境配置
cp ./apps/client/.env.example ./apps/client/.env

关键配置项（apps/api/.env）：

DATABASE_URL=postgresql://postgres:password@localhost:5433/earthworm
REDIS_URL=redis://localhost:6379
LOGTO_ENDPOINT=http://localhost:3010

模块3：Docker服务集群启动

# 初始化Logto认证数据
unzip logto_db_init_data.zip -d .volumes/

# 启动所有依赖服务
pnpm docker:start

⚠️ 风险提示：首次启动可能需要下载约1GB的Docker镜像，请确保网络通畅

服务启动后可通过docker compose ps验证状态，正常运行时所有服务状态应为"Up"。

模块4：数据库初始化

pnpm db:init       # 创建数据表结构
pnpm db:upload     # 导入初始课程数据

模块5：开发服务器启动

# 并行启动前后端开发服务
pnpm dev:serve &   # 后端API服务（http://localhost:3000）
pnpm dev:client    # 前端Nuxt服务（http://localhost:3011）

3/3 环境验证与性能优化

环境验证清单

验证项	操作方法	预期结果
前端访问	浏览器打开http://localhost:3011	显示Earthworm主界面
API连接	curl http://localhost:3000/api/health	返回{"status":"ok"}
数据库连接	psql -h localhost -p 5433 -U postgres earthworm	成功连接数据库
课程数据	SELECT COUNT(*) FROM courses;	返回导入的课程数量

Earthworm应用主界面 - 环境部署成功后可看到此界面

环境性能优化建议

1. Docker资源分配：在Docker Desktop设置中分配至少2GB内存给Docker引擎，避免因资源不足导致服务崩溃
2. 数据库性能：开发环境可启用PostgreSQL连接池，修改docker-compose.yml中db服务的max_connections参数
3. 前端构建优化：执行pnpm dev:client -- --open启用热重载，开发时仅编译修改的模块
4. 缓存策略：本地开发时可将npm依赖缓存到Docker卷中，减少重复下载

故障排除决策树

当环境出现问题时，按以下流程诊断：

1. 服务未启动？

   • 检查Docker服务状态：docker compose ps
   • 查看服务日志：docker logs [服务名]

2. 数据库连接失败？

   • 确认.env文件中的DATABASE_URL配置
   • 检查PostgreSQL容器是否正常运行

3. 前端无法访问API？

   • 验证后端服务是否启动：curl http://localhost:3000/api/health
   • 检查跨域配置是否正确

4. Logto认证失败？

   • 确认Logto服务端口是否被占用
   • 检查初始化数据是否正确导入

开发环境管理命令速查表

命令	功能描述
pnpm docker:start	启动所有Docker服务
pnpm docker:stop	停止所有Docker服务
pnpm docker:delete	删除容器（保留数据）
pnpm docker:down	完全清理（含数据卷）
pnpm db:migrate	执行数据库迁移
pnpm dev:serve	启动后端开发服务
pnpm dev:client	启动前端开发服务

重要提示：开发完成后建议使用pnpm docker:stop停止服务，而非直接关闭Docker，以确保数据正常保存

通过这套容器化方案，我们成功将Earthworm开发环境的搭建时间从2小时缩短到10分钟，同时保证了环境的一致性和稳定性。无论是团队协作还是个人开发，都能从中受益。现在，你可以专注于功能开发，而不必再为环境配置浪费宝贵的开发时间。