设计原则：如果代理或操作员无法通过阅读清单来理解您应用程序的形态，那么清单就是不完整的。

服务拓扑

选择您的服务

大多数 Eve 应用程序遵循以下模式之一：

API + 数据库（最简单）：

services:
  api:        # 带有入口的 HTTP 服务
  db:         # 托管的 Postgres

API + 工作进程 + 数据库：

services:
  api:        # HTTP 服务（面向用户）
  worker:     # 后台处理器（作业、队列）
  db:         # 托管的 Postgres

多服务：

services:
  web:        # 前端/SSR
  api:        # 后端 API
  worker:     # 后台作业
  db:         # 托管的 Postgres
  redis:      # 外部缓存 (x-eve.external: true)

服务设计规则

1. 每个服务一个关注点。 将 HTTP 服务与后台处理分开。API 服务不应同时运行计划作业。
2. 对 Postgres 使用托管数据库。 声明 x-eve.role: managed_db 并让平台进行配置、连接和注入凭据。无需手动连接字符串。
3. 明确标记外部服务。 对于托管在 Eve 之外的服务（Redis、第三方 API），使用 x-eve.external: true 和 x-eve.connection_url。
4. 对一次性任务使用 x-eve.role: job。 迁移、种子数据和数据回填是作业服务，而不是持久进程。
5. 有意识地暴露入口。 只有需要外部 HTTP 访问的服务才设置 x-eve.ingress.public: true。内部服务通过集群网络进行通信。

应用程序对象存储

需要存储文件（上传、头像、导出）的应用程序可以在清单中声明对象存储桶：

services:
  api:
    x-eve:
      object_store:
        buckets:
          - name: uploads
            visibility: private
          - name: avatars
            visibility: public

注意： 应用程序对象存储的数据库模式已存在，但清单的自动配置尚未完成。有关当前状态，请参阅 references/object-store-filesystem.md。

当配置完成后，平台会将 STORAGE_ENDPOINT、STORAGE_ACCESS_KEY、STORAGE_SECRET_KEY、STORAGE_BUCKET 和 STORAGE_FORCE_PATH_STYLE 注入到服务容器中。

云文件系统 / Google Drive 存储

对于面向文档的存储，请使用云文件系统挂载。每个组织通过 BYOA OAuth 凭据连接自己的 Google Drive，然后将文件夹挂载到组织文件系统中：

eve integrations configure google-drive --client-id "..." --client-secret "..."
eve integrations connect google-drive
eve cloud-fs mount --org org_xxx --provider google-drive --folder-id <id> --label "Shared Drive"

应用程序可以通过 Eve 的云文件系统界面（eve cloud-fs ls、eve cloud-fs search 以及每个挂载的云文件系统 API 路由）浏览和搜索已挂载的 Drive 内容。这是对对象存储桶的补充——使用云文件系统处理共享文档和协作，使用对象存储处理应用程序管理的二进制资源。

平台注入的变量

每个部署的服务都会收到 EVE_API_URL、EVE_PUBLIC_API_URL、EVE_PROJECT_ID、EVE_ORG_ID 和 EVE_ENV_NAME。使用 EVE_API_URL 进行服务器到服务器的调用。使用 EVE_PUBLIC_API_URL 处理面向浏览器的代码。设计您的应用程序来读取这些变量，而不是硬编码 URL。

参考架构：SPA + API + 托管数据库

最常见的 Eve 全栈模式。一个由 nginx 前置的 SPA 将 API 调用代理到内部后端，使用托管的 Postgres 和 eve-migrate 进行模式管理。

服务布局

services:
  web:        # nginx SPA（公共入口，代理 /api/ → api 服务）
  api:        # NestJS/Express 后端（内部，无公共入口）
  db:         # 托管的 Postgres 16
  migrate:    # eve-migrate 作业（运行 SQL 迁移）

为什么使用 nginx 代理？ Web 服务的 nginx 反向代理将 /api/ 代理到内部 API 服务。这消除了 CORS 问题，无需硬编码 API 主机名，并赋予 SPA 对后端的同源访问权限。API 服务没有公共入口——它只能在集群内部访问。

清单形态

services:
  api:
    build:
      context: ./apps/api
      dockerfile: ./apps/api/Dockerfile
    ports: [3000]
    environment:
      NODE_ENV: production
      DATABASE_URL: ${managed.db.url}
      CORS_ORIGIN: "https://myapp.eh1.incept5.dev"
    # 没有 x-eve.ingress — API 仅供内部使用

  web:
    build:
      context: ./apps/web
      dockerfile: ./apps/web/Dockerfile
    ports: [80]
    environment:
      API_SERVICE_HOST: ${ENV_NAME}-api    # nginx 代理的 k8s 服务 DNS
    depends_on:
      api:
        condition: service_healthy
    x-eve:
      ingress:
        public: true
        port: 80
        alias: myapp                        # https://myapp.{org}-{project}-{env}.eh1.incept5.dev

  migrate:
    image: public.ecr.aws/w7c4v0w3/eve-horizon/migrate:latest
    environment:
      DATABASE_URL: ${managed.db.url}
      MIGRATIONS_DIR: /migrations
    x-eve:
      role: job
      files:
        - source: db/migrations
          target: /migrations

  db:
    x-eve:
      role: managed_db
      managed:
        class: db.p1
        engine: postgres
        engine_version: "16"

nginx 代理

Web 服务 Dockerfile 使用 Vite 构建 SPA，然后通过 nginx 提供服务。nginx 配置使用 envsubst 在容器启动时解析 ${API_SERVICE_HOST}：

server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html;

    location /api/ {
        proxy_pass http://${API_SERVICE_HOST}:3000/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_buffering off;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /health {
        return 200 "ok";
        add_header Content-Type text/plain;
    }
}

在清单中，API_SERVICE_HOST: ${ENV_NAME}-api 解析为 k8s 服务名称（例如，sandbox-api），为 nginx 提供一个稳定的内部 DNS 目标。

用于模式管理的 Eve-Migrate

Eve 在 public.ecr.aws/w7c4v0w3/eve-horizon/migrate:latest 提供了一个专门构建的迁移运行器。它使用带有时间戳前缀的纯 SQL 文件，在 schema_migrations 表中进行跟踪（幂等、校验和、事务性）。

db/
  migrations/
    20260312000000_initial_schema.sql
    20260312100000_seed_data.sql
    20260315000000_add_status_column.sql

通过 x-eve.files 将迁移挂载到容器中。流水线中的迁移步骤在部署后运行（必须先配置托管数据库）。

