Earthworm容器化开发环境构建指南：从环境配置到应用部署

开发环境挑战与容器化价值

在多语言全栈开发过程中，开发者常面临"环境一致性"难题：本地开发环境与生产环境差异导致的"在我电脑上能运行"现象、多服务依赖配置繁琐（PostgreSQL/Redis/Logto等）、不同操作系统间的兼容性问题，以及团队协作时的环境同步成本。Earthworm项目通过Docker容器化方案，将传统需要2小时的环境配置流程压缩至10分钟，实现"一键启动全栈开发环境"，彻底解决上述痛点。

容器化方案带来三大核心价值：

• 环境一致性：通过容器镜像确保所有开发者使用相同版本的依赖服务
• 隔离性：避免本地服务与项目依赖的端口冲突和版本冲突
• 可移植性：在Windows/macOS/Linux系统上实现一致的开发体验
• 资源效率：比传统虚拟机节省60%以上的系统资源占用

系统兼容性矩阵

基础依赖要求

依赖项	最低版本	推荐版本	验证命令
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

操作系统差异配置

环境	特殊配置	性能基准	常见问题
Windows 10/11	需启用WSL2，分配至少4GB内存	启动时间约60秒	文件系统性能较差，建议将项目放在WSL2文件系统内
macOS	需安装Rosetta 2（Apple Silicon）	启动时间约45秒	Docker Desktop资源配置需≥4GB内存
Linux	需将用户加入docker组	启动时间约30秒	SELinux可能阻止容器端口映射

[!TIP] 性能优化基础：Docker Desktop建议配置至少4GB内存（Windows/macOS），Linux系统建议内核版本≥5.4以获得最佳容器性能。

容器架构解析

Earthworm采用微服务容器化架构，通过docker-compose.yml定义完整的开发环境生态系统，包含5个核心服务组件：

核心服务矩阵

服务名称	镜像信息	主要功能	资源需求	网络端口
db	postgres:14-alpine	主数据库，存储课程和用户数据	内存≥512MB，磁盘≥1GB	5433:5432
redis	redis:5-alpine	缓存服务，存储会话和临时数据	内存≥256MB	6379:6379
logto	svhd/logto:1.18.0	认证系统，处理用户登录和权限	内存≥1GB	3010:3010, 3011:3011
logtoPostgres	postgres:14-alpine	Logto专用数据库	内存≥256MB	内部服务，无暴露端口

服务间数据流向

graph TD
    Client[前端应用] --> API[API服务]
    API --> DB[(主数据库)]
    API --> Redis[(缓存服务)]
    API --> Logto[认证服务]
    Logto --> LogtoDB[(Logto数据库)]
    Client --> Logto

数据流程说明：

1. 用户通过前端应用发起请求
2. API服务处理业务逻辑，与主数据库交互
3. 频繁访问的数据通过Redis缓存加速
4. 用户认证请求由Logto服务处理，其数据存储在独立数据库
5. 前端应用直接与Logto交互完成登录流程

实施流程

阶段一：环境预检

1.1 检查系统依赖

# 验证Docker是否安装并正常运行
docker info

# 验证Node.js和pnpm版本
node --version && pnpm -v

预期输出：

Client: Docker Engine - Community
 Version:    25.0.0
...（省略其他Docker信息）

v20.10.0
8.15.0

[!TIP] 如遇Docker权限问题（Linux）：

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

1.2 获取项目代码

# 克隆代码仓库（获取项目基础文件）
git clone https://gitcode.com/GitHub_Trending/ea/earthworm
cd earthworm

阶段二：资源配置

2.1 安装项目依赖

# 启用corepack以确保pnpm版本一致性
corepack enable

# 安装所有工作区依赖（含前后端及工具链）
pnpm install

依赖安装原理：项目采用pnpm workspace管理多包架构，通过根目录的pnpm-workspace.yaml定义工作区范围，执行pnpm install会递归安装所有子项目依赖。

2.2 配置环境变量

# 创建后端环境配置文件
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	Redis连接地址，默认端口6379
LOGTO_ENDPOINT	http://localhost:3010	Logto服务地址，与docker-compose中logto服务端口一致

[!WARNING] 常见误区：修改数据库端口后未同步更新DATABASE_URL，导致连接失败。确保端口与docker-compose.yml中的映射保持一致。

