chat-room

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Chat Room

聊天室

IMPORTANT: Before doing anything, you MUST read
BASE_SKILL.md
in this skill's directory. It contains essential guidance on debugging, error handling, state management, deployment, and project setup. Those rules and patterns apply to all RivetKit work. Everything below assumes you have already read and understood it.

重要提示：在进行任何操作之前，你必须阅读此技能目录下的
BASE_SKILL.md
文件。其中包含调试、错误处理、状态管理、部署和项目设置的关键指南。这些规则和模式适用于所有RivetKit工作。以下所有内容均假设你已阅读并理解该文件。

Working Examples

示例参考

If you need a reference implementation, read the raw working example code in these templates:

chat-room

Patterns for building a chat room backend with RivetKit: room-scoped actors, persistent message history, and realtime delivery over WebSocket connections.

如果你需要参考实现，可以查看以下模板中的完整示例代码：

chat-room

使用RivetKit构建聊天室后端的模式：房间级Actor、持久化消息历史、通过WebSocket连接实现实时消息推送。

Starter Code

起始代码

Start with the working example on GitHub and adapt it. The backend is a single

chatRoom

actor; the frontend is a React app using

@rivetkit/react

(see the React quickstart).

Topic	Summary
Room model	One `chatRoom` actor per room key. The frontend defaults the key to `general` ; typing a different room name connects to a different actor.
History	SQLite `messages` table created in `db({ onMigrate })` , read back with `ORDER BY id ASC` .
Delivery	`sendMessage` inserts the row, then broadcasts a typed `newMessage` event to every connected client.
Identity	None in the example. `sender` is a plain action argument; production should bind identity to the connection.

可以从GitHub上的示例项目开始进行适配：chat-room。后端是一个单独的

chatRoom

Actor；前端是使用

@rivetkit/react

的React应用（可查看React快速入门）。

主题	概述
房间模型	每个房间密钥对应一个 `chatRoom` Actor。前端默认密钥为 `general` ；输入不同的房间名称会连接到不同的Actor。
消息历史	在 `db({ onMigrate })` 中创建SQLite `messages` 表，通过 `ORDER BY id ASC` 读取历史消息。
消息推送	`sendMessage` 方法插入消息行，然后向所有连接的客户端广播类型化的 `newMessage` 事件。
用户身份	示例中未实现身份验证。 `sender` 是一个普通的动作参数；生产环境中应将身份与连接绑定。

Room-Per-Actor Model

单房间单Actor模型

Each room is one Rivet Actor instance, addressed by key. The client calls

useActor({ name: "chatRoom", key: [roomId] })

, which gets-or-creates the actor for that room. This gives you:

Isolation: each room's history and connections are fully scoped to its key. Switching the room input re-keys the hook and connects to a different actor with separate history.
A single serialized writer: all
```
sendMessage
```
calls for one room run through one actor, so message ordering is consistent without locks. The SQLite
```
AUTOINCREMENT
```
id is the canonical order, which is why
```
getHistory
```
sorts by
```
id
```
rather than by timestamp.
Natural scaling: rooms spread across the cluster independently. A hot room does not slow down other rooms.

每个房间对应一个Rivet Actor实例，通过密钥寻址。客户端调用

useActor({ name: "chatRoom", key: [roomId] })

，该方法会获取或创建对应房间的Actor。这种模型的优势：

隔离性：每个房间的历史消息和连接都完全限定在其密钥范围内。切换房间输入会重新绑定钩子并连接到具有独立历史的不同Actor。
单一序列化写入器：同一房间的所有
```
sendMessage
```
调用都通过同一个Actor处理，因此无需锁就能保证消息顺序一致。SQLite的
```
AUTOINCREMENT
```
id是消息的标准顺序，这也是
```
getHistory
```
按
```
id
```
而非时间戳排序的原因。
自然扩展：房间会在集群中独立分布。热门房间不会影响其他房间的性能。

Message History Storage

