Earthworm开发环境搭建指南：从环境痛点到容器化部署的完整解决方案

环境痛点分析

传统开发环境的挑战

在本地开发Earthworm项目时，开发者常常面临三大核心痛点：环境配置耗时、依赖冲突频发和多服务协同困难。传统方式下，仅PostgreSQL、Redis和Logto认证服务的配置就需要至少2小时，且容易出现版本不兼容问题。特别是Logto认证服务的部署，涉及复杂的数据库初始化和配置流程，对新手极不友好。

环境一致性难题

团队协作中，不同开发者的本地环境差异经常导致"在我电脑上能运行"的尴尬局面。数据库版本、环境变量配置和依赖库版本的细微差别，都可能造成功能异常或测试失败。这种环境不一致性严重影响开发效率和代码质量。

容器化方案优势

环境一致性保障

容器化方案通过Docker镜像确保所有开发者使用完全一致的环境配置，消除了"环境差异"导致的问题。Earthworm的Docker Compose配置将所有依赖服务打包为标准化容器，确保开发、测试和生产环境的一致性。

快速部署与资源隔离

采用容器化部署后，Earthworm的开发环境搭建时间从2小时压缩到10分钟，且所有服务运行在隔离的容器中，避免了对本地系统的污染。开发者可以随时创建或销毁完整的开发环境，而不会影响其他项目。

简化协作流程

新团队成员只需安装Docker和Git，即可通过简单命令快速搭建完整的开发环境，大幅降低了项目准入门槛。容器化也使得CI/CD流程更加顺畅，测试和部署效率显著提升。

架构设计

容器服务架构

Earthworm采用多容器微服务架构，通过Docker Compose协调五个核心服务：

graph TD
    A[前端服务\nNuxt.js] --> B[API服务\nNestJS]
    B --> C[主数据库\nPostgreSQL]
    B --> D[缓存服务\nRedis]
    B --> E[认证服务\nLogto]
    E --> F[Logto数据库\nPostgreSQL]

服务组件说明

服务名称	技术栈	主要功能	端口映射
前端服务	Nuxt.js	用户界面与交互	3001:3001
API服务	NestJS	业务逻辑处理	3000:3000
主数据库	PostgreSQL 14	存储应用数据	5433:5432
缓存服务	Redis 5	会话管理与缓存	6379:6379
Logto认证	Logto 1.18.0	用户认证与授权	3010:3010

分步实施

环境准备

必备工具安装

确保系统已安装以下工具，版本需满足最低要求：

工具	最低版本	验证命令	获取渠道
Docker	24.0.0+	docker --version	Docker官网
Node.js	v20+	node --version	Node.js官网
pnpm	8+	pnpm -v	npm install -g pnpm

🛠️ 操作步骤：

1. 执行命令检查版本：docker --version && node --version && pnpm -v
2. 预期结果：所有命令均输出版本号，且版本满足最低要求

项目获取与依赖安装

克隆代码仓库

🛠️ 操作目标：获取Earthworm项目源代码

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

✅ 预期结果：项目代码克隆到本地earthworm目录，当前工作目录切换为项目根目录

安装项目依赖

🛠️ 操作目标：安装所有项目依赖包

corepack enable  # 确保pnpm可用
pnpm install      # 安装工作区所有依赖

✅ 预期结果：终端显示依赖安装进度，最终输出"Done"或类似成功信息

环境配置

创建环境变量文件

🛠️ 操作目标：配置前后端环境变量

# 创建后端环境变量文件
cp ./apps/api/.env.example ./apps/api/.env

# 创建前端环境变量文件
cp ./apps/client/.env.example ./apps/client/.env

✅ 预期结果：在apps/api和apps/client目录下生成.env文件

关键配置项说明

打开apps/api/.env文件，确保以下关键配置正确：

# 数据库连接配置
DATABASE_URL=postgresql://postgres:password@localhost:5433/earthworm

# Redis缓存配置
REDIS_URL=redis://localhost:6379

# 认证服务配置
LOGTO_ENDPOINT=http://localhost:3010

⚠️ 注意事项：这些配置必须与docker-compose.yml中的服务配置保持一致，否则会导致服务连接失败

Docker服务启动

初始化Logto数据

🛠️ 操作目标：准备Logto认证服务的初始数据

unzip logto_db_init_data.zip -d .volumes/

✅ 预期结果：在.volumes目录下生成logto数据库初始化文件

启动容器集群

🛠️ 操作目标：启动所有依赖服务容器

pnpm docker:start

✅ 预期结果：终端显示各服务启动过程，最终所有容器状态为"Up"

验证服务状态

🛠️ 操作目标：确认所有服务正常运行

docker compose ps

✅ 预期结果：输出应显示至少4个服务（db、redis、logto、logtoPostgres）状态为"Up"

数据库初始化

创建数据表结构

🛠️ 操作目标：初始化应用数据库表结构

pnpm db:init

✅ 预期结果：终端显示数据库迁移过程，无错误信息输出

导入课程数据

🛠️ 操作目标：加载初始课程内容

pnpm db:upload

✅ 预期结果：终端显示数据导入进度，最终提示导入成功

启动开发服务器

启动后端API服务

