rivetkit

RivetKit 後端與 Rivet Actor 執行時期指引。用於建置、修改、除錯或測試 Rivet Actors、註冊表、無伺服器/執行器模式、部署或基於 Actor 的工作流程。

16星標

6分支

更新於 2026/7/13

獲取技能源代碼

Rivet Actors

在 Rivet 的 actor 執行時期上建置高效能、長時間運行、記憶體內的處理程序。當 HTTP 端點、資料庫或佇列不再滿足 AI 代理、即時協作、工作流程編排或地理分散式資料的需求時，請使用此技能。

卡住時該怎麼辦

如果某個功能不如預期運作或您卡住了，請提示使用者加入 Rivet Discord 或在 Rivet GitHub 上提交問題以回報問題並獲得協助。

提供使用者一份預先產生的報告，內容包含：

症狀
- 此問題發生在本機開發、部署環境或兩者皆有
- 您看到的錯誤
- 與此相關的原始碼
您嘗試解決的方法
環境
- RivetKit 版本
- 執行時期（Node、Bun 等）及版本
- 若適用，所使用的提供者（例如 Vercel、Railway 等）
- 若適用，所使用的 HTTP 路由器（例如 Hono、Express、Elysia）

除錯 Actors

使用 inspector HTTP API 檢查正在運行的 actors。這些端點可透過閘道器在 /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": [...]} 執行動作
POST /inspector/database/execute - 使用 {"sql": "...", "args": [...]} 或 {"sql": "...", "properties": {...}} 執行 SQL 讀取或變更
GET /inspector/queue?limit=50 - 佇列狀態
GET /inspector/traces?startMs=0&endMs=...&limit=1000 - 追蹤跨度（OTLP JSON）
GET /inspector/workflow-history - 工作流程歷史與狀態（JSON 格式，包含 nameRegistry、entries、entryMetadata）
POST /inspector/workflow/replay - 從特定步驟或從頭開始重播工作流程；若工作流程仍在執行中，則回傳 409 actor/workflow_in_flight
GET /inspector/database/schema - 由 c.db 公開的 SQLite 表格與檢視
GET /inspector/database/rows?table=...&limit=100&offset=0 - 分頁的 SQLite 表格或檢視資料列

在本機開發環境中，不需要驗證令牌。在正式環境中，請傳遞 Authorization: Bearer <inspector-token>，其中 inspector 令牌是首次啟動時自動產生並儲存在 actor 內部 KV 中（鍵值為 0x03）的 actor 專用令牌。Rivet 儀表板會自動取得此令牌；若要直接存取 API，請透過管理 KV 端點取得。詳情請參閱除錯文件。

引用來源

當提供來自 Rivet 文件的資訊時，請引用標準 URL，以便使用者進一步了解。每個參考檔案在其標頭元資料中都包含標準 URL。

如何引用：

對關鍵概念使用行內連結："使用 actor 金鑰來唯一識別實例。"
在複雜主題的說明後加上「了解更多」連結

尋找標準 URL：

下方的參考對應表連結到參考檔案。每個檔案的標頭包含：

> 標準 URL：https://rivet.dev/docs/actors/actions

引用時請使用該標準 URL，而非參考檔案路徑。

範例：

Actions → https://rivet.dev/docs/actors/actions
React 客戶端 → https://rivet.dev/docs/clients/react
在 Kubernetes 上自行託管 → https://rivet.dev/docs/self-hosting/kubernetes

版本檢查

在開始任何工作之前，請檢查使用者的專案是否使用最新版本的 RivetKit（最新版：2.3.3-rc.2）。查看使用者 package.json 中的 rivetkit 版本（檢查 dependencies 和 devDependencies）。如果安裝的版本早於 2.3.3-rc.2，請通知使用者並建議升級：

npm install rivetkit@2.3.3-rc.2

