监听器配置 (proto)

config.listener.v3.AdditionalAddress

[config.listener.v3.AdditionalAddress proto]

监听器监听的附加地址。

{
  "address": {...},
  "socket_options": {...}
}

地址: (config.core.v3.Address)

套接字选项: (config.core.v3.SocketOptionsOverride) 可能不在 Envoy 源代码或预编译二进制文件中存在的附加套接字选项。如果指定，这将覆盖监听器中的套接字选项。如果指定但没有套接字选项或一个空的套接字选项列表，这意味着将不应用任何套接字选项。

config.listener.v3.Listener

[config.listener.v3.Listener proto]

{
  "name": ...,
  "address": {...},
  "additional_addresses": [],
  "stat_prefix": ...,
  "filter_chains": [],
  "filter_chain_matcher": {...},
  "use_original_dst": {...},
  "default_filter_chain": {...},
  "per_connection_buffer_limit_bytes": {...},
  "metadata": {...},
  "drain_type": ...,
  "listener_filters": [],
  "listener_filters_timeout": {...},
  "continue_on_listener_filters_timeout": ...,
  "transparent": {...},
  "freebind": {...},
  "socket_options": [],
  "tcp_fast_open_queue_length": {...},
  "traffic_direction": ...,
  "udp_listener_config": {...},
  "api_listener": {...},
  "connection_balance_config": {...},
  "reuse_port": ...,
  "enable_reuse_port": {...},
  "access_log": [],
  "tcp_backlog_size": {...},
  "max_connections_to_accept_per_socket_event": {...},
  "bind_to_port": {...},
  "internal_listener": {...},
  "enable_mptcp": ...,
  "ignore_global_conn_limit": ...,
  "bypass_overload_manager": ...
}

名称: (string) 此监听器已知的唯一名称。如果未提供名称，Envoy 将为监听器分配一个内部 UUID。如果监听器要通过 LDS 动态更新或删除，则必须提供唯一的名称。

地址: (config.core.v3.Address) 监听器应监听的地址。一般来说，地址必须是唯一的，但这由操作系统的绑定规则决定。例如，多个监听器可以在 Linux 上监听端口 0，因为实际端口将由操作系统分配。必需的，除非填充了 api_listener 或 listener_specifier。

附加地址: (repeated config.listener.v3.AdditionalAddress) 监听器应监听的附加地址。这些地址在所有监听器中必须是唯一的。可以提供多个端口为 0 的地址。当在单个监听器中使用多个地址时，所有地址都使用相同的协议，并且不支持多个内部地址。

统计前缀: (string) 监听器统计信息要使用的可选前缀。如果为空，统计信息将以 listener.<address as string>. 为根。如果非空，统计信息将以 listener.<stat_prefix>. 为根。

过滤器链

(repeated config.listener.v3.FilterChain) 此监听器要考虑的一系列过滤器链。具有最具体的 FilterChainMatch 标准的 FilterChain 将在连接上使用。

可以在常见问题解答条目中找到使用 SNI 进行过滤器链选择的示例。

过滤器链匹配器: (.xds.type.matcher.v3.Matcher) Matcher API 从网络属性解析过滤器链名称。此匹配器用作过滤器链匹配条件 filter_chain_match 的替代。如果指定，所有 filter_chains 必须具有一个非空且唯一的 name 字段，并且不指定 filter_chain_match 字段。

注意

匹配后，每个连接都永久绑定到其过滤器链。如果匹配器更改，但过滤器链保持不变，则绑定到过滤器链的连接不会被排空。但是，如果过滤器链被删除或结构发生修改，则将启动对其连接的排空。

警告

此 API 功能目前处于开发中。标记为开发中的 API 功能不被认为是稳定的，不受威胁模型的保护，不受安全团队的支持，并且可能会发生重大更改。请勿在不了解以上所有要点的情况下使用此功能。