不要使用 TypeORM、Knex 或 Flyway 迁移——它们增加了复杂性，并且与 Eve 平台的迁移跟踪不一致。eve-migrate 运行器在本地开发和暂存环境之间提供了一致性。

多阶段 Dockerfile

API Dockerfile（NestJS/Node）：

FROM node:22-slim AS base
WORKDIR /app
ENV PNPM_HOME="/pnpm" PATH="$PNPM_HOME:$PATH"
RUN corepack enable && corepack prepare pnpm@latest --activate

FROM base AS deps
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile 2>/dev/null || pnpm install

FROM deps AS build
COPY tsconfig.json ./
COPY src ./src
RUN pnpm build

FROM node:22-slim AS production
WORKDIR /app
RUN groupadd --gid 1000 node || true && useradd --uid 1000 --gid node --shell /bin/bash --create-home node || true
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY package.json ./
USER node
ENV NODE_ENV=production PORT=3000
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD node -e "fetch('http://localhost:3000/health').then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))"
CMD ["node", "dist/main.js"]

Web Dockerfile（Vite SPA + nginx）：

FROM node:22-slim AS build
WORKDIR /app
ENV PNPM_HOME="/pnpm" PATH="$PNPM_HOME:$PATH"
RUN corepack enable && corepack prepare pnpm@latest --activate
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile 2>/dev/null || pnpm install
COPY tsconfig.json vite.config.ts index.html ./
COPY src ./src
RUN pnpm build

FROM nginx:alpine AS production
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/templates/default.conf.template
EXPOSE 80
HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost/health || exit 1
CMD ["nginx", "-g", "daemon off;"]

约定：node:22-slim 基础镜像，通过 corepack 使用 pnpm，冻结的 lockfile，非 root 用户（API），两个服务都进行健康检查。

数据库设计

配置

在清单中声明一个托管数据库：

services:
  db:
    x-eve:
      role: managed_db
      managed:
        class: db.p1
        engine: postgres
        engine_version: "16"

在其他服务中引用连接 URL：${managed.db.url}。

模式策略

1. 迁移是纯 SQL。 在 db/migrations/ 中创建带有时间戳前缀的 SQL 文件（例如，20260312000000_initial.sql）。通过 eve-migrate 运行（参见上面的参考架构）。切勿手动修改生产模式。
2. 从一开始就为 RLS 设计。 每个包含多租户数据的表都应有 org_id TEXT NOT NULL、RLS 策略以及设置会话上下文的 DatabaseService（见下文）。事后添加行级安全性非常痛苦。
3. 在更改前进行检查。 使用 eve db schema 检查当前模式。在开发期间使用 eve db sql --env <env> 进行临时查询。
4. 将应用程序数据与代理数据分开。 使用不同的模式或命名约定。应用程序表服务于产品；代理表服务于内存和协调（有关存储模式，请参阅 eve-agent-memory）。

RLS + DatabaseService 模式（NestJS）

在 NestJS 中实现多租户 RLS 的成熟模式是使用原始的 pg.Pool（而不是 ORM）和请求作用域的事务包装器：

db.ts — 带有启动健康检查的连接池配置：

import { Pool } from 'pg';

const databaseUrl = process.env.DATABASE_URL || 'postgresql://app:app@localhost:5432/myapp';
const parsed = new URL(databaseUrl);
const isLocal = ['localhost', '127.0.0.1'].includes(parsed.hostname);

export const pool = new Pool({
  connectionString: databaseUrl,
  ssl: !isLocal ? { rejectUnauthorized: false } : undefined,
});

database.service.ts — 带有 RLS 上下文的事务包装器：

import { Injectable } from '@nestjs/common';
import type { PoolClient, QueryResult, QueryResultRow } from 'pg';
import { pool } from '../db';

export interface DbContext {
  org_id: string;
  user_id?: string;
}

@Injectable()
export class DatabaseService {
  async withClient<T>(context: DbContext | null, fn: (client: PoolClient) => Promise<T>): Promise<T> {
    const client = await pool.connect();
    try {
      await client.query('BEGIN');
      if (context?.org_id) {
        await client.query("SELECT set_config('app.org_id', $1, true)", [context.org_id]);
      }
      if (context?.user_id) {
        await client.query("SELECT set_config('app.user_id', $1, true)", [context.user_id]);
      }
      const result = await fn(client);
      await client.query('COMMIT');
      return result;
    } catch (error) {
      await client.query('ROLLBACK');
      throw error;
    } finally {
      client.release();
    }
  }

  async query<T extends QueryResultRow>(ctx: DbContext | null, sql: string, params?: unknown[]): Promise<QueryResult<T>> {
    return this.withClient(ctx, (client) => client.query<T>(sql, params));
  }

  async queryOne<T extends QueryResultRow>(ctx: DbContext | null, sql: string, params?: unknown[]): Promise<T | null> {
    const result = await this.query<T>(ctx, sql, params);
    return result.rows[0] ?? null;
  }
}

为什么使用这种模式？

• set_config('app.org_id', $1, true) 是事务作用域的——当连接返回到连接池时，它会自动清除。
• 每个数据库访问都通过 withClient，确保在任何查询之前设置 RLS 上下文。
• 没有 ORM 开销——原始 SQL 可以完全控制查询计划和连接。
• DbContext 对象派生自 req.user（由 Eve 认证中间件设置）。

RLS 策略模板（在迁移 SQL 中应用于每个表）：

ALTER TABLE my_table ENABLE ROW LEVEL SECURITY;

CREATE POLICY my_table_select ON my_table FOR SELECT
  USING (current_setting('app.org_id', true) IS NOT NULL
    AND org_id = current_setting('app.org_id', true));

CREATE POLICY my_table_insert ON my_table FOR INSERT
  WITH CHECK (current_setting('app.org_id', true) IS NOT NULL
    AND org_id = current_setting('app.org_id', true));

CREATE POLICY my_table_update ON my_table FOR UPDATE
  USING (current_setting('app.org_id', true) IS NOT NULL
    AND org_id = current_setting('app.org_id', true))
  WITH CHECK (current_setting('app.org_id', true) IS NOT NULL
    AND org_id = current_setting('app.org_id', true));

表约定：每个表都有 id UUID PRIMARY KEY DEFAULT gen_random_uuid()、org_id TEXT NOT NULL、created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()，对于可变表还有 updated_at TIMESTAMPTZ（带有触发器）。在第一次迁移中启用 pgcrypto 扩展。

访问模式

构建和发布流水线

规范流程

每个生产应用程序都应遵循 构建 → 发布 → 部署 → 迁移 → 冒烟测试：

