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

环境痛点深度剖析

在多团队协作开发场景中，Earthworm项目面临三大核心环境挑战：开发环境一致性问题导致"在我电脑上能运行"现象频发、依赖服务配置繁琐（PostgreSQL/Redis/Logto需手动部署）、环境搭建耗时超过2小时且错误率高。传统开发环境配置存在三个维度的痛点：

• 版本依赖冲突：PostgreSQL 14与其他项目的12版本需求冲突，Redis配置参数因环境而异
• 服务编排复杂：认证服务Logto需要独立数据库实例，与主应用数据库形成多数据源架构
• 数据初始化繁琐：课程数据与认证系统基础数据需手动导入，步骤易遗漏

这些问题直接导致新开发者上手门槛高、环境修复时间长、团队协作效率低下。

容器化方案架构设计

整体架构选型

采用Docker Compose实现多容器应用编排，通过容器化解决环境一致性问题。整体架构采用分层设计：

graph LR
    Client[前端应用] --> API[后端服务]
    API --> DB[(主数据库)]
    API --> Redis[(缓存服务)]
    API --> Logto[认证服务]
    Logto --> LogtoDB[(认证数据库)]
    subgraph 开发环境层
        Client
        API
    end
    subgraph 基础设施层
        DB
        Redis
        Logto
        LogtoDB
    end

核心服务配置

容器化方案包含四大核心服务组件，通过docker-compose.yml实现统一编排：

服务标识	技术选型	资源需求	网络策略	数据持久化策略
db	PostgreSQL 14	512MB RAM	端口映射5433:5432	本地卷挂载/volumes
redis	Redis 5	256MB RAM	端口映射6379:6379	内存存储+AOF持久化
logto	svhd/logto:1.18.0	384MB RAM	端口映射3010:3010	内部网络+数据卷挂载
logtoPostgres	PostgreSQL 14	256MB RAM	仅内部暴露	独立数据卷

环境变量设计

采用环境变量注入机制实现配置解耦，核心环境变量包括：

• DATABASE_URL：主数据库连接字符串，格式为postgresql://用户:密码@主机:端口/数据库名
• REDIS_URL：缓存服务连接地址，影响API服务的会话管理与数据缓存策略
• LOGTO_ENDPOINT：认证服务端点，控制用户身份验证流程的交互目标

环境变量通过.env文件管理，实现开发环境与生产环境配置分离。

分步实施流程

1. 环境前置检查

验证基础工具链版本兼容性：

docker --version  # 需返回24.0.0+
node --version    # 需返回v20.x.x
pnpm -v           # 需返回8.x.x

常见错误：Docker版本过低会导致compose语法不兼容，建议通过Docker官方脚本升级

2. 项目代码准备

获取项目源码并进入工作目录：

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

3. 依赖管理与环境配置

安装项目依赖并配置环境变量：

corepack enable               # 启用pnpm包管理
pnpm install                  # 安装工作区依赖
cp apps/api/.env.example apps/api/.env  # 复制后端环境变量模板
cp apps/client/.env.example apps/client/.env  # 复制前端环境变量模板

配置要点：确保.env文件中数据库连接参数与docker-compose.yml中的服务配置一致

4. 认证数据初始化

部署Logto认证系统的基础数据：

unzip logto_db_init_data.zip -d .volumes/  # 解压预置数据库文件

初始凭证：管理员账户admin，默认密码WkN7g5-i8ZrJckX

5. 容器集群编排

启动完整服务集群并验证状态：

pnpm docker:start             # 启动所有容器服务
docker compose ps             # 检查服务运行状态

成功启动后应显示所有服务状态为"Up"：

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

6. 应用数据初始化

完成数据库结构创建与基础数据导入：

pnpm db:init       # 执行数据库迁移创建表结构
pnpm db:upload     # 导入课程数据与系统配置

验证提示：可通过psql -h localhost -p 5433 -U postgres earthworm连接数据库验证数据导入

7. 开发服务启动

启动前后端开发服务器：

pnpm dev:serve &   # 启动后端API服务（端口3000）
pnpm dev:client    # 启动前端Nuxt服务（端口3011）

环境验证策略

应用功能验证

访问前端应用首页http://localhost:3011，应显示Earthworm主界面：

界面应包含课程进度条、句子构造练习区和导航控制按钮，表明前端应用与后端服务已正常连接。

服务连通性测试

验证各服务间通信状态：

# 测试数据库连接
docker exec -it earthworm_db_1 psql -U postgres -d earthworm -c "SELECT COUNT(*) FROM courses;"

# 测试Redis连接
docker exec -it earthworm_redis_1 redis-cli PING  # 应返回PONG

# 测试API服务健康状态
curl http://localhost:3000/health  # 应返回JSON格式健康状态

数据完整性检查

确认核心数据已正确加载：

# 验证课程数据数量
curl http://localhost:3000/api/courses | jq '.data | length'  # 应返回非零数值

问题排查指南

容器启动失败

症状：docker compose ps显示服务状态为"Exited"

排查流程：

1. 查看服务日志：docker logs earthworm_logto_1
2. 检查端口占用：netstat -tulpn | grep 3010
3. 验证数据卷权限：ls -la .volumes/logto/postgres

解决方案：

• 端口冲突：修改docker-compose.yml中的端口映射
• 权限问题：执行sudo chmod -R 777 .volumes修复数据卷权限

数据库连接错误

常见原因：

• 环境变量配置错误：检查DATABASE_URL格式
• 数据库初始化失败：重新执行pnpm db:init
• 容器网络问题：通过docker network inspect earthworm_default检查网络配置

认证服务异常

诊断命令：

# 检查Logto服务状态
docker exec -it earthworm_logto_1 npm run status

# 查看认证数据库连接
docker exec -it earthworm_logtoPostgres_1 psql -U postgres -d logto -c "\dt"

性能优化建议

容器资源配置

编辑docker-compose.yml添加资源限制：

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

开发效率提升

配置Docker Compose健康检查，实现服务就绪自动通知：

services:
  api:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 5

日志管理优化

配置集中式日志收集：

# 实时查看API服务日志
pnpm docker:logs api

# 跟踪数据库查询日志
docker exec -it earthworm_db_1 tail -f /var/log/postgresql/postgresql-14-main.log

环境迁移与备份策略

数据备份方案

定期备份关键数据卷：

# 备份主数据库
docker run --rm -v earthworm_db_data:/source -v $(pwd)/backups:/backup alpine tar -czf /backup/db_$(date +%Y%m%d).tar.gz -C /source .

# 备份认证数据
docker run --rm -v earthworm_logto_postgres_data:/source -v $(pwd)/backups:/backup alpine tar -czf /backup/logto_$(date +%Y%m%d).tar.gz -C /source .

环境迁移步骤

1. 打包当前环境配置：tar -czf earthworm_env.tar.gz .env .volumes docker-compose.yml
2. 在目标机器解压：tar -xzf earthworm_env.tar.gz
3. 启动服务：pnpm docker:start

多环境隔离方案

通过环境变量文件实现开发/测试/生产环境隔离：

# 创建测试环境配置
cp .env .env.test

# 使用测试环境配置启动
docker compose --env-file .env.test up

通过以上容器化方案，Earthworm项目实现了开发环境的标准化与自动化，将环境搭建时间从2小时缩短至10分钟，同时大幅降低了环境相关问题的发生率。开发者可专注于业务功能开发，而非环境配置调试，显著提升了团队协作效率。