eve-fullstack-app-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Full-Stack App Design on Eve Horizon

在Eve Horizon上设计全栈应用

Architect applications where the manifest is the blueprint, the platform handles infrastructure, and every design decision is intentional.

构建以清单为蓝图、平台负责基础设施、每项设计决策都经过审慎考量的应用。

When to Use

适用场景

Load this skill when:

Designing a new application from scratch on Eve
Migrating an existing app onto the platform
Evaluating whether your current architecture uses Eve's capabilities well
Planning service topology, database strategy, or deployment pipelines
Deciding between managed and external services

This skill teaches design thinking for Eve's PaaS layer. For CLI usage and operational detail, load the corresponding eve-se skills (

eve-manifest-authoring

eve-deploy-debugging

eve-auth-and-secrets

eve-pipelines-workflows

在以下场景中使用本技能：

在Eve上从零开始设计新应用
将现有应用迁移至该平台
评估当前架构是否充分利用了Eve的功能
规划服务拓扑、数据库策略或部署流水线
抉择使用托管服务还是外部服务

本技能讲解Eve PaaS层的设计思路。如需了解CLI使用方法与操作细节，请加载对应的eve-se技能（

eve-manifest-authoring

、

eve-deploy-debugging

、

eve-auth-and-secrets

、

eve-pipelines-workflows

）。

The Manifest as Blueprint

作为蓝图的清单

The manifest (

.eve/manifest.yaml

) is the single source of truth for your application's shape. Treat it as an architectural document, not just configuration.

清单（

.eve/manifest.yaml

）是应用架构的唯一可信来源。请将其视为架构文档，而非单纯的配置文件。

What the Manifest Declares

清单声明的内容

Concern	Manifest Section	Design Decision
Service topology	`services`	What processes run, how they connect
Infrastructure	`services[].x-eve`	Managed DB, ingress, roles
Build strategy	`services[].build` + `registry`	What gets built, where images live
Release pipeline	`pipelines`	How code flows from commit to production
Environment shape	`environments`	Which environments exist, what pipelines they use
Agent configuration	`x-eve.agents` , `x-eve.chat`	Agent profiles, team dispatch, chat routing
Runtime defaults	`x-eve.defaults`	Harness, workspace, git policies

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

关注点	清单章节	设计决策
服务拓扑	`services`	运行哪些进程、进程间如何连接
基础设施	`services[].x-eve`	托管数据库、入口、角色
构建策略	`services[].build` + `registry`	构建内容、镜像存储位置
发布流水线	`pipelines`	代码从提交到生产环境的流转路径
环境形态	`environments`	存在哪些环境、使用哪些流水线
Agent配置	`x-eve.agents` , `x-eve.chat`	Agent配置文件、团队调度、聊天路由
运行时默认值	`x-eve.defaults`	Harness、工作区、Git策略

设计原则：如果Agent或运维人员无法通过阅读清单理解应用的架构，那么这份清单就是不完整的。

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)

大多数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）

Service Design Rules

服务设计规则

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

单一职责原则：将HTTP服务与后台处理分离。API服务不应同时运行定时任务。
使用托管Postgres数据库：声明
```
x-eve.role: managed_db
```
，由平台负责配置、连接并注入凭证，无需手动配置连接字符串。
显式标记外部服务：对于Eve平台外的服务（如Redis、第三方API），使用
```
x-eve.external: true
```
并配置
```
x-eve.connection_url
```
。
使用
x-eve.role: job
处理一次性任务：数据迁移、初始化填充、数据回填属于任务服务，而非持久化进程。
按需暴露入口：仅为需要外部HTTP访问的服务设置
```
x-eve.ingress.public: true
```
。内部服务通过集群网络通信。

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.

每个已部署的服务都会收到

EVE_API_URL

、

EVE_PUBLIC_API_URL

、

EVE_PROJECT_ID

、

EVE_ORG_ID

和

EVE_ENV_NAME

。服务间调用使用

EVE_API_URL

，面向浏览器的代码使用

EVE_PUBLIC_API_URL

。请设计应用读取这些变量，而非硬编码URL。

Database Design

数据库设计

Provisioning

配置方式

Declare a managed database in the manifest:

yaml

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}

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

yaml

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

在其他服务中引用连接URL：

${managed.db.url}

。

Schema Strategy

架构策略