pipelines:
  deploy:
    steps:
      - name: build
        action:
          type: build          # 创建 BuildSpec + BuildRun，生成镜像摘要
      - name: release
        depends_on: [build]
        action:
          type: release        # 从构建工件创建不可变的发布
      - name: deploy
        depends_on: [release]
        action:
          type: deploy         # 将发布部署到目标环境
      - name: migrate
        depends_on: [deploy]
        action:
          type: job
          service: migrate     # 针对托管数据库运行 eve-migrate
      - name: smoke-test
        depends_on: [migrate]
        script:
          run: ./scripts/smoke-test.sh
          timeout: 300

为什么这个顺序很重要：

• 构建 生成 SHA256 镜像摘要。发布 固定这些确切的摘要。部署 使用固定的发布。您部署的正是您构建的内容——没有标签漂移，没有“最新”的意外。
• 迁移 在部署之后运行，因为必须先配置托管数据库。eve-migrate 作业应用任何待处理的 SQL 迁移。
• 冒烟测试 在流水线报告成功之前验证已部署服务的端到端功能。

注册表决策

对于 GHCR，在 Dockerfile 中添加 OCI 标签以实现自动仓库链接：

LABEL org.opencontainers.image.source="https://github.com/YOUR_ORG/YOUR_REPO"

构建配置

每个具有自定义镜像的服务都需要一个 构建 部分：

services:
  api:
    build:
      context: ./apps/api
      dockerfile: Dockerfile
    image: ghcr.io/org/my-api

使用多阶段 Dockerfile。BuildKit 原生支持它们。将 OCI 标签放在最终阶段。

部署和环境

环境策略

在清单中将每个环境链接到流水线：

environments:
  staging:
    pipeline: deploy
  production:
    pipeline: deploy

部署模式

标准部署：eve env deploy staging --ref main --repo-dir . 触发链接的流水线。

直接部署（绕过流水线）：eve env deploy staging --ref <sha> --direct 用于紧急情况或简单设置。

升级：在暂存环境中构建一次，然后将相同的发布工件升级到生产环境。构建步骤的摘要会传递下去，保证镜像完全相同。

恢复

当部署失败时：

1. 诊断：eve env diagnose <project> <env> —— 显示健康状态、最近部署、服务状态。
2. 日志：eve env logs <project> <env> —— 容器输出。
3. 回滚：重新部署之前已知良好的发布。
4. 重置：eve env reset <project> <env> —— 核选项，从头重新配置。

设计您的应用程序以支持安全回滚：迁移应向前兼容，服务应在滚动部署期间优雅地处理模式版本不匹配。

用于应用集成的按组织 OAuth

与 Google Drive、Slack 或其他 OAuth 提供商集成的应用程序使用按组织凭据（BYOA——自带应用）。每个组织注册自己的 OAuth 应用，从而控制品牌、范围、速率限制和凭据轮换。

eve integrations configure google-drive --client-id "..." --client-secret "..."
eve integrations connect google-drive

设计影响：使用 Google Drive 数据或 Slack 消息的应用程序应通过 Eve API 引用集成令牌，而不是自行存储 OAuth 凭据。平台使用组织的注册 OAuth 应用凭据处理令牌刷新。

用于工作流的事件触发器

工作流可以由平台事件触发，从而实现响应式自动化：

workflows:
  on-deploy:
    trigger:
      system.event: environment.deployed
    steps:
      - name: smoke-test
        script:
          run: ./scripts/smoke-test.sh

  on-ingest:
    trigger:
      system.event: doc.ingest.completed
    steps:
      - name: process
        agent: doc-processor

事件源包括：GitHub webhooks、Slack 事件、系统事件（部署、构建、摄取）、cron 计划以及手动触发器。有关触发器语法，请参阅 eve-pipelines-workflows；有关完整事件目录，请参阅 references/events.md。

应用程序 CLI 框架

应用程序可以发布对代理友好的 CLI，以替代原始的 REST/curl 交互。在清单中声明 CLI：

services:
  api:
    x-eve:
      cli:
        name: myapp
        bin: cli/bin/myapp

平台将捆绑的二进制文件符号链接到代理工作空间的 $PATH 中。代理调用 myapp --help 来发现功能，从而消除了 URL 构造、认证头和 JSON 引用。有关声明细节，请参阅 eve-manifest-authoring；有关完整实现模式，请参阅 references/app-cli.md。

应用程序卸载/删除生命周期

管理环境和项目的完整生命周期：

# 卸载服务（停止 pod，保留环境记录和历史记录）
eve env undeploy <project> <env>

# 完全删除环境（级联到托管数据库、密钥）
eve env delete <project> <env>

# 删除项目（级联到所有环境、工件、历史记录）
eve project delete <project-id>

设计您的应用程序以实现干净的拆卸：迁移应是幂等的，托管数据库删除是不可逆的，即使环境删除后，流水线历史记录也会保留在审计日志中。

密钥和配置

作用域模型

密钥解析具有级联优先级：项目 > 用户 > 组织 > 系统。项目级别的 API_KEY 会覆盖组织级别的 API_KEY。

设计规则

1. 按项目设置密钥。 使用 eve secrets set KEY "value" --project proj_xxx。保持项目密钥自包含。
2. 在清单中使用插值。 在服务环境块中引用 ${secret.KEY}。平台在部署时解析。
3. 在部署前验证。 运行 eve manifest validate --validate-secrets 以捕获缺失的密钥引用，避免它们导致部署失败。
4. 使用 .eve/dev-secrets.yaml 进行本地开发。 使用本地值镜像生产密钥。此文件被 git 忽略。
5. 切勿直接将密钥存储在环境变量中。 始终使用 ${secret.KEY} 插值。这确保密钥流经平台的解析和审计链。

Git 凭据

代理需要仓库访问权限。将 github_token（HTTPS）或 ssh_key（SSH）设置为项目密钥。工作进程在 git 操作期间自动注入这些凭据。

SSO 认证

向您的应用程序添加 SSO

Eve 提供了消除样板代码的共享认证包。用大约 25 行代码添加 Eve SSO 登录。

后端（@eve-horizon/auth）：

import { eveUserAuth, eveAuthGuard, eveAuthConfig } from '@eve-horizon/auth';

app.use(eveUserAuth());                                     // 解析令牌（非阻塞）
app.get('/auth/config', eveAuthConfig());                   // 提供 SSO 发现
app.get('/auth/me', eveAuthGuard(), (req, res) => {
  res.json(req.eveUser);                                    // { id, email, orgId, role }
});
app.use('/api', eveAuthGuard());                            // 保护所有 API 路由

