---
url: /docs/recipes/websockets.md
---
# 实时连接

## 当前状态

`packages/ws-protocol/` 提供消息定义、路由与独立 Bun 示例。主网站尚未把实时连接接入登录、任务进度或 Cloudflare 生产架构。

演示服务器的认证函数只返回连接时间，广播接口也是测试用途；它们不能直接作为生产身份和权限实现。

## 运行独立示例

```sh
bun --cwd packages/ws-protocol run example
```

示例默认监听 3000，连接路径是 `ws://localhost:3000/ws`。先确认端口未占用，结束后停止本次进程。消息结构见 `messages.ts`，示例支持探测、回声和请求响应。

## 接入主站需要补齐

在升级连接前校验有效会话与来源，按用户或组织授权订阅主题；限制消息大小、频率及连接数，校验所有消息输入。断线重连需要恢复订阅并防止重复业务写入。

独立 Bun 示例使用内存发布订阅，不能保证多个实例间共享。Cloudflare 部署需要适配其连接生命周期及持久协调方式，不能直接部署 `Bun.serve()`。

## 是否需要实时连接

短任务可先使用普通请求，长任务可先使用队列和状态查询。队列和模型任务当前也未接入；选择实时连接应基于真实进度需求，而不是仅为模板增加功能名称。

验收需覆盖未登录、跨用户主题、消息超限、断线恢复和多实例行为。