第 5 章 管理客户端配置属性

Type: list
Default: ""
Importance: high

用于建立到 KRaft 控制器仲裁的初始连接的主机/端口对列表。此列表的格式应为 host1:port1,host2:port2,…​。

Type: list
Default: ""
Importance: high

用于建立到 Kafka 集群的初始连接的主机/端口对列表。客户端将使用所有服务器与此处为引导指定的服务器无关 - 此列表仅影响用于发现完整服务器集的初始主机。此列表的格式应为 host1:port1,host2:port2,…​。由于这些服务器仅用于初始连接来发现完整的群集成员身份（可能会动态更改），因此此列表不需要包含整组服务器（但是如果服务器停机，您可能需要多个服务器）。

Type: password
Default: null
Importance: high

密钥存储文件中私钥的密码或 'ssl.keystore.key' 中指定的 PEM 密钥。

Type: password
Default: null
Importance: high

使用由 'ssl.keystore.type" 指定的格式的证书链。默认 SSL 引擎工厂仅支持使用 X.509 证书列表的 PEM 格式。

Type: password
Default: null
Importance: high

使用 'ssl.keystore.type" 指定的格式的私钥。默认 SSL 引擎工厂只支持使用 PKCS#8 密钥的 PEM 格式。如果密钥加密，必须使用 'ssl.key.password' 指定密钥密码。

Type: string
Default: null
Importance: high

密钥存储文件的位置。这对客户端是可选的，可用于客户端进行双向身份验证。

Type: password
Default: null
Importance: high

密钥存储文件的存储密码。这对客户端是可选的，只有在配置了 'ssl.keystore.location' 时才需要。PEM 格式不支持密钥存储密码。

Type: password
Default: null
Importance: high

可信证书，格式为 'ssl.truststore.type'。默认 SSL 引擎工厂仅支持使用 X.509 证书使用 PEM 格式。

Type: string
Default: null
Importance: high

信任存储文件的位置。

Type: password
Default: null
Importance: high

信任存储文件的密码。如果没有设置密码，则仍然使用配置的信任存储文件，但禁用完整性检查。PEM 格式不支持信任存储密码。

Type: string
Default: use_all_dns_ips
Valid Values: [use_all_dns_ips, resolve_canonical_bootstrap_servers_only]
Importance: medium

控制客户端如何使用 DNS 查找。如果设置为 use_all_dns_ips，请按顺序连接到每个返回的 IP 地址，直到成功建立连接。断开连接后，会使用下一个 IP。当所有 IP 都被一次使用后，客户端会再次解析主机名(JVM 和 OS 缓存 DNS 名称查找)中的 IP。如果设置为 resolve_canonical_bootstrap_servers_only，请将每个 bootstrap 地址解析为规范名称列表。bootstrap 阶段后，它的行为与 use_all_dns_ips 相同。

Type: string
Default: ""
Importance: medium

在发出请求时传递给服务器的 id 字符串。这样做的目的是通过允许逻辑应用程序名称包含在服务器端请求日志记录中，从而跟踪除 ip/port 以外的请求源。

Type: long
Default: 300000 (5 minutes)
Importance: medium

在这个配置指定的毫秒数后关闭闲置连接。

type: int
Default: 60000 (1 minute)
Valid Values: [0,…​]
Importance: medium

指定客户端 API 的超时时间（以毫秒为单位）。此配置用作没有指定 timeout 参数的所有客户端操作的默认超时时间。

type: int
Default: 65536 (64 kibibytes)
Valid Values: [-1,…​]
Importance: medium

读取数据时要使用的 TCP 接收缓冲区(SO_RCVBUF)的大小。如果值为 -1，则使用操作系统默认值。

type: int
Default: 30000 (30 秒)
Valid Values: [0,…​]
Importance: medium

配置控制客户端等待请求响应的最长时间。如果在超时之前没有收到响应，客户端将在需要时重新发送请求（如果重试用时失败）。

Type: class
Default: null
Importance: medium

实现 AuthenticateCallbackHandler 接口的 SASL 客户端回调处理程序类的完全限定名称。

Type: password
Default: null
Importance: medium

