eve 部署指南：从 Vercel 托管到自建 Node 服务的完整生产化方案

• 人工智能
• AI Agent
• Agent 框架
• 后端
• 工具调用

本指南围绕 eve 官方部署概览展开，系统讲解在 Vercel 与自建基础设施两种策略下，如何完成eve build构建、模型凭据与路由鉴权配置、工作流持久化、沙箱选型、反向代理与健康检查，最终把 agent 真正运行到生产环境。读完本文，你将掌握 eve 生产部署的完整决策链路、可复制的命令行操作与配置文件，以及这些行为背后的源码实现依据。

部署策略总览：先决定运行时在哪里

eve 的部署起点不是“选框架”，而是先确定 eve 运行时（runtime）的运行位置。部署策略直接决定了三件事：构建产物形态、工作流（Workflow）存储方式、沙箱（Sandbox）提供方，进而影响路由与进程拓扑。

无论选择哪种策略，一个关键事实保持不变：agent 基于文件系统的配置（agent/目录下的agent.ts、channels/、tools/、sandbox/等）在两种策略间完全可移植。换平台不需要重写 agent，只需要更换构建宿主与运行时周边设施。

此外 eve 是前端无关（frontend agnostic）的：同一个 agent 可以嵌入 Next.js、Nuxt、SvelteKit 或 TanStack Start 应用，也可以独立运行后通过 HTTP 路由对外提供服务，详见 Frontend integrations。

生产就绪五步检查清单

任何生产部署都必须满足同一组运行时要求，官方给出五步清单：

1. 执行eve build：编译 agent 并生成宿主侧输出产物；
2. 提供模型凭据：以及工具、连接（connections）和路由鉴权所需的全部 secrets；
3. 替换placeholderAuth()：在浏览器流量进入前，换成真正的生产路由策略；
4. 选择与宿主匹配的工作流与沙箱实现；
5. 验证健康路由并完成一次真实的 agent turn。

eve build总会把编译器产物写入.eve/目录；Vercel 构建额外写入.vercel/output；面向其他宿主的构建则输出标准的 Nitro 服务端到.output/。

从源码看，build 命令实现 会区分两种路径：workspace 根目录下的eve build调用buildAgentWorkspace生成 Vercel 部署产物；单个 agent 目录下则走 Nitro 的buildApplication，其中publicRoutePrefix由环境变量EVE_PUBLIC_ROUTE_PREFIX规范化而来——这正是后文“路径挂载”一节会再次用到的配置项。

凭据配置：模型、工具与路由鉴权分开管理

凭据必须放在部署环境变量或密钥管理器中，绝不能写进源码或编译产物。

模型凭据的两种形态

你的模型配置决定了需要哪种凭据：

• 字符串模型 ID（Gateway 路径）：例如"anthropic/claude-opus-5.5"，请求经由 Vercel AI Gateway 路由。在 Vercel 上通过项目 OpenID Connect（OIDC）自动鉴权，无需 provider API key；在非 Vercel 宿主上则需要设置AI_GATEWAY_API_KEY。
• provider 直连模型：使用该 provider 的 AI SDK 包与 API key，在agent.ts中传入LanguageModel对象。

从实现看，网关凭据解析逻辑 依次检查MODEL_CONNECTION_ENV选择、AI_GATEWAY_API_KEY环境变量，最后回退到 Vercel OIDC token——这印证了文档中“非 Vercel 宿主用AI_GATEWAY_API_KEY、Vercel 宿主走项目 OIDC”的行为。

模型配置的完整写法见 Agent configuration：字符串 ID、anthropic()/openai()帮助函数、chatgpt()（仅本地开发）、动态模型defineDynamic({ events })等。生产部署与本地开发的凭据来源不同：本地可用/login保存的凭据，部署环境必须把 API key 放进服务端环境变量。

路由鉴权独立于模型访问

生产路由鉴权（route auth）必须与模型访问分开配置。eve 默认策略（[vercelOidc(), localDev(), placeholderAuth()]）在生产环境拒绝浏览器流量——placeholderAuth()在生产会返回结构化401，而localDev()只在eve dev/vercel dev进程内放行。

可用的鉴权策略与 secrets 要求见 Authentication，包括：

• 有序鉴权链（auth walk）：auth接受单个AuthFn或数组，eve 按顺序走：返回SessionAuthContext即放行；返回null/undefined跳到下一项；抛出异常则以指定状态拒绝。全部跳过则返回401并携带声明的挑战方案（Basic/Bearer）。
• 内置 verifier 帮助函数：localDev()、vercelOidc()、none()、httpBasic(...)、jwtHmac(...)、jwtEcdsa(...)、oidc(...)，以及底层纯函数verifyHttpBasic/verifyJwtHmac/verifyJwtEcdsa/verifyOidc/verifyVercelOidc。
• 自定义AuthFn：例如从应用会话解析 principal 后返回{ authenticator, principalId, principalType }，可完全取代 Vercel OIDC。自定义函数默认不声明挑战方案，可用withAuthChallenges(fn, challenges)包装。
• 网络策略：createIpAllowList(...)/isIpAllowed(...)在任何模型工作开始前就拦截请求。

