7步极速部署Earthworm：零障碍容器化环境配置指南

一、问题诊断：开发环境部署的核心痛点解析

1.1 传统部署模式的三大困境

在Earthworm开发过程中，开发者常面临以下环境配置难题：

• 版本冲突地狱：PostgreSQL与Redis的版本依赖复杂，本地安装易与其他项目产生冲突
• 认证服务部署门槛：Logto认证系统需要独立数据库和特定配置，手动部署耗时超过1小时
• 环境一致性缺失：不同开发者的本地环境差异导致"在我电脑上能运行"的协作障碍

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

容器化部署通过隔离环境、统一配置和自动化流程，将Earthworm的环境搭建时间从传统方式的2小时压缩至10分钟，同时带来三大收益：

• 环境一致性：所有开发者使用相同版本的依赖服务
• 部署自动化：通过docker-compose实现一键启动多服务集群
• 资源隔离：避免开发环境与其他项目的资源竞争

二、方案设计：容器化部署架构与前置检查

2.1 容器协作流程图

Earthworm采用多容器架构设计，通过docker-compose.yml定义5个核心服务，形成以下数据流向：

前端服务 (Nuxt) → API服务 (NestJS) → 主数据库 (PostgreSQL)
                      ↑
                      ↓
              认证服务 (Logto) → Logto数据库 (PostgreSQL)
                      ↑
                      ↓
                  缓存服务 (Redis)

2.2 部署前置检查清单

在开始部署前，请确保满足以下环境要求：

依赖项	版本要求	验证命令	资源占用预估
Docker	24.0.0+	docker --version	基础镜像约3GB
Node.js	v20+	node --version	-
pnpm	8+	pnpm -v	-

硬件配置建议：

• 内存：至少8GB（Docker容器同时运行时需占用约4GB）
• 磁盘空间：预留10GB以上（含镜像、数据库文件及项目依赖）

三、实施验证：七步完成容器化环境部署

3.1 克隆代码仓库

git clone https://gitcode.com/GitHub_Trending/ea/earthworm  # 克隆项目仓库
cd earthworm                                              # 进入项目根目录

预期结果：项目文件夹包含apps、packages等子目录，根目录存在docker-compose.yml文件

3.2 安装项目依赖

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

预期结果：node_modules目录生成，pnpm-lock.yaml文件更新

3.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

⚠️ 安全最佳实践：生产环境中应使用强密码，并通过环境变量注入而非明文存储，敏感配置可使用Docker Secrets管理

3.4 初始化Logto认证数据

unzip logto_db_init_data.zip -d .volumes/  # 解压预置的Logto数据库初始化数据

初始管理员账户：admin/WkN7g5-i8ZrJckX
管理界面：http://localhost:3011

3.5 启动Docker服务集群

pnpm docker:start  # 启动所有依赖服务
docker compose ps  # 验证服务状态

预期结果：所有服务状态显示为"Up"：

NAME                   IMAGE                  STATUS              PORTS
earthworm_db_1         postgres:14-alpine     Up 5 minutes        0.0.0.0:5433->5432/tcp
earthworm_redis_1      redis:5-alpine         Up 5 minutes        0.0.0.0:6379->6379/tcp
earthworm_logto_1      svhd/logto:1.18.0      Up 5 minutes        0.0.0.0:3010->3010/tcp, 0.0.0.0:3011->3011/tcp

3.6 初始化应用数据库

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

验证数据库连接：

psql -h localhost -p 5433 -U postgres earthworm  # 连接主数据库
SELECT COUNT(*) FROM courses;                     # 应返回导入的课程数量

3.7 启动开发服务器

pnpm dev:serve &  # 后台启动后端API服务（http://localhost:3000）
pnpm dev:client   # 启动前端Nuxt服务（http://localhost:3001）

环境验证：访问前端应用 http://localhost:3001，应能看到Earthworm主界面：

四、容器健康检查与资源优化

4.1 容器健康检查命令

# 检查数据库连接
docker exec earthworm_db_1 pg_isready -U postgres

# 检查Redis状态
docker exec earthworm_redis_1 redis-cli ping

# 查看服务日志
docker logs -f earthworm_logto_1  # 实时查看Logto服务日志

4.2 资源优化建议

• 内存分配：为Docker Desktop分配至少4GB内存（Preferences → Resources → Memory）
• 镜像清理：定期清理未使用镜像 docker system prune -a
• 容器重启策略：在docker-compose.yml中设置 restart: unless-stopped 确保服务稳定性

五、多环境配置策略

5.1 开发环境（默认）

使用本地开发配置，代码热重载，调试功能开启：

pnpm dev:serve  # 开发模式启动API服务

5.2 测试环境

使用测试数据库，自动运行测试用例：

pnpm test:api   # 运行API测试
pnpm test:client # 运行前端测试

5.3 生产环境

使用优化配置，禁用调试功能，启用进程守护：

pnpm build      # 构建生产版本
pnpm start      # 启动生产服务

六、故障排除速查表

6.1 Docker权限问题

错误现象：permission denied while trying to connect to the Docker daemon socket
解决方案：

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

6.2 数据库连接失败

检查项：

1. 确认docker-compose.yml中数据库配置：

services:
  db:
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: earthworm

2. 验证.env文件中的DATABASE_URL与上述配置匹配

6.3 Logto认证失败

排查步骤：

1. 检查Logto服务状态：docker logs earthworm_logto_1
2. 确认Logto数据库初始化：.volumes/logto-postgres目录存在数据文件
3. 验证LOGTO_ENDPOINT配置是否指向正确地址

七、开发环境管理命令速查

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

通过以上步骤，您已成功搭建Earthworm的容器化开发环境。如需进一步优化或定制配置，请参考项目中的docker-compose.yml文件及官方文档。