用于 SASL 连接的 JAAS 登录上下文参数，其格式供 JAAS 配置文件使用。JAAS 配置文件格式描述 在此处。该值的格式是： loginModuleClass controlFlag (optionName=optionValue)*;。对于代理，配置必须在小写中带有监听前缀和 SASL 机制名称前缀。例如： listener.name.sasl_ssl.scram-sha-256.sasl.jaas.config=com.example.ScramLoginModule required;。

Type: string
Default: null
Importance: medium

Kafka 运行的 Kerberos 主体名称。这可以在 Kafka 的 JAAS 配置或 Kafka 配置中定义。

Type: class
Default: null
Importance: medium

实现 AuthenticateCallbackHandler 接口的 SASL 登录回调处理程序类的完全限定名称。对于代理，登录回调处理器配置必须以监听器前缀和 SASL 机制名称作为前缀作为前缀。例如： listener.name.sasl_ssl.scram-sha-256.sasl.login.callback.handler.class=com.example.CustomScramLoginCallbackHandler。

Type: class
Default: null
Importance: medium

实现登录接口的类的完全限定名称。对于代理，登录配置必须在小写中带有监听前缀和 SASL 机制名称前缀。For example, listener.name.sasl_ssl.scram-sha-256.sasl.login.class=com.example.CustomScramLogin.

Type: string
Default: GSSAPI
Importance: medium

用于客户端连接的 SASL 机制。这可能是提供安全提供程序的任何机制。GSSAPI 是默认机制。

Type: string
Default: null
Importance: medium

可以从中检索供应商的 JWKS (JSON Web Key Set) 的 OAuth/OIDC 供应商 URL。URL 可以是基于 HTTP (S)或基于文件的 URL。如果 URL 基于 HTTP (S)，则 JWKS 数据将通过代理启动时配置的 URL 从 OAuth/OIDC 供应商中检索。所有 then-current 密钥都将缓存在代理上以进行传入请求。如果为 JWT 收到了身份验证请求，其中包含缓存中尚未在缓存中的"kid"标头声明值，则将根据需要再次查询 JWKS 端点。但是，代理会轮询每个 sasl.oauthbearer.jwks.endpoint.refresh.ms 毫秒的 URL，以便在收到包含这些密钥的任何 JWT 请求前刷新缓存。如果 URL 基于文件，代理将在启动时从配置的位置加载 JWKS 文件。如果 JWT 包含没有在 JWKS 文件中的 "kid" 标头值，代理将拒绝 JWT 并且身份验证将失败。

Type: string
Default: null
Importance: medium

OAuth/OIDC 身份提供程序的 URL。如果 URL 基于 HTTP (S)，这是签发者的令牌端点 URL，其请求将根据 sasl.jaas.config 中的配置登录。如果 URL 基于文件，它指定一个包含由 OAuth/OIDC 身份提供程序发布的访问令牌( JWT 序列化形式)的文件，以用于授权。

Type: string
Default: PLAINTEXT
Valid Values: (case insensitive)[SASL_SSL, PLAINTEXT, SSL, SASL_PLAINTEXT]
Importance: medium

用于与代理通信的协议。有效值为： PLAINTEXT, SSL, SASL_PLAINTEXT, SASL_SSL。

type: int
Default: 131072 (128 kibibytes)
Valid Values: [-1,…​]
Importance: medium

发送数据时要使用的 TCP 发送缓冲区(SO_SNDBUF)的大小。如果值为 -1，则使用操作系统默认值。

type: long
Default: 30000 (30 秒)
Importance: medium

客户端等待套接字连接建立的最大时间。当每个连续连接失败时，连接设置超时会达到这个最大值。为避免连接差异，将把一个随机化因值应用于超时，导致计算值高于 20% 的随机范围。

type: long
Default: 10000 (10 seconds)
Importance: medium

客户端等待套接字连接建立的时间长度。如果在超时时间前没有构建连接，客户端将关闭套接字频道。这个值是初始 backoff 值，每个连续连接失败都会按指数增加，最高为 socket.connection.setup.timeout.max.ms 值。

type: list
Default: TLSv1.2,TLSv1.3
Importance: medium