前端（@eve-horizon/auth-react）：

import { EveAuthProvider, EveLoginGate } from '@eve-horizon/auth-react';

function App() {
  return (
    <EveAuthProvider apiUrl="/api">
      <EveLoginGate>
        <ProtectedApp />
      </EveLoginGate>
    </EveAuthProvider>
  );
}

对于组件中的认证 API 调用，使用 createEveClient：

import { createEveClient } from '@eve-horizon/auth-react';
const client = createEveClient('/api');
const res = await client.fetch('/data');

自定义认证门——当您需要控制加载和登录状态时（自定义登录页面、更丰富的加载 UI），直接使用 useEveAuth() 而不是 EveLoginGate：

import { EveAuthProvider, useEveAuth } from '@eve-horizon/auth-react';

function AuthGate() {
  const { user, loading, loginWithToken, loginWithSso, logout } = useEveAuth();
  if (loading) return <Spinner />;
  if (!user) return <LoginPage onSso={loginWithSso} onToken={loginWithToken} />;
  return <AppShell user={user} onLogout={logout}><Routes /></AppShell>;
}

export default function App() {
  return (
    <EveAuthProvider apiUrl={API_BASE}>
      <AuthGate />
    </EveAuthProvider>
  );
}

工作原理

1. EveAuthProvider 检查 sessionStorage 中缓存的令牌
2. 如果没有令牌，则探测 SSO 代理 /session（根域 cookie）
3. 如果存在 SSO 会话，则获取新的 Eve RS256 令牌
4. 如果没有会话，则显示登录表单（SSO 重定向或令牌粘贴）
5. 所有 API 请求都包含 Authorization: Bearer <token>

NestJS 后端

在 main.ts 中将 eveUserAuth() 应用为全局中间件。如果现有控制器期望 req.user 而不是 req.eveUser，请在一个地方添加一个薄桥，将 Eve 角色映射到应用程序特定角色：

import { eveUserAuth } from '@eve-horizon/auth';

app.use(eveUserAuth());
app.use((req, _res, next) => {
  if (req.eveUser) {
    req.user = { ...req.eveUser, role: req.eveUser.role === 'member' ? 'viewer' : 'admin' };
  }
  next();
});

自动注入的变量

平台将 EVE_SSO_URL、EVE_API_URL 和 EVE_ORG_ID 注入到已部署的容器中。无需手动配置。在前端可访问的 SSO URL 的清单环境块中使用 ${SSO_URL}。

设计规则

1. 使用 SDK，而不是自定义认证。 SDK 用大约 50 行代码替换了大约 750 行手动编写的认证代码。
2. 首先使用非阻塞中间件。 全局使用 eveUserAuth()，然后在受保护的路由上使用 eveAuthGuard()。这使得混合的公共/私有路由成为可能。
3. /auth/config 端点是握手。 前端通过调用后端的 eveAuthConfig() 端点来发现 SSO URL。这将前端与平台环境变量解耦，并且在本地开发和部署环境中同样有效。
4. 为令牌过期设计。 orgs JWT 声明反映了铸造时的成员资格（1 天 TTL）。如果需要立即撤销，请使用 strategy: 'remote'。

有关完整的 SDK 参考，请参阅 eve-read-eve-docs 技能中的 references/auth-sdk.md。

可观察性和调试

调试阶梯

按以下阶段逐步升级：

1. 状态    → eve env show <project> <env>
2. 诊断  → eve env diagnose <project> <env>
3. 日志      → eve env logs <project> <env>
4. 流水线  → eve pipeline logs <pipeline> <run-id> --follow
5. 恢复   → eve env deploy (rollback) 或 eve env reset

从顶部开始。每个阶段提供更多细节和更高成本。大多数问题在阶段 1-2 解决。

流水线可观察性

实时监控流水线执行：

eve pipeline logs <pipeline> <run-id> --follow         # 流式传输所有步骤
eve pipeline logs <pipeline> <run-id> --follow --step build  # 流式传输一个步骤

失败的步骤包括失败提示，并在适用时链接到构建诊断。

构建调试

当构建失败时：

eve build list --project <project_id>
eve build diagnose <build_id>
eve build logs <build_id>

常见原因：缺少注册表凭据、Dockerfile 路径不匹配、构建上下文过大。

健康检查

设计带有健康端点的服务。Eve 轮询健康状态以确定部署就绪情况。当 ready === true 且 active_pipeline_run === null 时，部署完成。

设计清单

服务拓扑：

• 每个服务有一个职责
• 为 Postgres 需求声明了托管数据库
• 外部服务标记为 x-eve.external: true
• 只有面向公众的服务启用了入口
• 使用了平台注入的环境变量（而非硬编码 URL）

数据库：

• 迁移是带有时间戳前缀的纯 SQL 文件，位于 db/migrations/ 中
• 在清单中声明了带有 x-eve.files 挂载的 eve-migrate 作业服务
• DatabaseService 包装所有带有 RLS 上下文（set_config）的数据库访问
• 每个带有 org_id 的表都有 RLS 策略
• 启用了 pgcrypto 扩展，UUID 主键，updated_at 触发器
• 通过模式或约定将应用程序数据与代理数据分开

流水线：

• 定义了规范的 构建 → 发布 → 部署 → 迁移 → 冒烟测试 流水线
• 迁移步骤在部署后运行（必须先存在托管数据库）
• 冒烟测试脚本端到端验证已部署的服务
• 选择了注册表并将凭据设置为密钥
• Dockerfile 上有 OCI 标签（用于 GHCR）
• 镜像摘要通过发布传递（无基于标签的部署）

环境：

• 定义了暂存和生产环境
• 每个环境都链接到一个流水线
• 定义了升级工作流（构建一次，部署多次）
• 已知恢复过程（诊断 -> 回滚 -> 重置）

密钥：

• 所有密钥都通过 eve secrets set 按项目设置
• 清单使用 ${secret.KEY} 插值
• eve manifest validate --validate-secrets 通过
• 存在 .eve/dev-secrets.yaml 用于本地开发
• 配置了 Git 凭据（github_token 或 ssh_key）

认证：

• 向后端添加了 @eve-horizon/auth 中间件（eveUserAuth + eveAuthGuard）
• 认证配置端点提供 SSO 发现（eveAuthConfig）
• @eve-horizon/auth-react 包装前端（EveAuthProvider + EveLoginGate 或自定义 useEveAuth 门）
• 前端使用 createEveClient 进行认证的 API 调用
• 使用了平台注入的认证环境变量（EVE_SSO_URL、EVE_ORG_ID）
• 在一个地方（桥接中间件）将 Eve 角色映射到应用程序角色，而不是分散在各个控制器中