使用原始目标: (BoolValue) 如果连接使用 iptables 重定向，代理接收它的端口可能与原始目标地址的端口不同。当此标志设置为 true 时，监听器将重定向的连接传递到与原始目标地址关联的监听器。如果没有与原始目标地址关联的监听器，则连接将由接收它的监听器处理。默认值为 false。

默认过滤器链: (config.listener.v3.FilterChain) 如果没有过滤器链匹配，则使用默认过滤器链。如果没有提供默认过滤器链，则连接将被关闭。此字段中的过滤器链匹配将被忽略。

每个连接缓冲区限制字节

(UInt32Value) 监听器新连接读写缓冲区大小的软限制。如果未指定，将应用实现定义的默认值（1MiB）。

注意

此字段应在存在不可信的下游时进行配置。

不可信环境的示例配置

per_connection_buffer_limit_bytes: 32768.0

元数据: (config.core.v3.Metadata) 监听器元数据。

排空类型: (config.listener.v3.Listener.DrainType) 在监听器级别执行的排空类型。

监听器过滤器: (repeated config.listener.v3.ListenerFilter) 监听器过滤器有机会操纵和增强用于连接过滤器链匹配的连接元数据，例如。这些过滤器在 filter_chains 中的任何过滤器运行之前运行。顺序很重要，因为过滤器会在套接字被监听器接受后立即按顺序处理，并且在创建连接之前处理。当 protocol 为 UDP 且 udp_listener_config 中未指定 quic_options 时，可以指定 UDP 监听器过滤器。当 udp_listener_config 中指定了 quic_options 时，可以指定 QUIC 监听器过滤器。它们在创建连接之前按顺序处理。与 TCP 监听器过滤器一样，它们可用于操纵连接元数据和套接字。但不同之处在于它们不能用于暂停连接创建。

监听器过滤器超时: (Duration) 等待所有监听器过滤器完成操作的超时时间。如果超时，则接受的套接字将在不创建连接的情况下关闭，除非 continue_on_listener_filters_timeout 设置为 true。指定 0 以禁用超时。如果未指定，则使用 15 秒的默认超时。

在监听器过滤器超时时继续: (bool) 监听器过滤器超时时是否应该创建连接。默认为 false。

注意

某些监听器过滤器，例如 Proxy Protocol 过滤器，不应与此选项一起使用。这会导致在创建连接时出现意外行为。

透明: (BoolValue) 是否将侦听器设置为透明套接字。当此标志设置为 true 时，可以使用 iptables TPROXY 目标将连接重定向到侦听器，在这种情况下，原始源和目标地址以及端口将在接受的连接上保留。此标志应与原始目标侦听器过滤器结合使用，以将连接的本地地址标记为“已恢复”。这可用于将每个重定向的连接传递给与连接的目标地址关联的另一个侦听器。不使用 TPROXY 的直接连接无法与使用 TPROXY 重定向的连接区分开来，因此会被视为已重定向。当此标志设置为 false 时，侦听器的套接字将明确重置为非透明。设置此标志需要 Envoy 使用 CAP_NET_ADMIN 功能运行。当此标志未设置（默认）时，套接字不会修改，即透明选项既不会设置也不会重置。

freebind: (BoolValue) 是否侦听器应设置 IP_FREEBIND 套接字选项。当此标志设置为 true 时，侦听器可以绑定到未在运行 Envoy 的系统上配置的 IP 地址。当此标志设置为 false 时，选项 IP_FREEBIND 在套接字上被禁用。当此标志未设置（默认）时，套接字不会修改，即选项既不会启用也不会禁用。

套接字选项: (repeated config.core.v3.SocketOption) Envoy 源代码或预编译二进制文件中可能不存在的额外套接字选项。当 enable_reuse_port 为 true 时，可以更新侦听器的套接字选项。否则，如果在侦听器更新期间套接字选项发生更改，则会拒绝更新，以明确表明选项未更新。

tcp_fast_open_queue_length