2.3 准备Logto初始化数据

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

初始化数据说明：该压缩包包含Logto的初始管理员账户（admin/WkN7g5-i8ZrJckX）和基础配置，避免手动配置认证服务的繁琐流程。

阶段三：服务编排

3.1 启动容器集群

# 使用pnpm脚本启动所有Docker服务
pnpm docker:start

脚本执行原理：该命令对应package.json中的"docker:start"脚本，实际执行docker compose up -d，以 detached模式启动所有服务。

3.2 验证服务状态

# 查看容器运行状态
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
earthworm_logtoPostgres_1  postgres:14-alpine  "docker-entrypoint.s…"   Up 5 minutes        5432/tcp

[!TIP] 服务健康检查：可通过docker logs <容器名>查看服务日志，确认是否正常启动。例如：docker logs earthworm_logto_1

阶段四：应用初始化

4.1 数据库初始化

# 创建数据表结构
pnpm db:init

# 导入初始课程数据
pnpm db:upload

命令解析：

• pnpm db:init：执行Drizzle ORM迁移，创建数据库表结构
• pnpm db:upload：将xingrong-courses/data目录下的课程数据导入数据库

4.2 启动开发服务器

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

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

服务启动原理：

• 后端使用NestJS的开发模式，支持热重载
• 前端使用Nuxt3的开发服务器，提供快速刷新能力
• &符号使后端服务在后台运行，可同时使用同一终端启动前端服务

验证与维护

环境功能验证

前端应用验证

访问http://localhost:3001，应能看到Earthworm主界面：

成功登录后进入用户控制台：

数据库连接验证

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

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

预期输出：

 count 
-------
    55
(1 row)

环境管理命令

命令	功能描述	适用场景
pnpm docker:start	启动所有Docker服务	日常开发开始时
pnpm docker:stop	停止所有Docker服务	暂时不需要开发时
pnpm docker:delete	删除容器（保留数据）	服务异常需要重建容器时
pnpm docker:down	完全清理（含数据卷）	需要从零开始重建环境时
pnpm db:migrate	执行数据库迁移	数据库结构更新后

环境性能优化

资源分配方案

根据开发机器配置调整docker-compose.yml中的资源限制：

services:
  db:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G
  logto:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 1G

推荐配置：

• 8GB内存机器：总分配4GB（db:1G, logto:1G, redis:512M, 预留1.5G）
• 16GB内存机器：总分配8GB（db:2G, logto:2G, redis:1G, 预留3G）

多环境切换指南

项目支持开发/测试/生产三种环境配置，通过环境变量文件区分：

# 开发环境（默认）
cp ./apps/api/.env.example ./apps/api/.env

# 测试环境
cp ./apps/api/.env.test ./apps/api/.env

# 生产环境
cp ./apps/api/.env.prod ./apps/api/.env

关键差异点：

• 开发环境：使用本地Docker服务，启用热重载
• 测试环境：连接测试数据库，启用详细日志
• 生产环境：使用远程数据库，禁用调试功能

自动化脚本使用

创建开发环境启动脚本（save as start-dev.sh）：

#!/bin/bash
# 一键启动开发环境脚本

# 检查Docker是否运行
if ! docker info > /dev/null 2>&1; then
  echo "Docker未运行，请先启动Docker"
  exit 1
fi

# 启动Docker服务
pnpm docker:start

# 等待数据库就绪（关键步骤）
echo "等待数据库服务就绪..."
while ! nc -z localhost 5433; do
  sleep 1
done

# 初始化数据库
pnpm db:init
pnpm db:upload

# 启动开发服务器
pnpm dev:serve &
pnpm dev:client

添加执行权限并使用：

chmod +x start-dev.sh
./start-dev.sh

总结

通过Docker容器化方案，Earthworm实现了开发环境的标准化和自动化，大幅降低了环境配置门槛。本文详细介绍了从环境预检到应用部署的完整流程，包括系统兼容性配置、容器架构解析、多阶段实施步骤以及环境维护技巧。

后续进阶方向：

• 探索Docker Compose的多环境配置（docker-compose.override.yml）
• 学习使用Docker volumes实现数据持久化
• 了解CI/CD流程中容器化部署的最佳实践

掌握这些技能不仅能提升Earthworm项目的开发效率，更能为其他复杂应用的环境管理提供参考模式。