可观察性：

• 服务暴露健康端点
• 理解调试阶梯（状态 -> 诊断 -> 日志 -> 恢复）
• 可以通过 eve pipeline logs --follow 访问流水线日志

交叉引用

• 清单语法和选项：eve-manifest-authoring
• 部署命令和错误解决：eve-deploy-debugging
• 密钥管理和访问组：eve-auth-and-secrets
• 流水线和工作流定义：eve-pipelines-workflows
• 本地开发工作流：eve-local-dev-loop
• 在此基础之上分层代理能力：eve-agentic-app-design
• 认证 SDK 和 SSO 集成：eve-read-eve-docs → references/auth-sdk.md
• 对象存储和文件系统：eve-read-eve-docs → references/object-store-filesystem.md
• 外部集成（Slack、GitHub）：eve-read-eve-docs → references/integrations.md

每周安装次数

117

仓库

incept5/eve-skillpacks

首次出现

2026年2月16日

安全审计

Gen Agent Trust HubPassSocketPass[SnykPass](/incept5/eve-skillpacks/eve-fullstack-app-design/

Design principle : If an agent or operator can't understand your app's shape by reading the manifest, the manifest is incomplete.

Service Topology

Choose Your Services

Most Eve apps follow one of these patterns:

API + Database (simplest):

services:
  api:        # HTTP service with ingress
  db:         # managed Postgres

API + Worker + Database :

services:
  api:        # HTTP service (user-facing)
  worker:     # Background processor (jobs, queues)
  db:         # managed Postgres

Multi-Service :

services:
  web:        # Frontend/SSR
  api:        # Backend API
  worker:     # Background jobs
  db:         # managed Postgres
  redis:      # external cache (x-eve.external: true)

Service Design Rules

1. One concern per service. Separate HTTP serving from background processing. An API service should not also run scheduled jobs.
2. Use managed DB for Postgres. Declare x-eve.role: managed_db and let the platform provision, connect, and inject credentials. No manual connection strings.
3. Mark external services explicitly. Use x-eve.external: true with x-eve.connection_url for services hosted outside Eve (Redis, third-party APIs).
4. Usex-eve.role: job for one-off tasks. Migrations, seeds, and data backfills are job services, not persistent processes.
5. Expose ingress intentionally. Only services that need external HTTP access get x-eve.ingress.public: true. Internal services communicate via cluster networking.

App Object Storage

Apps that need to store files (uploads, avatars, exports) can declare object store buckets in the manifest:

services:
  api:
    x-eve:
      object_store:
        buckets:
          - name: uploads
            visibility: private
          - name: avatars
            visibility: public

Note: The database schema for app object stores exists, but automatic provisioning from the manifest is not yet wired. See references/object-store-filesystem.md for current status.

When wired, the platform injects STORAGE_ENDPOINT, STORAGE_ACCESS_KEY, STORAGE_SECRET_KEY, STORAGE_BUCKET, and STORAGE_FORCE_PATH_STYLE into the service container.

Cloud FS / Google Drive Storage

For document-oriented storage, use cloud FS mounts. Each org connects its own Google Drive via BYOA OAuth credentials, then mounts folders into the org filesystem:

eve integrations configure google-drive --client-id "..." --client-secret "..."
eve integrations connect google-drive
eve cloud-fs mount --org org_xxx --provider google-drive --folder-id <id> --label "Shared Drive"

Apps can browse and search mounted Drive content through Eve's Cloud FS surface (eve cloud-fs ls, eve cloud-fs search, and the per-mount Cloud FS API routes). This is complementary to object store buckets -- use cloud FS for shared documents and collaboration, use object store for app-managed binary assets.

Platform-Injected Variables

Every deployed service receives EVE_API_URL, EVE_PUBLIC_API_URL, EVE_PROJECT_ID, EVE_ORG_ID, and EVE_ENV_NAME. Use EVE_API_URL for server-to-server calls. Use EVE_PUBLIC_API_URL for browser-facing code. Design your app to read these rather than hardcoding URLs.

Reference Architecture: SPA + API + Managed DB

The most common Eve fullstack pattern. A nginx-fronted SPA proxies API calls to an internal backend, with managed Postgres and eve-migrate for schema management.

Service Layout

services:
  web:        # nginx SPA (public ingress, proxies /api/ → api service)
  api:        # NestJS/Express backend (internal, no public ingress)
  db:         # managed Postgres 16
  migrate:    # eve-migrate job (runs SQL migrations)

Why nginx proxy? The web service's nginx reverse-proxies /api/ to the internal API service. This eliminates CORS, removes the need for hard-coded API hostnames, and gives the SPA same-origin access to the backend. The API service has no public ingress — it's only reachable inside the cluster.

Manifest Shape

services:
  api:
    build:
      context: ./apps/api
      dockerfile: ./apps/api/Dockerfile
    ports: [3000]
    environment:
      NODE_ENV: production
      DATABASE_URL: ${managed.db.url}
      CORS_ORIGIN: "https://myapp.eh1.incept5.dev"
    # No x-eve.ingress — API is internal only

  web:
    build:
      context: ./apps/web
      dockerfile: ./apps/web/Dockerfile
    ports: [80]
    environment:
      API_SERVICE_HOST: ${ENV_NAME}-api    # k8s service DNS for nginx proxy
    depends_on:
      api:
        condition: service_healthy
    x-eve:
      ingress:
        public: true
        port: 80
        alias: myapp                        # https://myapp.{org}-{project}-{env}.eh1.incept5.dev

  migrate:
    image: public.ecr.aws/w7c4v0w3/eve-horizon/migrate:latest
    environment:
      DATABASE_URL: ${managed.db.url}
      MIGRATIONS_DIR: /migrations
    x-eve:
      role: job
      files:
        - source: db/migrations
          target: /migrations

  db:
    x-eve:
      role: managed_db
      managed:
        class: db.p1
        engine: postgres
        engine_version: "16"

The nginx Proxy

The web service Dockerfile builds the SPA with Vite, then serves it via nginx. The nginx config uses envsubst to resolve ${API_SERVICE_HOST} at container startup:

server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html;

    location /api/ {
        proxy_pass http://${API_SERVICE_HOST}:3000/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_buffering off;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /health {
        return 200 "ok";
        add_header Content-Type text/plain;
    }
}

In the manifest, API_SERVICE_HOST: ${ENV_NAME}-api resolves to the k8s service name (e.g., sandbox-api), giving nginx a stable internal DNS target.

Eve-Migrate for Schema Management