🛠️ 操作目标：启动NestJS后端服务

pnpm dev:serve &

✅ 预期结果：终端显示"Application is running on: http://localhost:3000"

启动前端服务

🛠️ 操作目标：启动Nuxt.js前端服务

pnpm dev:client

✅ 预期结果：终端显示"Nuxt dev server listening on: http://localhost:3011"

验证与排障

环境验证

前端应用验证

打开浏览器访问http://localhost:3001，应该能看到Earthworm的主界面：

✅ 验证点：页面加载正常，显示课程学习界面

数据库连接验证

🛠️ 操作目标：确认数据库连接正常并包含课程数据

psql -h localhost -p 5433 -U postgres earthworm -c "SELECT COUNT(*) FROM courses;"

✅ 预期结果：查询返回课程数量，应大于0

认证服务验证

访问http://localhost:3010，应该能看到Logto认证服务界面。使用初始管理员账户（admin/WkN7g5-i8ZrJckX）登录Logto管理界面（http://localhost:3011）。

✅ 验证点：成功登录Logto管理后台，显示应用配置页面

常见问题解决

Docker权限问题

故障现象：执行docker命令时出现"permission denied"错误

可能原因：当前用户没有Docker操作权限

解决方案：

sudo usermod -aG docker $USER
newgrp docker  # 无需重启立即生效

数据库连接失败

故障现象：API服务启动失败，提示数据库连接错误

可能原因：

1. PostgreSQL容器未正常启动
2. .env文件中的DATABASE_URL配置错误
3. 数据库初始化失败

解决方案：

1. 检查容器状态：docker compose ps | grep db
2. 验证数据库连接：psql -h localhost -p 5433 -U postgres earthworm
3. 确认密码匹配docker-compose.yml中的POSTGRES_PASSWORD配置

Logto服务启动失败

故障现象：Logto容器反复重启或状态为"Exited"

可能原因：

1. Logto数据库初始化失败
2. 端口3010或3011已被占用

解决方案：

1. 查看日志：docker logs earthworm_logto_1
2. 检查端口占用：netstat -tulpn | grep 3010
3. 重新初始化Logto数据：rm -rf .volumes/logto && unzip logto_db_init_data.zip -d .volumes/

进阶技巧

环境优化建议

资源占用监控

Earthworm容器集群运行时会占用一定系统资源，可通过以下命令监控资源使用情况：

# 实时监控容器资源占用
docker stats

# 查看各服务日志大小
du -sh .volumes/*/logs

优化建议：

• 开发时可暂停不使用的服务：docker compose stop logto
• 定期清理未使用的Docker镜像：docker system prune -a
• 调整Docker资源分配（Preferences > Resources）

启动速度优化

优化技巧：

1. 使用Docker BuildKit加速镜像构建：

   export DOCKER_BUILDKIT=1
   

2. 配置npm镜像源加速依赖安装：

   pnpm config set registry https://registry.npmmirror.com
   

3. 创建开发启动脚本（scripts/dev-start.sh）：

   #!/bin/bash
   pnpm docker:start && sleep 10 && pnpm db:init && pnpm dev:serve & pnpm dev:client
   

多环境管理

环境配置文件策略

为不同环境创建独立的配置文件：

• .env.development：开发环境配置
• .env.test：测试环境配置
• .env.production：生产环境配置

使用环境变量切换配置：

# 测试环境启动
NODE_ENV=test pnpm dev:serve

容器编排扩展

创建针对不同场景的Docker Compose配置：

• docker-compose.yml：基础开发环境
• docker-compose.test.yml：测试环境（含测试数据库）
• docker-compose.prod.yml：生产环境配置

使用多配置文件启动：

docker compose -f docker-compose.yml -f docker-compose.test.yml up

环境迁移

开发环境备份

备份关键数据和配置：

# 备份数据库数据
docker exec earthworm_db_1 pg_dump -U postgres earthworm > backup_$(date +%Y%m%d).sql

# 备份环境变量配置
tar -czf env_backup.tar.gz apps/api/.env apps/client/.env

新环境快速部署

在新环境中恢复开发环境：

# 克隆代码
git clone https://gitcode.com/GitHub_Trending/ea/earthworm
cd earthworm

# 恢复环境变量
tar -xzf env_backup.tar.gz

# 恢复数据库
docker compose up -d db
cat backup_xxxxxx.sql | docker exec -i earthworm_db_1 psql -U postgres earthworm

# 启动所有服务
pnpm install
pnpm docker:start
pnpm dev:serve & pnpm dev:client

总结

通过容器化方案，Earthworm项目实现了开发环境的快速搭建和一致性保障。本文详细介绍了从环境准备到服务部署的完整流程，并提供了环境优化和问题排查的实用技巧。掌握这些方法后，开发者可以将更多精力集中在功能开发而非环境配置上。

Earthworm的容器化架构不仅简化了本地开发流程，也为后续的CI/CD和生产部署奠定了基础。随着项目的发展，建议进一步探索Docker Swarm或Kubernetes等容器编排工具，以应对更复杂的部署需求。

成功搭建开发环境后，你可以开始探索Earthworm的课程学习功能，或参考贡献指南参与项目开发。祝你在Earthworm的开发之旅愉快！