为 SSL 连接启用的协议列表。在使用 Java 11 或更新版本时，默认为 'TLSv1.2,TLSv1.3'，否则 'TLSv1.2'。使用 Java 11 的默认值，如果客户端和服务器同时支持 TLSv1.3，则客户端和服务器将首选 TLSv1.3，否则将回退到 TLSv1.2（假设两者都至少支持 TLSv1.2）。对于大多数情况，这个默认值应该可以正常工作。另请参阅 ssl.protocol 的配置文档。

Type: string
Default: JKS
Importance: medium

密钥存储文件的文件格式。这对客户端是可选的。默认 ssl.engine.factory.class 当前支持的值为 [JKS、PKCS12、PEM]。

type: string
Default: TLSv1.3
Importance: medium

用于生成 SSLContext 的 SSL 协议。使用 Java 11 或更新版本运行时，默认为 'TLSv1.3'，否则 'TLSv1.2'。对于大多数用例，这个值应该可以正常工作。最近的 JVM 中允许的值为 'TLSv1.2' 和 'TLSv1.3'。旧的 JVM 可以支持 'TLS', 'TLSv1.1', 'SSLv2', 'SSLv2' 和 'SSLv3'，但由于已知的安全漏洞，不建议使用它们。使用这个配置和 'ssl.enabled.protocols' 的默认值，如果服务器不支持 'TLSv1.3'，客户端将降级为 'TLSv1.2'。如果此配置被设置为 'TLSv1.2'，客户端将不会使用 'TLSv1.3'，即使它是 ssl.enabled.protocols 中的值之一，服务器只支持 'TLSv1.3'。

Type: string
Default: null
Importance: medium

用于 SSL 连接的安全供应商的名称。默认值是 JVM 的默认安全提供程序。

Type: string
Default: JKS
Importance: medium

信任存储文件的文件格式。默认 ssl.engine.factory.class 当前支持的值为 [JKS、PKCS12、PEM]。

Type: boolean
Default: true
Importance: low

已弃用。是否自动包含 JmxReporter，即使它在 metric.reporters 中未列出。此配置将在 Kafka 4.0 中删除，用户应在 metric.reporters 中包含 org.apache.kafka.common.metrics.JmxReporter，以启用 JmxReporter。

Type: boolean
Default: true
Importance: low

是否启用将客户端指标推送到集群，如果集群具有与此客户端匹配的客户端指标订阅。

Type: long
Default: 300000 (5 minutes)
Valid Values: [0,…​]
Importance: low

即使我们未看到任何分区领导力更改来主动发现任何新的代理或分区，我们才会强制刷新元数据的时间（以毫秒为单位）。

Type: list
Default: ""
Importance: low

用作指标报告器的类列表。实施 org.apache.kafka.common.metrics.MetricsReporter 接口，允许插入将收到新指标创建通知的类。总是包括 JmxReporter 来注册 JMX 统计信息。

type: int
Default: 2
Valid Values: [1,…​]
Importance: low

为计算指标维护的示例数量。

Type: string
Default: INFO
Valid Values: [INFO, DEBUG, TRACE]
Importance: low

指标的最高记录级别。

type: long
Default: 30000 (30 秒)
Valid Values: [0,…​]
Importance: low

计算指标示例的时间窗口。

type: long
Default: 1000 (1 second)
Valid Values: [0,…​]
Importance: low

重新连接到重复连接失败的代理时等待的最大时间（以毫秒为单位）。如果提供，每个主机的 backoff 将为每个连续的连接失败指数增加，直到最高值。在计算 backoff 增长后，添加了 20% 的随机 jitter，以避免连接状况。

type: long
Default: 50
Valid Values: [0,…​]
Importance: low

尝试重新连接到给定主机前等待的基本时间。这可避免在紧密循环中重复连接到主机。此 backoff 应用到客户端到代理的所有连接尝试。这个值是初始 backoff 值，并为每个连续连接失败指数增加，最高为 reconnect.backoff.max.ms 值。

type: int
Default: 2147483647
Valid Values: [0,…​,2147483647]
Importance: low

设置大于零的值将导致客户端重新发送失败并可能出现临时错误的请求。建议将值设为 0 或 MAX_VALUE，并使用对应的超时参数来控制客户端应重试请求的时长。

type: long
Default: 1000 (1 second)
Valid Values: [0,…​]
Importance: low