如果使用者同時使用 @rivetkit/react、@rivetkit/next-js 或其他 @rivetkit/* 客戶端套件，也建議一併升級。過舊的版本可能存在已知錯誤或缺少功能，導致問題發生。

第一步

安裝 RivetKit（最新版：2.3.3-rc.2）
```
npm install rivetkit@2.3.3-rc.2
```
使用 setup({ use: { /* actors */ } }) 定義註冊表。
呼叫 registry.start() 啟動伺服器。若要整合自訂 HTTP 伺服器，請使用 registry.handler() 搭配路由器（如 Hono）。若為無伺服器部署，請使用 registry.serve()。若僅使用執行器模式，請使用 registry.startEnvoy()。
在部署前確認 /api/rivet/metadata 回傳 200。
設定 Rivet Cloud 或自行託管的引擎
- 您必須為正式建置設定版本控制。本機開發不需要此步驟。請參閱版本與升級。
整合客戶端（請參閱下方 JavaScript、React 或 Swift 的客戶端指南）
詢問使用者是否要部署。如果是，請前往「部署 Rivet 後端」。

更多資訊請閱讀與使用者專案相關的快速入門指南。

專案設定

.gitignore

每個 RivetKit 專案都應有 .gitignore。至少包含：

node_modules/
dist/
.env

.dockerignore

每個包含 Dockerfile 的專案都應有 .dockerignore，以保持映像檔小巧並避免洩漏機密：

node_modules/
dist/
.env
.git/

Dockerfile

使用此 Dockerfile 作為部署 RivetKit 專案的基礎。RIVET_RUNNER_VERSION 建置參數僅在自行託管或使用自訂執行器時需要（Rivet Compute 不需要）。它讓 Rivet 能夠追蹤正在運行的 actor 版本，並在部署時清空舊的 actor。詳情請參閱 https://rivet.dev/docs/actors/versions。

FROM node:24-alpine

ARG RIVET_RUNNER_VERSION
ENV RIVET_RUNNER_VERSION=$RIVET_RUNNER_VERSION

WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build --if-present

CMD ["node", "dist/index.js"]

使用以下指令建置：

docker build --build-arg RIVET_RUNNER_VERSION=$(date +%s) .

根據專案的進入點調整 CMD。如果專案使用不同的輸出目錄或啟動指令，請相應更新。

錯誤處理原則

預設採用快速失敗的行為。
除非需要真正的復原路徑、清理邊界或新增可操作的上下文，否則避免使用 try/catch。
絕不吞沒錯誤。如果加入 catch，必須明確處理錯誤，至少記錄下來。
當無法復原時，記錄上下文並重新拋出。

State 與 Vars：持久性規則

c.vars 是短暫的。 c.vars 中的資料會在每次重新啟動、崩潰、升級或休眠/喚醒週期中遺失。僅將 c.vars 用於不可序列化的物件（例如物理引擎、WebSocket 參考、事件發射器、快取）或真正短暫的執行時期資料（例如斷線後不再重要的當前輸入方向）。

持久儲存選項。 任何必須在重新啟動後保留的資料都應放在以下其中之一，而非 c.vars：

c.state — 適用於小型、有界資料集的 CBOR 可序列化資料。適合設定、計數器、小型玩家清單、階段標記等。保持在 128 KB 以下。不要在此儲存無界或持續增長的資料（例如聊天記錄、事件歷史、無限制增長的生成實體清單）。狀態在每次持久化週期中作為單一 blob 讀取/寫入。
c.kv — 適用於無界資料的鍵值儲存。c.state 底層使用的就是這個。支援二進位值。用於較大或可變大小的資料，例如使用者庫存、世界區塊、檔案 blob 或任何可能隨時間增長的集合。金鑰範圍限定於 actor 實例。
c.db — 適用於結構化或複雜資料的 SQLite 資料庫。當需要查詢、索引、關聯、聚合或關聯模型時使用。適合排行榜、比賽歷史、玩家池或任何受益於 SQL 的資料。

