mcpField
E
eve-local-dev-loop

eve-local-dev-loop

github.com/incept5开发0313 次安装17 周前更新
代码仓库

关于 eve-local-dev-loop

Eve Local Dev Loop 是用于通过 Docker Compose 本地运行和测试应用，并将其交由 Eve 部署到预发布环境的技能。它指导开发者保持服务与清单一致、运行迁移、管理本地密钥并跟踪部署任务。

主要功能

  1. 01通过 Docker Compose 运行本地服务
  2. 02保持 Compose 服务与 Eve 清单一致
  3. 03使用 eve-migrate 执行数据库迁移
  4. 04配置本地环境变量和密钥
  5. 05部署到预发布环境并跟踪任务

适用场景

  1. 01启动本地应用服务栈进行开发
  2. 02核对迁移在本地与预发布环境的表现
  3. 03排查本地与预发布环境的差异
  4. 04将已测试应用部署到 Eve 预发布环境

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/incept5/eve-skillpacks --skill eve-local-dev-loop

安装后在 Claude Code 中输入/eve-local-dev-loop确认已加载。

详细介绍

Eve 本地开发循环（Docker Compose）

使用此技能通过 Docker Compose 在本地运行和测试应用，然后交由 Eve 部署到预发布环境。

前提条件

  • 仓库中存在 compose.yaml 或 docker-compose.yml。
  • Eve 清单（.eve/manifest.yaml）中的服务和端口与其一致。

本地运行

# Start local services (DB + migrations)
docker compose up -d

# Start API in dev mode (hot reload)
cd apps/api && npm run dev

# Start web in dev mode (Vite dev server with /api proxy)
cd apps/web && npm run dev

# View DB logs
docker compose logs -f

# Reset DB (drop + recreate + migrate)
docker compose down -v && docker compose up -d

推荐的 docker-compose.yml

在本地使用 Eve-migrate 镜像，以确保迁移与预发布环境一致：

services:
  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: myapp
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d myapp"]
      interval: 5s
      timeout: 5s
      retries: 5

  migrate:
    image: ghcr.io/eve-horizon/eve-migrate:latest
    environment:
      DATABASE_URL: postgres://app:app@db:5432/myapp
    volumes:
      - ./db/migrations:/migrations:ro
    depends_on:
      db:
        condition: service_healthy

volumes:
  pgdata:

为什么使用 eve-migrate？ 本地和预发布环境都使用同一个运行器，因此迁移保持一致。它会在 schema_migrations 中记录已应用的迁移（幂等、带校验和、支持事务）。使用带时间戳前缀的纯 SQL 文件：20260312000000_initial_schema.sql。

添加新文件后，手动运行迁移：

docker compose run --rm migrate

保持 Compose 和清单同步

  • 确保 Compose 和 Eve 清单中的服务名称及对外暴露的端口一致。
  • Compose 中的 db 服务对应清单中托管的数据库。本地运行时它是一个容器；在预发布环境中，由 Eve 进行配置。
  • Compose 中的 migrate 服务对应清单中的 migrate 任务。两者都使用 eve-migrate，并挂载 db/migrations/。
  • 如果某个服务在生产环境中是公开的，请在清单中设置 x-eve.ingress.public: true。
  • 在清单中使用 ${secret.KEY}，并将本地值保存在 .eve/dev-secrets.yaml 中。

本地环境变量

  • 为 API 创建 .env（例如，DATABASE_URL=postgresql://app:app@localhost:5432/myapp）。
  • Compose 优先使用 .env，清单插值优先使用 .eve/dev-secrets.yaml。
  • 切勿提交密钥；将 .eve/dev-secrets.yaml 保留在 .gitignore 中。
  • 对于 Vite 开发服务器，在 vite.config.ts 中配置代理，将 /api 转发到 http://localhost:3000（与生产环境中的 nginx 代理模式一致）。

部署到预发布环境

# Ensure profile and auth are set
eve profile use staging
eve auth status

# Set required secrets
eve secrets set API_KEY "value" --project proj_xxx

# Deploy to staging (requires --ref with 40-char SHA or a ref resolved against --repo-dir)
eve env deploy staging --ref main --repo-dir .

# If the environment has a pipeline configured, this triggers the pipeline.
# Use --direct to bypass pipeline and deploy directly:
eve env deploy staging --ref main --repo-dir . --direct

跟踪部署任务：

eve job list --phase active
eve job follow <job-id>
eve job result <job-id>

本地运行正常但预发布环境部署失败时

  • 重新检查清单与 Compose 是否一致。
  • 确认 Eve 中存在所需密钥（eve secrets list）。
  • 使用 eve job diagnose <job-id> 查看故障详情。

评论

支持 Markdown