消息历史存储

This example stores history in the actor's SQLite database, not in JSON state. Pick based on history size and query needs:

Approach	Use When	Implementation Guidance
SQLite (what this example uses)	Large or long-lived history that needs ordering, caps, pagination, or search	Create the `messages` table in `db({ onMigrate })` , insert with parameterized queries ( `c.db.execute("INSERT ... VALUES (?, ?, ?)", ...)` ), and read with `ORDER BY id ASC` . History survives actor sleep and scales past what you want in memory.
JSON state	Small recent history, for example the last 50 to 100 messages	Push onto a `messages` array in actor state and trim to a cap on every send. Simplest option, but the whole history lives in memory and there is no query layer, so it only fits bounded recent-history use cases.

本示例将消息历史存储在Actor的SQLite数据库中，而非JSON状态。可根据历史消息的大小和查询需求选择存储方式：

方案	使用场景	实现指南
SQLite（本示例使用）	需要排序、数量限制、分页或搜索的大型或长期保存的历史消息	在 `db({ onMigrate })` 中创建 `messages` 表，使用参数化查询插入数据（ `c.db.execute("INSERT ... VALUES (?, ?, ?)", ...)` ），并通过 `ORDER BY id ASC` 读取。消息历史在Actor休眠后仍会保留，且能突破内存存储的限制。
JSON状态	小型近期历史消息，例如最近50到100条消息	在Actor状态的 `messages` 数组中添加新消息，并在每次发送时截断到指定数量。这是最简单的方案，但所有历史消息都存储在内存中，且没有查询层，仅适用于有限的近期历史场景。

Broadcast Delivery

广播推送

New messages reach connected clients through a typed event:

The actor declares

events: { newMessage: event() }

, where

Message

{ sender, text, timestamp }

The
```
sendMessage
```
action builds the message with a server-side
```
Date.now()
```
timestamp, inserts it into the
```
messages
```
table, then calls
```
c.broadcast("newMessage", message)
```
and returns the message to the caller.
Each client subscribes with
```
useEvent("newMessage", ...)
```
and appends to its local list. The sender renders its own message through the same broadcast path as everyone else, so all clients stay on one code path.
History load is connection-gated: once the connection is ready, the client calls
```
getHistory()
```
once to render the backlog, then relies on events for everything after.

Use

c.broadcast(...)

for room-wide messages. For private or per-recipient payloads (such as DMs inside a room), send on the individual connection instead, which is a recommended extension beyond this example.

新消息通过类型化的事件发送给连接的客户端：

Actor声明

events: { newMessage: event() }

，其中

Message

的结构为

{ sender, text, timestamp }

。

```
sendMessage
```
动作使用服务器端的
```
Date.now()
```
生成时间戳构建消息，将其插入
```
messages
```
表，然后调用
```
c.broadcast("newMessage", message)
```
并将消息返回给调用者。
每个客户端通过
```
useEvent("newMessage", ...)
```
订阅事件，并将新消息添加到本地列表中。发送者的消息也通过相同的广播路径渲染，因此所有客户端的处理逻辑保持一致。
历史消息加载由连接触发：连接就绪后，客户端调用一次
```
getHistory()
```
渲染历史消息，之后所有新消息都通过事件获取。

使用

c.broadcast(...)

发送房间内的全局消息。如需发送私有或指定接收者的消息（例如房间内的私信），建议通过单个连接发送，这是本示例之外的扩展功能。

Typing Indicators And Presence (Extension)

输入提示与在线状态（扩展功能）

The example does not implement typing indicators, presence, or join/leave handling of any kind. There is no

createConnState

onConnect

, or

onDisconnect

in the code. If you need them, add them as ephemeral connection behavior:

Keep it ephemeral: store the username and typing flag in per-connection state, never in SQLite or persisted actor state. Presence is derived from live connections and should disappear with them.
Broadcast on change only: emit a typing event when a user starts or stops typing, and a presence event from
```
onConnect
```
/
```
onDisconnect
```
, rather than polling or ticking.
Expire on the client: clear a typing indicator after a short client-side timeout so a dropped connection never leaves a stuck "is typing" row.

