3步极速部署：Earthworm容器化开发环境搭建指南

问题诊断：环境依赖冲突与容器化解决方案

在本地开发Earthworm项目时，开发者常面临三大痛点：PostgreSQL版本不兼容导致数据结构异常、Redis配置繁琐引发缓存服务不稳定、Logto认证系统部署复杂延长环境准备时间。容器化技术（Containerization）通过隔离应用运行环境，可将传统2小时的环境配置过程压缩至10分钟内完成。

环境兼容性矩阵

操作系统	Docker支持度	资源占用差异	特殊配置
Linux	★★★★★	内存占用低15%	需配置Docker用户组
macOS	★★★★☆	磁盘IO性能下降约8%	需开启Rosetta转译（Apple Silicon）
Windows	★★★☆☆	网络延迟增加约12%	需启用WSL2后端

环境预检清单

执行以下命令验证系统依赖（预计耗时3分钟）：

# 检查Docker版本（需24.0.0+）
docker --version && docker compose version

# 验证Node.js环境（需v20+）
node --version && pnpm -v

[!TIP] 若提示docker: command not found，需先安装Docker Desktop。Linux用户需执行sudo usermod -aG docker $USER配置权限，避免每次使用sudo。

方案设计：多容器服务编排架构

Earthworm采用容器编排（Container Orchestration）技术，通过docker-compose.yml定义4个核心服务，实现一键启动完整开发环境。

核心服务配置表

服务名称	镜像版本	功能描述	端口映射	数据卷
db	postgres:14-alpine	主数据库服务	5433:5432	.volumes/postgres
redis	redis:5-alpine	缓存服务	6379:6379	.volumes/redis
logto	svhd/logto:1.18.0	认证服务	3010:3010	.volumes/logto
logtoPostgres	postgres:14-alpine	Logto专用数据库	内部服务	.volumes/logto-postgres

服务启动流程图

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  db服务     │────▶│  redis服务  │────▶│  logto数据库 │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                                │
                                                ▼
                                          ┌─────────────┐
                                          │  logto服务  │
                                          └─────────────┘

实施验证：从环境配置到服务验证

1. 代码仓库准备（预计耗时2分钟）

git clone https://gitcode.com/GitHub_Trending/ea/earthworm
cd earthworm

验证点：执行ls -la应看到docker-compose.yml和package.json文件。

2. 环境变量配置（预计耗时3分钟）

# 复制环境变量模板
cp ./apps/api/.env.example ./apps/api/.env
cp ./apps/client/.env.example ./apps/client/.env

# 编辑关键配置（使用nano或vim）
nano ./apps/api/.env

关键配置项及风险提示：

• DATABASE_URL=postgresql://postgres:password@localhost:5433/earthworm
  ⚠️ 风险提示：生产环境需使用强密码并限制数据库访问IP

• LOGTO_ENDPOINT=http://localhost:3010
  ⚠️ 风险提示：确保与docker-compose中logto服务端口一致

[!TIP] .env文件权限建议设置为chmod 600 .env，防止敏感信息泄露。

3. 容器集群启动（预计耗时5分钟）

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

# 启动所有服务
pnpm docker:start

验证点：执行docker compose ps应看到4个服务均为Up状态。

4. 数据库初始化（预计耗时4分钟）

# 创建数据表结构
pnpm db:init

# 导入课程数据
pnpm db:upload

验证点：执行docker exec -it earthworm_db_1 psql -U postgres earthworm -c "SELECT COUNT(*) FROM courses;"应返回课程数量。

5. 开发服务启动（预计耗时2分钟）

# 并行启动前后端服务
pnpm dev:serve &
pnpm dev:client

验证点：访问http://localhost:3001应看到Earthworm登录界面。

服务验证与资源监控

应用界面验证

成功部署后，前端应用首页应显示课程学习界面，包含课程选择和学习进度统计功能。

登录成功后进入个人学习中心，显示最近使用的课程包和学习日历：

资源占用监控

启动后建议监控系统资源使用情况（使用htop或Docker Desktop资源面板）：

• 正常运行时总内存占用约4GB
• 数据库初始化阶段CPU使用率可能短暂达到80%
• idle状态下容器网络流量应低于10KB/s

故障排除速查表

问题现象	可能原因	解决方案
数据库连接超时	PostgreSQL服务未启动	执行docker compose restart db重启服务
Logto登录失败	初始化数据未正确导入	检查.volumes/logto-postgres目录是否有数据文件
前端报500错误	API服务未启动	执行pnpm dev:serve单独启动后端服务
容器启动后立即退出	端口冲突	使用lsof -i :5433检查占用进程并关闭

部署时间优化建议

1. 预拉取镜像：提前执行docker pull postgres:14-alpine redis:5-alpine svhd/logto:1.18.0节省启动时间
2. 后台初始化：数据库初始化可与前端依赖安装并行执行
3. 资源分配：Docker Desktop建议分配至少4GB内存（Preferences > Resources > Memory）

通过以上步骤，开发者可在15分钟内完成Earthworm完整开发环境的部署，专注于功能开发而非环境配置。容器化方案确保了开发、测试与生产环境的一致性，显著降低"在我电脑上能运行"的问题发生率。