Earthworm开发环境容器化部署指南：从配置到运行的完整实践

一、开发环境的痛点与容器化解决方案

开发Earthworm项目时，你是否曾遇到过这些困扰：PostgreSQL版本冲突导致数据迁移失败、Redis配置繁琐占用大量调试时间、Logto认证服务部署复杂难以快速验证功能？传统开发环境搭建往往需要手动配置多个服务，不仅耗时（平均2小时以上），还容易出现"在我电脑上能运行"的兼容性问题。

容器化技术通过将应用及其依赖打包成标准化单元，完美解决了环境一致性问题。Earthworm采用Docker Compose实现的多容器架构，将开发环境搭建时间压缩至10分钟，让开发者可以专注于功能实现而非环境配置。

二、容器化方案的核心优势

Earthworm的Docker部署方案带来三大核心价值：

1. 环境一致性保障

• 开发/测试/生产环境统一：所有服务版本和配置通过docker-compose.yml固化
• 消除"Works on My Machine"问题：容器隔离确保依赖不冲突
• 跨平台兼容：在Windows、macOS和Linux系统上行为一致

2. 部署效率提升

传统部署方式	Docker容器化部署
需手动安装PostgreSQL、Redis等服务	一键启动所有依赖服务
环境配置平均2小时	标准化部署10分钟内完成
版本冲突需手动解决	依赖版本通过镜像严格控制
服务启停需单独操作	统一管理所有服务生命周期

3. 资源优化与隔离

• 资源按需分配：可限制各容器CPU/内存使用
• 服务相互隔离：数据库、缓存、认证服务独立运行
• 数据持久化：通过Docker数据卷保留开发数据

三、环境规划与准备

1. 系统需求检查

在开始部署前，请确认你的系统满足以下要求：

依赖项	最低版本	推荐版本	验证命令
Docker	24.0.0	25.0.0+	docker --version
Node.js	v20.0.0	v20.10.0+	node --version
pnpm	8.0.0	8.15.0+	pnpm -v

[!TIP] 如果你使用的是Linux系统，建议将当前用户添加到docker用户组以避免每次使用sudo：

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

2. 硬件资源规划

为确保容器集群流畅运行，建议配置：

• 内存：至少8GB（同时运行5个容器约占用4-5GB）
• 磁盘空间：预留10GB以上（含镜像、数据库文件及项目依赖）
• CPU：2核以上（推荐4核，提升数据库查询性能）

3. 服务依赖关系可视化

Earthworm采用多容器架构，各服务间关系如下：

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

核心服务说明：

• 主数据库：存储课程数据、用户进度等核心业务数据
• Redis：缓存频繁访问数据，提升API响应速度
• Logto：处理用户认证与授权，保护敏感操作
• 前端服务：提供用户学习界面，基于Nuxt.js构建
• API服务：处理业务逻辑，基于NestJS构建

四、分步实施指南

阶段一：环境准备（5分钟）

1. 获取项目代码

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

2. 安装项目依赖

corepack enable  # 确保pnpm可用（如已启用可跳过）
pnpm install     # 安装所有工作区依赖，约需2-3分钟

[!WARNING] 常见误区：直接使用npm install替代pnpm。Earthworm采用pnpm workspace管理多包项目，必须使用pnpm安装依赖以确保依赖结构正确。

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缓存配置
REDIS_URL=redis://localhost:6379
# 认证服务配置
LOGTO_ENDPOINT=http://localhost:3010

阶段二：容器部署（3分钟）

1. 初始化Logto认证数据

unzip logto_db_init_data.zip -d .volumes/

此操作将预置的Logto初始化数据解压到数据卷目录，包含默认管理员账户：admin/WkN7g5-i8ZrJckX

2. 启动容器集群

pnpm docker:start  # 启动所有服务容器

[!TIP] 该命令等效于docker compose up -d，会后台启动所有定义在docker-compose.yml中的服务。首次执行会拉取所需镜像，可能需要额外时间。

3. 验证容器状态

