Websocket Hub Patterns

Polar Sponsor
爱发电 赞助
.NET 9.0

可水平扩展的 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 心跳机制 —— 负载均衡器会主动关闭“空闲”连接

相关专题

更多
WebSocket发送和接收数据教程合集
WebSocket发送和接收数据教程合集

本专题整合了WebSocket发送与接收数据教程合集,阅读专题下面的文章了解更多详细内容。

2026.05.25

221

20

WebSocket 前端开发与实战技巧
WebSocket 前端开发与实战技巧

聚焦 WebSocket 在前端项目中的工程化实践,涵盖原生 JavaScript WebSocket 连接的封装与状态管理、Vue 3 中 WebSocket 的 Composable 封装(useWebSocket)、React 中自定义 Hook 管理连接生命周期、心跳检测(Ping/Pong 定时器)与自动断线重连的实现策略、指数退避重连算法、消息序列化协议(JSON / Protobuf / MessagePack)的选型与性

2026.05.25

268

33

Python WebSocket实时通信与异步服务开发实践
Python WebSocket实时通信与异步服务开发实践

本专题聚焦 Python 在实时通信场景中的开发实践,系统讲解 WebSocket 协议原理、长连接管理、消息推送机制以及异步服务架构设计。内容包括客户端与服务端通信实现、连接稳定性优化、消息队列集成及高并发处理策略。通过完整案例,帮助开发者构建高效稳定的实时通信系统,适用于聊天应用、实时数据推送等场景。

2026.03.18

115

14

PHP WebSocket 实时通信开发
PHP WebSocket 实时通信开发

本专题系统讲解 PHP 在实时通信与长连接场景中的应用实践,涵盖 WebSocket 协议原理、服务端连接管理、消息推送机制、心跳检测、断线重连以及与前端的实时交互实现。通过聊天系统、实时通知等案例,帮助开发者掌握 使用 PHP 构建实时通信与推送服务的完整开发流程,适用于即时消息与高互动性应用场景。

2026.01.19

316

22

Golang WebSocket与实时通信开发
Golang WebSocket与实时通信开发

本专题系统讲解 Golang 在 WebSocket 开发中的应用,涵盖 WebSocket 协议、连接管理、消息推送、心跳机制、群聊功能与广播系统的实现。通过构建实际的聊天应用或实时数据推送系统,帮助开发者掌握 如何使用 Golang 构建高效、可靠的实时通信系统,提高并发处理与系统的可扩展性。

2025.12.22

135

11

Go-Zero API开发使用教程
Go-Zero API开发使用教程

本专题聚焦Go-Zero的API开发,拆解.api描述文件的语法结构、路由与分组定义、参数绑定与校验规则,说明统一响应体、JWT鉴权、跨域与接口文档生成的落地方式,并给出网关聚合与接口测试的实践建议。

2026.11.12

0

15

Go-Zero安装与goctl环境配置教程
Go-Zero安装与goctl环境配置教程

本专题围绕Go-Zero的安装与工具链配置展开,讲清Go版本要求、goctl安装方式、代理镜像、protoc依赖与环境变量设置,说明多版本共存、升级回退与CI流水线安装的做法,并整理安装阶段的常见报错与验证步骤。

2026.11.12

0

15

Go-Zero零基础入门教程
Go-Zero零基础入门教程

本专题整理Go-Zero的入门知识,从框架定位、环境准备到跑通第一个API服务,讲清目录分层、配置加载、日志与中间件的基本用法,并对比Gin、Kratos的差异,帮助Go开发者建立整体认知,判断它是否适合当前项目。

2026.11.12

0

15

Postman身份认证怎么配置
Postman身份认证怎么配置

本专题从实际API接口调试场景出发,讲解Postman身份认证的完整配置流程,包括常见认证协议介绍、授权参数设置、访问令牌填写、OAuth 2.0授权及认证失败排查,帮助用户正确完成接口授权与访问验证。

2026.11.06

0

12

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
相关推荐
/
热门推荐
/
最新课程
WebSocket手册
WebSocket手册

共0课时 | 0人学习

Webman中文手册
Webman中文手册

共0课时 | 0人学习