Earthworm开发环境容器化部署指南：从环境困境到高效开发的完整解决方案
环境困境与容器化解决方案
在本地开发Earthworm项目时，开发者常面临三大核心挑战：多服务依赖管理复杂、环境配置耗时且易出错、不同开发环境间存在兼容性问题。传统部署方式需要手动配置PostgreSQL、Redis、Logto等多个服务，平均耗时超过2小时，且容易出现"在我电脑上能运行"的环境一致性问题。
容器化技术通过将应用及其依赖打包成标准化单元，完美解决了这些痛点。Earthworm采用Docker Compose实现的多容器架构，将开发环境搭建时间压缩至10分钟，并确保所有开发者使用完全一致的环境配置。
容器化架构设计决策
Earthworm选择Docker Compose而非Kubernetes作为开发环境解决方案，主要基于以下考量：
- 开发效率优先：Docker Compose配置简单，学习曲线平缓，适合本地开发场景
- 资源占用优化：相比K8s更轻量，适合个人开发者的笔记本环境
- 服务编排简洁：5个核心服务的依赖关系通过简单的YAML配置即可清晰表达
- 跨平台一致性：在Windows、macOS和Linux系统上提供一致的运行体验
基础部署：10分钟启动开发环境
环境准备与依赖检查
开始部署前，请确保系统已安装以下工具：
-
Docker 24.0.0+：容器化运行环境
- 验证命令：
docker --version - 预期输出：
Docker version 24.0.0或更高版本
- 验证命令：
-
Node.js v20+：JavaScript运行时环境
- 验证命令：
node --version - 预期输出：
v20.0.0或更高版本
- 验证命令：
-
pnpm 8+：高效的包管理工具
- 验证命令：
pnpm -v - 预期输出：
8.0.0或更高版本
- 验证命令：
⚠️ 系统资源要求：至少8GB内存（Docker容器运行时将占用约4GB），建议预留10GB以上磁盘空间。
代码获取与项目结构
首先克隆项目代码库并进入项目目录：
git clone https://gitcode.com/GitHub_Trending/ea/earthworm
cd earthworm
Earthworm采用monorepo项目结构，核心代码组织如下：
apps/api：后端API服务apps/client：前端Nuxt应用packages/db：数据库相关配置packages/schema：数据模型定义docker-compose.yml：容器编排配置
容器服务启动
Earthworm通过Docker Compose定义了5个核心服务：
- db：PostgreSQL 14数据库，端口映射5433:5432
- redis：Redis 5缓存服务，端口映射6379:6379
- logto：Logto认证服务，端口映射3010:3010
- logtoPostgres：Logto专用PostgreSQL数据库（内部服务）
启动所有容器服务：
# 安装项目依赖
corepack enable # 确保pnpm可用
pnpm install
# 启动Docker服务集群
pnpm docker:start
💡 技巧：首次运行会下载所需Docker镜像，耗时取决于网络状况。后续启动将直接使用本地镜像，速度显著提升。
服务状态验证
执行以下命令检查服务是否正常启动：
docker compose ps
正常状态下，所有服务的STATUS应显示为"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
环境变量配置
环境变量是连接应用与容器服务的关键桥梁，需要为前后端分别配置：
# 后端环境配置
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缓存连接地址
- 配置值：
redis://localhost:6379
- 配置值：
- LOGTO_ENDPOINT：Logto认证服务地址
- 配置值：
http://localhost:3010
- 配置值：
⚠️ 安全提示：生产环境中应使用强密码并通过环境变量注入，避免硬编码敏感信息。
数据库初始化
完成容器启动和环境变量配置后，需要初始化应用数据库：
# 创建数据表结构
pnpm db:init
# 导入初始课程数据
pnpm db:upload
数据库连接验证
通过以下命令验证数据库是否初始化成功：
# 连接PostgreSQL数据库
psql -h localhost -p 5433 -U postgres earthworm
# 查询课程数据
SELECT COUNT(*) FROM courses;
预期输出应显示导入的课程数量（通常大于0）。
应用启动与访问
最后启动前后端开发服务器：
# 启动后端API服务（http://localhost:3000）
pnpm dev:serve &
# 启动前端Nuxt服务（http://localhost:3001）
pnpm dev:client
服务启动后，访问http://localhost:3001即可看到Earthworm应用界面：
深度配置：定制化开发环境
Logto认证系统配置
Earthworm使用Logto提供身份认证服务，需要完成初始配置：
- 解压预置数据：
unzip logto_db_init_data.zip -d .volumes/
-
访问管理界面：
- 地址：
http://localhost:3011 - 初始账户：
admin/WkN7g5-i8ZrJckX
- 地址：
-
创建应用：
- 应用名称：
Earthworm - 应用类型：
Traditional Web - 重定向URI：
http://localhost:3001/callback
- 应用名称：
容器网络通信原理
Earthworm容器间通过Docker默认网络进行通信：
- 内部服务发现：容器可通过服务名相互访问（如
db代表PostgreSQL服务） - 端口映射：仅必要端口映射到宿主机，内部服务通过Docker网络通信
- 数据持久化：使用Docker卷（volumes）保存数据库数据，确保容器重启后数据不丢失
💡 网络调试技巧：使用docker network inspect earthworm_default命令查看容器网络详情。
开发环境变量高级配置
除基础配置外，以下高级环境变量可优化开发体验：
- LOG_LEVEL：日志级别，开发环境建议设为
debug - API_PREFIX：API路径前缀，默认为
/api - CORS_ORIGIN：跨域请求允许的源，开发环境可设为
* - REDIS_CACHE_TTL：Redis缓存过期时间，单位秒
环境调优：性能优化与资源管理
容器资源分配优化
默认情况下，Docker可能会限制容器使用的系统资源。对于Earthworm开发环境，建议调整资源分配：
# 在docker-compose.yml中为服务添加资源限制
services:
db:
deploy:
resources:
limits:
cpus: '1'
memory: 1G
logto:
deploy:
resources:
limits:
cpus: '0.5'
memory: 512M
常见性能瓶颈及解决方案
-
数据库查询缓慢
- 解决方案：创建常用查询索引，执行
pnpm db:migrate应用索引变更 - 验证方法：使用
EXPLAIN ANALYZE分析慢查询
- 解决方案：创建常用查询索引，执行
-
Redis缓存命中率低
- 解决方案：调整缓存策略，增加热点数据缓存时间
- 监控命令：
redis-cli info stats | grep keyspace_hits
-
前端构建缓慢
- 解决方案：启用Vite构建缓存，执行
pnpm dev:client --force清除缓存后重试
- 解决方案：启用Vite构建缓存，执行
开发与生产环境配置对比
| 配置项 | 开发环境 | 生产环境 |
|---|---|---|
| 数据库连接 | 本地Docker容器 | 远程数据库服务 |
| 日志级别 | Debug | Info |
| 代码热更新 | 启用 | 禁用 |
| 资源限制 | 较低 | 较高 |
| 自动重启 | 启用 | 按需配置 |
| 安全验证 | 简化 | 严格 |
容器资源监控
使用以下命令监控容器资源占用情况：
# 实时监控容器CPU、内存使用
docker stats
# 查看特定容器详细资源使用历史
docker stats earthworm_db_1 --no-stream
# 查看容器网络流量
docker exec -it earthworm_api_1 iftop
问题定位与解决方案
容器启动失败
问题表现：docker compose ps显示服务状态为Exited
排查步骤：
- 查看服务日志：
docker logs earthworm_logto_1 - 检查端口占用：
netstat -tulpn | grep 3010 - 验证数据卷权限：
ls -la .volumes/
常见解决方案：
- 释放占用端口：
kill $(lsof -t -i:3010) - 修复权限问题：
chmod -R 777 .volumes/ - 重新拉取镜像：
docker compose pull
数据库连接错误
问题表现：API服务日志显示"connection refused"
解决方案：
- 确认数据库容器正常运行：
docker compose ps db - 验证数据库连接参数：
cat apps/api/.env | grep DATABASE_URL - 手动测试连接：
psql -h localhost -p 5433 -U postgres earthworm
前端无法访问API
问题定位：
- 检查API服务是否启动：
curl http://localhost:3000/api/health - 验证CORS配置：
grep CORS apps/api/.env - 查看浏览器控制台网络请求错误信息
解决方案：
- 确保前后端服务在同一网络：
docker network inspect earthworm_default - 调整CORS配置：
CORS_ORIGIN=http://localhost:3001 - 重启API服务：
pnpm dev:serve
开发环境管理命令速查表
| 命令 | 功能描述 |
|---|---|
pnpm docker:start |
启动所有Docker服务 |
pnpm docker:stop |
停止所有Docker服务 |
pnpm docker:delete |
删除容器（保留数据） |
pnpm docker:down |
完全清理（含数据卷） |
pnpm db:migrate |
执行数据库迁移 |
pnpm db:seed |
重置数据库并填充测试数据 |
pnpm dev:serve |
启动后端API开发服务 |
pnpm dev:client |
启动前端开发服务 |
pnpm test |
运行所有测试 |
通过本文介绍的容器化部署方案，开发者可以快速搭建一致、高效的Earthworm开发环境，将更多精力投入到功能开发而非环境配置中。容器化不仅解决了"环境一致性"难题，还为团队协作提供了统一的技术基础，是现代软件开发的必备实践。
GLM-5智谱 AI 正式发布 GLM-5，旨在应对复杂系统工程和长时域智能体任务。Jinja00
LongCat-AudioDiT-1BLongCat-AudioDiT 是一款基于扩散模型的文本转语音（TTS）模型，代表了当前该领域的最高水平（SOTA），它直接在波形潜空间中进行操作。00
jiuwenclawJiuwenClaw 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。Python0245- QQwen3.5-397B-A17BQwen3.5 实现了重大飞跃，整合了多模态学习、架构效率、强化学习规模以及全球可访问性等方面的突破性进展，旨在为开发者和企业赋予前所未有的能力与效率。Jinja00
AtomGit城市坐标计划AtomGit 城市坐标计划开启！让开源有坐标，让城市有星火。致力于与城市合伙人共同构建并长期运营一个健康、活跃的本地开发者生态。01
HivisionIDPhotos⚡️HivisionIDPhotos: a lightweight and efficient AI ID photos tools. 一个轻量级的AI证件照制作算法。Python05
项目优选
kernel
docs
pytorch
ops-math
kernel
RuoYi-Vue3
flutter_flutter
cangjie_runtimeMindSpeed-LLM
leetcode