Eve provides a purpose-built migration runner at public.ecr.aws/w7c4v0w3/eve-horizon/migrate:latest. It uses plain SQL files with timestamp prefixes, tracked in a schema_migrations table (idempotent, checksummed, transactional).

db/
  migrations/
    20260312000000_initial_schema.sql
    20260312100000_seed_data.sql
    20260315000000_add_status_column.sql

Mount migrations into the container via x-eve.files. The migrate step in the pipeline runs after deploy (the managed DB must be provisioned first).

Do not use TypeORM, Knex, or Flyway migrations — they add complexity and diverge from the Eve platform's migration tracking. The eve-migrate runner gives parity between local dev and staging.

Multi-Stage Dockerfiles

API Dockerfile (NestJS/Node):

FROM node:22-slim AS base
WORKDIR /app
ENV PNPM_HOME="/pnpm" PATH="$PNPM_HOME:$PATH"
RUN corepack enable && corepack prepare pnpm@latest --activate

FROM base AS deps
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile 2>/dev/null || pnpm install

FROM deps AS build
COPY tsconfig.json ./
COPY src ./src
RUN pnpm build

FROM node:22-slim AS production
WORKDIR /app
RUN groupadd --gid 1000 node || true && useradd --uid 1000 --gid node --shell /bin/bash --create-home node || true
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY package.json ./
USER node
ENV NODE_ENV=production PORT=3000
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD node -e "fetch('http://localhost:3000/health').then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))"
CMD ["node", "dist/main.js"]

Web Dockerfile (Vite SPA + nginx):

FROM node:22-slim AS build
WORKDIR /app
ENV PNPM_HOME="/pnpm" PATH="$PNPM_HOME:$PATH"
RUN corepack enable && corepack prepare pnpm@latest --activate
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile 2>/dev/null || pnpm install
COPY tsconfig.json vite.config.ts index.html ./
COPY src ./src
RUN pnpm build

FROM nginx:alpine AS production
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/templates/default.conf.template
EXPOSE 80
HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost/health || exit 1
CMD ["nginx", "-g", "daemon off;"]

Conventions : node:22-slim base, pnpm via corepack, frozen lockfiles, non-root user (API), health checks on both services.

Database Design

Provisioning

Declare a managed database in the manifest:

services:
  db:
    x-eve:
      role: managed_db
      managed:
        class: db.p1
        engine: postgres
        engine_version: "16"

Reference the connection URL in other services: ${managed.db.url}.

Schema Strategy

1. Migrations are plain SQL. Create timestamp-prefixed SQL files in db/migrations/ (e.g., 20260312000000_initial.sql). Run via eve-migrate (see Reference Architecture above). Never modify production schemas by hand.
2. Design for RLS from the start. Every table with multi-tenant data gets org_id TEXT NOT NULL, RLS policies, and a DatabaseService that sets the session context (see below). Retrofitting row-level security is painful.
3. Inspect before changing. Use eve db schema to examine current schema. Use eve db sql --env <env> for ad-hoc queries during development.
4. Separate app data from agent data. Use distinct schemas or naming conventions. App tables serve the product; agent tables serve memory and coordination (see eve-agent-memory for storage patterns).

RLS + DatabaseService Pattern (NestJS)

The proven pattern for multi-tenant RLS in NestJS uses raw pg.Pool (not an ORM) with a request-scoped transaction wrapper:

db.ts — Pool configuration with startup health check:

import { Pool } from 'pg';

const databaseUrl = process.env.DATABASE_URL || 'postgresql://app:app@localhost:5432/myapp';
const parsed = new URL(databaseUrl);
const isLocal = ['localhost', '127.0.0.1'].includes(parsed.hostname);

export const pool = new Pool({
  connectionString: databaseUrl,
  ssl: !isLocal ? { rejectUnauthorized: false } : undefined,
});

database.service.ts — Transaction wrapper with RLS context:

import { Injectable } from '@nestjs/common';
import type { PoolClient, QueryResult, QueryResultRow } from 'pg';
import { pool } from '../db';

export interface DbContext {
  org_id: string;
  user_id?: string;
}

@Injectable()
export class DatabaseService {
  async withClient<T>(context: DbContext | null, fn: (client: PoolClient) => Promise<T>): Promise<T> {
    const client = await pool.connect();
    try {
      await client.query('BEGIN');
      if (context?.org_id) {
        await client.query("SELECT set_config('app.org_id', $1, true)", [context.org_id]);
      }
      if (context?.user_id) {
        await client.query("SELECT set_config('app.user_id', $1, true)", [context.user_id]);
      }
      const result = await fn(client);
      await client.query('COMMIT');
      return result;
    } catch (error) {
      await client.query('ROLLBACK');
      throw error;
    } finally {
      client.release();
    }
  }

  async query<T extends QueryResultRow>(ctx: DbContext | null, sql: string, params?: unknown[]): Promise<QueryResult<T>> {
    return this.withClient(ctx, (client) => client.query<T>(sql, params));
  }

  async queryOne<T extends QueryResultRow>(ctx: DbContext | null, sql: string, params?: unknown[]): Promise<T | null> {
    const result = await this.query<T>(ctx, sql, params);
    return result.rows[0] ?? null;
  }
}

Why this pattern?

• set_config('app.org_id', $1, true) is transaction-scoped — it automatically clears when the connection returns to the pool.
• Every database access goes through withClient, guaranteeing RLS context is set before any query.
• No ORM overhead — raw SQL gives full control over query plans and joins.
• The DbContext object is derived from req.user (set by Eve auth middleware).

RLS policy template (applied per table in migration SQL):

ALTER TABLE my_table ENABLE ROW LEVEL SECURITY;

CREATE POLICY my_table_select ON my_table FOR SELECT
  USING (current_setting('app.org_id', true) IS NOT NULL
    AND org_id = current_setting('app.org_id', true));

CREATE POLICY my_table_insert ON my_table FOR INSERT
  WITH CHECK (current_setting('app.org_id', true) IS NOT NULL
    AND org_id = current_setting('app.org_id', true));

CREATE POLICY my_table_update ON my_table FOR UPDATE
  USING (current_setting('app.org_id', true) IS NOT NULL
    AND org_id = current_setting('app.org_id', true))
  WITH CHECK (current_setting('app.org_id', true) IS NOT NULL
    AND org_id = current_setting('app.org_id', true));

Table conventions : Every table gets id UUID PRIMARY KEY DEFAULT gen_random_uuid(), org_id TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), and updated_at TIMESTAMPTZ (with a trigger) on mutable tables. Enable pgcrypto extension in the first migration.