当重试请求重复失败的代理时，等待的最大时间（毫秒）。如果提供，每个客户端将为每个失败请求按指数增加 backoff，直到达到这个最大值。要防止所有客户端在重试时同步，一个随机的 jitter 会被应用到 backoff，从而导致 backoff 在以下 20 到 20% 之间的范围内，超过计算值。如果将 retry.backoff.ms 设置为大于 retry.backoff.max.ms，则 retry.backoff.max.ms 将用作开始的常量 backoff，而不会增加任何指数增加。

Type: long
Default: 100
Valid Values: [0,…​]
Importance: low

尝试重试对给定主题分区失败的请求前等待的时间。这可避免在某些故障场景中的紧密循环中重复发送请求。这个值是初始 backoff 值，每个失败请求都会按指数增加，最多为 retry.backoff.max.ms 值。

type: string
Default: /usr/bin/kinit
Importance: low

Kerberos kinit 命令路径。

Type: long
Default: 60000
Importance: low

刷新尝试之间的登录线程睡眠时间。

type: double
Default: 0.05
Importance: low

添加到续订时间的随机 jitter 的百分比。

Type: double
Default: 0.8
Importance: low

登录线程将处于睡眠状态，直到达到最后一次刷新到票据到期的时间因素前处于睡眠状态，此时将尝试续订票据。

type: int
Default: null
Importance: low

（可选）外部身份验证供应商连接超时的值（以毫秒为单位）。目前仅适用于 OAUTHBEARER。

type: int
Default: null
Importance: low

（可选）外部身份验证供应商读取超时的值（以毫秒为单位）。目前仅适用于 OAUTHBEARER。

Type: short
Default: 300
Valid Values: [0,…​,3600]
Importance: low

在刷新凭证时凭证过期前的缓冲时间（以秒为单位）。如果刷新情况比缓冲区秒数接近过期，则刷新将移动，以尽可能多地维护缓冲区时间。法律值介于 0 到 3600 (1 小时)之间；如果没有指定值，则使用默认值 300 (5 分钟)。如果这个值和 sasl.login.refresh.min.period.seconds 超过了凭证剩余的生命周期，则忽略这个值。目前仅适用于 OAUTHBEARER。

Type: short
Default: 60
Valid Values: [0,…​,900]
Importance: low

登录刷新线程在刷新凭证前等待的时间（以秒为单位）。法律值介于 0 到 900 (15 分钟)之间；如果没有指定值，则使用默认值 60 (1 分钟)。如果这个值和 sasl.login.refresh.buffer.seconds 都会被忽略，如果它们的总和超过凭证的剩余生命周期。目前仅适用于 OAUTHBEARER。

type: double
Default: 0.8
Valid Values: [0.5,…​,1.0]
Importance: low

登录刷新线程将休眠到与凭证生命周期相关的指定窗口因素，此时将尝试刷新凭证。法律值介于 0.5 (50%)和 1.0 (100%)之间，如果没有指定值，则使用默认值 0.8 (80%)。目前仅适用于 OAUTHBEARER。

type: double
Default: 0.05
Valid Values: [0.0,…​,0.25]
Importance: low

与凭证的生命周期相关的最大随机 jitter 量添加到登录刷新线程的睡眠时间中。法律值介于 0 到 0.25(25%)之间，如果没有指定值，则使用默认值 0.05(5%)。目前仅适用于 OAUTHBEARER。

type: long
Default: 10000 (10 seconds)
Importance: low

（可选）登录尝试外部身份验证提供程序之间等待的最大等待值（以毫秒为单位）。登录使用基于 sasl.login.retry.backoff.ms 设置的初始等待的指数 backoff 算法，并在尝试到 sasl.login.retry.backoff.max.ms 设置指定的最大等待长度之间加倍。目前仅适用于 OAUTHBEARER。

Type: long
Default: 100
Importance: low

（可选）登录尝试外部身份验证提供程序期间初始等待的值（以毫秒为单位）。登录使用基于 sasl.login.retry.backoff.ms 设置的初始等待的指数 backoff 算法，并在尝试到 sasl.login.retry.backoff.max.ms 设置指定的最大等待长度之间加倍。目前仅适用于 OAUTHBEARER。

