四层路由
除了普通路由处理的标准第 7 层（HTTP/HTTPS）流量外，四层路由还支持 API7 网关代理第 4 层（L4）流量，即 TCP 和 UDP 连接。这样，你可以将 API7 网关作为统一代理，同时处理 HTTP API 以及数据库、消息队列、自定义 TCP 服务等非 HTTP 协议。
四层路由如何工作
不同于按 URI 路径、HTTP 方法和请求头匹配的 HTTP 路由，四层路由根据网络层属性进行匹配：
| 匹配字段 | 描述 | 示例 |
|---|---|---|
remote_addr | 客户端 IP 地址或 CIDR 范围 | 10.0.0.0/8 |
server_addr | 网关监听 IP 地址 | 192.168.1.100 |
server_port | 网关监听端口 | 3306 |
sni | TLS Server Name Indication（用于 TLS Stream） | db.example.com |
所有指定的匹配字段都会按 AND 逻辑求值。如果未指定任何匹配字段，则该四层路由会匹配配置的 stream 代理端口上的所有流量。
请求流程
- TCP 或 UDP 客户端连接到网关配置的某个
stream_proxy端口。 - 网关会根据连接的网络属性评估所有四层路由。
- 匹配到的四层路由决定上游，随后连接会被代理到上游服务。
Stream 服务
四层路由必须属于一个 stream 类型服务（即 type: stream 的服务）。Stream 服务不能包含普通 HTTP 路由，HTTP 服务也不能包含四层路由。
Stream 服务与 HTTP 服务拥有相同的生命周期：
- 配置限定在网关组作用域内
- 上游继承（除非覆盖，否则四层路由会继承其父级服务的上游配置）
支持的插件
只有一部分插件支持 stream（L4）上下文：
| 插件 | 类别 | 描述 |
|---|---|---|
ip-restriction | 安全 | 基于客户端 IP 允许或拒绝流量 |
limit-conn | 流量 | 限制并发连接数 |
mqtt-proxy | 协议 | MQTT 协议代理与路由 |
traffic-split | 流量 | 按权重在多个上游之间拆分流量 |
prometheus | 可观测性 | 暴露 Stream 指标 |
syslog | 可观测性 | 将 Stream 事件记录到 syslog |
HTTP 专用插件（例如 key-auth、proxy-rewrite 或 response-rewrite）不能应用于四层路由。
启用 Stream 代理
使用四层路由前，你必须配置网关监听用于 Stream 流量的 TCP 和/或 UDP 端口。该配置位于网关的 config.yaml：
apisix:
stream_proxy:
tcp:
- addr: 9100 # 监听所有接口的 9100 端口
- addr: "127.0.0.1:9101" # 监听指定 IP
tls: true # 在此端口启用 TLS
udp:
- 9200 # 监听所有接口的 9200 端口
信息
Stream 代理端口独立于 HTTP 代理端口（node_listen / ssl.listen）。客户端连接到 Stream 代理端口以访问 L4 流量，连接到 HTTP 端口以访问 L7 流量。
四层路由与 HTTP 路由
| 方面 | HTTP 路由 | 四层路由 |
|---|---|---|
| 协议 | HTTP、HTTPS、gRPC、WebSocket | TCP、UDP |
| 匹配条件 | URI、host、headers、methods、expressions | 客户端 IP、服务器 IP、服务器端口、SNI |
| 服务类型 | http | stream |
| 插件支持 | 完整插件库 | 6 个兼容 Stream 的插件 |
| 路由算法 | 基于 URI 的基数树 | 按 IP/端口顺序匹配（TLS 场景下基于 SNI 使用基数树） |
后续步骤
- TCP/UDP 代理：逐步学习如何代理 TCP 和 UDP 流量。
- 服务与路由：了解 HTTP 服务和路由。
- 插件：插件系统概览。