Earthworm容器化部署全攻略：从环境搭建到效率提升实践

开发环境的三大核心挑战

在现代软件开发流程中，环境配置往往成为团队协作和项目推进的隐形障碍。开发者经常面临以下困境：

版本迷宫困境
不同开发者本地环境中PostgreSQL版本差异导致数据结构不兼容，Redis配置参数混乱引发缓存机制失效，耗费大量时间在"我这里能运行"的调试循环中。

服务依赖困境
Logto认证服务部署需要独立数据库支持，手动配置时容易出现端口冲突、权限不足等问题，单环境准备平均耗时超过90分钟。

数据一致性困境
团队成员间数据库初始化脚本执行顺序不同，导致测试数据状态不一致，影响功能验证和Bug修复的准确性。

[!TIP] 开发效率提升关键：通过容器化技术将环境配置标准化，可使团队新成员上手时间从2小时缩短至10分钟，环境一致性问题减少85%以上。

容器化乐高：构建模块化开发环境

Earthworm采用容器化架构解决环境一致性问题，就像搭积木一样将不同服务组件组合成完整开发环境。每个容器作为独立模块，既保持功能完整性又实现灵活组合。

环境组件架构

graph LR
    subgraph 数据层
        A[主数据库容器<br/>postgres:14-alpine]
        B[缓存服务容器<br/>redis:5-alpine]
        C[认证数据库容器<br/>postgres:14-alpine]
    end
    
    subgraph 服务层
        D[API服务] --> A
        D --> B
        E[Logto认证服务] --> C
    end
    
    subgraph 应用层
        F[前端应用] --> D
        F --> E
    end

核心服务配置参数

组件名称	技术规格	资源需求	网络端口
主数据库	PostgreSQL 14	1GB内存，10GB存储	5433:5432
缓存服务	Redis 5	512MB内存	6379:6379
认证服务	Logto 1.18.0	1GB内存	3010:3010, 3011:3011

避坑指南：所有容器默认使用桥接网络模式，需确保宿主机对应端口未被占用，可通过netstat -tuln命令检查端口占用情况。

三步搭建法：环境部署实施指南

1. 环境准备阶段

系统要求验证

# 检查Docker版本（需24.0.0+）
docker --version  # 示例输出：Docker version 24.0.5, build 24.0.5-0ubuntu1~22.04.1

# 检查Node.js版本（需v20+）
node --version    # 示例输出：v20.10.0

# 检查pnpm版本（需8+）
pnpm -v           # 示例输出：8.15.4

资源配置建议

• 内存：最低8GB（推荐16GB），容器同时运行时内存占用约4-5GB
• 存储：至少20GB可用空间，包含镜像、依赖和数据文件
• 网络：稳定的互联网连接，首次部署需下载约3GB镜像

避坑指南：Linux用户需将当前用户加入docker用户组，避免每次命令前加sudo：sudo usermod -aG docker $USER && newgrp docker

2. 项目部署阶段

代码获取与依赖安装

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

# 启用corepack管理pnpm版本
corepack enable  # 示例输出：Corepack enabled

# 安装项目依赖
pnpm install     # 输出将显示各工作区依赖安装进度

环境变量配置

# 配置后端环境变量
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/  # 输出将显示解压进度

[!TIP] 初始管理员账户：admin/WkN7g5-i8ZrJckX，管理界面地址：http://localhost:3011

容器集群启动

# 启动所有容器服务
pnpm docker:start  # 首次运行将下载所需镜像，耗时取决于网络速度

# 验证容器状态
docker compose ps  # 应显示4个服务，状态均为Up

成功启动后状态示例：

NAME                   IMAGE                  COMMAND                  STATUS              PORTS
earthworm_db_1         postgres:14-alpine     "docker-entrypoint.s…"   Up 2 minutes        0.0.0.0:5433->5432/tcp
earthworm_redis_1      redis:5-alpine         "docker-entrypoint.s…"   Up 2 minutes        0.0.0.0:6379->6379/tcp
earthworm_logto_1      svhd/logto:1.18.0      "sh -c 'npm run cli …"   Up 2 minutes        0.0.0.0:3010->3010/tcp, 0.0.0.0:3011->3011/tcp
earthworm_logtoPostgres_1 postgres:14-alpine  "docker-entrypoint.s…"   Up 2 minutes        5432/tcp

避坑指南：若Logto容器启动失败，检查.volumes/logto/postgres目录权限，可执行sudo chmod -R 777 .volumes/logto修复权限问题。

3. 应用初始化阶段

数据库结构与数据导入

# 创建数据库表结构
pnpm db:init  # 输出将显示数据库迁移过程

# 导入初始课程数据
pnpm db:upload  # 输出将显示数据导入进度和统计

开发服务器启动

# 启动后端API服务（默认端口3000）
pnpm dev:serve &

# 启动前端Nuxt服务（默认端口3001）
pnpm dev:client

验证点：此时访问http://localhost:3001应能看到Earthworm应用界面，显示课程学习界面。

环境健康检查清单

基础设施验证

• [ ] 所有Docker容器状态正常（docker compose ps显示4个Up状态服务）
• [ ] PostgreSQL端口可访问（telnet localhost 5433能建立连接）
• [ ] Redis服务响应正常（redis-cli ping返回PONG）
• [ ] Logto管理界面可访问（http://localhost:3011能打开登录页）

应用功能验证

• [ ] API服务返回状态（访问http://localhost:3000/api/health返回{"status":"ok"}）
• [ ] 前端应用加载正常（http://localhost:3001无控制台错误）
• [ ] 数据库连接有效（psql -h localhost -p 5433 -U postgres earthworm -c "SELECT COUNT(*) FROM courses"返回大于0的数值）

环境自测10问

1. 能否通过http://localhost:3001访问应用首页？
2. 数据库连接字符串中的端口是否为5433？
3. Logto服务是否在3010端口监听？
4. 执行pnpm docker:stop后所有容器是否停止？
5. .env文件是否添加到.gitignore中？
6. Redis缓存是否正常工作（可通过API响应时间判断）？
7. 数据库初始化脚本是否成功执行？
8. 前端开发热重载是否正常工作？
9. 能否通过Logto管理界面修改用户权限？
10. 项目根目录下是否存在.volumes目录？

避坑指南：开发过程中如遇服务异常，优先检查容器日志：docker logs <容器名称>，常见问题可参考项目文档中的故障排除章节。

通过以上步骤，您已成功搭建Earthworm开发环境。这种容器化方案不仅解决了环境一致性问题，还大幅提升了团队协作效率，让开发者能够将更多精力投入到功能开发而非环境配置中。随着项目的推进，您还可以根据需要扩展容器架构，添加如Elasticsearch等更多服务组件。