自托管场景不要把vercelOidc()当作唯一的生产认证器：应配置 Basic auth、JWT 校验、通用 OIDC 或自定义 verifier。鉴权 secrets（如ROUTE_AUTH_BASIC_PASSWORD、签名密钥）只存在于环境变量，运行时在启动时从编写的 channel 定义中重新物化，永远不会进入编译产物。

生产部署前的关键检查：替换 placeholderAuth

eve init脚手架生成的agent/channels/eve.ts带有placeholderAuth()护栏：

import { eveChannel } from "eve/channels/eve"; import { localDev, placeholderAuth, vercelOidc } from "eve/channels/auth"; export default eveChannel({ auth: [vercelOidc(), localDev(), placeholderAuth()], });

在生产中，placeholderAuth()返回结构化的401，让生成的 Web Chat 应用显示“auth 尚未配置”，而不是抛内部错误。在任何浏览器调用方提交生产请求之前必须替换它：换成应用自己的AuthFn或某个内置 helper；也可以直接删掉该 channel 文件，让 eve 使用默认 channel 源（同样拒绝生产流量）。注意健康路由由eveChannel()创建，是公开的、跳过鉴权链，因此负载均衡器与 uptime 探针无需凭据即可探测。

自托管部署：构建并启动 Node 服务

当你在自己的基础设施上运行 Node 服务、容器平台或反向代理时，选择自托管。核心操作只有两条命令：

eve build PORT=3000 eve start --host 0.0.0.0

• eve build把 Nitro 服务端写到.output/；
• eve start服务该产物，端口既可来自PORT环境变量也可用--port标志；
• 进程管理（TLS、扩缩容、重启、日志采集）交给与 Node Web 服务相同的进程管理器或容器平台。

自托管下的模型访问与路由鉴权

• 非 Vercel 宿主使用字符串模型 ID 时，设置AI_GATEWAY_API_KEY走 Vercel AI Gateway；要直连 provider，则安装其 AI SDK provider 包，在agent.ts中传入模型对象并配置 API key（示例见 Agent configuration）。
• 不要依赖vercelOidc()作为 Vercel 之外唯一的生产认证器，改用 Basic auth、JWT、通用 OIDC 或自定义 verifier（见 Authentication）。

持久化工作流状态

默认的本地 Workflow world 把运行状态存在.eve/.workflow-data下。必须把该目录挂载到持久存储，否则进程或容器替换会导致运行状态丢失。

也可以在根agent.ts中选择一个已安装的 Workflow world 包：

import { defineAgent } from "eve"; export default defineAgent({ experimental: { workflow: { world: "@acme/eve-workflow-world", }, }, });

注意事项（均有源码级依据）：

