尧图网站建设 
在 Cloudflare Workers 上运行 Rivet ActorsRaw Fetch Router 手写路由完整实战指南【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actorsRivet Actors 是有状态工作负载的原语专为 AI Agent、协作应用与持久化执行而生。本篇基于仓库中的 hello-world-cloudflare-workers-raw 示例讲解如何在 Cloudflare Workers 上托管一个带状态的自增计数 Actor并用手写的fetch路由与 Rivet 官方 Manager API默认挂载在/api/rivet共存在同一个 Worker 中。读完本文你将掌握rivetkit/cloudflare-workers的setup/createHandler组合用法、rivet dev本地联调流程、RIVET_ENDPOINT环境变量的配置语义以及如何从客户端调用 Actor 的 Actions。示例概览一个无框架依赖的“裸路由”Worker与 hello-world-cloudflare-workers纯 Rivet 处理一切和 hello-world-cloudflare-workers-hono挂载 Hono 应用不同本示例刻意不引入任何路由框架你只需提供一个符合标准签名的fetch(request)函数用原生URL解析与正则匹配完成路由。这也是官方文档 Cloudflare Workers Quickstart 中明确列出的三种集成方式之一Default / Hono / Raw。示例的核心文件结构如下examples/hello-world-cloudflare-workers-raw/ ├── src/index.ts # Actor 定义 setup createHandler 手写路由 ├── scripts/client.ts # 独立客户端脚本验证端到端调用 ├── wrangler.toml # Cloudflare Workers 配置 ├── package.json # 脚本与依赖 ├── tsconfig.json └── turbo.json核心机制createHandler如何同时托管 Rivet 与你的路由rivetkit/cloudflare-workers包源码位于 rivetkit-typescript/packages/cloudflare-workers/src/mod.ts是整个示例的基石。它做了三件事自动接线 WASM 运行时setup()内部调用rivetkit的setup并强制指定runtime: wasm同时注入rivetkit/rivetkit-wasm的 bindings 与初始化输入还通过import ./websocket安装基于 fetch 的globalThis.WebSocketshimWASM 运行时通过它建立到 Rivet 引擎的出站隧道暴露类型化的 Registrysetup返回RegistryA可直接用于createClienttypeof registry()推导出完全类型安全的客户端路径分发的 fetch 入口createHandler返回的 handler 会先检查请求路径——命中managerPath默认/api/rivet前缀的请求交给registry.handler(request)处理 Rivet Manager API其余请求全部转发给你提供的options.fetch。关键的分发逻辑如下见 mod.tsconst managerPath options.managerPath ?? DEFAULT_MANAGER_PATH; // /api/rivet return { async fetch(request, env, ctx) { // 首次请求时从 env 读取 RIVET_* 变量填充连接配置 applyEnv(registry, env ?? {}, managerPath); const url new URL(request.url); if (url.pathname managerPath || url.pathname.startsWith(${managerPath}/)) { return registry.handler(request); // Rivet Manager API } if (options.fetch) { return options.fetch(request, env, ctx); // 你的业务路由 } return new Response(This is a RivetKit server...); }, };两点值得注意的实现细节applyEnv只在首次请求时执行。因为在 Cloudflare Workers 上env在模块作用域不可用所以连接配置RIVET_ENDPOINT、RIVET_NAMESPACE、RIVET_TOKEN、RIVET_POOL都要在第一个请求到来时从 Worker 环境变量中补填managerPath可自定义但修改后必须同步配置引擎侧的 serverless runner URL引擎会轮询managerPath/metadata否则rivet dev将无法感知你的 Worker。逐行拆解src/index.ts 的实现完整源码见 examples/hello-world-cloudflare-workers-raw/src/index.ts。它由三个层次构成。1. 定义有状态 Actorconst counter actor({ state: { count: 0 }, actions: { increment: (c, amount 1) { c.state.count amount; return c.state.count; }, getCount: (c) c.state.count, }, });state声明了 Actor 的持久化状态。这里的count属于可持久化Durable状态——默认会被自动保存并在重启后恢复详见 docs/content/docs/state.mdxactions定义了客户端可远程调用的方法。每个 Action 的第一个参数是上下文对象c通过c.state读写状态后续参数为业务参数这里amount默认值为1。Action 非常轻量可安全地每秒被调用数千次默认并行执行详见 docs/content/docs/actions.mdx。2. 组装 Registryexport const registry setup({ use: { counter } });setup返回带类型的Registryexport出去后既可供createHandler使用也可在scripts/client.ts里通过import type { registry }获得完整类型信息。3. 手写 fetch 路由export default createHandler(registry, { fetch: async (request: Request) { const url new URL(request.url); if (url.pathname /) { return new Response(Hello from a raw Rivet Worker router!); } const increment url.pathname.match(/^\/increment\/(.)$/); if (request.method POST increment) { const client createClienttypeof registry(); const count await client.counter .getOrCreate(increment[1]) .increment(1); return Response.json({ count }); } return new Response(Not found, { status: 404 }); }, });这条路由示范了三个最典型的模式GET /直接返回文本响应验证 Worker 存活POST /increment/:name用正则^\/increment\/(.)$捕获路径参数作为 Actor 的 KeycreateClienttypeof registry()创建类型安全的客户端client.counter.getOrCreate(name)获取必要时创建指定 Key 的 Actor 实例随后.increment(1)远程调用 Action 并返回最新计数。.getOrCreate链式调用返回的是一个“Actor 句柄”Action 调用是异步的必须await兜底 404未匹配任何路由时返回404 Not Found。这里createClient未显式传endpoint它会从环境变量读取RIVET_ENDPOINT——本地由rivet dev自动注入生产环境则作为 Worker 变量或 Secret 配置未设置时回退到本地引擎。Wrangler 配置nodejs_compat 是硬性要求wrangler.toml 非常精简name hello-world-cloudflare-workers-raw main src/index.ts compatibility_date 2025-04-01 compatibility_flags [nodejs_compat]nodejs_compat标志是必须的WASM 运行时需要从process.env读取连接配置RIVET_ENDPOINT等没有该标志运行时将无法读取环境变量官方 Quickstart 文档同样强调这一点见 docs/content/docs/quickstart/cloudflare.mdx。生产环境的变量声明有两种方式[vars]静态变量RIVET_ENDPOINThttps://namespace:tokenhost命名空间与 Token 可直接嵌入 URL即 URL 认证语法https://namespace:tokenhost/path详见 docs/content/docs/general/endpoints.mdxwrangler secret put将RIVET_ENDPOINT设为加密 Secret避免敏感 Token 出现在配置文件与源码仓库中。本地开发rivet dev一键拉起引擎与 Wranglerpackage.json 中定义了四个脚本见 examples/hello-world-cloudflare-workers-raw/package.jsonscripts: { dev: npx rivetkit/cli dev --provider cloudflare, client: tsx scripts/client.ts, check-types: tsc --noEmit, deploy: wrangler deploy }启动流程git clone https://github.com/rivet-dev/rivet.git cd rivet/examples/hello-world-cloudflare-workers-raw npm install npm run devrivet dev即npx rivetkit/cli dev --provider cloudflare会同时做两件事在本机启动一个本地 Rivet 引擎control plane并为你拉起wrangler dev。本地引擎默认绑定http://localhost:6420浏览器打开该地址即可进入 Rivet 开发者工具Inspector实时查看你的 Actor 实例、状态与调用日志。端到端验证客户端脚本npm run client会执行 scripts/client.ts它独立于 Worker 进程直接与本地引擎通信import { createClient } from rivetkit/client; import type { registry } from ../src/index.ts; const client createClienttypeof registry({ endpoint: process.env.RIVET_ENDPOINT ?? http://localhost:6420, }); async function main() { const counter client.counter.getOrCreate(demo); console.log(increment(3) - ${await counter.increment(3)}); console.log(getCount() - ${await counter.getCount()}); console.log(round trip ok); }这段脚本展示了客户端调用 Actor 的标准姿势createClient显式指定endpoint回退到http://localhost:6420getOrCreate(demo)定位 Actor然后以链式方式调用 Action。这与 Worker 路由内createClienttypeof registry()的用法互为印证——同一份registry类型既驱动服务端路由也驱动客户端类型推导。深入理解RIVET_ENDPOINT与连接配置RIVET_ENDPOINT是本示例唯一必需的变量它的完整语义在 docs/content/docs/general/environment-variables.mdx 中有系统说明环境变量说明RIVET_ENDPOINT连接 Rivet control plane 的端点 URL支持 URL 认证语法RIVET_TOKEN连接引擎的认证 TokenRIVET_NAMESPACE命名空间默认default用于 Actor 隔离RIVET_POOL池名称默认default在 Cloudflare Workers 集成中见 mod.ts 的applyEnv这些变量从 Worker 的env对象按需注入RIVET_ENDPOINT、RIVET_NAMESPACE、RIVET_TOKEN、RIVET_POOL均可选其中RIVET_POOL会映射为 Envoy 的poolName。推荐的生产实践是使用 URL 认证语法将命名空间与 Token 一并内嵌RIVET_ENDPOINThttps://my-namespace:sk_xxxxxapi.rivet.dev这样只需配置一个变量语义自包含。部署到 Cloudflare Workers开发验证通过后直接执行npm run deploy # 等价于 wrangler deploy部署前请确保wrangler.toml中的name、main与compatibility_flags正确RIVET_ENDPOINT已通过[vars]或wrangler secret put配置为指向生产 control plane 的地址若使用自建 control plane还需确认引擎侧的 serverless runner URL 与 Worker 的managerPath/api/rivet保持一致引擎才能轮询到你的 Worker 元数据。延伸阅读本示例与以下仓库内文档、源码直接相关可继续深入官方 Quickstartdocs/content/docs/quickstart/cloudflare.mdxDefault / Hono / Raw 三种集成方式对照本文示例即其中的 Raw 变体Actions 定义与调用docs/content/docs/actions.mdx状态持久化语义docs/content/docs/state.mdx环境变量总表docs/content/docs/general/environment-variables.mdx端点与 URL 认证语法docs/content/docs/general/endpoints.mdx集成包源码rivetkit-typescript/packages/cloudflare-workers/src/mod.ts同类变体示例hello-world-cloudflare-workers 与 hello-world-cloudflare-workers-hono如果你需要保留 Rivet Manager API 的完整能力/api/rivet下的生命周期管理、状态查询、日志等又希望业务路由完全掌控在自己手里Raw Fetch Router 这种零依赖组合方式是成本最低、最易审计的选型。【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 Cloudflare Workers 上运行 Rivet Actors：Raw Fetch Router 手写路由完整实战指南
在 Cloudflare Workers 上运行 Rivet ActorsRaw Fetch Router 手写路由完整实战指南【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actorsRivet Actors 是有状态工作负载的原语专为 AI Agent、协作应用与持久化执行而生。本篇基于仓库中的 hello-world-cloudflare-workers-raw 示例讲解如何在 Cloudflare Workers 上托管一个带状态的自增计数 Actor并用手写的fetch路由与 Rivet 官方 Manager API默认挂载在/api/rivet共存在同一个 Worker 中。读完本文你将掌握rivetkit/cloudflare-workers的setup/createHandler组合用法、rivet dev本地联调流程、RIVET_ENDPOINT环境变量的配置语义以及如何从客户端调用 Actor 的 Actions。示例概览一个无框架依赖的“裸路由”Worker与 hello-world-cloudflare-workers纯 Rivet 处理一切和 hello-world-cloudflare-workers-hono挂载 Hono 应用不同本示例刻意不引入任何路由框架你只需提供一个符合标准签名的fetch(request)函数用原生URL解析与正则匹配完成路由。这也是官方文档 Cloudflare Workers Quickstart 中明确列出的三种集成方式之一Default / Hono / Raw。示例的核心文件结构如下examples/hello-world-cloudflare-workers-raw/ ├── src/index.ts # Actor 定义 setup createHandler 手写路由 ├── scripts/client.ts # 独立客户端脚本验证端到端调用 ├── wrangler.toml # Cloudflare Workers 配置 ├── package.json # 脚本与依赖 ├── tsconfig.json └── turbo.json核心机制createHandler如何同时托管 Rivet 与你的路由rivetkit/cloudflare-workers包源码位于 rivetkit-typescript/packages/cloudflare-workers/src/mod.ts是整个示例的基石。它做了三件事自动接线 WASM 运行时setup()内部调用rivetkit的setup并强制指定runtime: wasm同时注入rivetkit/rivetkit-wasm的 bindings 与初始化输入还通过import ./websocket安装基于 fetch 的globalThis.WebSocketshimWASM 运行时通过它建立到 Rivet 引擎的出站隧道暴露类型化的 Registrysetup返回RegistryA可直接用于createClienttypeof registry()推导出完全类型安全的客户端路径分发的 fetch 入口createHandler返回的 handler 会先检查请求路径——命中managerPath默认/api/rivet前缀的请求交给registry.handler(request)处理 Rivet Manager API其余请求全部转发给你提供的options.fetch。关键的分发逻辑如下见 mod.tsconst managerPath options.managerPath ?? DEFAULT_MANAGER_PATH; // /api/rivet return { async fetch(request, env, ctx) { // 首次请求时从 env 读取 RIVET_* 变量填充连接配置 applyEnv(registry, env ?? {}, managerPath); const url new URL(request.url); if (url.pathname managerPath || url.pathname.startsWith(${managerPath}/)) { return registry.handler(request); // Rivet Manager API } if (options.fetch) { return options.fetch(request, env, ctx); // 你的业务路由 } return new Response(This is a RivetKit server...); }, };两点值得注意的实现细节applyEnv只在首次请求时执行。因为在 Cloudflare Workers 上env在模块作用域不可用所以连接配置RIVET_ENDPOINT、RIVET_NAMESPACE、RIVET_TOKEN、RIVET_POOL都要在第一个请求到来时从 Worker 环境变量中补填managerPath可自定义但修改后必须同步配置引擎侧的 serverless runner URL引擎会轮询managerPath/metadata否则rivet dev将无法感知你的 Worker。逐行拆解src/index.ts 的实现完整源码见 examples/hello-world-cloudflare-workers-raw/src/index.ts。它由三个层次构成。1. 定义有状态 Actorconst counter actor({ state: { count: 0 }, actions: { increment: (c, amount 1) { c.state.count amount; return c.state.count; }, getCount: (c) c.state.count, }, });state声明了 Actor 的持久化状态。这里的count属于可持久化Durable状态——默认会被自动保存并在重启后恢复详见 docs/content/docs/state.mdxactions定义了客户端可远程调用的方法。每个 Action 的第一个参数是上下文对象c通过c.state读写状态后续参数为业务参数这里amount默认值为1。Action 非常轻量可安全地每秒被调用数千次默认并行执行详见 docs/content/docs/actions.mdx。2. 组装 Registryexport const registry setup({ use: { counter } });setup返回带类型的Registryexport出去后既可供createHandler使用也可在scripts/client.ts里通过import type { registry }获得完整类型信息。3. 手写 fetch 路由export default createHandler(registry, { fetch: async (request: Request) { const url new URL(request.url); if (url.pathname /) { return new Response(Hello from a raw Rivet Worker router!); } const increment url.pathname.match(/^\/increment\/(.)$/); if (request.method POST increment) { const client createClienttypeof registry(); const count await client.counter .getOrCreate(increment[1]) .increment(1); return Response.json({ count }); } return new Response(Not found, { status: 404 }); }, });这条路由示范了三个最典型的模式GET /直接返回文本响应验证 Worker 存活POST /increment/:name用正则^\/increment\/(.)$捕获路径参数作为 Actor 的 KeycreateClienttypeof registry()创建类型安全的客户端client.counter.getOrCreate(name)获取必要时创建指定 Key 的 Actor 实例随后.increment(1)远程调用 Action 并返回最新计数。.getOrCreate链式调用返回的是一个“Actor 句柄”Action 调用是异步的必须await兜底 404未匹配任何路由时返回404 Not Found。这里createClient未显式传endpoint它会从环境变量读取RIVET_ENDPOINT——本地由rivet dev自动注入生产环境则作为 Worker 变量或 Secret 配置未设置时回退到本地引擎。Wrangler 配置nodejs_compat 是硬性要求wrangler.toml 非常精简name hello-world-cloudflare-workers-raw main src/index.ts compatibility_date 2025-04-01 compatibility_flags [nodejs_compat]nodejs_compat标志是必须的WASM 运行时需要从process.env读取连接配置RIVET_ENDPOINT等没有该标志运行时将无法读取环境变量官方 Quickstart 文档同样强调这一点见 docs/content/docs/quickstart/cloudflare.mdx。生产环境的变量声明有两种方式[vars]静态变量RIVET_ENDPOINThttps://namespace:tokenhost命名空间与 Token 可直接嵌入 URL即 URL 认证语法https://namespace:tokenhost/path详见 docs/content/docs/general/endpoints.mdxwrangler secret put将RIVET_ENDPOINT设为加密 Secret避免敏感 Token 出现在配置文件与源码仓库中。本地开发rivet dev一键拉起引擎与 Wranglerpackage.json 中定义了四个脚本见 examples/hello-world-cloudflare-workers-raw/package.jsonscripts: { dev: npx rivetkit/cli dev --provider cloudflare, client: tsx scripts/client.ts, check-types: tsc --noEmit, deploy: wrangler deploy }启动流程git clone https://github.com/rivet-dev/rivet.git cd rivet/examples/hello-world-cloudflare-workers-raw npm install npm run devrivet dev即npx rivetkit/cli dev --provider cloudflare会同时做两件事在本机启动一个本地 Rivet 引擎control plane并为你拉起wrangler dev。本地引擎默认绑定http://localhost:6420浏览器打开该地址即可进入 Rivet 开发者工具Inspector实时查看你的 Actor 实例、状态与调用日志。端到端验证客户端脚本npm run client会执行 scripts/client.ts它独立于 Worker 进程直接与本地引擎通信import { createClient } from rivetkit/client; import type { registry } from ../src/index.ts; const client createClienttypeof registry({ endpoint: process.env.RIVET_ENDPOINT ?? http://localhost:6420, }); async function main() { const counter client.counter.getOrCreate(demo); console.log(increment(3) - ${await counter.increment(3)}); console.log(getCount() - ${await counter.getCount()}); console.log(round trip ok); }这段脚本展示了客户端调用 Actor 的标准姿势createClient显式指定endpoint回退到http://localhost:6420getOrCreate(demo)定位 Actor然后以链式方式调用 Action。这与 Worker 路由内createClienttypeof registry()的用法互为印证——同一份registry类型既驱动服务端路由也驱动客户端类型推导。深入理解RIVET_ENDPOINT与连接配置RIVET_ENDPOINT是本示例唯一必需的变量它的完整语义在 docs/content/docs/general/environment-variables.mdx 中有系统说明环境变量说明RIVET_ENDPOINT连接 Rivet control plane 的端点 URL支持 URL 认证语法RIVET_TOKEN连接引擎的认证 TokenRIVET_NAMESPACE命名空间默认default用于 Actor 隔离RIVET_POOL池名称默认default在 Cloudflare Workers 集成中见 mod.ts 的applyEnv这些变量从 Worker 的env对象按需注入RIVET_ENDPOINT、RIVET_NAMESPACE、RIVET_TOKEN、RIVET_POOL均可选其中RIVET_POOL会映射为 Envoy 的poolName。推荐的生产实践是使用 URL 认证语法将命名空间与 Token 一并内嵌RIVET_ENDPOINThttps://my-namespace:sk_xxxxxapi.rivet.dev这样只需配置一个变量语义自包含。部署到 Cloudflare Workers开发验证通过后直接执行npm run deploy # 等价于 wrangler deploy部署前请确保wrangler.toml中的name、main与compatibility_flags正确RIVET_ENDPOINT已通过[vars]或wrangler secret put配置为指向生产 control plane 的地址若使用自建 control plane还需确认引擎侧的 serverless runner URL 与 Worker 的managerPath/api/rivet保持一致引擎才能轮询到你的 Worker 元数据。延伸阅读本示例与以下仓库内文档、源码直接相关可继续深入官方 Quickstartdocs/content/docs/quickstart/cloudflare.mdxDefault / Hono / Raw 三种集成方式对照本文示例即其中的 Raw 变体Actions 定义与调用docs/content/docs/actions.mdx状态持久化语义docs/content/docs/state.mdx环境变量总表docs/content/docs/general/environment-variables.mdx端点与 URL 认证语法docs/content/docs/general/endpoints.mdx集成包源码rivetkit-typescript/packages/cloudflare-workers/src/mod.ts同类变体示例hello-world-cloudflare-workers 与 hello-world-cloudflare-workers-hono如果你需要保留 Rivet Manager API 的完整能力/api/rivet下的生命周期管理、状态查询、日志等又希望业务路由完全掌控在自己手里Raw Fetch Router 这种零依赖组合方式是成本最低、最易审计的选型。【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考