常見錯誤： 將有意義的遊戲/應用程式資料儲存在 c.vars 中而非持久化。例如，如果使用者可以在物理模擬中生成物件，則生成定義（位置、大小、類型）必須持久化在 c.state（或無界時使用 c.kv）中，即使物理引擎處理（不可序列化）的即時資料存在於 c.vars 中。重新啟動時，run() 應從持久化資料重新建立執行時期物件。

部署 Rivet 後端

除非另有指定，否則假設使用者部署到 Rivet Cloud。如果使用者自行託管，請閱讀下方的自行託管指南。

確認 Rivet Actors 在本機開發環境中正常運作
詢問使用者選擇要部署的提供者（請參閱連線以取得提供者清單，例如 Vercel、Railway 等）
遵循該提供者的部署指南。您需要在需要手動介入時指示使用者。

API 參考

RivetKit OpenAPI 規格可在技能目錄的 openapi.json 中找到。此檔案記錄了所有用於管理 actors 的 HTTP 端點。

雜項備註

Rivet 的網域是 rivet.dev，不是 rivet.gg

TypeScript 注意事項：Actor 客戶端推論

在多檔 TypeScript 專案中，雙向 actor 呼叫可能會在兩個 actor 都使用 c.client<typeof registry>() 時產生循環型別依賴。
症狀通常包括 c.state 變成 unknown、actor 方法可能變成 undefined，或在首次跨 actor 呼叫後出現 TS2322 / TS2722 錯誤。
如果某個動作回傳另一個 actor 呼叫的結果，建議在該動作上使用明確的回傳型別註解，而非依賴透過 c.client<typeof registry>() 的推論。
如果明確回傳型別不夠，請對該動作所需的 actors 使用更狹窄的客戶端或註冊表型別。
作為最後手段，將註冊表型別傳遞為 unknown，並明確表示這會放棄該呼叫點的型別安全性。

功能

長時間運行、有狀態的運算：每個運算單元就像一個小型伺服器，能在請求之間記住事物——無需從資料庫重新擷取資料或擔心超時。就像 AWS Lambda，但有記憶體且無超時。
極速讀寫：狀態儲存在與運算相同的機器上，因此讀寫極快。無需資料庫往返，沒有延遲峰值。狀態會持久化到 Rivet 以進行長期儲存，因此能在伺服器重新啟動後保留。
即時：透過 WebSocket 即時更新狀態並廣播變更。無需外部發布/訂閱系統，無需輪詢——只需內建的低延遲事件。
無限擴展：自動從零擴展到數百萬個並發 actors。僅需為使用量付費，即時擴展且無冷啟動。
容錯：內建錯誤處理與復原。Actors 在失敗時自動重新啟動，同時保持狀態完整性並繼續運作。

何時使用 Rivet Actors

AI 代理與沙箱：多步驟工具鏈、對話記憶、沙箱編排。
多人或協作應用：CRDT 文件、共享游標、即時儀表板、聊天。
工作流程自動化：背景任務、cron、速率限制器、持久佇列、背壓控制。
資料密集型後端：地理分散或每租戶資料庫、記憶體快取、分片 SQL。
網路工作負載：WebSocket 伺服器、自訂協定、本地優先同步、邊緣扇出。

最小專案

後端

index.ts

客戶端文件

使用符合您應用程式的客戶端 SDK：

Actor 快速參考

記憶體狀態

能夠在重新啟動、崩潰和部署後保留的持久資料。狀態會持久化在 Rivet Cloud 或 Rivet 自行託管環境中，因此即使當前處理程序崩潰或退出，也能在重新啟動後保留。

靜態初始狀態

動態初始狀態

文件

金鑰

金鑰唯一識別 actor 實例。使用複合金鑰（陣列）進行階層式定址：

不要使用字串插值（如 "org:${userId}"）來建構金鑰，因為 userId 包含使用者資料。請改用陣列以防止金鑰注入攻擊。

文件

輸入

在建立 actors 時傳遞初始化資料。輸入僅在 createState 和 onCreate 中可用，因此如果之後需要，請將其儲存在狀態中。

