建立长连接¶
请求参数¶
此路径执行 WebSocket Upgrade 握手,成功为 HTTP 101,不返回普通 ApiResponse。不允许查询参数,不把 Token 或票据放进 URL。
| 项目 | 约定 |
|---|---|
| 协议 | 原生 WebSocket,文本 JSON,协议 version: 1;未启用 STOMP/SockJS |
| 当前公网地址 | wss://api.budyoo.cn/ws/v1/realtime,已由ESA接入并通过HTTPS回源到中国大陆Nginx |
| 客户端迁移 | 域名、路径和票据协议不变;连接生命周期、真实账号与退出联动仍按各自验收范围处理 |
| 浏览器 Origin | 只允许配置白名单,当前允许文档站来源;原生客户端可不发送 Origin |
| 客户端元数据 | 在申请票据的 HTTP 请求中校验,WebSocket 不重复要求自定义握手头 |
| 认证 | 建连 5 秒内发送 auth 帧,Redis 原子消费一次性票据 |
正式身份通过申请连接票据获得凭据,未登录返回401,资料及VIP准入遵循票据接口。开发人员也可通过受独立密钥保护的开发联调票据验证基础能力;本次ESA连接验收使用后者,不代表已完成真实用户全链路验收。
ESA与外部服务出口¶
API和WebSocket共用api.budyoo.cn的ESA站点,API主机全域绕过缓存,启用WebSocket Upgrade与智能路由,严格验证HTTPS回源证书。中国大陆ECS继续由Nginx接收回源,Java绑定回环地址;仅确认的ESA网段可提供真实客户端IP头,该清单不等于关闭其他站点的公网443入口。媒体继续使用独立的media.budyoo.cn CDN,不把媒体缓存规则套到票据或聊天连接上。
Google、FCM 等外部供应商后续从香港中转节点访问,属于服务端出站路径,与 App 的 API/WebSocket 入口分离。香港服务器尚未购买,也没有现成的中转地址;在它上线前,客户端不得改用香港地址,也不得把香港节点当作开放代理。上线时需要为每个供应商单独配置目标白名单、mTLS/签名认证、超时重试、健康检查、日志脱敏和费用告警。
2026-11-20 00:18(北京时间)已将API DNS从原A记录切为ESA CNAME。切换前后均通过受信TLS的WSS 101、hello、无效票据拒绝、隔离票据首帧认证、80秒心跳及正常关闭;公开地址保持不变。香港节点仍未采购,跨地域与客户端验证范围见安全说明。
连接流程¶
- HTTP 申请新票据,保存于内存;票据有效期 30 秒且只能消费一次。
- 建立 WebSocket,服务端发送
hello。 - 5 秒内发送
auth,服务端返回ready后才可心跳或使用受控探针。 - 每 20 秒发送应用层
ping,对应响应为pong;65 秒没有有效活动会关闭连接。 - 断线后按指数退避重新申请票据并建连,不能复用已消费票据。消息业务尚未实现,本阶段不做聊天记录补拉。
消息格式¶
客户端帧可传 language,读取当前 App 界面语言。例如认证前发送 ja-JP,错误提示也可直接显示日文;未提供时认证成功后沿用票据申请时的语言。App 切换语言后,在下一条心跳或消息中传新值即可更新连接语言,未知或空标签回退英文。
客户端帧:
{
"version": 1,
"type": "auth",
"language": "zh-CN",
"requestId": "632e403d-fbf8-43a1-8dc6-d87c20371a2e",
"data": {"ticket": "替换为本次接口返回的一次性票据"}
}
requestId 每条消息生成新的 UUID。type 当前仅接受 auth、ping、probe;probe 只允许开发票据使用,不接受任意用户 ID、订阅频道或聊天发送。
服务端帧统一为:
{
"version": 1,
"type": "ready",
"requestId": "632e403d-fbf8-43a1-8dc6-d87c20371a2e",
"code": "SUCCESS",
"message": "请求已处理。",
"language": "zh-CN",
"data": {
"connectionId": "a16dd3ae-19cf-49e0-890e-99114b079177",
"heartbeatSeconds": 20,
"sessionExpiresAt": 1793640000000,
"developmentProbe": true
},
"serverTime": 1793636400000
}
服务端 message 为当前接收连接的本地化提示,language 为实际语言 zh-CN/en/ja/ko;code 始终固定。通过 Redis 推送给同一用户的不同连接时,也分别使用各连接的语言。未认证 hello 使用握手的 Accept-Language,未提供时英文;浏览器可在 auth 帧明确传 App 语言。WebSocket 关闭原因仍为稳定诊断码,不作为直接展示文案。
| type | 含义 | data |
|---|---|---|
hello |
等待认证,code 为 AUTH_REQUIRED |
认证等待时间、心跳间隔 |
ready |
认证和 Redis 在线登记完成 | 连接 ID、心跳间隔、最长会话到期时间、探针标识 |
pong |
对应 ping 的响应 | 空对象;requestId 与请求一致 |
probe.result |
开发探针经过 Redis 路由后返回 | connectionId、via: redis |
event |
内部服务端事件扩展点 | 由未来业务定义,当前无对外聊天发送能力 |
error |
协议或依赖失败,随后关闭 | 空对象;错误语义由 code 表达 |
shutdown |
节点正在停止,code 为 SERVER_RESTART |
建议重连等待毫秒数 |
限额和关闭¶
| 项目 | 默认值 |
|---|---|
| 单节点连接数 | 500,包含待认证连接;这是开发配置,不是容量承诺 |
| 每身份连接数 | 5,由 Redis 原子限制;HTTP登录会话仍只保留一个 |
| 每连接消息频率 | 每秒 10 帧,含认证与无效帧 |
| 输入消息大小 | 8 KiB,仅文本 |
| 输出缓冲/发送等待 | 64 KiB/5 秒 |
| 在线租约 | 90 秒,随有效消息续期,进程异常退出后自动失效 |
| 最长会话 | 60 分钟,到期重新申请票据;正式账号退出与撤销联动待身份系统对接 |
关闭码:1008 表示认证/协议/限额或会话过期,1009 表示消息过大,1011 表示发送或传输失败,1012 表示服务重启,1013 表示容量或依赖暂不可用。未认证超时可能直接关闭,不保证先收到 error 帧。
稳定错误码包括 AUTH_REQUIRED、AUTH_TIMEOUT、INVALID_TICKET、CONNECTION_LIMIT、INVALID_FRAME、RATE_LIMITED、SESSION_EXPIRED、FORBIDDEN 和 SERVICE_UNAVAILABLE。恢复连接时使用新票据;无效凭据不应无间隔重试。
客户端封装¶
可下载 budyoo-realtime.mjs 与 budyoo-client.mjs。封装实现首帧认证、20 秒心跳、随机抖动退避重连和 stop 清理;由调用者提供 getTicket(),不要把开发密钥硬编码进客户端发布包。
import {createRealtimeClient} from './budyoo-realtime.mjs';
const connection = createRealtimeClient({
url: 'wss://你的接口域名/ws/v1/realtime',
getTicket: () => api.request({path:'/api/v1/realtime/tickets', method:'POST'}),
getLanguage: () => currentAppLanguage, // 每次发送读取 App 当前语言,如 ja-JP。
onState: state => console.log(state),
onEvent: event => console.log(event.type, event.code),
});
connection.start();
// 页面销毁或明确退出时调用 connection.stop()。
上述api应使用完成登录认证后的统一请求封装。公网WSS入口已接通;例子不包含可用账号,真实账号准入与客户端连接生命周期仍需独立验收。
可靠性边界¶
Redis Pub/Sub 仅用于实时通知,离线或订阅恢复期间可能丢失事件;ready、路由尝试数和 probe.result 都不是聊天消息持久化、送达或已读承诺。未来聊天消息需要数据库存储、业务 ACK、去重、顺序和离线补拉;本阶段只搭连接架构。
验证结果¶
本次独立服务器快照通过85项 Java 测试,其中新增19项覆盖真实 Redis/WebSocket、双应用节点路由、节点停止、连接限制、票据重放、空闲清理、重连与生产环境隔离。SSH 隧道真实连接与公开 JS 封装的自动重连、stop 清理通过;短暂停止 Redis 响应时票据入口返回503,恢复后重新签票与路由正常。
后续四语改动已合入包含登录注册的整合工程,140 项测试通过;新增用例验证票据语言、同用户不同连接分别使用日文/韩文、切换语言后的异步事件,以及认证前四语错误提示。真实公网无敏感凭据的错误帧已验证四语及缺省/未知语言英文回退。
2026-11-20另完成ESA切换前后的公网WSS连接验收,范围见上文。历史功能测试及本次隔离票据验收均不代表高并发容量、真机弱网、正式账号全流程或退出即时撤销联动已完成。