# Traffic Split 配置选项

traffic-split 插件根据条件或权重将流量定向到多个上游服务，为 API 发布策略和流量管理提供灵活方式。<!-- --> <!-- -->配置涵盖插件参数。

## 参数[​](#参数 "参数的直接链接")

有关所有插件均可使用的配置项，请参阅[插件通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md)。

* rules

  array\[object]

  ***

  要执行的一组或多组匹配条件和动作。

  * match

    array\[object]

    ***

    用于条件流量拆分的匹配规则。

    * vars

      array\[array]

      ***

      一个或多个 [APISIX 表达式](https://docs.apiseven.com/apisix/reference/apisix-expressions.md) 形式的匹配条件数组，用于按条件执行插件。

  * weighted\_upstreams

    array\[object]

    ***

    上游配置列表。

    * upstream\_id

      string or integer

      ***

      配置的上游对象的 ID。

    * weight

      integer

      默认值：`1`

      ***

      发送到 `weighted_upstreams` 中该项的相对流量份额。

    * upstream

      object

      ***

      内联上游配置。APISIX 3.20.0 及更高版本除应用下列其他字段外，还会应用 `tls` 和 `keepalive_pool`。较早的 APISIX 版本以及 API7 企业版 3.9.23 和 3.10.10 会忽略内联 `traffic-split` 上游的这两个配置。

      如需使用健康检查、重试、预热、服务发现、其他[上游配置](https://docs.apiseven.com/apisix/reference/admin-api.md#tag/Upstream/paths/~1apisix~1admin~1upstreams/post)，或在多个路由中复用同一上游配置，请创建上游对象并设置 `upstream_id`。

      * type

        string

        默认值：`roundrobin`

        有效值：

        `roundrobin`、`chash`、`ewma` 或 `least_conn`

        ***

        在此内联上游内选择节点的负载均衡算法。`roundrobin` 表示加权轮询，`chash` 表示一致性哈希，`ewma` 表示指数加权移动平均，`least_conn` 表示最少连接。父级 `weight` 字段控制分配给该上游的流量份额。

      * hash\_on

        string

        默认值：`vars`

        有效值：

        `vars`、`header`、`cookie`、`consumer` 或 `vars_combinations`

        ***

        当 `type` 为 `chash` 时使用。支持对[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)、请求头、Cookie、消费者或[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)的组合进行哈希。

      * key

        string

        ***

        当 `type` 为 `chash` 时使用。当 `hash_on` 设置为 `header` 或 `cookie` 时，`key` 为必填项。当 `hash_on` 设置为 `consumer` 时，无需配置 `key`，因为 Consumer 名称会自动用作键。

      * scheme

        string

        默认值：`http`

        有效值：

        API7 网关：`http` 或 `https`

        <br />

        APISIX：`http` 或 `https`；APISIX 3.19.0 及更高版本还支持 `ws` 和 `wss`

        ***

        用于与此内联上游通信的协议。如需使用其他协议，请创建上游对象并设置 `upstream_id`。

      * nodes

        object

        ***

        上游节点的地址。

      * timeout

        object

        ***

        连接、发送和接收消息的超时时间（以秒为单位）。

      * pass\_host

        string

        默认值：`pass`

        有效值：

        `pass`、`node` 或 `rewrite`

        ***

        决定如何传递主机名的模式。`pass` 将客户端的主机名传递给上游。`node` 传递上游节点中配置的主机。`rewrite` 传递 `upstream_host` 中配置的值。

      * upstream\_host

        string

        ***

        当 `pass_host` 为 `rewrite` 时使用。上游的主机名。

      * name

        string

        ***

        上游的标识符，用于指定服务名称、使用场景等。

      * tls

        object

        ***

        此内联上游的 TLS 设置。从 APISIX 3.20.0 开始应用。

        * verify

          boolean

          ***

          是否验证上游证书。省略时，上游遵循 NGINX 的验证设置。

        * ca\_certs

          array\[string]

          有效值：

          至少一张 PEM 编码的 CA 证书

          ***

          用于验证上游证书的 CA 证书。启用验证且省略此字段时，使用共享 CA 信任存储。`ws` 或 `wss` 上游不支持此字段，它们使用共享信任存储。

        * client\_cert

          string

          ***

          向上游提供的 PEM 编码客户端证书。需要配置 `client_key`。

        * client\_key

          string

          ***

          `client_cert` 对应的 PEM 编码私钥。需要配置 `client_cert`。

        * client\_cert\_id

          string or integer

          ***

          客户端 SSL 对象的 ID。不要与 `client_cert` 和 `client_key` 同时配置。

      * keepalive\_pool

        object

        ***

        此内联上游的连接池设置。从 APISIX 3.20.0 开始应用。

        * size

          integer

          默认值：`320`

          有效值：

          大于或等于 1

          ***

          每个工作进程在连接池中保留的最大空闲连接数。

        * idle\_timeout

          number

          默认值：`60`

          有效值：

          大于或等于 0

          ***

          空闲连接在连接池中可保留的秒数。

        * requests

          integer

          默认值：`1000`

          有效值：

          大于或等于 1

          ***

          一个连接关闭前最多可处理的请求数。