文件

臨時變數

不會在重新啟動後保留的臨時資料。用於不可序列化的物件（事件發射器、連線等）。

靜態初始 Vars

動態初始 Vars

文件

動作

動作是客戶端和其他 actor 與 actor 通訊的主要方式。

文件

事件與廣播

事件實現從 actor 到已連線客戶端的即時通訊。

文件

連線

透過 c.conn 存取當前連線，或透過 c.conns 存取所有已連線客戶端。使用 c.conn.id 或 c.conn.state 安全地識別誰在呼叫動作。c.conn 僅適用於透過已連線客戶端呼叫的動作；無狀態的 actor 控制代碼呼叫在沒有連線的情況下執行，因此請防範此情況。連線狀態透過 connState 或 createConnState 初始化，這些函式接收客戶端在連線時傳遞的參數。

靜態連線初始狀態

動態連線初始狀態

文件

佇列

使用佇列在 run 迴圈中依序處理持久訊息。

文件

工作流程

當您的 run 邏輯需要持久、可重播的多步驟執行時，請使用工作流程。

文件

Actor 間通訊

Actors 可以使用 c.client() 呼叫其他 actors。

文件

排程

排程動作在延遲後或特定時間執行。排程會在重新啟動、升級和崩潰後保留。

文件

銷毀 Actors

使用 c.destroy() 永久刪除 actor 及其狀態。

文件

生命週期鉤子

Actors 支援初始化、背景處理、連線、網路和狀態變更的鉤子。使用 run 進行長時間運行的背景迴圈，並使用 c.aborted 或 c.abortSignal 進行優雅關閉。

文件

上下文型別

在 actor 定義之外編寫輔助函式時，使用 *ContextOf<typeof myActor> 來提取正確的上下文型別。輔助函式如 ActionContextOf、CreateContextOf、ConnContextOf 和 ConnInitContextOf 從 "rivetkit" 匯出。請勿手動定義自己的上下文介面。始終從 actor 定義推導。

文件

錯誤

使用 UserError 拋出可安全回傳給客戶端的錯誤。傳遞 metadata 以包含結構化資料。其他錯誤會轉換為通用的「內部錯誤」以確保安全。

Actor

客戶端

文件

低階 HTTP 與 WebSocket 處理器

對於自訂協定或需要直接存取 HTTP Request/Response 或 WebSocket 連線的函式庫整合，請使用 onRequest 和 onWebSocket。

HTTP 處理器文件 · WebSocket 處理器文件

圖示與名稱

使用顯示名稱和圖示自訂 actors 在 UI 中的外觀。建議始終為 actors 提供名稱和圖示，以便在儀表板中更容易區分。

import { actor } from "rivetkit";

const chatRoom = actor({
	options: {
		name: "聊天室",
		icon: "💬", // 或 FontAwesome："comments"、"chart-line" 等
	},
	// ...
});

文件

客戶端文件

在此找到完整的客戶端指南：

常見模式

Actors 透過隔離狀態和訊息傳遞自然擴展。使用這些模式建構您的應用程式：

文件

每個實體一個 Actor

為每個使用者、文件或房間建立一個 actor。使用複合金鑰來限定實體範圍：

協調器與資料 Actors

資料 actors 處理核心邏輯（聊天室、遊戲會話、使用者資料）。協調器 actors 追蹤和管理資料 actors 的集合——將其視為索引。

Run 迴圈

在 actor 內部使用 run 迴圈進行持續的背景工作。依序處理佇列訊息、按間隔執行邏輯、串流 AI 回應或協調長時間運行的任務。

工作流程迴圈

使用此模式進行長時間運行、持久的工作流程，這些工作流程初始化資源、在迴圈中處理指令，然後清理。

文件

動作與佇列

動作不持久。用於即時讀取、短暫資料和低延遲通訊，例如玩家輸入。
佇列是持久的。用於透過 run 迴圈序列化變更，避免與 SQLite 和其他本地狀態發生競爭條件。呼叫者仍然可以等待佇列工作的回應。

