5步容器化部署：Earthworm开发环境搭建从入门到精通

开发环境的"三难困境"与容器化破局之道

团队协作时，你是否经历过这些场景：新成员花两天配置环境仍无法运行项目、本地调试正常的代码提交后CI却频繁报错、不同开发者的数据库版本冲突导致数据结构不兼容？这些问题的根源在于传统开发环境"配置繁琐、版本混乱、依赖复杂"的三大痛点。

Earthworm项目采用Docker容器化方案，将开发环境的搭建时间从数小时压缩至10分钟，实现了"一次配置，处处可用"的一致性体验。本文将通过"问题-方案-验证"三段式框架，带你从零开始构建容器化开发环境，即使是Docker新手也能轻松掌握。

容器化方案的技术解析

为什么选择Docker Compose？

容器化方案相比传统开发环境具有显著优势：

特性	传统开发环境	Docker容器化环境
环境一致性	低（依赖本地配置）	高（容器镜像保证一致性）
搭建时间	2-4小时	10分钟
资源占用	高（需安装所有服务）	中（容器按需分配资源）
版本隔离	弱（易发生版本冲突）	强（容器间完全隔离）
协作效率	低（环境问题频发）	高（统一环境配置）

Earthworm容器架构解析

Earthworm采用多容器架构，通过docker-compose.yml定义了5个核心服务，形成完整的开发环境生态系统：

@startuml
!theme bluegray
rectangle "宿主机" {
  rectangle "前端服务\n(localhost:3001)" as frontend
  rectangle "API服务\n(localhost:3000)" as api
  
  node "Docker网络" {
    database [主数据库\nPostgreSQL:14\n5433:5432]
    redis [缓存服务\nRedis:5\n6379:6379]
    logto [认证服务\nLogto:1.18.0\n3010:3010]
    logtoDB [Logto数据库\nPostgreSQL:14]
  }
}

frontend --> api
api --> database
api --> redis
api --> logto
logto --> logtoDB
@enduml

容器间网络通信机制：Docker Compose会自动创建专用网络，各服务通过服务名相互访问（如API服务通过logto:3010访问认证服务），无需暴露不必要的端口到宿主机。这种隔离性既保证了服务间通信安全，又简化了配置流程。

从零开始的容器化部署四阶段

阶段一：环境准备与依赖检查

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

✅ 基础工具安装

• Docker Engine (24.0.0+)：容器运行核心引擎
• Node.js (v20+)：JavaScript运行环境
• pnpm (8+)：高效的包管理器

# 验证工具版本
docker --version
node --version
pnpm -v

⚠️ 注意事项：Linux用户需将当前用户加入docker组，避免每次使用sudo：

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

✅ 代码仓库准备 克隆Earthworm项目代码到本地：

git clone https://gitcode.com/GitHub_Trending/ea/earthworm
cd earthworm

阶段二：容器环境部署

🔍 检查点：确保当前目录包含docker-compose.yml文件

1. 安装项目依赖

corepack enable  # 启用pnpm包管理器
pnpm install     # 安装所有工作区依赖

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@db:5432/earthworm
# Redis缓存配置
REDIS_URL=redis://redis:6379
# 认证服务配置
LOGTO_ENDPOINT=http://logto:3010

3. 初始化Logto认证数据

Logto需要预置的数据库初始化数据来提供认证服务：

unzip logto_db_init_data.zip -d .volumes/

4. 启动容器集群

# 后台启动所有服务
pnpm docker:start

# 查看服务状态
docker compose ps

🔍 验证服务状态：确保所有服务状态为"Up"

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

阶段三：应用初始化与验证

1. 数据库初始化

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

2. 启动开发服务器

# 启动后端API服务
pnpm dev:serve &

# 启动前端Nuxt服务
pnpm dev:client

3. 验证开发环境

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

🔍 功能验证步骤：

1. 点击右上角"Log in"按钮
2. 使用初始账户登录（admin/WkN7g5-i8ZrJckX）
3. 选择任意课程包开始学习

成功登录后将显示用户仪表盘，包含课程进度和学习统计：

阶段四：环境优化与自动化

自动化脚本替代方案

为进一步简化开发流程，可创建以下自动化脚本（保存为setup-dev-env.sh）：

#!/bin/bash
set -e

# 检查依赖
command -v docker >/dev/null 2>&1 || { echo "Docker未安装"; exit 1; }
command -v pnpm >/dev/null 2>&1 || { echo "pnpm未安装"; exit 1; }

# 克隆仓库（如未克隆）
[ -d "earthworm" ] || git clone https://gitcode.com/GitHub_Trending/ea/earthworm
cd earthworm

# 安装依赖
corepack enable
pnpm install

# 配置环境变量
[ -f "apps/api/.env" ] || cp ./apps/api/.env.example ./apps/api/.env
[ -f "apps/client/.env" ] || cp ./apps/client/.env.example ./apps/client/.env

# 初始化Logto数据
[ -d ".volumes/logto" ] || unzip logto_db_init_data.zip -d .volumes/

# 启动容器
pnpm docker:start

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

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

添加执行权限并运行：

chmod +x setup-dev-env.sh
./setup-dev-env.sh

故障排查与进阶技巧

故障排查流程图

@startuml
start
:服务无法启动?;
if (是) then (yes)
  :检查容器日志;
  :docker logs [容器名];
  if (日志显示端口冲突) then (yes)
    :修改.env文件端口配置;
  else (no)
    :检查环境变量是否正确;
  endif
else (no)
  :应用无法访问?;
  if (是) then (yes)
    :检查防火墙设置;
    :确认端口映射正确;
  else (no)
    :功能异常?;
    if (是) then (yes)
      :检查数据库连接;
      :pnpm db:migrate;
    else (no)
      :环境正常;
    endif
  endif
endif
stop
@enduml

进阶优化建议

1. 容器资源限制：编辑docker-compose.yml，为各服务添加资源限制，避免资源竞争：

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

2. 开发数据持久化：为频繁修改的配置创建单独的数据卷，避免容器重启丢失数据

3. CI/CD集成：将容器化环境集成到GitHub Actions，实现自动化测试和部署

4. 镜像优化：为开发环境创建自定义镜像，预安装常用工具，加速启动过程

总结

通过Docker容器化方案，Earthworm成功解决了开发环境一致性问题，将环境搭建时间从小时级缩短到分钟级。本文详细介绍了"准备-部署-验证-优化"四阶段部署流程，帮助开发者快速上手项目开发。

容器化不仅是一种技术选择，更是现代开发流程的最佳实践。它消除了"在我电脑上能运行"的协作障碍，让团队精力聚焦于功能开发而非环境配置。随着项目复杂度提升，容器化带来的收益将更加显著。

现在，你已经掌握了Earthworm容器化开发环境的搭建方法，立即开始你的英语学习应用开发之旅吧！