1 极速搭建 Earthworm 开发环境：容器化部署全攻略

开发环境痛点剖析

开发环境配置耗费数小时？数据库版本冲突导致项目无法启动？认证服务部署流程复杂劝退新手？这些问题严重阻碍开发者快速上手 Earthworm 项目。本文提供一套容器化解决方案，将环境搭建时间压缩至10分钟内，让开发者专注于功能实现而非环境配置。

环境配置方案

验证系统环境

⌛ 准备中：检查本地环境是否满足以下要求：

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

# 检查 Node.js 版本（需 v20+）
node --version

# 检查 pnpm 版本（需 8+）
pnpm -v

📌 关键步骤：若版本不满足要求，使用官方安装包更新对应软件。Linux 用户需确保当前用户拥有 Docker 操作权限。

获取项目代码

⌛ 准备中：克隆项目代码库并进入项目目录

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

安装依赖包

⌛ 准备中：安装项目所有依赖

corepack enable
pnpm install

🔧 提示：国内用户可配置 npm 镜像源加速依赖安装：pnpm config set registry https://registry.npmmirror.com

配置环境变量

📌 关键步骤：创建环境变量文件

# 配置后端环境变量
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

服务部署流程

初始化认证服务数据

📌 关键步骤：解压 Logto 数据库初始化数据

unzip logto_db_init_data.zip -d .volumes/

✅ 验证点：检查 .volumes/logto/postgres 目录是否生成，确保初始化数据已正确解压。

启动容器集群

⌛ 准备中：启动所有依赖服务

pnpm docker:start

🔍 验证点：检查服务状态

docker compose ps

正常运行时应显示以下服务状态：

• earthworm_db_1：主数据库服务
• earthworm_redis_1：缓存服务
• earthworm_logto_1：认证服务
• earthworm_logtoPostgres_1：认证系统数据库

服务关系说明

各服务功能、端口与依赖关系：

1. 主数据库服务

   • 功能：存储应用核心数据
   • 端口：5433（映射容器内5432）
   • 依赖：无

2. 缓存服务

   • 功能：提供数据缓存和会话存储
   • 端口：6379
   • 依赖：无

3. 认证服务

   • 功能：处理用户认证和授权
   • 端口：3010（应用访问）、3011（管理界面）
   • 依赖：认证系统数据库

4. 认证系统数据库

   • 功能：存储认证服务相关数据
   • 端口：内部服务（不对外暴露）
   • 依赖：无

初始化应用数据

📌 关键步骤：创建数据库表结构并导入初始数据

pnpm db:init       # 创建数据表
pnpm db:upload     # 导入课程数据

🔧 提示：若导入数据失败，检查数据库服务是否正常运行，可通过 docker logs earthworm_db_1 查看数据库日志。

启动开发服务器

⌛ 准备中：启动前后端开发服务

# 启动后端 API 服务
pnpm dev:serve &

# 启动前端 Nuxt 服务
pnpm dev:client

✅ 验证点：访问前端应用 http://localhost:3001，应能看到应用主界面。

开发效率提升

开发环境优化建议

1. 资源监控

   • 实时监控容器资源占用：

   docker stats
   

   • 设置资源使用上限，编辑 docker-compose.yml：

   services:
     db:
       deploy:
         resources:
           limits:
             cpus: '1'
             memory: 2G
   

2. 多环境配置 创建环境配置文件切换脚本：

   # 创建 development 环境配置
   cp ./apps/api/.env.development ./apps/api/.env
   
   # 创建 production 环境配置
   cp ./apps/api/.env.production ./apps/api/.env
   

3. 自动化脚本 创建快捷启动脚本 start-dev.sh：

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

扩展服务集成

1. 数据库管理工具 添加 pgAdmin 服务到 docker-compose.yml：

   services:
     pgadmin:
       image: dpage/pgadmin4
       ports:
         - "5050:80"
       environment:
         - PGADMIN_DEFAULT_EMAIL=[e-mail]
         - PGADMIN_DEFAULT_PASSWORD=password
       depends_on:
         - db
   

2. API 文档工具 启动 Swagger UI 服务查看 API 文档：

   pnpm dev:api-docs
   

故障排除流程

服务启动失败

1. 检查容器日志：

   docker logs [容器名称]
   

2. 常见问题排查：

   • 端口冲突：使用 netstat -tulpn 检查占用端口
   • 权限问题：确保 .volumes 目录有读写权限
   • 配置错误：核对环境变量与 docker-compose 配置

数据库连接问题

1. 验证数据库连接：

   psql -h localhost -p 5433 -U postgres -d earthworm
   

2. 检查数据库服务状态：

   docker compose exec db pg_isready
   

3. 重置数据库：

   pnpm docker:down
   rm -rf .volumes/db
   pnpm docker:start
   pnpm db:init
   pnpm db:upload
   

认证服务问题

1. 检查 Logto 服务状态：

   docker compose exec logto npm run status
   

2. 访问 Logto 管理界面：

   • 地址：http://localhost:3011
   • 默认账户：admin/WkN7g5-i8ZrJckX

总结

通过容器化方案，我们实现了 Earthworm 开发环境的快速搭建与部署。这种方式不仅解决了环境一致性问题，还大幅提升了开发效率。随着项目的发展，你可以基于本文提供的扩展方案，进一步定制适合自己的开发环境。

掌握这些技能后，你将能够：

• 在10分钟内完成开发环境搭建
• 轻松管理多个服务组件
• 快速排查和解决环境问题
• 根据需求扩展开发工具链

现在，你已经准备好开始 Earthworm 项目的开发之旅了！