Type: int
Default: 30
Importance: low

（可选）值（以秒为单位），允许 OAuth/OIDC 身份提供程序和代理间的差别。

Type: list
Default: null
Importance: low

（可选）代理用逗号分隔的设置来验证是否已为其中一个预期的受众发出 JWT。JWT 将检查是否有标准的 OAuth "aud" 声明，如果设置了这个值，代理将与 JWT 的"aud"声明中的值匹配，以查看是否有完全匹配。如果没有匹配项，代理将拒绝 JWT，身份验证将失败。

Type: string
Default: null
Importance: low

代理的 （可选）用于验证 JWT 是否已由预期签发者创建的（可选）设置。JWT 将检查是否有标准 OAuth "iss" 声明，如果设置了这个值，代理会完全匹配 JWT 的"iss"声明中的内容。如果没有匹配项，代理将拒绝 JWT，身份验证将失败。

Type: long
Default: 3600000 (1 hour)
Importance: low

（可选）代理在刷新其 JWKS (JSON Web Key Set)缓存之间等待的值，其中包含键以验证 JWT 的签名。

type: long
Default: 10000 (10 seconds)
Importance: low

（可选）尝试从外部身份验证提供程序检索 JWKS (JSON Web Key Set)之间的最大等待值（以毫秒为单位）。JWKS 检索使用基于 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 设置的初始等待算法的指数 backoff 算法，并在尝试到 sasl.oauthbearer.jwks.endpoint.retry.backoff.max.ms 设置所指定的最大等待长度之间加倍。

Type: long
Default: 100
Importance: low

（可选）在 JWKS (JSON Web Key Set)检索外部身份验证提供程序尝试时的初始等待值（以毫秒为单位）。JWKS 检索使用基于 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 设置的初始等待算法的指数 backoff 算法，并在尝试到 sasl.oauthbearer.jwks.endpoint.retry.backoff.max.ms 设置所指定的最大等待长度之间加倍。

Type: string
Default: scope
Importance: low

范围的 OAuth 声明通常命名为 "scope"，但如果 OAuth/OIDC 供应商为该声明使用不同的名称，则此（可选）设置可以提供用于 JWT 有效负载声明中包含的范围的名称。

Type: string
Default: sub
Importance: low

该主题的 OAuth 声明通常命名为 "sub"，但如果 OAuth/OIDC 供应商为该声明使用不同的名称，则此（可选）设置可以为 JWT 有效负载的声明中包含的主题提供不同的名称。

Type: string
Default: null
Importance: low

每个返回供应商实施安全算法的可配置创建者类列表。这些类应实施 org.apache.kafka.common.security.auth.SecurityProviderCreator 接口。

Type: list
Default: null
Importance: low

密码套件列表。这是用来使用 TLS 或 SSL 网络协议协商网络连接的安全设置的身份验证、加密、MAC 和密钥交换算法的命名组合。默认情况下，支持所有可用的密码套件。

Type: string
Default: https
Importance: low

使用服务器证书验证服务器主机名的端点标识算法。

Type: class
Default: null
Importance: low

org.apache.kafka.common.security.auth.SslEngineFactory 类型的类提供 SSLEngine 对象。默认值为 org.apache.kafka.common.security.ssl.DefaultSslEngineFactory。或者，将其设置为 org.apache.kafka.common.security.ssl.CommonNameLoggingSslEngineFactory 将记录客户端用于与日志级别 INFO 的任何代理进行身份验证的通用 SSL 证书名称。请注意，由于检查客户端提供的证书链，这会在建立从 mTLS 客户端到代理的新连接时造成小延迟。请注意，该实施还使用基于标准 Java 信任存储的自定义信任存储，因此由于标准版本不成熟，因此可能会被视为安全风险。

Type: string
Default: SunX509
Importance: low

密钥管理器工厂用于 SSL 连接的算法。默认值是为 Java 虚拟机配置的密钥管理器工厂算法。

Type: string
Default: null
Importance: low

用于 SSL 加密操作的 SecureRandom PRNG 实施。

Type: string
Default: PKIX
Importance: low

信任管理器工厂用于 SSL 连接的算法。默认值是为 Java 虚拟机配置的信任管理器工厂算法。