(UInt32Value) 侦听器是否应接受 TCP 快速打开 (TFO) 连接。当此标志设置为大于 0 的值时，选项 TCP_FASTOPEN 在套接字上启用，队列长度为指定的大小（参见 RFC7413 中的详细信息）。当此标志设置为 0 时，选项 TCP_FASTOPEN 在套接字上禁用。当此标志未设置（默认）时，套接字不会修改，即选项既不会启用也不会禁用。

在 Linux 上，net.ipv4.tcp_fastopen 内核参数必须包含标志 0x2 才能启用 TCP_FASTOPEN。参见 ip-sysctl.txt。

在 macOS 上，只有 0、1 和未设置的值有效；其他值可能会导致错误。要在 macOS 上设置队列长度，请设置 net.inet.tcp.fastopen_backlog 内核参数。

traffic_direction: (config.core.v3.TrafficDirection) 指定流量相对于本地 Envoy 的预期方向。此属性在 Windows 上对于使用原始目标过滤器的侦听器是必需的，参见原始目标。

udp_listener_config: (config.listener.v3.UdpListenerConfig) 如果 protocol 中侦听器套接字地址的协议是 UDP，则此字段指定 UDP 侦听器特定的配置。

api_listener: (config.listener.v3.ApiListener) 用于表示 API 侦听器，它在非代理客户端中使用。向非代理应用程序公开的 API 类型取决于 API 侦听器的类型。当设置此字段时，不应设置除 name 以外的任何其他字段。

注意

目前只能安装一个 ApiListener；并且只能通过引导配置来完成，而不是 LDS。

connection_balance_config

(config.listener.v3.Listener.ConnectionBalanceConfig) 侦听器的连接均衡器配置，目前仅适用于 TCP 侦听器。如果没有指定配置，Envoy 不会尝试在工作线程之间均衡活动连接。

在侦听器 X 通过在 X 中设置 use_original_dst 和在 Y1 和 Y2 中将 bind_to_port 设置为 false 将所有连接重定向到侦听器 Y1 和 Y2 的情况下，建议在侦听器 X 中禁用均衡配置以避免均衡成本，并在 Y1 和 Y2 中启用均衡配置以均衡工作线程之间的连接。

reuse_port: (bool) 已弃用。请使用 enable_reuse_port 代替。

enable_reuse_port

(BoolValue) 当此标志设置为 true 时，侦听器会设置 SO_REUSEPORT 套接字选项，并为每个工作线程创建一个套接字。这使得传入连接在存在大量连接的情况下大致均匀地分布到工作线程之间。当此标志设置为 false 时，所有工作线程共享一个套接字。此字段默认为 true。当运行时标志 envoy.reloadable_features.enable_update_listener_socket_options 启用时，侦听器更新期间的字段更改将被拒绝。否则，此字段的更新将被静默忽略。

注意

虽然此字段默认为 true，但在不同的平台上具有不同的行为。有关更多信息，请参阅以下文本。

在 Linux 上，reuse_port 对于 TCP 和 UDP 侦听器都有效。它也可以与热重启一起正常工作。
在 macOS 上，TCP 的 reuse_port 与在 Linux 上的行为不同。它不会进行负载均衡，而是最后一个套接字获胜，并接收所有连接/数据包。对于 TCP，reuse_port 被强制禁用，并向用户发出警告。对于 UDP，它已启用，但只有一个工作线程会接收数据包。对于 QUIC/H3，SW 路由将数据包发送到其他工作线程。对于“原始”UDP，目前只有一个工作线程会接收数据包。
在 Windows 上，TCP 的 reuse_port 的行为未定义。它被强制禁用，并向用户发出类似于 macOS 的警告。目前它已启用 UDP，但行为未定义。

access_log: (repeated config.accesslog.v3.AccessLog) 此侦听器发出的访问日志的配置。

tcp_backlog_size: (UInt32Value) TCP 侦听器的挂起连接队列可以增长到的最大长度。如果未提供值，将在 Linux 上使用 net.core.somaxconn，否则使用 128。

