可水平扩展的 WebSocket 中心模式,支持懒加载 Redis 订阅、连接注册表和优雅关闭。适用于构建可跨多实例扩展的实时 WebSocket 服务器。
WebSocket Hub 模式
功能概述
WebSocket Hub 模式是一项面向实际任务的技能,主要用于用于水平可扩展的WebSocket连接的制式模式, 与 Redis 支持的协调.;OpenClaw / Moltbot / Clawbot.;
核心要点
- When to use.;
- Real-time 双向共通。
- 它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。
使用与执行
使用时应结合输入条件选择合适的执行方式,核对必要参数、依赖环境与输出内容,并按原始要求处理异常情况。从功能定位来看,该技能强调把分散的操作要求整理成清晰、可复用的处理流程,使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数,再依据技能说明逐步执行;若输入条件不完整,应先补齐信息或采用保守配置,避免因错误假设导致结果偏离需求。
结果检查与注意事项
执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期,并对异常提示、缺失字段和边界情况进行处理;涉及批量任务时,还应保存进度,避免中断后重复操作。该技能适合用于一次性任务,也可以接入自动化工作流,与其他技能或上层代理配合完成更完整的业务链路;在组合使用时,应明确每一步的输入输出关系,并避免不同步骤之间出现参数冲突。
WebSocket Hub 模式
基于 Redis 协调的、支持水平扩展的 WebSocket 连接生产级实践模式。
安装
OpenClaw / Moltbot / Clawbot
npx clawhub@latest install websocket-hub-patterns
适用场景
- 实时双向通信
- 聊天应用、协同编辑系统
- 支持客户端交互的实时仪表盘
- 需在多个网关实例间实现水平扩展
Hub 结构
type Hub struct {
// 本地状态
connections map[*Connection]bool
subscriptions map[string]map[*Connection]bool // channel -> connections
// 通道
register chan *Connection
unregister chan *Connection
broadcast chan *Event
// Redis(用于扩展)
redisClient *redis.Client
redisSubs map[string]*goredis.PubSub
redisSubLock sync.Mutex
// 可选:分布式连接注册表
connRegistry *ConnectionRegistry
instanceID string
// 关闭控制
done chan struct{}
wg sync.WaitGroup
}
Hub 主循环
func (h *Hub) Run() {
for {
select {
case <-h.done:
return
case conn := <-h.register:
h.connections[conn] = true
if h.connRegistry != nil {
h.connRegistry.RegisterConnection(ctx, conn.ID(), info)
}
case conn := <-h.unregister:
if _, ok := h.connections[conn]; ok {
if h.connRegistry != nil {
h.connRegistry.UnregisterConnection(ctx, conn.ID())
}
h.removeConnection(conn)
}
case event := <-h.broadcast:
h.broadcastToChannel(event)
}
}
}
懒加载 Redis 订阅
仅当首个本地订阅者加入时,才向 Redis 发起订阅:
func (h *Hub) subscribeToChannel(conn *Connection, channel string) error {
// 加入本地订阅映射
if h.subscriptions[channel] == nil {
h.subscriptions[channel] = make(map[*Connection]bool)
}
h.subscriptions[channel][conn] = true
// 懒加载:仅在首个订阅者出现时订阅 Redis
h.redisSubLock.Lock()
defer h.redisSubLock.Unlock()
if _, exists := h.redisSubs[channel]; !exists {
pubsub := h.redisClient.Subscribe(context.Background(), channel)
h.redisSubs[channel] = pubsub
go h.forwardRedisMessages(channel, pubsub)
}
return nil
}
func (h *Hub) unsubscribeFromChannel(conn *Connection, channel string) {
if subs, ok := h.subscriptions[channel]; ok {
delete(subs, conn)
// 无本地订阅者时清理
if len(subs) == 0 {
delete(h.subscriptions, channel)
h.closeRedisSubscription(channel)
}
}
}
Redis 消息转发
func (h *Hub) forwardRedisMessages(channel string, pubsub *goredis.PubSub) {
ch := pubsub.Channel()
for {
select {
case <-h.done:
return
case msg, ok := <-ch:
if !ok {
return
}
h.broadcast <- &Event{
Channel: channel,
Data: []byte(msg.Payload),
}
}
}
}
func (h *Hub) broadcastToChannel(event *Event) {
subs := h.subscriptions[event.Channel]
for conn := range subs {
select {
case conn.send <- event.Data:
// 成功发送
default:
// 缓冲区满 —— 关闭慢客户端
h.removeConnection(conn)
}
}
}
连接写入泵(Write Pump)
func (c *Connection) writePump() {
ticker := time.NewTicker(54 * time.Second) // Ping 间隔
defer func() {
ticker.Stop()
c.conn.Close()
}()
for {
select {
case message, ok := <-c.send:
c.conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
if !ok {
c.conn.WriteMessage(websocket.CloseMessage, []byte{})
return
}
c.conn.WriteMessage(websocket.TextMessage, message)
// 批量清空队列
for i := 0; i < len(c.send); i++ {
c.conn.WriteMessage(websocket.TextMessage, <-c.send)
}
case <-ticker.C:
if err := c.conn.WriteMessage(websocket.PingMessage, nil); err != nil {
return
}
}
}
}
面向水平扩展的连接注册表(Connection Registry)
type ConnectionRegistry struct {
client *redis.Client
instanceID string
}
func (r *ConnectionRegistry) RegisterConnection(ctx context.Context, connID string, info ConnectionInfo) error {
info.InstanceID = r.instanceID
data, _ := json.Marshal(info)
return r.client.Set(ctx, "ws:conn:"+connID, data, 2*time.Minute).Err()
}
func (r *ConnectionRegistry) HeartbeatInstance(ctx context.Context, connectionCount int) error {
info := InstanceInfo{
InstanceID: r.instanceID,
Connections: connectionCount,
}
data, _ := json.Marshal(info)
return r.client.Set(ctx, "ws:instance:"+r.instanceID, data, 30*time.Second).Err()
}
优雅关闭(Graceful Shutdown)
func (h *Hub) Shutdown() {
close(h.done)
// 关闭所有 Redis 订阅
h.redisSubLock.Lock()
for channel, pubsub := range h.redisSubs {
pubsub.Close()
delete(h.redisSubs, channel)
}
h.redisSubLock.Unlock()
// 关闭所有连接
for conn := range h.connections {
conn.Close()
}
h.wg.Wait()
}
决策树
| 场景 | 应对方式 |
|---|---|
| 单实例部署 | 跳过 ConnectionRegistry |
| 多实例部署 | 启用 ConnectionRegistry |
| 频道无订阅者 | 懒加载式取消 Redis 订阅 |
| 慢客户端 | 缓冲区溢出时主动关闭连接 |
| 需消息历史支持 | 结合使用 Redis Streams 与 Pub/Sub |
关联技能
- 元技能(Meta-skill): ai/skills/meta/realtime-dashboard/ —— 完整的实时仪表盘开发指南
- dual-stream-architecture —— 事件发布架构
- resilient-connections —— 连接韧性保障
绝对禁止事项(NEVER Do)
- 绝对不可阻塞在 conn.send 上 —— 必须使用带 default 分支的 select 语句检测缓冲区溢出
- 绝对不可跳过优雅关闭流程 —— 客户端依赖标准关闭帧(close frame)完成清理
- 绝对不可跨频道复用 pubsub 实例 —— 每个频道必须持有独立的订阅对象
- 绝对不可忽略实例心跳上报 —— 失联实例将导致连接“孤儿化”(orphaned connections)
- 绝对不可省略 ping/pong 心跳机制 —— 负载均衡器会主动关闭“空闲”连接
热门AI工具
相关专题
聚焦 WebSocket 在前端项目中的工程化实践,涵盖原生 JavaScript WebSocket 连接的封装与状态管理、Vue 3 中 WebSocket 的 Composable 封装(useWebSocket)、React 中自定义 Hook 管理连接生命周期、心跳检测(Ping/Pong 定时器)与自动断线重连的实现策略、指数退避重连算法、消息序列化协议(JSON / Protobuf / MessagePack)的选型与性
268
2026.05.25
本专题聚焦 Python 在实时通信场景中的开发实践,系统讲解 WebSocket 协议原理、长连接管理、消息推送机制以及异步服务架构设计。内容包括客户端与服务端通信实现、连接稳定性优化、消息队列集成及高并发处理策略。通过完整案例,帮助开发者构建高效稳定的实时通信系统,适用于聊天应用、实时数据推送等场景。
115
2026.03.18
本专题系统讲解 PHP 在实时通信与长连接场景中的应用实践,涵盖 WebSocket 协议原理、服务端连接管理、消息推送机制、心跳检测、断线重连以及与前端的实时交互实现。通过聊天系统、实时通知等案例,帮助开发者掌握 使用 PHP 构建实时通信与推送服务的完整开发流程,适用于即时消息与高互动性应用场景。
316
2026.01.19
本专题系统讲解 Golang 在 WebSocket 开发中的应用,涵盖 WebSocket 协议、连接管理、消息推送、心跳机制、群聊功能与广播系统的实现。通过构建实际的聊天应用或实时数据推送系统,帮助开发者掌握 如何使用 Golang 构建高效、可靠的实时通信系统,提高并发处理与系统的可扩展性。
135
2025.12.22
本专题聚焦Go-Zero的API开发,拆解.api描述文件的语法结构、路由与分组定义、参数绑定与校验规则,说明统一响应体、JWT鉴权、跨域与接口文档生成的落地方式,并给出网关聚合与接口测试的实践建议。
0
2026.11.12
本专题围绕Go-Zero的安装与工具链配置展开,讲清Go版本要求、goctl安装方式、代理镜像、protoc依赖与环境变量设置,说明多版本共存、升级回退与CI流水线安装的做法,并整理安装阶段的常见报错与验证步骤。
0
2026.11.12
本专题整理Go-Zero的入门知识,从框架定位、环境准备到跑通第一个API服务,讲清目录分层、配置加载、日志与中间件的基本用法,并对比Gin、Kratos的差异,帮助Go开发者建立整体认知,判断它是否适合当前项目。
0
2026.11.12
本专题从实际API接口调试场景出发,讲解Postman身份认证的完整配置流程,包括常见认证协议介绍、授权参数设置、访问令牌填写、OAuth 2.0授权及认证失败排查,帮助用户正确完成接口授权与访问验证。
0
2026.11.06
热门下载
相关下载
精品课程
最新文章
