VoltAgent 部署指南：在 Node.js 服务器与 Serverless 边缘运行时之间选择与落地

人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载本指南以 VoltAgent 官方部署总览为核心系统梳理 VoltAgent 应用在经典 Node.js 服务器与 Serverless边缘运行时两类形态下的部署选项、选型依据、网络绑定配置与平台化工具链并结合仓库源码深入剖析voltagent/server-hono与voltagent/serverless-hono两个 provider 的底层实现原理。读完本文你将掌握为 VoltAgent 项目选择合适的运行环境、配置双栈网络、使用 CLI 脚手架与本地隧道、并完成 Cloudflare Workers / Netlify Functions / VoltOps Deploy 全流程部署的完整能力。支持的部署场景总览VoltAgent 既可以运行在经典 Node.js 服务器中也可以运行在 Serverless边缘运行时中。官方将部署形态归纳为四类场景运行载体典型平台特点ServerNode.jsvoltagent/server-hono或其他 HTTP 层Fly.io、Render、AWS、Railway 等任意主机常驻进程支持长连接、WebSocket 流式输出Serverlessedge统一的 serverless providerCloudflare Workers、Vercel Edge、Deno Deploy低延迟、全球就近响应按请求计费Serverless FunctionsNode 兼容的函数运行时Netlify Functions 等保留 Node 兼容性同时享受托管冷启动Hybrid混合Node 服务器 边缘端点任意组合重活留在 Node 端轻量端点暴露在边缘其中边缘运行时的支持是通过voltagent/serverless-hono包实现的。该包基于 Hono 框架构建一个 fetch 型 provider 即可同时覆盖 Cloudflare Workers、Vercel Edge、Deno Deploy 与 Netlify Functions见 serverless-hono/README.md避免了为每个平台维护独立实现。从源码结构看VoltAgent实例通过构造参数中的server或serverless二选一来决定运行时形态。调用voltAgent.serverless()时如果未配置 serverless provider 会直接抛出错误见 voltagent.ts这保证了两种模式在 API 层面是互斥且明确的。何时选择哪种部署形态选型没有绝对优劣官方建议按以下维度权衡选择 Node.js当应用需要长时间运行的任务、重度状态、或大量保持打开的连接时。Node 常驻进程天然适合 WebSocket 实时流式输出hono-server-provider.ts 中enableWebSocket默认开启会创建 WebSocket 服务器并处理升级请求。选择 Serverlessedge当全球覆盖和极低延迟比本地磁盘访问、Node 专属库更重要时。边缘运行时按请求冷启动无需管理服务器。可观测性两种模式均可用在 Serverless 运行时下VoltAgent 会退化为 HTTP 轮询而非 WebSocket 流式推送——这一点在 app-factory.ts 中有直接体现/ws路由返回明确的提示信息WebSocket streaming is not implemented in the serverless runtime yet. Falling back to HTTP polling.Node.js 服务器的网络绑定配置IPv6 与双栈部署到现代云平台时网络绑定配置是高频踩坑点。Railway 和 Fly.io 等平台使用 IPv6 或双栈网络此时需要让服务器同时绑定 IPv4 和 IPv6import { VoltAgent } from voltagent/core; import { honoServer } from voltagent/server-hono; new VoltAgent({ agents: { myAgent }, server: honoServer({ port: parseInt(process.env.PORT || 3141), hostname: ::, // Binds to both IPv4 and IPv6 }), });hostname的具体语义在服务器架构文档中有完整说明默认行为IPv4不传hostname时默认绑定0.0.0.0接受所有 IPv4 接口的连接。IPv6 双栈生产环境推荐传::同时绑定 IPv4 与 IPv6兼容现代云平台网络基础设施。仅本机开发传127.0.0.1限制仅本机访问适合本地调试。在实现层面HonoServerProvider的startServer方法将hostname直接透传给hono/node-server的serve()函数见 hono-server-provider.ts端口则通过portManager.allocatePort统一分配hono-server-provider.ts启动失败时会自动释放端口。部署工具链CLI、本地隧道与现成模板volt deploy一键生成部署配置VoltAgent CLI 提供deploy命令来脚手架部署文件Wrangler 配置、Netlify/Vercel 模板等。命令定义位于 deploy.ts支持四种目标npm run volt deploy --target cloudflare npm run volt deploy --target netlify npm run volt deploy --target vercel npm run volt deploy --target voltops实现细节值得注意SUPPORTED_TARGETS仅包含voltops、cloudflare、vercel、netlify四个值传入其他目标会输出错误并终止deploy.ts。不带--target时会通过inquirer交互式询问目标平台默认voltops。CLI 使用ensureFile幂等写入目标配置文件如wrangler.toml已存在则不覆盖避免破坏用户已有配置deploy.ts。Cloudflare 目标生成的 cloudflare-wrangler.toml 模板 与 Netlify 目标生成的 netlify.toml 模板 都以Generated by VoltAgent CLI注释开头方便用户识别与后续编辑。volt tunnel本地服务器的 HTTPS 隧道开发调试阶段可用隧道将本机服务分享给无法访问localhost的协作者、webhook 回调或移动设备完整步骤见本地隧道指南pnpm volt tunnel 3141 # 随机子域名 pnpm volt tunnel 3141 --prefix agent # 持久子域名 前缀Core/Pro npx voltagent/cli tunnel 3141 # 免安装一次性使用隧道行为由 tunnel.ts 实现要点包括默认端口为3141可省略参数。前缀校验规则1–20 字符、仅字母数字与短横线、必须以字母或数字开头且www、mail、admin、console、api-voltagent为保留前缀tunnel.ts。volt login后 Core/Pro 用户可获得基于用户名的持久子域名如john-doe.tunnel.voltagent.dev免费用户每次获得随机子域名。令牌有效期 365 天防火墙需放行到*.tunnel.voltagent.dev的出站 HTTPS 流量。隧道仅用于开发与演示不适合生产流量关闭隧道按CtrlC即可。现成示例模板仓库examples/目录提供了可直接运行的部署模板与本主题强相关的两个是examples/with-cloudflare-workers最小 Worker 入口voltAgent.serverless().toCloudflareWorker()加wrangler.toml并附 D1 绑定示例。examples/with-netlify-functions单入口 Netlify Functionnetlify/functions/voltagent.ts中通过createNetlifyFunctionHandler(getVoltAgent())暴露netlify.toml中配置/*全量重定向到该函数。平台部署详解VoltOps Deploy托管部署GitHub 集成VoltOps Deploy 指南 是官方托管部署方案连接 GitHub 仓库后即可零配置部署 AI Agent自动签发 SSL 证书并支持自定义域名。核心能力包括GitHub 集成通过 VoltOps GitHub App 连接公有或私有仓库公有仓库也可直接输入 URL。自动部署开启 Auto-deploy 后每次 push 到所选分支都会触发 Webhook 部署。环境变量管理区分运行时变量、构建期变量与加密的 Secret 值Secret 在 UI 与日志中隐藏支持将.env文件内容直接粘贴批量导入。自定义域名在 Domains 标签页添加域名创建指向目标地址的 CNAME 记录DNS 生效后自动签发 SSL。HTTP Basic AuthPro 计划可启用用户名密码保护。Agent Discovery从部署面板直接查看已注册的 agents 与 workflows。构建系统自动检测仓库内容支持 Dockerfile 与 Nixpacks 两种构建方式。CLI 中的volt deploy --target voltops会直接在浏览器打开console.voltagent.dev/deployments控制台deploy.ts。Cloudflare Workers边缘运行时部署Cloudflare Workers 部署指南 是边缘部署的完整流程此处提炼关键步骤前置条件Node.js 18、pnpm或npm、Cloudflare 账号与wranglerCLI、LLM 提供方 API Key如OPENAI_API_KEY可选VOLTAGENT_PUBLIC_KEY与VOLTAGENT_SECRET_KEYVoltOps 可观测性。生成项目文件npm run volt deploy --target cloudflareCLI 自动写wrangler.toml、serverless 入口文件并提示环境变量或手动创建。环境变量使用wrangler secret put存储或在wrangler.toml的vars/env.production下声明。Serverless 入口文件最小示例import { VoltAgent, Agent, Memory, InMemoryStorageAdapter } from voltagent/core; import { serverlessHono } from voltagent/serverless-hono; import { openai } from ai-sdk/openai; import { weatherTool } from ./tools; const memory new Memory({ storage: new InMemoryStorageAdapter(), }); const agent new Agent({ name: serverless-assistant, instructions: Answer user questions quickly., model: openai(gpt-4o-mini), tools: [weatherTool], memory, }); const voltAgent new VoltAgent({ agents: { agent }, serverless: serverlessHono(), }); export default voltAgent.serverless().toCloudflareWorker();wrangler.toml配置name voltagent-worker main dist/index.js compatibility_date 2025-01-01 workers_dev true compatibility_flags [ nodejs_compat, nodejs_compat_populate_process_env, no_handle_cross_request_promise_resolution, ]三个compatibility_flags各有明确作用nodejs_compat启用 VoltAgent 依赖的 Node API 兼容层。nodejs_compat_populate_process_env把 Cloudflare env 绑定镜像到process.env让 VoltAgent 无需额外配置即可读取 secret。no_handle_cross_request_promise_resolution消除后台导出产生的噪音告警与内部waitUntil调用方式对齐。运行与部署pnpm install pnpm wrangler dev # 本地边缘沙箱--local 仅用于 Node 专属调试 pnpm wrangler deploy # 部署后得到 workers.dev URL curl https://your-worker.workers.dev/将 Cloudflare 绑定D1/KV/R2接入 AgentCloudflare 绑定通过 Workerfetch处理函数的env参数暴露。若工具、工作流步骤或 memory 适配器需要绑定正确的模式是把 VoltAgent 实例构建放进一个接收env的工厂函数中并闭包捕获const createWorker (env: Env) { const memory new Memory({ storage: new D1MemoryAdapter({ binding: env.DB }), }); const agent new Agent({ name: serverless-assistant, instructions: Answer user questions quickly., model: openai(gpt-4o-mini), tools: makeTools(env), memory, }); const voltAgent new VoltAgent({ agents: { agent }, serverless: serverlessHono(), }); return voltAgent.serverless().toCloudflareWorker(); }; let cached: ReturnTypetypeof createWorker | undefined; export default { fetch: (request: Request, env: Env, ctx: ExecutionContext) { if (!cached) { cached createWorker(env); } return cached.fetch(request, env, ctx); }, };D1MemoryAdapter来自voltagent/cloudflare-d1包pnpm add voltagent/cloudflare-d1D1 绑定在wrangler.toml中声明[[d1_databases]] binding DB database_name voltagent database_id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx在路由执行时VoltAgent 还会把 Worker 的env注入执行上下文 Map工具或工作流步骤可通过SERVERLESS_ENV_CONTEXT_KEY定义于 context-keys.ts随时读取import { createTool, SERVERLESS_ENV_CONTEXT_KEY } from voltagent/core; import type { D1Database } from cloudflare/workers-types; import { z } from zod; export const listUsers createTool({ name: list-users, description: Fetch users from D1, parameters: z.object({}), execute: async (_args, options) { const env options?.context?.get(SERVERLESS_ENV_CONTEXT_KEY) as Env | undefined; const db env?.DB; if (!db) { throw new Error(D1 binding is missing (env.DB)); } const { results } await db.prepare(SELECT id, name FROM users).all(); return results; }, });注意D1MemoryAdapter本身不需要读取该 key它通过工厂闭包直接拿到env.DBSERVERLESS_ENV_CONTEXT_KEY是为无法走闭包路径的临时访问场景准备的。底层路由实现见 routes.tsgetServerlessEnv从 Hono 上下文读取c.env再通过mergeContextWithServerlessEnv注入到工具/工作流执行的 options 与 context 中。Netlify FunctionsNode 兼容的函数部署Netlify Functions 部署指南 演示了复用同一套 Hono HTTP API与 Cloudflare 示例一致在 Netlify Functions 上运行。前置条件为 Node.js 20、netlifyCLI、OpenAI API Key。生成文件npm run volt deploy --target netlify会生成 netlify.toml 模板随后手动添加netlify/functions/voltagent.ts与src/index.ts。环境变量Netlify Functions 通过process.env暴露 secret可直接依赖 VoltAgent 默认环境检测netlify secrets:set OPENAI_API_KEY netlify secrets:set VOLTAGENT_PUBLIC_KEY netlify secrets:set VOLTAGENT_SECRET_KEYAgent 设置创建一次、跨调用复用import { Agent, VoltAgent } from voltagent/core; import { serverlessHono } from voltagent/serverless-hono; import { openai } from ai-sdk/openai; import { weatherTool } from ./tools; const assistant new Agent({ name: netlify-function-agent, instructions: Answer user questions and call tools when needed., model: openai(gpt-4o-mini), tools: [weatherTool], }); const voltAgent new VoltAgent({ agents: { assistant }, serverless: serverlessHono(), }); export function getVoltAgent() { return voltAgent; }函数处理器voltagent/serverless-hono导出的createNetlifyFunctionHandler会把 Lambda 事件自动转换为 Fetch 请求import { createNetlifyFunctionHandler } from voltagent/serverless-hono; import { getVoltAgent } from ../src/index; const voltAgent getVoltAgent(); export const handler createNetlifyFunctionHandler(voltAgent);netlify.toml[functions] node_bundler esbuild directory netlify/functions [[redirects]] from /* to /.netlify/functions/voltagent/:splat status 200 force true重定向规则让所有 HTTP 路由/agents、/observability、/workflows等都指向同一个函数模拟 Cloudflare Workers 的路由行为。本地运行与部署pnpm install pnpm netlify dev # 本地 http://localhost:8888 curl http://localhost:8888/agents # 验证路由 pnpm netlify deploy --prodServerless provider 的底层原理源码级理解serverlessHono()背后的实现有助于排查部署问题。核心类HonoServerlessProvider位于 serverless-provider.ts关键机制如下运行时自动检测auto()方法通过 runtime-detection.ts 判断当前环境——存在globalThis.Deno判为 Deno、存在EdgeRuntime判为 Vercel、navigator.userAgent含 Cloudflare 判为 Cloudflare未知则默认走 Cloudflare Worker 形态。三种形态分别由toCloudflareWorker()、toVercelEdge()、toDeno()生成 fetch 处理器。waitUntil生命周期管理Cloudflare 等平台通过ctx.waitUntil注册后台任务如 OTLP 遥测导出。wait-until-wrapper.ts 将waitUntil绑定到全局___voltagent_wait_until随后deferCleanupserverless-provider.ts用一个跟踪代理记录所有由工具与可观测性导出器注册的 promise只有全部 promise 落定后才执行清理保证全局在请求整个生命周期内可用平台没有waitUntil时则回退为立即清理。Netlify 事件适配netlify-function.ts 中的createRequest负责把 Netlify 的 Lambda 事件含multiValueHeaders、rawUrl、isBase64Encoded等字段重建为标准的Request对象toNetlifyResponse则把Response转回 Netlify 函数结果格式body 以 base64 编码返回。路由一致性serverless 模式与 Node 模式共享同一套业务路由。从 app-factory.ts 可见serverless 应用注册了 Agent、Workflow、Tool、Log、Update、Memory、Observability、Trigger、A2A 共九类路由并默认启用 CORScorsOrigin默认*同时内置/ws探测路由用于指导 Console UI 回退到 HTTP 轮询。可观测性两种模式下的差异Node.js 模式WebSocket 流式推送可用VoltOps Console 可实时推送事件。Serverless 模式内存 span/log 存储默认开启可通过/observabilityREST 端点拉取 traces若配置了 VoltOps 凭据Worker 会通过 OTLP fetch 导出遥测经waitUntil执行不阻塞响应VoltOps Console 回退为 HTTP 轮询暂无 WebSocket 流式能力对应 app-factory.ts 中/ws的 200 兜底响应。Netlify Functions 特有注意点OTLP 导出通过 fetch 带重试执行但Lambda 执行会等待该响应返回需留意冷启动时长的影响。功能限制与依赖审查部署前必须核对运行时限制部分内容来自 cloudflare-workers.md 与 netlify-functions.md 的 Feature limitations 章节MCP client/server 暂不可用于 serverless 运行时当前 MCP 实现依赖 Node 的 stdio/网络 API请将 MCP 提供方部署在 Node 服务上。libSQL memory 适配器需要 TCP socket在 Netlify Functions 上不可用请改用内存适配器或外部 Postgres/Supabase 数据库。Serverless 边缘运行时不支持 Node-only API如fs、netVoltAgent core 会避开这些 API但自定义代码必须遵守同样的约束。WebSocket 流式在 serverless 运行时不可用流式与可观测性均退化为 HTTP 轮询/拉取。在 memory 选择上serverless 环境推荐组合包括默认InMemoryStorageAdapter、Cloudflare D1D1MemoryAdapter、外部 PostgreSQLPostgresMemoryAdapterPostgresVectorAdapter、SupabaseSupabaseMemoryAdapter以及 Turso/LibSQLLibSQLMemoryAdapter需/edge入口各适配器所在包分别为voltagent/core、voltagent/cloudflare-d1、voltagent/postgres、voltagent/supabase、voltagent/libsql。下一步行动清单按以下顺序推进部署审查依赖确认所有自定义代码未使用边缘运行时不可用的 Node-only APIfs、net等。选择平台按本指南选型矩阵确定 Node.js 服务器、Serverless 边缘或 Serverless 函数需要托管与 GitHub 集成时优先评估 VoltOps Deploy。脚手架npm run volt deploy --target cloudflare|netlify|vercel|voltops生成部署文件或参照 examples/with-cloudflare-workers 与 examples/with-netlify-functions 手动搭建。配置网络与环境变量Node 服务器部署到 IPv6 平台时设置hostname: ::各平台按wrangler secret put/netlify secrets:set等方式注入 LLM API Key 与 VoltOps 凭据。本地验证wrangler dev/netlify dev跑通路由配合volt tunnel向协作者暴露临时 HTTPS 地址。部署与监控使用对应平台 CLIwrangler deploy、netlify deploy --prod、vercel deploy发布部署后通过wrangler tail/netlify logs与/observabilityREST 端点持续观测 Agent 运行状态。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐carapace-bin 支持哪些 shell一文带你了解 Fish、Nushell、Powershell 等 10 种 shell 配置carapace bin 支持哪些 shell一文带你了解 Fish、Nushell、Powershell 等 10 种 shell 配置 carapace告别单调光标3分钟掌握macOS鼠标指针个性化定制告别单调光标3分钟掌握macOS鼠标指针个性化定制 你是否已经厌倦了macOS系统千篇一律的白色箭头光标每天面对相同的鼠标指针是否觉得工作桌面缺乏个性现桌面应用在 Cloudflare Workers 上部署 VoltAgent AI AgentServerless 边缘部署完整指南在 Cloudflare Workers 上部署 VoltAgent AI AgentServerless 边缘部署完整指南 导读 本指南以 examples人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音上一篇OOMWOO路线图全解从MVP手动建图到爬楼梯机器人的四阶段演进规划下一篇vue/composition-api迁移到Vue 2.7终极无痛升级路径和注意事项创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考