max_connections_to_accept_per_socket_event: (UInt32Value) 每个套接字事件从内核接受的最大连接数。Envoy 可能会决定在从内核接受这些连接后关闭它们，例如由于负载削减或其他策略。如果存在超过 max_connections_to_accept_per_socket_event 个挂起接受的连接，则超过此阈值的连接将在以后的事件循环迭代中被接受。如果未提供值，Envoy 将接受所有从内核挂起的接受连接。

bind_to_port: (BoolValue) 侦听器是否应绑定到端口。不绑定到端口的侦听器只能接收从其他设置了 use_original_dst 为 true 的侦听器重定向的连接。默认值为 true。

internal_listener

(config.listener.v3.Listener.InternalListenerConfig) 用于表示内部侦听器，它不监听 OSI L4 地址，但可以由 Envoy 集群用于创建用户空间连接。内部侦听器充当 TCP 侦听器。它支持侦听器过滤器和网络过滤器链。上游集群通过其 name 引用内部侦听器。在内部侦听器上不应设置 Address。

存在一些来自实现的限制。已知的限制包括

ConnectionBalanceConfig 不允许，因为集群连接和侦听器连接都必须由同一个调度器拥有。
tcp_backlog_size
freebind
透明

独占侦听器类型及其相应的配置。

enable_mptcp: (bool) 在此侦听器上启用 MPTCP（多路径 TCP）。客户端将被允许建立 MPTCP 连接。非 MPTCP 客户端将回退到常规 TCP。

ignore_global_conn_limit: (bool) 侦听器是否应根据 global_downstream_max_connections 的值限制连接。

bypass_overload_manager: (bool) 侦听器是否绕过配置的过载管理器操作。

config.listener.v3.Listener.ConnectionBalanceConfig

[config.listener.v3.Listener.ConnectionBalanceConfig proto]

侦听器连接均衡的配置。

{
  "exact_balance": {...},
  "extend_balance": {...}
}

exact_balance

(config.listener.v3.Listener.ConnectionBalanceConfig.ExactBalance) 如果指定，侦听器将使用精确连接均衡器。

必须且仅必须设置以下一项：exact_balance 或 extend_balance。

extend_balance

(config.core.v3.TypedExtensionConfig) 监听器将根据 type_url 使用连接均衡器。如果 type_url 无效，Envoy 将不会尝试在工作线程之间平衡活动连接。

提示

以下扩展仅在 contrib 镜像中可用

envoy.network.connection_balance.dlb

必须且仅必须设置以下一项：exact_balance 或 extend_balance。

config.listener.v3.Listener.ConnectionBalanceConfig.ExactBalance

[config.listener.v3.Listener.ConnectionBalanceConfig.ExactBalance proto]

一种实现精确均衡的连接均衡器。这意味着在均衡期间会持有锁，以便连接计数在工作线程之间几乎完全均衡。这在某种意义上是“几乎”精确的，因为连接可能并行关闭，从而使计数不正确，但这应该在下一个接受时得到纠正。这种均衡器牺牲了接受吞吐量以换取准确性，应该在连接数量很少且很少循环的情况下使用（例如，服务网格 gRPC 出站）。

config.listener.v3.Listener.InternalListenerConfig

[config.listener.v3.Listener.InternalListenerConfig proto]

Envoy 内部监听器的配置。所有未来的内部监听器功能都应在此处添加。

Enum config.listener.v3.Listener.DrainType

[config.listener.v3.Listener.DrainType proto]

DEFAULT: (DEFAULT) ⁣响应调用 /healthcheck/fail 管理端点（以及健康检查过滤器）、监听器删除/修改和热重启时执行排空。

MODIFY_ONLY: ⁣响应监听器删除/修改和热重启时执行排空。此设置不包括 /healthcheck/fail。如果 Envoy 托管入口和出口监听器，此设置可能很合适。