10分钟搭建Earthworm开发环境：Docker全流程自动化部署指南
项目地址: https://gitcode.com/GitHub_Trending/ea/earthworm 开发环境痛点与解决方案
本地开发时是否遇到过这些问题：PostgreSQL版本冲突、Redis配置繁琐、Logto认证服务部署复杂？Earthworm通过Docker容器化方案将开发环境搭建时间从2小时压缩到10分钟，实现"一键启动全栈开发环境"。本文将详解基于docker-compose.yml的容器化部署方案，即使是Docker新手也能顺利完成环境配置。
环境准备清单
开始前请确保已安装以下工具：
| 依赖项 | 版本要求 | 验证命令 |
|---|---|---|
| Docker | 24.0.0+ | docker --version |
| Node.js | v20+ | node --version |
| pnpm | 8+ | pnpm -v |
官方文档要求：README.md中详细列出了环境要求及版本兼容性说明
硬件配置建议
- 内存：至少8GB（Docker容器同时运行PostgreSQL、Redis、Logto时需占用约4GB内存）
- 磁盘空间：预留10GB以上（含镜像、数据库文件及项目依赖）
Docker容器架构解析
Earthworm采用多容器架构设计，通过docker-compose.yml定义5个核心服务：
核心服务说明：
| 服务名 | 镜像 | 用途 | 端口映射 |
|---|---|---|---|
| db | postgres:14-alpine | 主数据库 | 5433:5432 |
| redis | redis:5-alpine | 缓存服务 | 6379:6379 |
| logto | svhd/logto:1.18.0 | 认证系统 | 3010:3010 |
| logtoPostgres | postgres:14-alpine | Logto数据库 | 内部服务 |
分步实施指南
1. 克隆代码仓库
git clone https://gitcode.com/GitHub_Trending/ea/earthworm
cd earthworm
2. 安装项目依赖
corepack enable # 确保pnpm可用
pnpm install # 安装所有工作区依赖
3. 配置环境变量
复制环境变量模板文件并根据需要调整：
# 后端环境配置
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
4. 初始化Logto认证数据
解压预置的Logto数据库初始化数据：
unzip logto_db_init_data.zip -d .volumes/
初始管理员账户：admin/WkN7g5-i8ZrJckX，管理界面：http://localhost:3011
5. 启动Docker服务集群
# 启动所有依赖服务
pnpm docker:start
# 验证服务状态
docker compose ps
成功启动后状态示例：
NAME IMAGE COMMAND STATUS PORTS
earthworm_db_1 postgres:14-alpine "docker-entrypoint.s…" Up 5 minutes 0.0.0.0:5433->5432/tcp
earthworm_redis_1 redis:5-alpine "docker-entrypoint.s…" Up 5 minutes 0.0.0.0:6379->6379/tcp
earthworm_logto_1 svhd/logto:1.18.0 "sh -c 'npm run cli …" Up 5 minutes 0.0.0.0:3010->3010/tcp, 0.0.0.0:3011->3011/tcp
6. 初始化应用数据库
pnpm db:init # 创建数据表结构
pnpm db:upload # 导入初始课程数据
7. 启动开发服务器
# 并行启动前后端开发服务
pnpm dev:serve & # 后端API服务（http://localhost:3000）
pnpm dev:client # 前端Nuxt服务（http://localhost:3001）
验证开发环境
访问前端应用：http://localhost:3001，应能看到Earthworm主界面：
验证数据库连接：
# 连接主数据库
psql -h localhost -p 5433 -U postgres earthworm
# 查询课程数据
SELECT COUNT(*) FROM courses; # 应返回导入的课程数量
常见问题解决
Docker权限问题
Linux系统可能遇到权限错误：
permission denied while trying to connect to the Docker daemon socket
解决方案：
sudo usermod -aG docker $USER
newgrp docker # 无需重启生效
数据库连接失败
检查docker-compose.yml中数据库配置：
services:
db:
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: password
POSTGRES_DB: earthworm
确保与.env中的DATABASE_URL匹配。
Logto认证失败
确认Logto服务正常启动：
docker logs earthworm_logto_1 # 查看Logto服务日志
开发环境管理命令
| 命令 | 用途 |
|---|---|
| pnpm docker:start | 启动所有Docker服务 |
| pnpm docker:stop | 停止所有Docker服务 |
| pnpm docker:delete | 删除容器（保留数据） |
| pnpm docker:down | 完全清理（含数据卷） |
| pnpm db:migrate | 执行数据库迁移 |
总结与后续步骤
通过Docker Compose实现的容器化环境，解决了Earthworm开发过程中的"环境一致性"难题。下一步可参考：
- 贡献指南：packages/docs/contribution/
- 前端开发规范：README.md
- 测试流程：README.md#about-testing
提示：开发过程中遇到问题，可先查阅常见问题文档或提交issue反馈。
希望本指南能帮助你快速上手Earthworm开发，欢迎通过提交PR参与项目贡献！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