本示例未实现输入提示、在线状态或加入/离开处理逻辑。代码中没有

createConnState

、

onConnect

或

onDisconnect

方法。如果需要这些功能，可以添加临时的连接行为：

保持临时性：将用户名和输入状态存储在每个连接的状态中，切勿存储在SQLite或持久化Actor状态中。在线状态应基于活跃连接，连接断开后状态也应消失。
仅在变化时广播：当用户开始或停止输入时发送输入事件，在
```
onConnect
```
/
```
onDisconnect
```
时发送在线状态事件，而非轮询或定时发送。
客户端超时清除：在客户端设置短超时来清除输入提示，避免连接断开后仍显示“正在输入”状态。

Per-User Inbox (Extension)

个人收件箱（扩展功能）

For offline delivery, DMs, unread counts, or notification fanout, add a

userInbox[userId]

actor per user. This is an extension beyond the example:

The room actor forwards each message to the inbox actor of every member via actor-to-actor calls, so users who are not connected to the room still accumulate messages.
The inbox actor owns per-user unread state and serves it when the user comes online, independent of which rooms they are in.
DMs become a degenerate room: either a
```
chatRoom
```
keyed by the sorted pair of user ids, or direct inbox-to-inbox delivery if you do not need shared history semantics.

如需实现离线推送、私信、未读计数或通知分发，可以为每个用户添加一个

userInbox[userId]

Actor。这是本示例之外的扩展功能：

房间Actor通过Actor间调用将每条消息转发给所有成员的收件箱Actor，因此未连接到房间的用户仍能接收消息。
收件箱Actor管理用户的未读状态，并在用户上线时提供该状态，与用户所在的房间无关。
私信可以视为简化版的房间：要么是按用户ID排序对作为密钥的
```
chatRoom
```
，要么如果不需要共享历史语义，可以直接通过收件箱到收件箱的方式发送。

Actors

Key:
```
chatRoom[roomId]
```
Responsibility: Owns one chat room. Persists the room's message history in its SQLite database and broadcasts each new message to every connected client.
Actions
- ```
sendMessage
```
- ```
getHistory
```
Queues
- None
Events
- ```
newMessage
```
State
- SQLite
- ```
messages
```
  table:
```
id
```
  (autoincrement primary key),
```
sender
```
  ,
```
text
```
  ,
```
timestamp
```

密钥：
```
chatRoom[roomId]
```
职责：管理一个聊天室。将房间的消息历史持久化到SQLite数据库，并向所有连接的客户端广播每条新消息。
动作
- ```
sendMessage
```
- ```
getHistory
```
队列
- 无
事件
- ```
newMessage
```
状态
- SQLite
- ```
messages
```
  表：
```
id
```
  （自增主键）、
```
sender
```
  、
```
text
```
  、
```
timestamp
```

Lifecycle

生命周期

mermaid

sequenceDiagram
	participant A as Client A
	participant B as Client B
	participant R as chatRoom

	A->>R: connect with key [roomId]
	Note over R: every start runs onMigrate (CREATE TABLE IF NOT EXISTS messages)
	A->>R: getHistory()
	R-->>A: Message[] ordered by id
	B->>R: connect with key [roomId]
	B->>R: getHistory()
	R-->>B: Message[] ordered by id
	A->>R: sendMessage(sender, text)
	Note over R: INSERT row with server timestamp
	R-->>A: newMessage (broadcast)
	R-->>B: newMessage (broadcast)
	A->>R: disconnect
	Note over R: history stays in SQLite for the next connection

mermaid

