wueasy-websocket

切换主题

WebSocket 快速开始 🚀 ​

开始之前 🎯 ​

本页帮助你在5分钟内启动并使用 wueasy-websocket：

  • 启动服务并完成鉴权接入
  • 通过 /feign/publish 推送到用户/频道/全体
  • 连接 /ws 并接收消息

示例配置 ⚙️ ​

将以下内容保存为 config.yaml（精简示例，字段与源码一致）：

yaml
server:
  name: websocket
  port: 9811
log:
  level: info
  max-size: 20
  max-backups: 7
  max-age: 7
nacos:
  server-addr: ${NACOS_SERVER_ADDR:192.168.3.181:8848}  #地址，多个逗号分隔
  username: ${NACOS_USERNAME:dev}
  password: ${NACOS_PASSWORD:dev}
  config:
    namespace: ${NACOS_NAMESPACE:dev}
    group: ${NACOS_GROUP:dev}
    enabled: false
  discovery:
    namespace: ${NACOS_NAMESPACE:dev}
    group: ${NACOS_GROUP:dev}
    enabled: false
    # metadata:  #元数据
    #   version: gray-2  # 指定灰度版本号
    #ip: 192.168.3.54   #指定本机ip
    #port: 9720 #服务端口
websocket:
  cluster-enabled: true # 是否开启集群模式，若为false则仅广播消息至当前实例
  accept-client-message: true # 是否接受客户端消息，若为false则仅广播消息至其他实例·
  max-connections: 10000 # 最大连接数，0表示不限制
  max-message-size: 1048576 # 最大消息大小（字节）
  pong-timeout: "60s"  # 心跳超时时间（秒），超过此时间未收到心跳则认为连接已断开
  heartbeat-content: "heartbeat" # 心跳文本内容，匹配时仅刷新超时不写入MQ
  verify-uri: "http://127.0.0.1:8080/demo/websocket/getSession" # 示例: lb://wueasy-gateway/user/getSessionByCode 或 http://127.0.0.1:8080/user/getSessionByCode  
  verify-timeout: "30s"  # 验证超时时间（秒），超过此时间未收到验证响应则认为连接失败
  temp-verify-enabled: true # 是否开启临时用户验证
  temp-verify-uri: "http://127.0.0.1:8080/demo/temp-token/verify" # 示例: lb://wueasy-gateway/user/getTempSessionByCode 或 http://127.0.0.1:8080/user/getTempSessionByCode  
  temp-max-connection-time: "60s"  # 临时用户最大连接时间（秒）
  allowed-origins: 
    - "*" # 允许所有来源，生产环境建议指定具体域名
# 异步模式下的MQ配置
mq:
  type: "kafka" # MQ类型: kafka, rabbitmq
  # Kafka配置
  kafka:
    brokers: ["192.168.3.181:9092"] # Kafka broker地址列表
    topic: "websocket" # 服务端广播主题
    client-topic: "websocket-client" # 客户端消息主题（上行消息）
    group-id: "websocket-consumer" # 消费者组ID（非广播时所有实例共享）
    broadcast: true # 是否广播：true 时每个实例使用唯一消费者组ID
    # 生产者配置
    producer:
      acks: "all" # 确认机制: all, 1, 0
      retries: 3 # 重试次数
      batch-size: 16384 # 批次大小
      linger-ms: 5 # 等待时间(毫秒)
      buffer-memory: 33554432 # 缓冲区大小(字节)
    # 消费者配置
    consumer:
      auto-commit: true # 自动提交
      auto-offset-reset: "earliest" # 偏移量重置策略: earliest, latest
      session-timeout-ms: 30000 # 会话超时时间(毫秒)
      heartbeat-interval-ms: 3000 # 心跳间隔(毫秒)
  # RabbitMQ配置
  rabbitmq:
    url: "amqp://wueasy:1QAZ2wsx@192.168.3.181:5672/" # RabbitMQ连接URL
    exchange: "websocket" # 交换机名称（建议 direct 分流广播与客户端）
    routing-key: "ws.broadcast" # 广播路由键（WebSocket 集群消费绑定此键）
    client-routing-key: "ws.client" # 客户端消息路由键（其他服务队列绑定此键）
    queue: "" # 队列名称，留空将生成安全自定义队列（避免 amq.* 保留前缀），用于区分实例，确保每实例独立消费
    # 交换机配置
    exchange-type: "direct" # 交换机类型: direct, fanout, topic（建议 direct：使用不同路由键实现分流）
    durable: true # 持久化
    auto-delete: false # 自动删除
    # 队列配置
    queue-durable: true # 队列持久化
    queue-auto-delete: false # 队列自动删除
    # 消息配置
    delivery-mode: 1 # 消息持久化: 1(非持久), 2(持久)
    priority: 0 # 消息优先级
    expiration: "" # 消息过期时间