• 包必须默认导出一个工厂函数或createWorld()函数；
• 凭据与宿主选项从运行时环境变量读取，不写在agent.ts中；
• 必须安装与 eve 版本同一@workflow/*线构建的 world：当前线是5.0.0-beta，运行时拒绝不兼容的协议版本；npm 的latest标签可能落后，未锁版本安装可能拉到被拒绝的协议版本；
• 若该包在托管产物中必须保持外部，在build.externalDependencies中列出；
• 底层抽象见 Workflow Worlds）。

选择沙箱提供方

默认沙箱环境按本地可用性依次选择 Docker、microsandbox 或 just-bash（Vercel 上则选 Vercel Sandbox，见 Default Sandbox）。你可以显式选择某个 provider，或用defineSandboxProvider()为容器、虚拟机或隔离服务实现自定义 provider。

注意：除非自托管进程确实要创建托管 Vercel 沙箱，否则不要选择VercelSandbox.environment()。provider 配置与选择顺序见 Sandbox。

配置反向代理路由：两个前缀缺一不可

自托管时，必须把两个运行时路由前缀都转发到 eve，且不要改写路径：

• /eve/：健康检查、会话、流式输出、channel、工具与 subagent；
• /.well-known/workflow/：接收工作流回调。

官方明确警告：如果代理只转发/eve/，会话虽然能启动，但回调无法到达 eve 时运行会卡死。这是自托管最容易踩的坑，务必在 ingress 配置里同时保留两个前缀。

自托管多成员工作区：每个成员一个独立服务

agent 工作区（workspace）运行时并不依赖 Vercel 或前端。关键区别：从 workspace 根目录执行eve build产生的是 Vercel 工作区部署，而不是一组自托管 Node 服务器。要自托管，必须在每个成员自己的目录里分别构建：

(cd agents/support && npx eve build) (cd agents/research && npx eve build)

然后分别启动（可放进进程管理器）：

(cd agents/support && npx eve start --host 127.0.0.1 --port 3001) (cd agents/research && npx eve start --host 127.0.0.1 --port 3002)

官方给出的 Caddy 配置示例，为每个 agent 分配独立 origin 并原样转发两个前缀：

support.example.com { reverse_proxy 127.0.0.1:3001 } research.example.com { reverse_proxy 127.0.0.1:3002 }

每个成员都要应用前面提到的鉴权、持久存储与沙箱配置：默认本地 Workflow world 下，持久化各成员自己的.eve/.workflow-data。如果 agent 之间互相委派，必须配置显式的 workspace-peer 传输（含 peer 的 URL 与凭据）——默认传输要求 Vercel；同时确保回调 URL 对发起调用的服务可达。

为自托管工作区挂一个对等前端

apps/web/下的前端是宿主管辖的另一项服务，不由eve start管理，用框架自身命令构建启动。浏览器客户端可用useEveAgent({ host: "https://support.example.com" })直连（需配置 CORS 与浏览器凭据），或经反向代理把每个 agent 挂载到前端 origin 上。

路径挂载场景有两个要点：

1. 转发到 agent 前先剥离公共前缀，并在该 agent 的构建与运行环境中都设置EVE_PUBLIC_ROUTE_PREFIX（构建命令实现见 build.ts，运行时同样读取该环境变量以对齐公共路由前缀）；
2. 工作流回调路由与 eve 路由都要转发，且浏览器客户端、回调 URL、peer 传输要与公共挂载保持一致。

如果你希望 Next.js 自行启动已构建的 agent 进程并提供浏览器侧代理路由，可以使用eve/next集成；它是可选项，eve/vercel配置不会被自托管进程管理器使用。

自托管下的定时任务（schedules）

标准的eve build && eve start路径会启动 Nitro 的 schedule runner。若你把产物改造成自定义 HTTP-only 宿主或 preset，则需要运行 Nitro scheduled tasks，或在自己的调度器里调用同样的工作。

Vercel 部署：链接、构建与组合服务图

选择 Vercel 意味着让框架的托管构建与运行时集成替你运维 Web 服务、工作流、沙箱、调度与部署可观测性。

链接 Vercel 项目

在项目根目录（workspace 用 workspace 根，而不是成员目录）执行：

eve link

该命令链接已有项目或创建新项目，然后拉取环境变量。非交互场景可指定项目名：

eve link --project your_project_name --non-interactive

账户涉及多个团队时加--team。eve link在项目不存在时自动创建。

Vercel 上的凭据与鉴权

• 字符串模型 ID 走 Vercel AI Gateway，通过项目 OIDC 鉴权，该路径无需 provider API key；
• 直连 provider、工具与 connections 的凭据加入 Vercel 项目环境变量；
• 路由鉴权策略所需的签名密钥或密码同样加入项目环境，且必须在浏览器发出生产请求前替换placeholderAuth()。

显式选择 Vercel 沙箱

默认环境在 Vercel 上自动选 Vercel Sandbox；显式写法：

import { defineSandbox } from "eve/sandbox"; import { VercelSandbox } from "eve/sandbox/vercel"; export const environment = VercelSandbox.environment(); export default defineSandbox(() => environment.open());

沙箱准备、资源限制、网络策略与生命周期见 Sandbox。一个值得注意的细节：当环境使用VercelSandbox.environment({prepare})或存在 seed 文件时，Vercel 构建期间 eve 会创建或复用快照备份的模板；prewarm 失败会导致部署中止。

组合 agent 与其他 Vercel 服务

单一 agent 项目（无前端）直接用eve build。agent-only workspace 则从 workspace 根运行：eve 为每个成员生成独立构建的服务与/<name>/eve/v1/*传输路由，所有成员在同一个 Vercel 项目中一起部署（成员规则见 Project Structure）。

当 agent 与其他应用是对等服务时，使用eve/vercel的withEve：它把工作区 agent 贡献给 Vercel 服务图，不管理也不要求特定前端框架，且让项目生命周期与 Next.js 解耦。独立 agent（或带 peer Next.js 前端的 workspace）用根vercel.ts替代vercel.json：

import { withEve } from "eve/vercel"; export default await withEve({ services: { web: { framework: "nextjs", root: "apps/web", buildCommand: "node ../../node_modules/next/dist/bin/next build", }, }, routes: [ { src: "^(.*)$", destination: { type: "service", service: "web" }, }, ], });

withEve的语义要点：

• Vercel 在解析服务图之前求值vercel.ts；withEve把根 agent（或每个直接 workspace 成员）作为独立构建的服务加入，返回普通 Vercel 配置；
• 命名 workspace agent 挂载在/eve/<name>/v1/*，根 agent 挂载在/eve/v1/*；前端与每个 eve agent 分别构建，前端无需withEve或构建脚本；
• 生成的传输路由插入在 filesystem handler 之前（或没有该 handler 时插入在 authored routes 之前）；withEve遇到与生成 agent 冲突的 authored service key 或精确传输路由会抛错而非覆盖——需要删除 authored 路由、重命名 authored service，withEve会自动添加两者；services数组形式的名称也必须唯一；
• 自定义 agent channel 端点不会自动发布，需显式路由到生成的服务：

  routes: [ { src: "^/webhooks/github$", destination: { type: "service", service: "eve-triage" } }, { src: "^(.*)$", destination: { type: "service", service: "web" } }, ],

• 一个 Vercel 项目只能有一个配置源，采用vercel.ts时删除vercel.json；根 package 依赖中保留eve，Vercel 求值配置时才能 importeve/vercel；
• 已 authored 的 eve 服务路由在/eve/v1使用协议路径，回调仍在/eve/v1/callback/*；命名挂载如/eve/support会把挂载加在协议路径之前，得到/eve/support/v1/callback/*；
• 本地完整服务图可用 Vercel CLI 59.16.0+ 的vercel dev --local启动（生成项目暴露为pnpm dev:all），命名 agent 在开发环境使用同样的/eve/<name>/v1/*路由，默认defineWorkspaceAgent传输无需部署凭据即可调用 peer。

执行部署

从项目根部署已链接项目到生产：

eve deploy

eve deploy会安装依赖、运行vercel deploy --prod --logs展示构建日志、部署后拉取项目环境。也可以推送到 Git 连接的 Vercel 项目。托管 Vercel 构建会设置VERCEL，因此eve build会把部署包写到.vercel/output。

当eve deploy创建新 Vercel 项目时，会配置 trace sampling 让 traces 自动出现在 Agent Runs 中（可用--no-trace-sampling跳过）。非交互部署需预先确认生产部署，--project会先链接，新项目无需单独eve link：

eve deploy --project your_project_name --non-interactive --yes

Vercel 用生成产物配置以下服务：

• Web 运行时：提供健康、会话、流、channel、回调与调度路由；
• Vercel Workflow：持久化并恢复 durable runs，启用乐观重放前置条件（stale 事件日志快照在提交前重新加载）；
• Vercel Cron：调用 authored schedules；
• Vercel Sandbox：运行默认沙箱环境选择的沙箱会话。

部署验证：健康路由 + 远程 TUI 真实对话

部署完成后，先检查公开健康路由：

curl https://your_agent.example.com/eve/v1/health

Vercel 场景中，无名 agent 是：

curl https://your_agent.vercel.app/eve/v1/health eve remote connect --url https://your_agent.vercel.app

workspace agent 要带上公共/eve/<name>挂载，例如：

curl https://your_agent.vercel.app/eve/support/v1/health eve remote connect --url https://your_agent.vercel.app/eve/support

然后连接开发终端 UI（TUI）到部署并发送一条真实消息：

eve remote connect --url https://your_agent.example.com

如果 Vercel 部署启用了 Deployment Protection，本地需先设置VERCEL_AUTOMATION_BYPASS_SECRET。健康路由/eve/v1/health的公开 GET 路由在源码测试中有明确依据（见 build-agent-info-response.test.ts），远程连接能力由 TUI 的 remote-connection.ts 实现。

部署后的持续配置

生产部署并不止于上线，官方建议继续完成以下配置：

• 鉴权：配置宿主的路由策略，见 Authentication；
• 可观测性：导出 traces 并诊断运行时故障，见 Instrumentation；Vercel 上可进入 Observability 的Agent Runs标签浏览会话与对话 traces；
• 沙箱：选择并加固沙箱 provider，见 Sandbox。

小结：两种策略的共同心法

无论选择 Vercel 还是自托管，生产化的内核是一致的：eve build统一产出编译产物与宿主输出；模型凭据、路由鉴权 secrets、工作流持久化、沙箱提供方按宿主分别落地；最后用公开健康路由加eve remote connect完成真实 turn 验证。区别只在于“谁替你运营”：

• Vercel：运营 Web 运行时、Workflow、Cron、Sandbox 与可观测性，你用eve link/eve deploy/withEve组合服务图；
• 自托管：你运营 Nitro Node 服务，自己管理.eve/.workflow-data持久化、沙箱选择、两个路由前缀的反向代理与进程生命周期。

选好策略、配好凭据与鉴权、验证真实对话——你的 eve agent 就完成了从开发到生产的最后一步。

• 人工智能
• AI Agent
• Agent 框架
• 后端
• 工具调用