驗證、安全性與 CORS

在 onBeforeConnect 或 createConnState 中驗證憑證，並拋出錯誤以拒絕未經授權的連線。
使用 c.conn.state 安全地識別動作中的使用者，而不是信任動作參數。
對於跨來源存取，在 onBeforeConnect 中驗證請求來源。

驗證文件 · CORS 文件

版本與升級

部署新程式碼時，設定版本號碼，以便 Rivet 將新的 actors 路由到最新的執行器，並可選擇清空舊的。使用建置時間戳、git 提交計數或 CI 建置編號作為版本。在部署到正式環境之前，設定版本控制非常重要。沒有版本控制，actors 可能會因為在較舊的執行器版本上運行而退化，且現有的 actors 永遠不會被強制遷移到新的執行器。它們將在舊執行器上無限運行，直到退出。

文件

反模式

絕不建立「上帝」actor

不要將所有邏輯放在單一 actor 中。上帝 actor 會透過一個瓶頸序列化所有操作，扼殺平行性，並使整個系統作為一個單元失敗。請拆分為每個實體專注的 actors。

絕不為每個請求建立 actor

Actors 是長時間運行的，並在請求之間保持狀態。為每個傳入請求建立新的 actor 會拋棄該模型的核心優勢，並浪費 actor 建立和銷毀的資源。使用 actors 處理持久實體，並使用一般函式處理無狀態工作。

參考對應表

Actors

Cli

客戶端

食譜

部署

一般

自行託管

您可能也喜歡

deployment-patterns

230Kdevops-cloud

Deployment workflows, CI/CD pipeline patterns, Docker containerization, health checks, rollback strategies, and production readiness checklists for web applications.

affaan-m

獲取

import-infrastructure-as-code

37Kdevops-cloud

Import existing Azure resources into Terraform using Azure CLI discovery and Azure Verified Modules (AVM). Use when asked to reverse-engineer live Azure infrastructure, generate Infrastructure as Code from existing subscriptions/resource groups/resource IDs, map dependencies, derive exact import addresses from downloaded module source, prevent configuration drift, and produce AVM-based Terraform files ready for validation and planning across any Azure resource type.

github

獲取

docker-expert

41Kdevops-cloud

您是進階的 Docker 容器化專家，具備全面的實務知識，涵蓋容器優化、安全強化、多階段建置、編排模式以及基於當前業界最佳實務的生產部署策略。

sickn33

獲取

繼續探索

瀏覽 devops-cloud 熱門 Skills 最近更新

rivetkit

相關技能

Rivet Actors

卡住時該怎麼辦

除錯 Actors

引用來源

版本檢查

第一步

專案設定

.gitignore

.dockerignore

Dockerfile

錯誤處理原則

State 與 Vars：持久性規則

部署 Rivet 後端

API 參考

雜項備註

TypeScript 注意事項：Actor 客戶端推論

功能

何時使用 Rivet Actors

最小專案

後端

客戶端文件

Actor 快速參考

記憶體狀態

靜態初始狀態

動態初始狀態

金鑰

輸入

臨時變數

靜態初始 Vars

動態初始 Vars

動作

事件與廣播

連線

靜態連線初始狀態

動態連線初始狀態

佇列

工作流程

Actor 間通訊

排程

銷毀 Actors

生命週期鉤子

上下文型別

錯誤

Actor

客戶端

低階 HTTP 與 WebSocket 處理器

圖示與名稱

客戶端文件

常見模式

每個實體一個 Actor

協調器與資料 Actors

Run 迴圈

工作流程迴圈

動作與佇列

驗證、安全性與 CORS

版本與升級

反模式

絕不建立「上帝」actor

絕不為每個請求建立 actor

參考對應表

Actors

Cli

客戶端

食譜

部署

一般

自行託管

您可能也喜歡

deployment-patterns

import-infrastructure-as-code

docker-expert

繼續探索