ws 组件：WebSocket 客户端节点，对称 net 组件。两种工作模式：

• 出站拨号（server=ws://host:port）：作为 WebSocket 客户端拨号连接远端服务器，发送消息
• 会话寻址推送（server=ref://<endpoint/ws 实例ID>）：复用服务端 endpoint 已建立的 WS 连接，按 target 向指定客户端主动推送

提示

• 出站模式：文本/JSON 消息按原样发送；BINARY 类型或 messageType=binary 发送二进制帧
• 寻址模式：与 net 组件 ref:// 模式一致，target 支持 ${} 表达式

配置

字段	类型	是否必填	说明	默认值
server	string	是	ws://host:port 拨号发送；或 ref://<endpoint/ws 实例ID> 寻址推送	-
target	string	否	寻址目标，仅 server 为 ref:// 时生效。支持 ${} 表达式；值为 sessionKey 标识（如 deviceId）/*(广播)，精确匹配不按 IP 聚合	-
headers	object	否	握手时的 HTTP 请求头，如 Authorization	-
subprotocol	string	否	Sec-WebSocket-Protocol 子协议，如 mqtt / ocpp1.6。留空不协商	-
connectTimeout	int	否	拨号握手超时（秒），<=0 用默认	0
insecureSkipVerify	bool	否	跳过 TLS 证书验证（wss:// 自签证书场景）	false
messageType	string	否	发送的消息类型：text / binary	text
heartbeatInterval	int	否	心跳间隔（秒）。>0 定期发 Ping 帧保活+断线重连；0=禁用心跳与重连	60

心跳与重连（出站模式）

当 heartbeatInterval > 0 时，出站模式启用心跳保活与断线重连：

• 心跳：按间隔发送 WebSocket 协议级 Ping 帧，保持连接活跃
• 重连：连接断开（Ping 失败或读循环检测到错误）后自动重新拨号
• 读循环：内部持续读取以处理对端返回的 Pong 帧，并感知连接断开
• heartbeatInterval=0：不发送心跳也不自动重连；但写失败时会重置连接缓存，下次发送自动重新拨号

并发安全

gorilla/websocket 的 WriteMessage 不支持并发写，组件内部已用互斥锁保护业务发送；Ping 控制帧可与业务发送并发，无需额外加锁。

Relation Type

• Success: 消息发送/推送成功时，将消息转发到 Success 链路
• Failure: 以下情况消息发送到 Failure 链：
  • 拨号失败（出站模式）
  • 发送超时/连接断开
  • 寻址模式：target 未匹配任何会话，或表达式解析为空（非显式 *）

配置示例

出站拨号

{
  "id": "s1",
  "type": "ws",
  "name": "发送到ws服务",
  "configuration": {
    "server": "ws://127.0.0.1:8080/ws",
    "heartbeatInterval": 30
  }
}

会话寻址推送（ref:// 模式）

{
  "id": "s2",
  "type": "ws",
  "name": "下发指令",
  "configuration": {
    "server": "ref://ws_endpoint_1",
    "target": "${metadata.deviceId}"
  }
}

带认证与子协议

{
  "id": "s3",
  "type": "ws",
  "configuration": {
    "server": "wss://api.example.com/stream",
    "headers": { "Authorization": "Bearer token123" },
    "subprotocol": "mqtt",
    "insecureSkipVerify": true
  }
}

与 endpoint/ws_client 的区别

• ws 组件（本组件，type=ws）：发送节点，作为客户端向远端发送，或 ref:// 寻址推送已连接的客户端
• endpoint/ws_client：接收端点，主动连接远端 server 订阅其推送的消息。详见 websocket client endpoint

应用示例

示例参考：WebSocket 客户端测试 (opens new window)