Migrations are first-class. Use
```
eve db new
```
to create migration files. Use
```
eve db migrate
```
to apply them. Never modify production schemas by hand.
Design for RLS from the start. If agents or users will query the database directly, scaffold RLS helpers early:
```
eve db rls init --with-groups
```
. Retrofitting row-level security is painful.
Inspect before changing. Use
```
eve db schema
```
to examine current schema. Use
```
eve db sql --env <env>
```
for ad-hoc queries during development. Use
```
--direct-url
```
mode for local dev tools that need a raw connection string.
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).

迁移优先：使用
```
eve db new
```
创建迁移文件，使用
```
eve db migrate
```
执行迁移。禁止手动修改生产环境的数据库架构。
从一开始就设计RLS：如果Agent或用户需要直接查询数据库，请尽早搭建RLS辅助工具：
```
eve db rls init --with-groups
```
。后期再添加行级安全会非常繁琐。
先检查再修改：使用
```
eve db schema
```
查看当前架构。开发期间使用
```
eve db sql --env <env>
```
执行临时查询。使用
```
--direct-url
```
模式为本地开发工具提供原始连接字符串。
分离应用数据与Agent数据：使用不同的架构或命名规范。应用表为产品服务；Agent表用于存储记忆与协调（存储模式请参考
```
eve-agent-memory
```
）。

Access Patterns

访问模式

Who Queries	How	Auth
App service	`${managed.db.url}` in service env	Connection string injected at deploy
Agent via CLI	`eve db sql --env <env>`	Job token scopes access
Agent via RLS	SQL with `app.current_user_id()`	Session context set by runtime

查询主体	方式	认证
应用服务	服务环境变量中的 `${managed.db.url}`	部署时注入连接字符串
Agent通过CLI	`eve db sql --env <env>`	任务令牌限制访问范围
Agent通过RLS	使用 `app.current_user_id()` 的SQL语句	运行时设置会话上下文

Build and Release Pipeline

构建与发布流水线

The Canonical Flow

标准流程

Every production app should follow

build -> release -> deploy

yaml

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

Why this matters: The build step produces SHA256 image digests. The release step pins those exact digests. The deploy step uses the pinned release. You deploy exactly what you built — no tag drift, no "latest" surprises.

所有生产环境应用应遵循

构建 -> 发布 -> 部署

流程：

yaml

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       # 将发布版本部署到目标环境

重要性：构建步骤生成SHA256镜像摘要，发布步骤固定这些精确的摘要，部署步骤使用固定的发布版本。你部署的内容与构建的内容完全一致——无标签漂移，无“latest”镜像带来的意外。

Registry Decisions

镜像仓库选择

Option	When to Use
`registry: "eve"`	Default. Internal registry with JWT auth. Simplest setup.
BYO registry (GHCR, ECR)	When you need images accessible outside Eve, or have existing CI.
`registry: "none"`	Public base images only. No custom builds.

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

dockerfile

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

选项	适用场景
`registry: "eve"`	默认选项。带JWT认证的内部仓库，设置最简单。
自备仓库（GHCR、ECR）	需要镜像可在Eve外访问，或已有CI流程时使用。
`registry: "none"`	仅使用公开基础镜像，无需自定义构建。

使用GHCR时，在Dockerfile中添加OCI标签以自动关联仓库：

dockerfile

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

Build Configuration

构建配置

Every service with a custom image needs a

build

section:

yaml

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.

每个需要自定义镜像的服务都需要

build

章节：

yaml

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

使用多阶段Dockerfile，BuildKit原生支持该模式。在最终阶段添加OCI标签。

Deployment and Environments

部署与环境

Environment Strategy

环境策略

Environment	Type	Purpose	Pipeline
`staging`	persistent	Integration testing, demos	`deploy`
`production`	persistent	Live traffic	`deploy` (with promotion)
`preview-*`	temporary	PR previews, feature branches	`deploy` (auto-cleanup)

Link each environment to a pipeline in the manifest:

yaml

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

环境	类型	用途	流水线
`staging`	持久化	集成测试、演示	`deploy`
`production`	持久化	生产流量	`deploy` （需升级）
`preview-*`	临时	PR预览、功能分支	`deploy` （自动清理）

在清单中将每个环境与流水线关联：

yaml

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.

标准部署：

eve env deploy staging --ref main --repo-dir .

触发关联的流水线。

直接部署（绕过流水线）：

eve env deploy staging --ref <sha> --direct

用于紧急情况或简单配置。

升级部署：在预发布环境构建一次，然后将相同的发布产物升级到生产环境。构建步骤的摘要会被保留，确保镜像完全一致。

Recovery

故障恢复