sequenceDiagram
	participant A as Client A
	participant B as Client B
	participant R as chatRoom

	A->>R: connect with key [roomId]
	Note over R: every start runs onMigrate (CREATE TABLE IF NOT EXISTS messages)
	A->>R: getHistory()
	R-->>A: Message[] ordered by id
	B->>R: connect with key [roomId]
	B->>R: getHistory()
	R-->>B: Message[] ordered by id
	A->>R: sendMessage(sender, text)
	Note over R: INSERT row with server timestamp
	R-->>A: newMessage (broadcast)
	R-->>B: newMessage (broadcast)
	A->>R: disconnect
	Note over R: history stays in SQLite for the next connection

Security Checklist

安全检查清单

The example is intentionally minimal and skips all of the following. Add them before production:

Auth before join: any client can join any room by knowing its name, and
```
sender
```
is arbitrary client input on every call. Validate a token during connection auth, bind identity to connection state, and check room membership before serving history. Never trust a sender name passed as an action argument.
Message length clamps: the example accepts empty messages and has no length limit. Trim server-side, reject empty text, and clamp to a maximum length.
Per-connection rate limiting: rate limit
```
sendMessage
```
per connection to stop spam and broadcast amplification.
Server-side timestamps and ids: the example already does this correctly.
```
timestamp
```
comes from
```
Date.now()
```
inside the action and
```
id
```
from SQLite
```
AUTOINCREMENT
```
. Keep it that way; never accept client-supplied timestamps or ids.
History caps:
```
getHistory
```
returns every row with no limit. Add a
```
LIMIT
```
plus pagination, and prune or archive old rows so a long-lived room cannot grow unbounded.
Parameterized queries: the example already inserts with
```
?
```
placeholders. Keep all user-supplied text out of SQL string interpolation.

本示例故意简化了实现，未包含以下安全措施。在投入生产前需添加这些措施：

加入前验证身份：任何客户端只要知道房间名称就能加入任意房间，且每次调用的
```
sender
```
都是客户端任意输入的。在连接验证期间验证令牌，将身份与连接状态绑定，并在提供历史消息前检查房间成员身份。切勿信任作为动作参数传入的发送者名称。
消息长度限制：本示例接受空消息且无长度限制。在服务器端修剪消息，拒绝空文本，并设置最大长度限制。
单连接速率限制：对每个连接的
```
sendMessage
```
调用进行速率限制，防止垃圾消息和广播放大攻击。
服务器端时间戳和ID：本示例已正确实现此功能。
```
timestamp
```
来自动作内部的
```
Date.now()
```
，
```
id
```
来自SQLite的
```
AUTOINCREMENT
```
。请保持此实现方式；切勿接受客户端提供的时间戳或ID。
历史消息数量限制：
```
getHistory
```
会返回所有消息，无数量限制。添加
```
LIMIT
```
和分页功能，并删除或归档旧消息，避免长期运行的房间消息无限增长。
参数化查询：本示例已使用
```
?
```
占位符插入数据。请确保所有用户输入的文本都不直接用于SQL字符串拼接。

Reference Map

参考地图

Actors

Access Control
Actions
Actor Keys
Actor Scheduling
Actor Statuses
AI and User-Generated Rivet Actors
Authentication
Communicating Between Actors
Connections
Custom Inspector Tabs
Debugging
Design Patterns
Destroying Actors
Errors
Fetch and WebSocket Handler
Helper Types
Icons & Names
Input Parameters
Lifecycle
Limits
Low-Level HTTP Request Handler
Low-Level KV Storage
Low-Level WebSocket Handler
Metadata
Next.js Quickstart
Node.js & Bun Quickstart
Queues & Run Loops
React Quickstart
Realtime
Rust Quickstart (Preview)
Sandbox Actor
Scaling & Concurrency
Sharing and Joining State
SQLite
SQLite + Drizzle
State & Storage
Testing
Troubleshooting
Types
Vanilla HTTP API
Versions & Upgrades
Workflows

