# 铆钉演员在 Rivet 的 actor 运行时上构建高性能、长寿命的内存中进程。当 HTTP 端点、数据库或队列不再满足 AI 代理、实时协作、工作流编排或地理分布式数据的要求时，请使用此技能。 ## 如果遇到困难该怎么办如果某些内容未按预期工作或您遇到困难，请提示用户加入 [Rivet Discord]() 或在 [Rivet GitHub]() 上提出问题以报告问题并获取帮助。向用户提供预先生成的报告，其中包含： * 症状 * 如果这种情况发生在本地开发、部署或两者中 * 您看到的错误 * 与此相关的相关源码 * 您尝试解决的问题 * 环境 * 铆钉套件版本 * 运行时（Node、Bun 等）包括版本 * 如果适用，使用中的提供商（例如 Vercel、Railway 等） * 如果适用，正在使用的 HTTP 路由器（例如 Hono、Express、Elysia） ## 调试 Actor 使用检查器 HTTP API 检查正在运行的参与者。这些端点可通过“/gateway/{actor_id}/inspector/*”处的网关访问。关键终点： * `GET /inspector/summary` \- 完整的 actor 快照（状态、连接、RPC、队列） * `GET /inspector/state` / `PATCH /inspector/state` \- 读/写 actor 状态 * `GET /inspector/connections` \- 活动连接 * `GET /inspector/rpcs` \- 可用操作 * `POST /inspector/action/{name}` \- 使用 `{"args": [...]}` 执行操作 * `GET /inspector/queue?limit=50` \- 队列状态 * `GET /inspector/traces?startMs=0&endMs=...&limit=1000` \- 跟踪范围 (OTLP JSON) * `GET /inspector/workflow-history` \- 工作流程历史记录和状态在本地开发中，不需要身份验证令牌。在生产中，传递“授权：持有者”。有关详细信息，请参阅[调试文档]()。 ## 引用来源在提供 Rivet 文档中的信息时，请引用规范 URL，以便用户可以了解更多信息。每个参考文件在标头元数据中都包含其规范 URL。 **如何引用：** * 对关键概念使用内联链接：“使用 [actor key]() 来唯一标识实例。” * 在复杂主题的解释后添加“了解更多”链接 **查找规范 URL：** 下面的参考图链接到参考文件。每个文件的标头包含： > 规范 URL：https://rivet.dev/docs/actors/actions 引用时使用规范 URL，而不是参考文件路径。 **示例：** * 动作 → `https://rivet.dev/docs/actors/actions` * React 客户端 → `https://rivet.dev/docs/clients/react` * Kubernetes 上的自托管 → `https://rivet.dev/docs/self-hosting/kubernetes` ## 第一步 1.安装RivetKit（最新：2.1.6） npm 安装 rivetkit@2.1.6 2. 使用 setup({ use: { /* actor */ } })` 定义注册表。 3. 公开 `registry.serve()` 或 `registry.handler()` （无服务器）或 `registry.startRunner()` （运行程序模式）。优先选择无服务器模式，除非用户有特定原因使用运行程序模式。 4. 部署前验证 `/api/rivet/metadata` 返回 200。 5.配置Rivet Cloud或自托管引擎 6. 集成客户端（请参阅下面的 JavaScript、React 或 Swift 客户端指南） 7. 提示用户是否要部署。如果是这样，请转到部署 Rivet 后端。有关更多信息，请阅读与用户项目相关的快速入门指南。 ## 错误处理策略 * 默认情况下更喜欢快速失败行为。 * 避免“try/catch”，除非真正的恢复路径、清理边界或添加可操作的上下文需要它。 * 永远不要吞下错误。如果添加“catch”，则必须显式处理错误，至少通过记录错误来处理。 * 当无法恢复时，记录上下文并重新抛出。 ## 状态与变量：持久性规则 **`c.vars` 是短暂的。** `c.vars` 中的数据在每次重新启动、崩溃、升级或睡眠/唤醒周期时都会丢失。仅将“c.vars”用于不可序列化的对象（例如，物理引擎、WebSocket 引用、事件发射器、缓存）或真正瞬态的运行时数据（例如，断开连接后无关紧要的当前输入方向）。 **持久存储选项。** 重新启动后必须保留的任何数据都属于其中之一，而不是“c.vars”： * **`c.state`** — 用于小型有界数据集的 CBOR 可序列化数据。非常适合配置、计数器、小型玩家列表、阶段标志等。保持在 128 KB 以下。不要在此处存储无限制或不断增长的数据（例如，聊天日志、事件历史记录、无限制增长的衍生实体列表）。在每个持久化周期中，状态作为单个 blob 进行读/写。 * **`c.kv`** — 无界数据的键值存储。这就是“c.state”在幕后使用的内容。支持二进制值。用于较大或可变大小的数据，例如用户清单、世界块、文件 blob 或任何可能随时间增长的集合。键的范围仅限于参与者实例。 * **`c.db`** — 用于结构化或复杂数据的 SQLite 数据库。当您需要查询、索引、联接、聚合或关系建模时使用。非常适合排行榜、比赛历史记录、玩家池或任何受益于 SQL 的数据。 **常见错误：** 在 `c.vars` 中存储有意义的游戏/应用程序数据而不是持久化它。例如，如果用户可以在物理模拟中生成对象，则生成定义（位置、大小、类型）必须保留在“c.state”（或“c.kv”，如果无界）中，即使物理引擎处理（不可序列化）位于“c.vars”中。重新启动时，“run()”应该从持久数据重新创建运行时对象。 ## 部署 Rivet 后端除非另有说明，假设用户正在部署到 Rivet Cloud。如果用户是自托管，请阅读下面的自托管指南。 1. 验证 Rivet Actors 是否在本地开发中工作 2. 提示用户选择要部署的提供商（请参阅 Connect 以获取提供商列表，例如 Vercel、Railway 等） 3. 按照给定提供商的部署指南进行操作。当您需要手动干预时，您需要指示用户。 ## API 参考 RivetKit OpenAPI 规范可在技能目录“openapi.json”中找到。该文件记录了用于管理参与者的所有 HTTP 端点。 ## 其他注释 * Rivet 域名是 rivet.dev，而不是 rivet.gg ## TypeScript 警告：Actor 客户端推断 * 在多文件 TypeScript 项目中，当两个参与者都使用 `c.client()` 时，双向参与者调用可以创建循环类型依赖关系。 * 症状通常包括“c.state”变为“unknown”，actor 方法可能变为“undefined”，或在第一次跨 actor 调用后出现“TS2322”/“TS2722”错误。 * 如果一个操作返回另一个参与者调用的结果，则更喜欢在该操作上显式返回类型注释，而不是依赖于通过 `c.client()` 进行推断。 * 如果显式返回类型不够，请仅对操作所需的参与者使用更窄的客户端或注册表类型。 * 作为最后的手段，为注册表类型传递“未知”，并明确这会放弃该调用站点的类型安全。＃＃特征 * **长寿命、有状态的计算**：每个计算单元就像一个微型服务器，可以记住请求之间的信息 - 无需从数据库重新获取数据或担心超时。与 AWS Lambda 类似，但具有内存且无超时。 * **极速读取和写入**：状态与您的计算存储在同一台机器上，因此读取和写入速度超快。没有数据库往返，没有延迟峰值。状态会持久保存到 Rivet 中以进行长期存储，因此它可以在服务器重新启动后继续存在。 * **实时** ：使用 WebSocket 实时更新状态并广播更改。没有外部发布/订阅系统，没有轮询——只有内置的低延迟事件。 * **无限可扩展**：自动从零扩展到数百万并发参与者。只需按使用量付费，即可即时扩展，无需冷启动。 * **容错**：内置错误处理和恢复。 Actor 在发生故障时自动重新启动，同时保持状态完整性和持续操作。 ## 何时使用 Rivet Actor * **人工智能代理和沙箱**：多步骤工具链、对话内存、沙箱编排。 * **多人或协作应用程序**：CRDT 文档、共享光标、实时仪表板、聊天。 * **工作流程自动化**：后台作业、cron、速率限制器、持久队列、背压控制。 * **数据密集型后端**：地理分布式或每租户数据库、内存缓存、分片 SQL。 * **网络工作负载**：WebSocket 服务器、自定义协议、本地优先同步、边缘扇出。 ## 最小项目 ### 后端 **演员.ts** 从“rivetkit”导入{演员、事件、设置}；常量计数器=演员（{ 状态：{计数：0}，事件：{ 计数：事件<数量>(), }, 行动：{ 增量：（c，金额：数量）=> { c.state.count += 金额； c.broadcast("count", c.state.count); 返回c.state.count； }, }, }); 导出常量注册表=设置（{ 使用：{计数器}， }); **服务器.ts** 如果适用，与用户现有的服务器集成。否则，默认为 Hono。 ### 无框架从“./actors”导入{registry}；导出默认registry.serve(); ### 霍诺从“hono”导入{Hono}；从“./actors”导入{registry}； const app = new Hono(); app.all("/api/rivet/*", (c) =>registry.handler(c.req.raw)); 导出默认应用程序； ### 艾丽西亚从“elysia”导入{Elysia}；从“./actors”导入{registry}； const app = new Elysia() .all("/api/rivet/*", (c) =>registry.handler(c.request)); 导出默认应用程序； ### 客户端文档使用与您的应用程序匹配的客户端 SDK： * [JavaScript 客户端]() * [反应客户端]() * [Swift 客户端]() ## 演员快速参考 ### 内存中状态在重新启动、崩溃和部署后仍然存在的持久数据。状态保留在 Rivet Cloud 或 Rivet 自托管上，因此如果当前进程崩溃或退出，它可以在重新启动后继续存在。 ### 静态初始状态从“rivetkit”导入 { actor }；常量计数器=演员（{ 状态：{计数：0}，行动：{ 增量：(c) => c.state.count += 1, }, }); ### 动态初始状态从“rivetkit”导入 { actor }；接口计数器状态{ 计数：数量； } 常量计数器=演员（{ 状态：{计数：0}作为CounterState， createState: (c, 输入: { 开始?: 数字 }): CounterState => ({ 计数：输入。开始？ 0, }), 行动：{ 增量：(c) => c.state.count += 1, }, }); [文档]() ### 键键唯一地标识参与者实例。使用复合键（数组）进行分层寻址：从“rivetkit”导入 { actor, setup }；从“rivetkit/client”导入{createClient}； const 聊天室 = 演员({ 状态：{消息：[]作为字符串[]}，行动：{ getRoomInfo: (c) => ({ org: c.key[0], room: c.key[1] }), }, }); const 注册表 = setup({ use: { chatRoom } }); const client = createClient<注册表类型>(); // 复合键: [org, room] client.chatRoom.getOrCreate(["org-acme", "general"]); // 通过c.key访问actor内部的key 当 `userId` 包含用户数据时，不要使用字符串插值构建键，如 `"org:${userId}"`。使用数组来防止密钥注入攻击。 [文档]() ### 输入创建 Actor 时传递初始化数据。从“rivetkit”导入 { actor, setup }；从“rivetkit/client”导入{createClient}； const 游戏 = 演员({ createState: (c, input: { mode: string }) => ({ mode: input.mode }), 动作：{}， }); const 注册表 = 设置({ 使用: { 游戏 } }); const client = createClient<注册表类型>(); // 客户端使用 const gameHandle = client.game.getOrCreate(["game-1"], { createWithInput: { 模式: "排名" } }); [文档]() ### 临时变量无法保存的临时数据将重新启动。用于不可序列化的对象（事件发射器、连接等）。 ### 静态初始变量从“rivetkit”导入 { actor }；常量计数器=演员（{ 状态：{计数：0}，变量：{lastAccess：0}，行动：{ 增量：(c) => { c.vars.lastAccess = Date.now(); 返回c.state.count += 1; }, }, }); ### 动态初始变量从“rivetkit”导入 { actor }；常量计数器=演员（{ 状态：{计数：0}，创建变量：() => ({ 发射器：新的EventTarget()， }), 行动：{ 增量：(c) => { c.vars.emitter.dispatchEvent(new Event("change")); 返回c.state.count += 1; }, }, }); [文档]() ### 行动动作是客户和其他参与者与参与者沟通的主要方式。从“rivetkit”导入 { actor }；常量计数器=演员（{ 状态：{计数：0}，行动：{ 增量：(c，金额：数量) => (c.state.count += 金额)， getCount: (c) => c.state.count, }, }); [文档]() ### 活动和广播事件支持从参与者到连接的客户端的实时通信。从“rivetkit”导入{演员，事件}； const 聊天室 = 演员({ 状态：{消息：[]作为字符串[]}，事件：{ newMessage: 事件<{ 文本: 字符串 }>(), }, 行动：{ 发送消息：（c，文本：字符串）=> { // 广播到所有连接的客户端 c.broadcast("newMessage", { 文本 }); }, }, }); [文档]() ### 连接通过“c.conn”访问当前连接或通过“c.conns”访问所有连接的客户端。使用“c.conn.id”或“c.conn.state”来安全地识别谁在调用操作。连接状态通过`connState`或`createConnState`初始化，它接收客户端在连接时传递的参数。 ### 静态连接初始状态从“rivetkit”导入 { actor }； const 聊天室 = 演员({ 状态：{}， connState: { 访客 ID: 0 }, onConnect: (c, conn) => { conn.state.visitorId = Math.random(); }, 行动：{ 我是谁：(c) => c.conn.state.visitorId， }, }); ### 动态连接初始状态从“rivetkit”导入 { actor }； const 聊天室 = 演员({ 状态：{}， // 客户端传入的参数 createConnState: (c, params: { userId: string }) => ({ userId: params.userId, }), 行动：{ // 获取当前连接的状态和参数我是谁：(c) => ({ 状态：c.conn.state，参数：c.conn.params， }), // 使用 c.conns 迭代所有连接通知其他：（c，文本：字符串）=> { for (c.conns.values() 的 const conn) { if (conn !== c.conn) conn.send("通知", { text }); } }, }, }); [文档]() ### 队列使用队列在“run”循环内按顺序处理持久消息。从“rivetkit”导入{ actor，queue }；常量计数器=演员（{ 状态：{值：0}，队列：{ 增量：队列<{数量：数量}>()， }, 运行：异步（c）=> { for wait (c.queue.iter() 的 const 消息) { c.state.value += message.body.amount; } }, }); [文档]() ### 工作流程当您的“运行”逻辑需要持久、可重播的多步骤执行时，请使用工作流。从“rivetkit”导入{ actor，queue }；从“rivetkit/workflow”导入{工作流程}；常量工人=演员（{ 状态：{已处理：0}，队列：{ 任务：队列 <{ url: string }>(), }, 运行：工作流程（异步（ctx）=> { 等待 ctx.loop("任务循环", async (loopCtx) => { const message =等待loopCtx.queue.next(“等待任务”); 等待loopCtx.step（“处理任务”，async（）=> { 等待 processTask(message.body.url); LoopCtx.state.processed += 1; }); }); }), }); 异步函数 processTask(url: string): Promise { const res = wait fetch(url, { 方法: "POST" }); if (!res.ok) throw new Error(`任务失败：${res.status}`); } [文档]() ### 演员与演员之间的交流 Actor 可以使用“c.client()”调用其他 Actor。从“rivetkit”导入 { actor, setup }；常量库存 = 演员({ 状态：{ 库存：100 }，行动：{ 储备金：（c，金额：数量）=> { c.state.stock -= 金额； } } }); 常量顺序 = 演员({ 状态：{}，行动：{ 过程：异步（c）=> { const client = c.client<注册表类型>(); 等待 client.inventory.getOrCreate(["main"]).reserve(1); }, }, }); constregistry = setup({ use: { 库存, 订单 } }); [文档]() ### 日程安排安排操作在延迟后或在特定时间运行。计划在重新启动、升级和崩溃后仍然存在。从“rivetkit”导入{演员，事件}；常量提醒=演员（{ 状态：{消息：“”}，事件：{ 提醒：事件<{消息：字符串}>()， }, 行动：{ // 安排动作在延迟（毫秒）后运行 setReminder：（c，消息：字符串，delayMs：数字）=> { c.state.message = 消息； c.schedule.after(delayMs, "sendReminder"); }, // 安排操作在特定时间戳运行 setReminderAt: (c, 消息: 字符串, 时间戳: 数字) => { c.state.message = 消息； c.schedule.at(timestamp, "sendReminder"); }, 发送提醒：(c) => { c.broadcast("提醒", { 消息: c.state.message }); }, }, }); [文档]() ### 摧毁演员使用“c.destroy()”永久删除参与者及其状态。从“rivetkit”导入 { actor }； const userAccount = 演员({ 状态：{ 电子邮件：“”，姓名：“” }， onDestroy: (c) => { console.log(`帐户 ${c.state.email} 已删除`); }, 行动：{ 删除帐户：(c) => { c.destroy(); }, }, }); [文档]() ### 生命周期挂钩 Actor 支持初始化、后台处理、连接、网络和状态更改的钩子。使用“run”进行长期后台循环，并在关闭时使用“c.aborted”或“c.abortSignal”干净地退出。从“rivetkit”导入{演员，事件，队列}；接口房间状态{ 用户：记录<字符串，布尔值>；名称？：字符串； } 接口房间输入{ 房间名称：字符串； } 接口ConnState { 用户ID：字符串；加入时间：号码； } const 聊天室 = 演员({ 状态：{ 用户：{} } 作为 RoomState，变量：{开始时间：0}， connState: { userId: "", joinAt: 0 } 作为 ConnState, 事件：{ stateChanged: 事件(), }, 队列：{ 工作：队列<{任务：字符串}>()， }, // 状态和变量初始化 createState: (c, 输入: RoomInput): RoomState => ({ 用户: {}, 名称: input.roomName }), createVars: () => ({ startTime: Date.now() }), // 演员生命周期 onCreate: (c) => console.log("已创建", c.key), onDestroy: (c) => console.log("销毁"), onWake: (c) => console.log("演员开始"), onSleep: (c) => console.log("演员正在睡觉"), 运行：异步（c）=> { for wait (c.queue.iter() 的 const 消息) { console.log("正在处理", message.body.task); } }, onStateChange: (c, newState) => c.broadcast("stateChanged", newState), // 连接生命周期 createConnState: (c, params): ConnState => ({ userId: (params as { userId: string }).userId, joinAt: Date.now() }), onBeforeConnect: (c, params) => { /* 验证身份验证 */ }, onConnect: (c, conn) => console.log("已连接:", conn.state.userId), onDisconnect: (c, conn) => console.log("断开连接:", conn.state.userId), // 网络 onRequest: (c, req) => 新响应(JSON.stringify(c.state)), onWebSocket: (c, socket) => socket.addEventListener("message", console.log), // 响应变换 onBeforeActionResponse: (c: 未知，名称：字符串，args: 未知[]，输出：Out)：Out => 输出，动作：{}， }); [文档]() ### 上下文类型在 actor 定义之外编写辅助函数时，请使用 *ContextOf` 来提取正确的上下文类型。不要手动定义您自己的上下文接口 - 始终从参与者定义中派生它。从“rivetkit”导入 { actor, ActionContextOf }； const gameRoom = 演员({ 状态：{ 玩家：[] as string[]，分数：0 }，行动：{ addPlayer: (c,playerId: 字符串) => { validatePlayer(c, 玩家ID); c.state.players.push(playerId); }, }, }); // 好：从参与者定义中派生上下文类型函数 validatePlayer(c: ActionContextOf, playerId: string) { if (c.state.players.includes(playerId)) { throw new Error("玩家已经在房间里"); } } // 不好：不要像这样手动定义上下文类型 // type MyContext = { state: {players: string[] }; ... }; [文档]() ### 错误使用“UserError”抛出错误并安全返回给客户端。传递“元数据”以包含结构化数据。为了安全起见，其他错误将转换为通用“内部错误”。 ### 演员从“rivetkit”导入{ actor，UserError }；常量用户=演员（{ 状态: { 用户名: "" }, 行动：{ updateUsername: (c, 用户名: 字符串) => { if (用户名.length < 3) { throw new UserError("用户名太短", { 代码：“用户名_太短”，元数据：{ minLength：3，实际：用户名.length }， }); } c.state.username = 用户名； }, }, }); ### 客户端从“rivetkit”导入 { actor, setup }；从“rivetkit/client”导入 { createClient, ActorError }；常量用户=演员（{ 状态: { 用户名: "" }, actions: { updateUsername: (c, username: string) => { c.state.username = 用户名; } } }); const 注册表 = setup({ use: { user } }); const client = createClient<注册表类型>(); 尝试{ 等待 client.user.getOrCreate([]).updateUsername("ab"); } 捕获（错误）{ if (ActorError 的错误实例) { console.log(错误代码); //“用户名太短” console.log(错误.元数据); // { 最小长度：3，实际：2 } } } [文档]() ### 低级 HTTP 和 WebSocket 处理程序对于需要直接访问 HTTP `Request`/`Response` 或 WebSocket 连接的自定义协议或集成库，请使用 `onRequest` 和 `onWebSocket`。 [HTTP 处理程序文档]() · [WebSocket 处理程序文档]() ### 图标和名称使用显示名称和图标自定义参与者在 UI 中的显示方式。建议始终为参与者提供名称和图标，以便在仪表板中更容易区分它们。从“rivetkit”导入 { actor }； const 聊天室 = 演员({ 选项：{ 名称：“聊天室”， icon: "💬", // 或 FontAwesome: "评论"、"图表线" 等。 }, // ... }); [文档]() ## 客户端文档在这里找到完整的客户指南： * [JavaScript 客户端]() * [反应客户端]() * [Swift 客户端]() ## 常见模式参与者通过隔离状态和消息传递自然地扩展。使用以下模式构建您的应用程序： [文档]() ### 每个实体的参与者为每个用户、文档或房间创建一个参与者。使用复合键来确定实体范围：从“rivetkit/client”导入{createClient}；从“./actors”导入类型{registry}； const client = createClient<注册表类型>(); // 单键：每个用户一个演员 client.user.getOrCreate(["user-123"]); // 复合键：范围为组织的文档 client.document.getOrCreate(["org-acme", "doc-456"]); 从“rivetkit”导入 { actor, setup }；导出 const 用户 = 演员({ 状态：{名称：“”}，动作：{}， }); 导出常量文档 = actor({ 状态: { 内容: "" }, 动作：{}， }); 导出 const 注册表 = setup({ use: { 用户, 文档 } }); ### 协调员和数据参与者 **数据参与者**处理核心逻辑（聊天室、游戏会话、用户数据）。 **协调者参与者**跟踪和管理数据参与者的集合 - 将它们视为索引。从“rivetkit”导入 { actor, setup }； // 协调员：跟踪组织内的聊天室导出 const chatRoomList = actor({ 状态：{ 房间：[] as string[] }，行动：{ addRoom: async (c, name: string) => { // 创建聊天室参与者 const client = c.client<注册表类型>(); 等待 client.chatRoom.create([c.key[0], name]); c.state.rooms.push(名称); }, listRooms: (c) => c.state.rooms, }, }); // 数据参与者：处理单个聊天室导出 const chatRoom = 演员({ 状态：{消息：[]作为字符串[]}，行动：{ 发送: (c, msg: string) => { c.state.messages.push(msg); }, }, }); 导出 const 注册表 = setup({ use: { chatRoomList, chatRoom } }); 从“rivetkit/client”导入{createClient}；从“./actors”导入类型{registry}； const client = createClient<注册表类型>(); // 每个组织的协调员 const coordinator = client.chatRoomList.getOrCreate(["org-acme"]); 等待 coordinator.addRoom("一般"); 等待 coordinator.addRoom(“随机”); // 访问协调者创建的聊天室 client.chatRoom.get(["org-acme", "一般"]); ### 运行循环使用“run”循环在 Actor 内进行连续的后台工作。按顺序处理队列消息、按时间间隔运行逻辑、流式传输 AI 响应或协调长时间运行的任务。从“rivetkit”导入{ actor、queue、setup }； const counterWorker = actor({ 状态：{值：0}，队列：{ 变异：队列 <{ 增量：数字 }>()， }, 运行：异步（c）=> { for wait (c.queue.iter() 的 const 消息) { c.state.value += message.body.delta; } }, 行动：{ getValue: (c) => c.state.value, }, }); constregistry = setup({ use: { counterWorker } }); ### 工作流程循环将此模式用于长期、持久的工作流，这些工作流初始化资源、循环处理命令，然后进行清理。从“rivetkit”导入{ actor、queue、setup }；从“rivetkit/workflow”导入{循环，工作流程}；类型 WorkMessage = { 金额：数量 }; 类型 ControlMessage = { 类型：“停止”；原因：字符串}；常量工人=演员（{ 状态：{ 阶段：“空闲”为“空闲”| “跑步”| “停止”，已处理：0，总计: 0, stopReason: null 作为字符串 |空， }, 队列：{ 工作：队列(), 控制：队列(), }, 运行：工作流程（异步（ctx）=> { 等待 ctx.step("设置", async () => { 等待 fetch("https://api.example.com/workers/init", { 方法: "POST" }); ctx.state.phase = "运行"; ctx.state.stopReason = null; }); const stopReason =等待 ctx.loop("worker-loop", async (loopCtx) => { const message =等待loopCtx.queue.next("等待命令", { 名称：[“工作”，“控制”]， }); if (message.name === "工作") { 等待loopCtx.step（“应用工作”，async（）=> { 等待获取（“https://api.example.com/workers/process”，{ 方法：“POST”， body: JSON.stringify({ amount: message.body.amount }), }); LoopCtx.state.processed += 1; LoopCtx.state.total += message.body.amount; }); 返回； } return Loop.break((message.body as ControlMessage).reason); }); 等待 ctx.step("拆解", async () => { 等待 fetch("https://api.example.com/workers/shutdown", { 方法: "POST" }); ctx.state.phase = "已停止"; ctx.state.stopReason = stopReason; }); }), }); constregistry = setup({ use: {worker } }); [文档]() ### 操作与队列 * **行动**并不持久。将它们用于实时读取、临时数据和低延迟通信（例如玩家输入）。 * **队列**是持久的。使用它们通过运行循环序列化突变，避免与 SQLite 和其他本地状态的竞争条件。调用者仍然可以等待排队工作的响应。 ### 身份验证、安全性和 CORS * 验证“onBeforeConnect”或“createConnState”中的凭据并抛出错误以拒绝未经授权的连接。 * 使用 `c.conn.state` 来安全地识别操作中的用户，而不是信任操作参数。 * 对于跨域访问，请在`onBeforeConnect`中验证请求来源。 [身份验证文档]() · [CORS 文档]() ### 版本和升级部署新代码时，设置版本号，以便 Rivet 可以将新的 actor 路由到最新的运行器，并可选择排出旧的运行器。使用构建时间戳、git 提交计数或 CI 构建号作为版本。 [文档]() ### 反模式 ####永远不要打造“神”演员不要将所有逻辑都放在一个演员身上。神演员通过一个瓶颈将每个操作序列化，杀死并行性，并使整个系统作为一个单元失败。每个实体分为重点参与者。 #### 永远不要根据请求创建一个 actor Actor 的生命周期很长，并且可以跨请求维护状态。为每个传入请求创建一个新的 Actor 会放弃模型的核心优势，并在 Actor 创建和拆卸上浪费资源。将参与者用于持久实体，将常规函数用于无状态工作。 ## 参考图 ### 演员 * [访问控制]() * [操作]() * [演员钥匙]() * [演员调度]() * [演员状态]() * [AI 和用户生成的 Rivet Actors]() * [身份验证]() * [Cloudflare Workers 快速入门]() * [Actor 之间的通信]() * [连接]() * [调试]() * [设计模式]() * [摧毁 Actor]() * [临时变量]() * [错误]() * [外部 SQL 数据库]() * [Fetch 和 WebSocket 处理程序]() * [助手类型]() * [图标和名称]() * [内存状态]() * [输入参数]() * [生命周期]() * [限制]() * [低级 HTTP 请求处理程序]() * [低级 KV 存储]() * [低级 WebSocket 处理程序]() * [元数据]() * [Next.js 快速入门]() * [Node.js 和 Bun 快速入门]() * [队列和运行循环]() * [React 快速入门]() * [实时]() * [扩展和并发]() * [共享和加入状态]() * [SQLite]() * [SQLite + Drizzle]() * [测试]() * [疑难解答]() * [类型]() * [普通 HTTP API]() * [版本和升级]() * [工作流程]() ### 客户 * [Node.js 和 Bun]() * [反应]() * [Swift]() * [SwiftUI]() ### 连接 * [部署到 Amazon Web Services Lambda]() * [部署到 AWS ECS]() * [部署到 Cloudflare Workers]() * [部署到 Freestyle]() * [部署到 Google Cloud Run]() * [部署到 Hetzner]() * [部署到 Kubernetes]() * [部署到铁路]() * [部署到 Vercel]() * [部署到虚拟机和裸机]() * [Supabase]() ### 食谱 * [多人游戏]() ### 一般 * [演员配置]() * [架构]() * [跨域资源共享]() * [法学硕士和人工智能文档]() * [边缘网络]() * [端点]() * [环境变量]() * [HTTP 服务器]() * [日志记录]() * [生产清单]() * [注册表配置]() * [运行时模式]() ### 自托管 * [配置]() * [Docker Compose]() * [Docker 容器]() * [文件系统]() * [安装 Rivet 引擎]() * [Kubernetes]() * [多区域]() * [PostgreSQL]() * [生产清单]() * [铁路部署]() * [渲染部署]()

铆钉

包含技能