更多字段说明见《配置说明》。

启动服务 🟢 ​

将可执行程序与 config.yaml 放在同一目录，启动后监听 http://localhost:9811/。

连接与鉴权 🔐 ​

服务在升级为 WebSocket 前会调用 verify-uri 进行鉴权，要求返回包含 userId 的结果：

json
{
    "code": 0,
    "successful": true,
    "msg": null,
    "data": { 
      "userId": "1001" 
    },
    "encrypt": false
}

如果使用 Nacos，可将 verify-uri 设置为 lb://account-service/verify。

临时会话接入（可选） ​

当启用临时验证时，客户端可通过一次性 code 建立“临时链接”，服务端将该链接标记为临时并设定最大存活时长：

text
ws://localhost:9811/ws?temp=1&code=TEMP_CODE_123

发布时使用 targetType: "temp_user"，仅向该用户的临时链接推送，不影响该用户的正常链接。

浏览器示例前端 💻 ​

html
<script>
  const ws = new WebSocket("ws://localhost:9811/ws?temp=1&token=xxx");
  ws.onmessage = (e) => console.log("推送:", e.data);
  ws.onopen = () => ws.send("heartbeat"); // 心跳示例（与配置匹配）
</script>

推送消息 📤 ​

bash
# 全体广播
curl -X POST http://localhost:9811/publish \
  -H "Content-Type: application/json" \
  -d '{"targetType":"all","data":"hello"}'

# 推送给用户
curl -X POST http://localhost:9811/publish \
  -H "Content-Type: application/json" \
  -d '{"targetType":"user","target":"user-123","data":"hi user"}'

# 推送到频道
curl -X POST http://localhost:9811/publish \
  -H "Content-Type: application/json" \
  -d '{"targetType":"channel","target":"notice","data":"hi channel"}'

# 仅推送临时会话（目标为用户ID，仅投递临时链接）
curl -X POST http://localhost:9811/publish \
  -H "Content-Type: application/json" \
  -d '{"targetType":"temp_user","target":"user-123","data":"hi temp"}'

查询在线用户 👥 ​

bash
curl "http://localhost:9811/feign/getOnlineUsers"

常见问题 ❓ ​

  • 连接被拒：检查 allowed-origins 与浏览器来源一致
  • 无法推送：确认 /publish 返回 200 且 Hub 已初始化
  • 集群消息未达：检查 MQ 连接与交换机/主题配置

集群模式参考（可选） ​

将 cluster-enabled 设为 true 后，需要正确配置 MQ（Kafka 或 RabbitMQ）。示例（RabbitMQ）：

yaml
websocket:
  cluster-enabled: true
mq:
  type: rabbitmq
  rabbitmq:
    url: amqp://wueasy:1QAZ2wsx@192.168.3.181:5672/
    exchange: websocket
    routing-key: ws.broadcast
    client-routing-key: ws.client
    queue: ""
    exchange-type: direct
    durable: true
    auto-delete: false
    queue-durable: true
    queue-auto-delete: false
    delivery-mode: 1
    priority: 0
    expiration: ""

更多集群细节与最佳实践见《集群部署》。

Copyright © 2017-2025 wueasy.com