访问控制
动作
Actor密钥
Actor调度
Actor状态
AI与用户生成的Rivet Actors
身份验证
Actor间通信
连接
自定义检查器标签
调试
设计模式
销毁Actors
错误处理
Fetch与WebSocket处理器
辅助类型
图标与名称
输入参数
生命周期
限制
底层HTTP请求处理器
底层KV存储
底层WebSocket处理器
元数据
Next.js快速入门
Node.js & Bun快速入门
队列与运行循环
React快速入门
实时功能
Rust快速入门（预览版）
沙箱Actor
扩展与并发
状态共享与合并
SQLite
SQLite + Drizzle
状态与存储
测试
故障排除
类型
原生HTTP API
版本与升级
工作流

Agent Os

Agent-to-Agent Communication
agentOS vs Sandbox
Authentication
Benchmarks
Configuration
Core Package
Cron Jobs
Deployment
Embedded LLM Gateway
Events
Filesystem
Limitations
LLM Credentials
Multiplayer
Networking & Previews
Overview
Permissions
Persistence & Sleep
Pi
Processes & Shell
Queues
Quickstart
Sandbox Mounting
Security & Auth
Security Model
Sessions
Software
SQLite
System Prompt
Tools
Webhooks
Workflow Automation

Agent间通信
agentOS vs 沙箱
身份验证
基准测试
配置
核心包
定时任务
部署
嵌入式LLM网关
事件
文件系统
限制
LLM凭证
多人协作
网络与预览
概述
权限
持久化与休眠
Pi
进程与Shell
队列
快速入门
沙箱挂载
安全与身份验证
安全模型
会话
软件
SQLite
系统提示词
工具
Webhooks
工作流自动化

Clients

客户端

Node.js & Bun
React
Swift
SwiftUI

Node.js & Bun
React
Swift
SwiftUI

Connect

部署

Deploy To Amazon Web Services Lambda
Deploying to AWS ECS
Deploying to Cloudflare Workers
Deploying to Freestyle
Deploying to Google Cloud Run
Deploying to Hetzner
Deploying to Kubernetes
Deploying to Railway
Deploying to Rivet Compute
Deploying to Supabase Functions
Deploying to Vercel
Deploying to VMs & Bare Metal

部署到Amazon Web Services Lambda
部署到AWS ECS
部署到Cloudflare Workers
部署到Freestyle
部署到Google Cloud Run
部署到Hetzner
部署到Kubernetes
部署到Railway
部署到Rivet Compute
部署到Supabase Functions
部署到Vercel
部署到虚拟机与裸金属服务器

Cookbook

实战指南

AI Agent
AI Agent Workspaces
Chat Room
Collaborative Text Editor
Cron Jobs and Scheduled Tasks
Database per Tenant
Deploying Rivet in a VPC or Air-Gapped Network
Live Cursors and Presence
Multiplayer Game

AI Agent
AI Agent工作区
聊天室
协作文本编辑器
定时任务与计划任务
租户专属数据库
在VPC或隔离网络中部署Rivet
实时光标与在线状态
多人游戏

General

通用

Actor Configuration
Architecture
Cross-Origin Resource Sharing
Documentation for LLMs & AI
Edge Networking
Endpoints
Environment Variables
HTTP Server
Logging
Pool Configuration
Production Checklist
Registry Configuration
Runtime Modes

Actor配置
架构
跨域资源共享
面向LLM与AI的文档
边缘网络
端点
环境变量
HTTP服务器
日志
池配置
生产环境检查清单
注册表配置
运行时模式

Self Hosting

自托管

Configuration
Docker Compose
Docker Container
File System
FoundationDB (Enterprise)
Installing Rivet Engine
Kubernetes
Multi-Region
PostgreSQL
Production Checklist
Railway Deployment
Render Deployment
TLS & Certificates

配置
Docker Compose
Docker容器
文件系统
FoundationDB（企业版）
安装Rivet引擎
Kubernetes
多区域部署
PostgreSQL
生产环境检查清单
Railway部署
Render部署
TLS与证书