docker compose ps  # 查看所有服务状态

成功启动后应显示类似以下状态：

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

阶段三：应用初始化（2分钟）

1. 数据库结构初始化

pnpm db:init  # 创建数据表结构并执行迁移

2. 导入课程数据

pnpm db:upload  # 导入初始课程内容到数据库

3. 启动开发服务器

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

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

五、环境验证方案

1. 应用访问验证

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

点击"Create account"注册新用户，完成注册后可进入应用主界面：

2. 服务连通性测试

数据库连接测试

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

# 在数据库终端执行查询
SELECT COUNT(*) FROM courses;  # 应返回导入的课程数量
\q  # 退出数据库终端

API服务测试

# 测试API健康检查端点
curl http://localhost:3000/health
# 预期响应：{"status":"ok"}

3. 功能完整性验证

1. 登录系统后，选择任意课程包点击"继续游戏"
2. 完成至少一个练习单元，验证学习进度是否保存
3. 查看个人主页的学习日历，确认学习记录已更新

六、故障排查与优化

1. 故障排查流程图

开始 --> 检查容器状态(docker compose ps)
  --> 容器未运行 --> 查看日志(docker logs 容器名)
  --> 容器运行中 --> 检查端口占用(lsof -i :端口号)
    --> 端口冲突 --> 修改.env中的端口配置
    --> 端口正常 --> 检查服务日志
      --> API日志: pnpm logs:api
      --> 前端日志: pnpm logs:client

2. 常见问题解决方案

Docker权限问题

症状：permission denied while trying to connect to the Docker daemon socket
解决方案：将用户添加到docker组并重新登录

数据库连接失败

症状：API服务启动时报数据库连接错误
检查点：

• 确认db容器状态正常：docker compose ps db
• 验证.env中的DATABASE_URL与docker-compose.yml中的配置一致
• 检查数据库密码是否正确

Logto认证失败

症状：登录时提示"无法连接到认证服务"
解决方案：

# 查看Logto服务日志
docker logs earthworm_logto_1

# 确认Logto数据库是否正确初始化
ls -la .volumes/logto/postgres

3. 环境优化建议

资源配置优化

编辑docker-compose.yml调整容器资源限制：

services:
  db:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G
  redis:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

开发效率提升

添加命令别名到~/.bashrc或~/.zshrc：

# Earthworm开发命令别名
alias ew-start="pnpm docker:start && pnpm dev:serve & pnpm dev:client"
alias ew-stop="pnpm docker:stop"
alias ew-logs="docker compose logs -f"

七、从开发到部署全流程时间轴

0分钟  → 开始准备
5分钟  → 完成环境准备（代码克隆、依赖安装、配置）
8分钟  → 完成容器部署（数据初始化、服务启动）
10分钟 → 完成应用初始化（数据库迁移、课程数据导入）
12分钟 → 启动开发服务器并验证功能

八、扩展指南

贡献代码流程

1. Fork项目仓库：

2. 创建特性分支：

git checkout -b feature/your-feature-name

3. 提交代码时遵循约定式提交规范：

git commit -m "feat: add new course progress tracking"

4. 推送到远程并创建Pull Request

生产环境部署注意事项

• 使用环境变量管理敏感信息，避免硬编码
• 配置HTTPS证书确保数据传输安全
• 设置数据库定期备份策略
• 监控系统资源使用情况，及时扩容

技术原理速览

Docker Compose工作原理：通过YAML文件定义多容器应用的服务、网络和存储配置，使用单个命令创建和启动所有服务。Compose会创建专用网络连接各容器，实现服务间通信，同时通过数据卷实现数据持久化。

多容器通信机制：容器通过服务名相互访问（如API服务通过db主机名访问数据库），无需暴露不必要的端口到主机网络，提高安全性。

通过本文档的指南，你已经掌握了Earthworm开发环境的容器化部署方法。这种标准化的部署方式不仅解决了环境一致性问题，还大幅提升了开发效率，让你可以更专注于功能实现和用户体验优化。