Earthworm容器化开发环境搭建指南：从环境痛点到一键部署

环境痛点分析：开发路上的"绊脚石"

传统开发环境的三大困境

作为开发者，你是否也曾遭遇这些"踩坑"经历：PostgreSQL版本冲突导致数据模型加载失败，Redis配置参数不匹配引发缓存异常，Logto认证服务部署步骤繁琐如同"拆盲盒"？这些问题往往耗费数小时甚至一整天时间排查，严重影响开发效率。

[!WARNING] 环境配置不当可能导致：数据模型损坏、认证流程失效、开发进度延期，甚至需要从零开始重建开发环境。

容器化方案的核心优势

Docker容器化技术（类似标准化 shipping container，确保软件在任何环境都能一致运行）通过隔离应用依赖，完美解决了"在我电脑上能运行"的经典问题。Earthworm项目采用Docker Compose（容器编排工具，类似乐高积木的组合方式）实现全栈环境一键部署，将传统2小时的环境配置过程压缩至10分钟内。

---

容器化架构设计：服务组件的"交响乐团"

核心服务组件解析

Earthworm采用多容器架构设计，通过docker-compose.yml定义5个核心服务，它们之间的协作关系如下：

sequenceDiagram
    participant 前端服务
    participant API服务
    participant 主数据库(PostgreSQL)
    participant 缓存(Redis)
    participant Logto认证服务
    participant Logto数据库
    
    前端服务->>API服务: 请求数据
    API服务->>主数据库(PostgreSQL): 查询课程数据
    API服务->>缓存(Redis): 读写用户进度
    API服务->>Logto认证服务: 验证用户身份
    Logto认证服务->>Logto数据库: 存储认证信息
    API服务->>前端服务: 返回响应结果

服务配置参数详解

服务名	镜像	用途	端口映射	重要性
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专用数据库	内部服务	中

[!TIP] 服务间通过Docker网络自动发现，无需手动配置IP地址。修改服务端口需同步更新.env文件中的对应配置。

---

分阶段部署流程：从克隆到启动的全流程

环境准备与依赖检查

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

依赖项	推荐版本	最低版本	验证命令	重要性
Docker	24.0.0+	20.10.0+	docker --version	高
Node.js	v20.10.0+	v18.17.0+	node --version	高
pnpm	8.15.0+	8.0.0+	pnpm -v	中

硬件配置建议：

• 内存：8GB+（最低不低于4GB，容器同时运行时内存占用约3-4GB）
• 磁盘空间：10GB+（含镜像、数据库文件及项目依赖）

代码获取与环境配置

⌨️ 克隆代码仓库

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

执行后应看到项目文件列表，包括apps/、packages/和docker-compose.yml等文件

⌨️ 安装项目依赖

corepack enable  # 确保pnpm可用（如已启用可跳过）
pnpm install     # 安装所有工作区依赖

预期结果：控制台显示依赖安装进度，最终输出"dependencies installed successfully"

⌨️ 配置环境变量

# 复制后端环境变量模板
cp ./apps/api/.env.example ./apps/api/.env

# 复制前端环境变量模板
cp ./apps/client/.env.example ./apps/client/.env

关键配置项（apps/api/.env）：

# 数据库连接URL（格式：协议://用户名:密码@主机:端口/数据库名）
DATABASE_URL=postgresql://postgres:password@localhost:5433/earthworm
# Redis连接URL
REDIS_URL=redis://localhost:6379
# Logto认证服务地址
LOGTO_ENDPOINT=http://localhost:3010

容器集群启动与数据初始化

⌨️ 初始化Logto认证数据

unzip logto_db_init_data.zip -d .volumes/

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

⌨️ 启动Docker服务集群

pnpm docker:start  # 启动所有依赖服务

命令执行后将自动拉取所需镜像并启动容器，首次执行可能需要5-10分钟（取决于网络速度）

⌨️ 验证服务状态

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

⌨️ 初始化应用数据库

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

⌨️ 启动开发服务器

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

---

环境验证体系：确保环境配置正确的"体检表"

应用功能验证

成功启动服务后，通过以下步骤验证环境是否正常工作：

1. 访问前端应用：打开浏览器访问 http://localhost:3001，应能看到Earthworm主界面：

2. 验证课程数据加载：登录后进入课程页面，应能看到课程列表和学习进度显示：

服务连通性测试

⌨️ 数据库连接测试

# 连接主数据库
psql -h localhost -p 5433 -U postgres earthworm

# 查询课程数据（应返回导入的课程数量）
SELECT COUNT(*) FROM courses;

⌨️ API服务测试

# 测试API健康检查端点
curl http://localhost:3000/health
# 预期响应：{"status":"ok","timestamp":"2026-03-12T04:05:32.123Z"}

成功/失败状态对比

检查项	成功状态	失败状态
Docker服务	所有容器STATUS为Up	容器状态为Exited或Restarting
数据库连接	能查询到课程数据	连接超时或认证失败
前端页面	加载正常无错误	控制台显示404或500错误
API响应	返回200状态码	返回4xx或5xx错误码

---

问题排查指南：从现象到根源的故障树分析

Docker相关问题

现象：容器启动失败

ERROR: for earthworm_db_1  Cannot start service db: Ports are not available: listen tcp 0.0.0.0:5433: bind: address already in use

排查路径：

1. 检查端口占用情况：sudo lsof -i :5433
2. 终止占用进程：kill -9 <PID>
3. 或修改docker-compose.yml中对应服务的端口映射

现象：权限错误

permission denied while trying to connect to the Docker daemon socket

解决方案：

sudo usermod -aG docker $USER  # 将当前用户添加到docker组
newgrp docker  # 无需重启立即生效

数据库连接问题

现象：无法连接数据库

排查步骤：

1. 检查数据库容器状态：docker compose ps db
2. 查看数据库日志：docker compose logs db
3. 验证.env配置：确保DATABASE_URL中的端口、用户名和密码正确
4. 手动测试连接：psql -h localhost -p 5433 -U postgres earthworm

[!TIP] 默认数据库凭据：用户postgres，密码password，数据库名earthworm

Logto认证问题

现象：登录页面无法访问

排查路径：

1. 确认Logto服务状态：docker compose ps logto
2. 检查Logto数据库连接：docker compose logs logto
3. 验证Logto初始化数据：确保.volumes/logto/postgres目录存在数据文件

开发环境管理命令

命令	用途	参数说明
pnpm docker:start	启动所有Docker服务	无
pnpm docker:stop	停止所有Docker服务	无
pnpm docker:delete	删除容器（保留数据）	无
pnpm docker:down	完全清理（含数据卷）	-v 表示删除数据卷
pnpm db:migrate	执行数据库迁移	--force 强制迁移

---

通过本文介绍的容器化方案，你已经掌握了Earthworm开发环境的快速搭建方法。这种"一次配置，到处运行"的方式不仅解决了环境一致性问题，还大幅提升了团队协作效率。接下来，你可以开始探索Earthworm的代码结构，参与功能开发或提交改进建议。祝你在Earthworm项目中开发愉快！