Access Patterns

Build and Release Pipeline

The Canonical Flow

Every production app should follow build → release → deploy → migrate → smoke-test:

pipelines:
  deploy:
    steps:
      - name: build
        action:
          type: build          # Creates BuildSpec + BuildRun, produces image digests
      - name: release
        depends_on: [build]
        action:
          type: release        # Creates immutable release from build artifacts
      - name: deploy
        depends_on: [release]
        action:
          type: deploy         # Deploys release to target environment
      - name: migrate
        depends_on: [deploy]
        action:
          type: job
          service: migrate     # Runs eve-migrate against the managed DB
      - name: smoke-test
        depends_on: [migrate]
        script:
          run: ./scripts/smoke-test.sh
          timeout: 300

Why this order matters :

• build produces SHA256 image digests. release pins those exact digests. deploy uses the pinned release. You deploy exactly what you built — no tag drift, no "latest" surprises.
• migrate runs after deploy because the managed DB must be provisioned first. The eve-migrate job applies any pending SQL migrations.
• smoke-test validates the deployed services end-to-end before the pipeline reports success.

Registry Decisions

For GHCR, add OCI labels to Dockerfiles for automatic repository linking:

LABEL org.opencontainers.image.source="https://github.com/YOUR_ORG/YOUR_REPO"

Build Configuration

Every service with a custom image needs a build section:

services:
  api:
    build:
      context: ./apps/api
      dockerfile: Dockerfile
    image: ghcr.io/org/my-api

Use multi-stage Dockerfiles. BuildKit handles them natively. Place the OCI label on the final stage.

Deployment and Environments

Environment Strategy

Link each environment to a pipeline in the manifest:

environments:
  staging:
    pipeline: deploy
  production:
    pipeline: deploy

Deployment Patterns

Standard deploy : eve env deploy staging --ref main --repo-dir . triggers the linked pipeline.

Direct deploy (bypass pipeline): eve env deploy staging --ref <sha> --direct for emergencies or simple setups.

Promotion : Build once in staging, then promote the same release artifacts to production. The build step's digests carry forward, guaranteeing identical images.

Recovery

When a deploy fails:

1. Diagnose : eve env diagnose <project> <env> — shows health, recent deploys, service status.
2. Logs : eve env logs <project> <env> — container output.
3. Rollback : Redeploy the previous known-good release.
4. Reset : eve env reset <project> <env> — nuclear option, reprovisions from scratch.

Design your app to be rollback-safe: migrations should be forward-compatible, and services should handle schema version mismatches gracefully during rolling deploys.

Per-Org OAuth for App Integrations

Apps that integrate with Google Drive, Slack, or other OAuth providers use per-org credentials (BYOA -- Bring Your Own App). Each org registers its own OAuth app, giving it control over branding, scopes, rate limits, and credential rotation.

eve integrations configure google-drive --client-id "..." --client-secret "..."
eve integrations connect google-drive

Design implications : Apps that consume Google Drive data or Slack messages should reference integration tokens through the Eve API, not store OAuth credentials themselves. The platform handles token refresh using the org's registered OAuth app credentials.

Event Triggers for Workflows

Workflows can be triggered by platform events, enabling reactive automation:

workflows:
  on-deploy:
    trigger:
      system.event: environment.deployed
    steps:
      - name: smoke-test
        script:
          run: ./scripts/smoke-test.sh

  on-ingest:
    trigger:
      system.event: doc.ingest.completed
    steps:
      - name: process
        agent: doc-processor

Event sources include: GitHub webhooks, Slack events, system events (deploy, build, ingest), cron schedules, and manual triggers. See eve-pipelines-workflows for trigger syntax and references/events.md for the full event catalog.

App CLI Framework

Apps can ship agent-friendly CLIs that replace raw REST/curl interactions. Declare the CLI in the manifest:

services:
  api:
    x-eve:
      cli:
        name: myapp
        bin: cli/bin/myapp

The platform symlinks the bundled binary onto $PATH in agent workspaces. Agents invoke myapp --help to discover capabilities, eliminating URL construction, auth headers, and JSON quoting. See eve-manifest-authoring for declaration details and references/app-cli.md for the full implementation pattern.

App Undeploy/Delete Lifecycle

Manage the full lifecycle of environments and projects:

# Undeploy services (stops pods, keeps env record and history)
eve env undeploy <project> <env>

# Delete environment entirely (cascades to managed DB, secrets)
eve env delete <project> <env>

# Delete project (cascades to all environments, artifacts, history)
eve project delete <project-id>

Design your app for clean teardown: migrations should be idempotent, managed DB deletion is irreversible, and pipeline history is preserved in audit logs even after environment deletion.

Secrets and Configuration

Scoping Model

Secrets resolve with cascading precedence: project > user > org > system. A project-level API_KEY overrides an org-level API_KEY.

Design Rules

1. Set secrets per-project. Use eve secrets set KEY "value" --project proj_xxx. Keep project secrets self-contained.
2. Use interpolation in the manifest. Reference ${secret.KEY} in service environment blocks. The platform resolves at deploy time.
3. Validate before deploying. Run eve manifest validate --validate-secrets to catch missing secret references before they cause deploy failures.
4. Use.eve/dev-secrets.yaml for local development. Mirror the production secret keys with local values. This file is gitignored.
5. Never store secrets in environment variables directly. Always use ${secret.KEY} interpolation. This ensures secrets flow through the platform's resolution and audit chain.

Git Credentials

Agents need repository access. Set either github_token (HTTPS) or ssh_key (SSH) as project secrets. The worker injects these automatically during git operations.

SSO Authentication

Adding SSO to Your App

Eve provides shared auth packages that eliminate boilerplate. Add Eve SSO login in ~25 lines of code.

Backend (@eve-horizon/auth):

import { eveUserAuth, eveAuthGuard, eveAuthConfig } from '@eve-horizon/auth';

app.use(eveUserAuth());                                     // Parse tokens (non-blocking)
app.get('/auth/config', eveAuthConfig());                   // Serve SSO discovery
app.get('/auth/me', eveAuthGuard(), (req, res) => {
  res.json(req.eveUser);                                    // { id, email, orgId, role }
});
app.use('/api', eveAuthGuard());                            // Protect all API routes

Frontend (@eve-horizon/auth-react):

import { EveAuthProvider, EveLoginGate } from '@eve-horizon/auth-react';

function App() {
  return (
    <EveAuthProvider apiUrl="/api">
      <EveLoginGate>
        <ProtectedApp />
      </EveLoginGate>
    </EveAuthProvider>
  );
}

