🔌 TCP 监听器

TCP 代理通过监听器接收客户端连接并转发到上游服务。管理后台「TCP 代理 → 监听器」页面进行管理，保存后立即生效，无需重启。

什么是监听器

一个监听器定义：客户端连到本地某个端口后，流量被转发到指定的上游 host:port，并按配置的协议进行分帧与解析。

监听器字段

字段	说明
名称	监听器名称（唯一），TCP 规则通过名称引用
端口	本地监听端口
上游主机	转发目标主机
上游端口	转发目标端口
上游 TLS	与上游通信是否启用 TLS、是否跳过证书校验
协议	分帧与解析类型（见下）

协议类型

类型	说明	适用场景
raw	透传，不做分帧	私有二进制流
delimiter	按分隔符分帧（如 \n）	文本行协议
lengthPrefix	长度前缀分帧	二进制 RPC 协议
fixedLength	固定长度分帧	定长报文
redis	Redis RESP 协议解析	Redis 代理
mysql	MySQL 协议解析（COM 命令 / 结果集）	MySQL 代理
mqtt	MQTT 协议解析	MQTT 代理
websocket	WebSocket 握手 + 帧解析	WebSocket 代理
grpc	gRPC over HTTP/2 解析	gRPC 代理
custom	引用命名 Codec	自定义协议

常见配置示例

Redis 监听器

- name: redis-demo
  port: 16379
  upstreamHost: 127.0.0.1
  upstreamPort: 6379
  protocol:
    type: redis

分隔符文本协议

- name: text-demo
  port: 19001
  upstreamHost: 127.0.0.1
  upstreamPort: 19000
  protocol:
    type: delimiter
    delimiter: "\n"
    maxDelimiterScan: 1024
    parseFields:
        - name: cmd
          split: ' '
          index: 0
        - name: body
          json: true

长度前缀二进制协议

- name: bin-rpc-demo
  port: 19002
  upstreamHost: 127.0.0.1
  upstreamPort: 19003
  protocol:
    type: lengthPrefix
    lengthBytes: 4
    lengthEndian: big
    bodyOffset: 4

自定义 Codec

- name: line-cmd-demo
  port: 19004
  upstreamHost: 127.0.0.1
  upstreamPort: 19005
  protocol:
    type: custom
    codecName: line-cmd

codecName 引用 协议 Codec 表中已定义的命名 Codec。

MQTT / WebSocket / gRPC 监听器

- name: mqtt-demo        # MQTT 协议自动解析
  port: 1884
  upstreamHost: 127.0.0.1
  upstreamPort: 1883
  protocol:
    type: mqtt

- name: websocket-demo   # WebSocket 握手 + 数据帧
  port: 18080
  upstreamHost: 127.0.0.1
  upstreamPort: 8081
  protocol:
    type: websocket

- name: grpc-demo        # gRPC over HTTP/2
  port: 15051
  upstreamHost: 127.0.0.1
  upstreamPort: 50051
  protocol:
    type: grpc

生命周期管理

管理后台支持对监听器进行：

• 启动 / 停止：单独启停某个监听器
• 修改：修改端口、上游、协议配置，保存后立即生效
• 删除：删除监听器，同时停止其监听

相关 API

方法	路径	说明
GET	/api/tcp/listeners	监听器列表
POST	/api/tcp/listeners	新建监听器
PUT	/api/tcp/listeners/:name	更新监听器
DELETE	/api/tcp/listeners/:name	删除监听器
POST	/api/tcp/listeners/:name/start	启动
POST	/api/tcp/listeners/:name/stop	停止
GET	/api/tcp/sessions	活跃会话列表