When a deploy fails:

Diagnose:
```
eve env diagnose <project> <env>
```
— shows health, recent deploys, service status.
Logs:
```
eve env logs <project> <env>
```
— container output.
Rollback: Redeploy the previous known-good release.
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.

部署失败时：

诊断：
```
eve env diagnose <project> <env>
```
——显示健康状态、最近的部署记录、服务状态。
日志：
```
eve env logs <project> <env>
```
——容器输出日志。
回滚：重新部署之前验证通过的版本。
重置：
```
eve env reset <project> <env>
```
——终极方案，重新初始化环境。

设计应用时需确保支持回滚：迁移应向前兼容，服务在滚动部署期间应能优雅处理架构版本不匹配问题。

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

密钥解析遵循优先级顺序：项目 > 用户 > 组织 > 系统。项目级的

API_KEY

会覆盖组织级的

API_KEY

。

Design Rules

设计规则

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

按项目设置密钥：使用
```
eve secrets set KEY "value" --project proj_xxx
```
。保持项目密钥独立。
在清单中使用插值：在服务环境块中引用
```
${secret.KEY}
```
，平台会在部署时解析。
部署前验证：运行
```
eve manifest validate --validate-secrets
```
检查缺失的密钥引用，避免部署失败。
本地开发使用
.eve/dev-secrets.yaml
：使用本地值模拟生产环境的密钥，该文件已被Git忽略。
禁止直接在环境变量中存储密钥：始终使用
```
${secret.KEY}
```
插值，确保密钥通过平台的解析与审计链路流转。

Git Credentials

Git凭证

Agents need repository access. Set either

github_token

(HTTPS) or

ssh_key

(SSH) as project secrets. The worker injects these automatically during git operations.

Agent需要仓库访问权限。将

github_token

（HTTPS）或

ssh_key

（SSH）设置为项目密钥。工作进程会在Git操作期间自动注入这些凭证。

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.

按以下步骤逐步排查：

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（回滚）或eve env reset

从最上层开始排查。每个阶段提供的细节更多，成本也更高。大多数问题可在1-2阶段解决。

Pipeline Observability

流水线可观测性

Monitor pipeline execution in real time:

bash

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.

实时监控流水线执行：

bash

eve pipeline logs <pipeline> <run-id> --follow         # 流式查看所有步骤
 eve pipeline logs <pipeline> <run-id> --follow --step build  # 流式查看单个步骤

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

Build Debugging

构建调试

When builds fail:

bash

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.

构建失败时：

bash

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

常见原因：仓库凭证缺失、Dockerfile路径错误、构建上下文过大。

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

为服务设计健康检查端点。Eve会轮询健康状态以判断部署是否就绪。当

ready === true

且

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 managed via
```
eve db new
```
/
```
eve db migrate
```
RLS scaffolded if agents or users query directly
App data separated from agent data by schema or convention

Pipeline:

Canonical
```
build -> release -> deploy
```
pipeline defined
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 planned (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

Observability:

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

服务拓扑：

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

数据库：

通过
```
eve db new
```
/
```
eve db migrate
```
管理迁移
若Agent或用户直接查询，已搭建RLS
应用数据与Agent数据通过架构或规范分离

流水线：

定义了标准的
```
构建 -> 发布 -> 部署
```
流水线
选择了仓库并设置了凭证密钥
Dockerfile中添加了OCI标签（针对GHCR）
镜像摘要通过发布流程流转（无基于标签的部署）

环境：

定义了预发布与生产环境
每个环境都关联了流水线
规划了升级流程（构建一次，多次部署）
了解恢复流程（诊断 -> 回滚 -> 重置）

密钥：

所有密钥通过
```
eve secrets set
```
按项目设置
清单使用
```
${secret.KEY}
```
插值

eve manifest validate --validate-secrets

验证通过

本地开发使用
```
.eve/dev-secrets.yaml
```
配置了Git凭证（
```
github_token
```
或
```
ssh_key
```
）

可观测性：

服务暴露了健康检查端点
理解调试流程（状态 -> 诊断 -> 日志 -> 恢复）
可通过
```
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
```

清单语法与选项：
```
eve-manifest-authoring
```
部署命令与错误解决：
```
eve-deploy-debugging
```
密钥管理与访问组：
```
eve-auth-and-secrets
```
流水线与工作流定义：
```
eve-pipelines-workflows
```
本地开发流程：
```
eve-local-dev-loop
```
在此基础上添加Agent能力：
```
eve-agentic-app-design
```