For authenticated API calls from components, use createEveClient:

import { createEveClient } from '@eve-horizon/auth-react';
const client = createEveClient('/api');
const res = await client.fetch('/data');

Custom auth gate — When you need control over loading and login states (custom login page, richer loading UI), use useEveAuth() directly instead of EveLoginGate:

import { EveAuthProvider, useEveAuth } from '@eve-horizon/auth-react';

function AuthGate() {
  const { user, loading, loginWithToken, loginWithSso, logout } = useEveAuth();
  if (loading) return <Spinner />;
  if (!user) return <LoginPage onSso={loginWithSso} onToken={loginWithToken} />;
  return <AppShell user={user} onLogout={logout}><Routes /></AppShell>;
}

export default function App() {
  return (
    <EveAuthProvider apiUrl={API_BASE}>
      <AuthGate />
    </EveAuthProvider>
  );
}

How It Works

1. EveAuthProvider checks sessionStorage for cached token
2. If no token, probes SSO broker /session (root-domain cookie)
3. If SSO session exists, gets fresh Eve RS256 token
4. If no session, shows login form (SSO redirect or token paste)
5. All API requests include Authorization: Bearer <token>

NestJS Backend

Apply eveUserAuth() as global middleware in main.ts. If existing controllers expect req.user rather than req.eveUser, add a thin bridge that maps Eve roles to app-specific roles in one place:

import { eveUserAuth } from '@eve-horizon/auth';

app.use(eveUserAuth());
app.use((req, _res, next) => {
  if (req.eveUser) {
    req.user = { ...req.eveUser, role: req.eveUser.role === 'member' ? 'viewer' : 'admin' };
  }
  next();
});

Auto-Injected Variables

The platform injects EVE_SSO_URL, EVE_API_URL, and EVE_ORG_ID into deployed containers. No manual configuration needed. Use ${SSO_URL} in manifest env blocks for frontend-accessible SSO URLs.

Design Rules

1. Use the SDK, not custom auth. The SDK replaces ~750 lines of hand-rolled auth with ~50 lines.
2. Non-blocking middleware first. Use eveUserAuth() globally, then eveAuthGuard() on protected routes. This enables mixed public/private routes.
3. The/auth/config endpoint is the handshake. The frontend discovers the SSO URL by calling the backend's eveAuthConfig() endpoint. This decouples the frontend from platform env vars and works identically in local dev and deployed environments.
4. Design for token staleness. The orgs JWT claim reflects membership at mint time (1-day TTL). Use strategy: 'remote' for immediate revocation if needed.

For full SDK reference, see references/auth-sdk.md in the eve-read-eve-docs skill.

Observability and Debugging

The Debugging Ladder

Escalate through these stages:

1. Status    → eve env show <project> <env>
2. Diagnose  → eve env diagnose <project> <env>
3. Logs      → eve env logs <project> <env>
4. Pipeline  → eve pipeline logs <pipeline> <run-id> --follow
5. Recover   → eve env deploy (rollback) or eve env reset

Start at the top. Each stage provides more detail and more cost. Most issues resolve at stages 1-2.

Pipeline Observability

Monitor pipeline execution in real time:

eve pipeline logs <pipeline> <run-id> --follow         # stream all steps
eve pipeline logs <pipeline> <run-id> --follow --step build  # stream one step

Failed steps include failure hints and link to build diagnostics when applicable.

Build Debugging

When builds fail:

eve build list --project <project_id>
eve build diagnose <build_id>
eve build logs <build_id>

Common causes: missing registry credentials, Dockerfile path mismatch, build context too large.

Health Checks

Design services with health endpoints. Eve polls health to determine deployment readiness. A deploy is complete when ready === true and active_pipeline_run === null.

Design Checklist

Service Topology:

• Each service has one responsibility
• Managed DB declared for Postgres needs
• External services marked with x-eve.external: true
• Only public-facing services have ingress enabled
• Platform-injected env vars used (not hardcoded URLs)

Database:

• Migrations are plain SQL files in db/migrations/ with timestamp prefixes
• eve-migrate job service declared in manifest with x-eve.files mount
• DatabaseService wraps all DB access with RLS context (set_config)
• RLS policies on every table with org_id
• pgcrypto extension enabled, UUID primary keys, updated_at triggers
• App data separated from agent data by schema or convention

Pipeline:

• Canonical build → release → deploy → migrate → smoke-test pipeline defined
• Migrate step runs after deploy (managed DB must exist first)
• Smoke test script validates deployed services end-to-end
• Registry chosen and credentials set as secrets
• OCI labels on Dockerfiles (for GHCR)
• Image digests flow through release (no tag-based deploys)

Environments:

• Staging and production environments defined
• Each environment linked to a pipeline
• Promotion workflow defined (build once, deploy many)
• Recovery procedure known (diagnose -> rollback -> reset)

Secrets:

• All secrets set per-project via eve secrets set
• Manifest uses ${secret.KEY} interpolation
• eve manifest validate --validate-secrets passes
• .eve/dev-secrets.yaml exists for local development
• Git credentials (github_token or ssh_key) configured

Authentication:

• @eve-horizon/auth middleware added to backend (eveUserAuth + eveAuthGuard)
• Auth config endpoint serves SSO discovery (eveAuthConfig)
• @eve-horizon/auth-react wraps frontend (EveAuthProvider + EveLoginGate or custom useEveAuth gate)
• createEveClient used for authenticated API calls from frontend
• Platform-injected auth env vars used (EVE_SSO_URL, EVE_ORG_ID)
• Eve roles mapped to app roles in one place (bridge middleware), not scattered across controllers

Observability:

• Services expose health endpoints
• The debugging ladder is understood (status -> diagnose -> logs -> recover)
• Pipeline logs are accessible via eve pipeline logs --follow

Cross-References

• Manifest syntax and options : eve-manifest-authoring
• Deploy commands and error resolution : eve-deploy-debugging
• Secret management and access groups : eve-auth-and-secrets
• Pipeline and workflow definitions : eve-pipelines-workflows
• Local development workflow : eve-local-dev-loop
• Layering agentic capabilities onto this foundation : eve-agentic-app-design
• Auth SDK and SSO integration : eve-read-eve-docs → references/auth-sdk.md
• Object storage and filesystem : eve-read-eve-docs → references/object-store-filesystem.md
• External integrations (Slack, GitHub) : eve-read-eve-docs → references/integrations.md

Weekly Installs

117

Repository

incept5/eve-skillpacks

First Seen

Feb 16, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

gemini-cli117

codex117

claude-code115

pi52

opencode31

github-copilot31