# 代理传输层 (L4) 流量

默认情况下，APISIX 作为应用层 (L7) 代理运行。APISIX 还支持处理传输层 (L4) TCP 和 UDP 流量，既可以单独处理，也可以在处理应用层 (L7) 流量的基础上处理。

本指南将向你展示如何配置 APISIX 以代理传输层 (L4) 流量，并配置 [流路由](https://docs.apiseven.com/apisix/key-concepts/stream-routes.md) 以建立与 MySQL 服务器的连接。

## 前置条件[​](#前置条件 "前置条件的直接链接")

* 安装 [Docker](https://docs.docker.com/get-docker)。
* 安装 [cURL](https://curl.se/) 以向服务发送请求进行验证。
* 安装 [jq](https://jqlang.github.io/jq/download/)，以便创建包含 PEM 证书且不会破坏 JSON 转义的资源。
* 安装 [OpenSSL](https://www.openssl.org/)，以创建示例 mTLS 证书。
* 按照 [快速入门教程](https://docs.apiseven.com/apisix/getting-started.md) 在 Docker 或 Kubernetes 中启动一个新的 APISIX 实例。
* 安装 [MySQL 命令行客户端](https://dev.mysql.com/doc/refman/8.4/en/mysql.html)，以使用 `mysql` 命令验证四层路由。
* 如果使用 Admin API 示例且启用了身份验证，请将管理员角色的密钥导出为 `ADMIN_API_KEY`。请在 `deployment.admin.admin_key` 下配置该密钥。Docker 快速入门为了便于本地评估而禁用了身份验证；生产环境中请保持启用。

## 启动 MySQL 服务器[​](#启动-mysql-服务器 "启动 MySQL 服务器的直接链接")

启动一个 MySQL 实例作为示例上游服务，并将 root 密码配置为 `my-secret-pw`：

```
docker run -d \

  --name mysql \

  --network=apisix-quickstart-net \

  -e MYSQL_ROOT_PASSWORD=my-secret-pw \

  mysql:9.4
```

## 启用传输层 (L4) 代理[​](#启用传输层-l4-代理 "启用传输层 (L4) 代理的直接链接")

默认情况下，APISIX 仅启用应用层 (L7) 代理。要同时代理传输层 (L4) 流量，请配置 `proxy_mode` 和 `stream_proxy`。

将完整的当前[配置文件](https://docs.apiseven.com/apisix/reference/configuration-files.md#configyaml-and-configyamlexample)复制到宿主机并保留备份：

```
docker cp apisix-quickstart:/usr/local/apisix/conf/config.yaml ./config.yaml

cp ./config.yaml ./config.yaml.backup
```

在本地 `config.yaml` 中，将以下字段合并到现有的 `apisix` 映射。`http&stream` 模式会在启用 TCP 监听器的同时保留 HTTP（L7）代理。请保留现有的 Admin API 身份验证、白名单、etcd 和插件设置：

config.yaml（L4 设置）

```
apisix:

  proxy_mode: http&stream

  stream_proxy:

    tcp:

      - 9100
```

保留列表中现有的 Stream 监听器。此片段不是完整的替换配置。将候选文件复制到容器中，然后进行验证，仅在验证成功后重新加载 APISIX：

```
docker cp ./config.yaml apisix-quickstart:/usr/local/apisix/conf/config.yaml

docker exec apisix-quickstart apisix test && \

  docker exec apisix-quickstart apisix reload
```

如果验证失败，请先恢复备份，再进行其他更改：

```
docker cp ./config.yaml.backup apisix-quickstart:/usr/local/apisix/conf/config.yaml
```

### 配置 Stream 监听器[​](#配置-stream-监听器 "配置 Stream 监听器的直接链接")

`tcp` 和 `udp` 数组支持单个端口、绑定地址和端口范围。如果监听器需要终止 TLS，TCP 条目还可以是包含 `addr` 和 `tls` 字段的对象。

config.yaml

```
apisix:

  proxy_mode: http&stream

  stream_proxy:

    tcp:

      - 9100

      - "127.0.0.1:9101"

      - "[::1]:9102"

      - "9200-9210"

      - addr: "127.0.0.1:9300-9310"

        tls: true

    udp:

      - 9400

      - "127.0.0.1:9401"

      - "9500-9510"
```

端口值必须是 1 到 65535 之间的整数。对于端口范围，起始端口不得大于结束端口。请为 `"9200-9210"` 等范围值加引号，使 YAML 将其保留为字符串。同一配置中可以混用单个端口、地址、IPv6 地址、端口范围和对象条目。

请通过容器运行时、Kubernetes `Service`、主机防火墙以及所有外部负载均衡器公开每个已配置的监听器。例如，使用 9100 和 9200 到 9210 端口的 Docker 部署，在创建容器时需要同时配置 `-p 9100:9100` 和 `-p 9200-9210:9200-9210`。仅在 `config.yaml` 中添加监听器不会自动将其公开到容器外部。

### 配置 PROXY 协议[​](#配置-proxy-协议 "配置 PROXY 协议的直接链接")

APISIX 可从 TCP 负载均衡器接收 [PROXY 协议](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)，并向兼容的上游发送新的 PROXY 头。全局设置为所有 TCP 监听器提供默认值：

config.yaml

```
apisix:

  proxy_mode: http&stream

  proxy_protocol:

    enable_tcp_pp: true

    enable_tcp_pp_to_upstream: true

  stream_proxy:

    tcp:

      - addr: 9100

        proxy_protocol: false

        proxy_protocol_to_upstream: false

      - 9200
```

使用对象条目可为单个端口覆盖任一方向。显式的 `true` 或 `false` 优先于相应的全局默认值：

config.yaml

```
apisix:

  proxy_mode: http&stream

  proxy_protocol:

    enable_tcp_pp: true

  stream_proxy:

    tcp:

      - addr: 9100

        proxy_protocol: false

      - addr: 9200

      - addr: "[::]:9201"

        proxy_protocol_to_upstream: true
```

| 设置                         | 方向                        | 效果                                                                         |
| ---------------------------- | --------------------------- | ---------------------------------------------------------------------------- |
| `proxy_protocol`             | 客户端或负载均衡器到 APISIX | 为 TCP 监听器添加 `proxy_protocol` 参数，使 APISIX 读取并处理入站 PROXY 头。 |
| `proxy_protocol_to_upstream` | APISIX 到上游               | 在被代理的 Stream 数据之前发送 PROXY 头。                                    |

这些示例将端口 `9200` 保留给 PROXY 协议流量。端口 `9100` 仍与本指南后续直接使用的 MySQL 和 HTTP 客户端兼容。

使用端口 `9200` 前，请从网关容器公开它、将 Stream 路由绑定到它，并使用支持已启用 PROXY 协议方向的负载均衡器和上游。客户端和上游兼容之前，请勿在现有监听器上启用任一方向。

这些设置仅适用于 TCP；UDP 监听器绝不会接收或发送 PROXY 协议。

警告

仅在上游预期使用 PROXY 协议时启用 `proxy_protocol_to_upstream`。否则，上游会将明文 `PROXY` 行解释为应用数据，通常会关闭连接。TLS 上游无法将该行解析为 TLS 记录，除非它明确在开始 TLS 前接受 PROXY 协议。

默认情况下，APISIX 不信任入站 PROXY 头声明的客户端地址。请仅使用允许提供客户端地址的负载均衡器地址或网络配置 `nginx_config.stream.real_ip_from`：

config.yaml

```
apisix:

  proxy_mode: http&stream

  stream_proxy:

    tcp:

      - addr: 9200

        proxy_protocol: true

        proxy_protocol_to_upstream: true



nginx_config:

  stream:

    real_ip_from:

      - 192.168.1.0/24

      - 2001:db8:1234::/48
```

对于来自受信任对端的连接，`$remote_addr`、Stream access log 和基于地址的插件使用入站头中的地址；`$realip_remote_addr` 保留直接连接的对端地址。

如果对端不受信任，APISIX 会读取并处理入站 PROXY 头，但保留对端地址。因此，向上游重建的 PROXY 头会标识不受信任的对端，而不是它声明的客户端。

信任一个网络会允许其中的任何对端声明任意客户端地址。请将列表限制为你控制的负载均衡器。

[重新加载 APISIX](https://docs.apiseven.com/apisix/reference/apisix-cli.md#apisix-reload) 以使配置更改生效：

```
docker exec apisix-quickstart apisix reload
```

如果你使用 [快速入门](https://docs.apiseven.com/apisix/getting-started.md#%E8%8E%B7%E5%8F%96-apisix) 在 Docker 中启动 APISIX，端口 `9100` 已经映射 (`-p 9100:9100`)。

## 创建流路由[​](#创建流路由 "创建流路由的直接链接")

创建一个 [流路由](https://docs.apiseven.com/apisix/key-concepts/stream-routes.md) 并配置 MySQL 服务器作为上游服务。

```
curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

  "id": "stream-route-mysql",

  "server_port": 9100,

  "upstream": {

    "nodes": {

      "mysql:3306": 1

    },

    "type": "roundrobin"

  }

}'
```

## 验证[​](#验证 "验证的直接链接")

以 root 身份连接 MySQL 服务器，并在提示时输入密码 `my-secret-pw`：

```
mysql --host=127.0.0.1 --port=9100 -u root -p
```

如果成功，你应该看到类似以下的欢迎文本：

```
Welcome to the MySQL monitor.  Commands end with ; or \g.

Your MySQL connection id is 9

Server version: 9.4.0 MySQL Community Server - GPL

Copyright (c) 2000, 2025, Oracle and/or its affiliates.
```

## 使用 mTLS 向 TLS 上游进行身份认证[​](#使用-mtls-向-tls-上游进行身份认证 "使用 mTLS 向 TLS 上游进行身份认证的直接链接")

对于要求客户端证书的 Stream 上游，将上游 scheme 设为 `tls`，并以内联方式或通过客户端 SSL 资源提供证书和私钥。APISIX-Runtime 必须包含 Stream 上游 mTLS 模块。

生成示例 CA、服务端证书和客户端证书：

```
mkdir -p stream-mtls-certs



openssl req -x509 -newkey rsa:2048 -nodes -days 365 \

  -subj "/CN=stream-mtls-ca" \

  -keyout stream-mtls-certs/ca.key \

  -out stream-mtls-certs/ca.crt



openssl req -newkey rsa:2048 -nodes \

  -subj "/CN=mtls-upstream" \

  -keyout stream-mtls-certs/server.key \

  -out stream-mtls-certs/server.csr

openssl x509 -req -days 365 \

  -in stream-mtls-certs/server.csr \

  -CA stream-mtls-certs/ca.crt \

  -CAkey stream-mtls-certs/ca.key \

  -CAcreateserial \

  -out stream-mtls-certs/server.crt



openssl req -newkey rsa:2048 -nodes \

  -subj "/CN=apisix-stream-client" \

  -keyout stream-mtls-certs/client.key \

  -out stream-mtls-certs/client.csr

openssl x509 -req -days 365 \

  -in stream-mtls-certs/client.csr \

  -CA stream-mtls-certs/ca.crt \

  -CAkey stream-mtls-certs/ca.key \

  -CAcreateserial \

  -out stream-mtls-certs/client.crt
```

在 APISIX Docker 网络上启动一个上游，使其要求由示例 CA 签名的客户端证书：

```
docker run -d --name mtls-upstream \

  --network=apisix-quickstart-net \

  -v "${PWD}/stream-mtls-certs:/certs:ro" \

  alpine/openssl \

  s_server -accept 9443 \

  -cert /certs/server.crt \

  -key /certs/server.key \

  -CAfile /certs/ca.crt \

  -Verify 1 \

  -www
```

为避免将私钥放入 Upstream 资源，请根据 PEM 文件创建客户端 SSL 资源：

```
jq -n \

  --rawfile cert stream-mtls-certs/client.crt \

  --rawfile key stream-mtls-certs/client.key \

  '{type: "client", cert: $cert, key: $key}' | \

curl "http://127.0.0.1:9180/apisix/admin/ssls/stream-client" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  --data-binary @-
```

创建 TLS 上游并引用客户端 SSL 资源：

```
curl "http://127.0.0.1:9180/apisix/admin/upstreams/stream-mtls" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "scheme": "tls",

    "type": "roundrobin",

    "nodes": {

      "mtls-upstream:9443": 1

    },

    "tls": {

      "client_cert_id": "stream-client"

    }

  }'
```

临时更新现有 Stream 路由以使用 mTLS 上游。后续流量拆分示例会再次用 MySQL 上游替换该路由配置。

```
curl "http://127.0.0.1:9180/apisix/admin/stream_routes/stream-route-mysql" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "server_port": 9100,

    "upstream_id": "stream-mtls"

  }'
```

当上游信任签署 `client.crt` 的 CA 时，TLS 握手成功，Stream 流量会到达上游。APISIX 会在资源校验时拒绝格式错误的内联证书和密钥对；若引用的客户端 SSL 资源缺失或类型错误，则关闭 Stream 会话。如果未配置客户端证书，或上游不信任呈现的证书，上游会拒绝握手，客户端不会收到代理响应。请同时检查 APISIX 和上游 TLS 错误日志，以区分配置和解析错误与上游验证失败。

通过 TCP 监听器发送普通 HTTP 请求。APISIX 会与示例上游建立 TLS 连接并出示其客户端证书：

```
curl -i "http://127.0.0.1:9100/"
```

你应收到以下开头的响应：

```
HTTP/1.0 200 ok

Content-type: text/html
```

你也可以在 Upstream 或内联 Stream Route 上游中内联配置 `upstream.tls.client_cert` 和 `upstream.tls.client_key`。启用数据加密时，APISIX 会在存储前加密内联 `client_key`；Stream Route 的 `GET` 响应不会以明文返回该密钥。

要使用 `$secret://...` 或 `$env://...` 证书引用，请将引用置于客户端 SSL 资源的 `cert` 和 `key` 字段，并通过 `client_cert_id` 选择它。Stream Worker 会在上游握手前解析这些字段。

## 配置 TLS 透传[​](#配置-tls-透传 "配置 TLS 透传的直接链接")

TLS 透传会将客户端的加密连接转发到上游。APISIX 读取 TLS ClientHello 中的服务器名称指示（SNI）来选择 Stream 路由，但由上游出示证书并完成握手。APISIX 无法检查加密的应用负载，也无法在此路径上认证客户端证书；如有需要，请在上游配置 mTLS。

在 `config.yaml` 中现有 TCP 监听器旁添加专用透传监听器：

config.yaml（新增 TCP 监听器）

```
apisix:

  proxy_mode: http&stream

  stream_proxy:

    tcp:

      - 9100

      - addr: 9101

        tls_passthrough: true
```

重新加载 APISIX 以应用监听器配置：

```
docker exec apisix-quickstart apisix reload
```

对于生产流量，请按照[配置 Stream 监听器](#%E9%85%8D%E7%BD%AE-stream-%E7%9B%91%E5%90%AC%E5%99%A8)中的说明，通过容器运行时或 Kubernetes Service 公开 9101 端口。下面的本地验证在现有 Docker 网络中运行，因此不需要额外的主机端口映射。

创建一条指向公共 HTTPS 服务的 Stream 路由：

```
curl "http://127.0.0.1:9180/apisix/admin/stream_routes/tls-passthrough" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "server_port": 9101,

    "snis": ["httpbin.org"],

    "tls_passthrough": true,

    "upstream": {

      "type": "roundrobin",

      "scheme": "tcp",

      "nodes": {

        "httpbin.org:443": 1

      }

    }

  }'
```

❶ `server_port` 选择上面配置的透传监听器。

❷ `snis` 匹配数组中的任意主机名。

❸ `tls_passthrough` 标识透传路由。在专用透传监听器上该字段是可选的，但在下面的混合监听器上是必需的。

❹ `scheme` 保持为 `tcp`，使 APISIX 转发客户端的 TLS 握手。使用 `tls` 会启动第二次 TLS 握手，导致连接失败。

从 Docker 网络发送请求。连接使用网关容器地址，同时保留用于 SNI 和证书验证的上游主机名：

```
docker run --rm --network apisix-quickstart-net curlimages/curl:8.16.0 \

  -i --connect-to "httpbin.org:443:apisix-quickstart:9101" \

  "https://httpbin.org/get"
```

成功的 HTTPS 响应表明客户端已通过 APISIX 与上游协商 TLS。此透传路由不需要在 APISIX 上配置 SSL 资源。

### 在两种 TLS 模式之间共享端口[​](#在两种-tls-模式之间共享端口 "在两种 TLS 模式之间共享端口的直接链接")

混合监听器可以在同一端口上透传部分服务，并为其他服务终止 TLS。同时启用两个监听器选项：

config.yaml（混合 TCP 监听器）

```
apisix:

  proxy_mode: http&stream

  stream_proxy:

    tcp:

      - addr: 9101

        tls: true

        tls_passthrough: true

        proxy_protocol_to_upstream: false
```

❶ `tls` 为使用 [SSL 证书资源](https://docs.apiseven.com/apisix/key-concepts/ssl-certificates.md)的路由启用 TLS 终止。

❷ `tls_passthrough` 允许配置了 `tls_passthrough: true` 的路由原样转发加密字节。未配置该字段的路由在 APISIX 处终止 TLS。

❸ `proxy_protocol_to_upstream` 保持为 `false`，因为混合监听器无法向上游发送 PROXY 协议。

路由变更会动态生效。监听器变更需要重新加载 APISIX。

如果上游需要 PROXY 头，请使用专用的 TLS 终止或透传监听器。在混合监听器上，NGINX Stream 会话指标会对每个客户端连接计数两次。

## 拆分 Stream 流量[​](#拆分-stream-流量 "拆分 Stream 流量的直接链接")

`traffic-split` 插件可以为 Stream 路由选择备用上游。Stream 路由会向规则表达式公开 `route_id` 等变量，而加权上游可以通过 ID 引用独立的上游对象。

使用不同的 root 密码启动第二个 MySQL 实例：

```
docker run -d \

  --name mysql-canary \

  --network=apisix-quickstart-net \

  -e MYSQL_ROOT_PASSWORD=canary-secret-pw \

  mysql:9.4
```

为灰度实例创建备用上游：

```
curl "http://127.0.0.1:9180/apisix/admin/upstreams/mysql-canary" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "type": "roundrobin",

    "nodes": {

      "mysql-canary:3306": 1

    }

  }'
```

更新 Stream 路由，使其路由 ID 匹配的请求使用灰度上游。仅包含权重的条目代表 Stream 路由的默认上游。下面的 `1:0` 权重会将所有匹配连接发送到灰度实例，以便进行确定性验证。

```
curl "http://127.0.0.1:9180/apisix/admin/stream_routes/stream-route-mysql" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "server_port": 9100,

    "plugins": {

      "traffic-split": {

        "rules": [

          {

            "match": [

              {

                "vars": [["route_id", "==", "stream-route-mysql"]]

              }

            ],

            "weighted_upstreams": [

              {

                "upstream_id": "mysql-canary",

                "weight": 1

              },

              {

                "weight": 0

              }

            ]

          }

        ]

      }

    },

    "upstream": {

      "type": "roundrobin",

      "nodes": {

        "mysql:3306": 1

      }

    }

}'
```

要将约 10% 的匹配连接发送到灰度实例，请将它的权重保持为 `1`，并将仅包含权重的默认上游条目改为 `9`。流量拆分必须同时包含两个条目；只修改单个条目的权重不会让其余流量继续使用路由的默认上游。

再次连接到 9100 端口，并在提示时输入 `canary-secret-pw`：

```
mysql --host=127.0.0.1 --port=9100 -u root -p
```

连接成功即表示规则选择了 `mysql-canary`。如果没有规则匹配，APISIX 会使用 Stream 路由的默认上游。

## 下一步[​](#下一步 "下一步的直接链接")

APISIX 在接受下游客户端请求或代理到上游服务时，还支持在 TCP 连接上使用 TLS 进行传输层（L4）代理。有关相关 TLS 和 Stream 路由概念，请参阅 [SSL 证书](https://docs.apiseven.com/apisix/key-concepts/ssl-certificates.md)和 [Stream 路由](https://docs.apiseven.com/apisix/key-concepts/stream-routes.md)。
