跳到主要内容
版本:2.0.7

Pulsar 客户端

Doubao 中英对照 Pulsar Client

目录

当你使用 Pulsar Spring Boot Starter 时,会得到自动配置的 PulsarClient。

默认情况下,应用程序尝试连接位于 pulsar://localhost:6650 的本地 Pulsar 实例。可以通过将 spring.pulsar.client.service-url 属性设置为其他值来调整。

提示

该值必须是有效的 Pulsar 协议 URL。

你可以通过指定任何 spring.pulsar.client.* 应用属性来进一步配置客户端。

备注

如果你不使用 starter,则需要自己配置并注册 PulsarClient。有一个 DefaultPulsarClientFactory,它接受一个 builder 定制器,可以用来协助完成此工作。

1. TLS 加密(SSL)​

默认情况下,Pulsar 客户端以明文与 Pulsar 服务通信。以下章节介绍如何配置 Pulsar 客户端使用 TLS 加密(SSL)。前提是 Broker 也已配置为使用 TLS 加密。

Spring Boot 自动配置目前不支持任何 TLS/SSL 配置属性。你可以改为提供一个 PulsarClientBuilderCustomizer,在 Pulsar client builder 上设置必要属性。Pulsar 同时支持 Privacy Enhanced Mail(PEM)和 Java KeyStore(JKS)证书格式。

按照以下步骤配置 TLS:

  1. 调整 Pulsar 客户端 service url,使用 pulsar+ssl:// scheme 和 TLS 端口(通常为 6651)。
  2. 调整 admin 客户端 service url,使用 https:// scheme 和 TLS web 端口(通常为 8443)。
  3. 提供客户端 builder 定制器,在 builder 上设置相关属性。

更多相关信息请参阅官方 Pulsar TLS 加密 文档。

2. 认证​

要连接需要认证的 Pulsar 集群,你需要指定使用哪个认证插件以及该插件所需的任何参数。使用 Spring Boot 自动配置时,你通常可以通过配置属性设置插件和插件参数。

备注

你需要确保在 spring.pulsar.client.authentication.param.* 下定义的名称与你的认证插件所期望的名称完全匹配(通常是驼峰命名)。Spring Boot 不会对这些条目尝试任何宽松绑定。

例如,如果你想为 AuthenticationOAuth2 认证插件配置 issuer url,必须使用 spring.pulsar.client.authentication.param.issuerUrl。如果使用其他形式,例如 issuerurl 或 issuer-url,该设置将不会应用到插件。

提示

使用环境变量传递认证参数通常会有问题,因为在转换过程中会丢失大小写。例如,考虑以下通过环境变量设置的 issuerUrl 认证参数:

SPRING_PULSAR_CLIENT_AUTHENTICATION_PARAM_ISSUERURL=https://some.server.com

当 Spring Boot 加载此属性时,它会使用 issuerurl(小写)而不是期望的 issuerUrl(驼峰)。你可以通过在 application.yml 中使用环境变量的值作为相关认证属性的值来绕过此限制。承接上例:

spring:
pulsar:
client:
authentication:
param:
issuerUrl: ${SPRING_PULSAR_CLIENT_AUTHENTICATION_PARAM_ISSUERURL}

不使用 Spring Boot 自动配置时,你可以使用 org.apache.pulsar.client.api.AuthenticationFactory 创建认证,然后在你提供给客户端工厂的客户端定制器中,将其直接设置到 Pulsar client builder 上。

以下清单展示了如何配置每种受支持的认证机制。

点击此处查看 Athenz

spring:
pulsar:
client:
authentication:
plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationAthenz
param:
tenantDomain: ...
tenantService: ...
providerDomain: ...
privateKey: ...
keyId: ...
备注

这还需要 TLS 加密。

点击此处查看 Token

spring:
pulsar:
client:
authentication:
plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationToken
param:
token: some-token-goes-here

点击此处查看 Basic

spring:
pulsar:
client:
authentication:
plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationBasic
param:
userId: ...
password: ...

点击此处查看 OAuth2

spring:
pulsar:
client:
authentication:
plugin-class-name: org.apache.pulsar.client.impl.auth.oauth2.AuthenticationOAuth2
param:
issuerUrl: ...
privateKey: ...
audience: ...
scope: ...

点击此处查看 Sasl

spring:
pulsar:
client:
authentication:
plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationSasl
param:
saslJaasClientSectionName: ...
serverType: ...

点击此处查看 mTLS(PEM)

备注

由于此选项需要 TLS 加密,而 TLS 加密已经要求你提供客户端 builder 定制器,建议直接在你提供的 TLS 定制器中的 client builder 上添加认证。你可以使用 org.apache.pulsar.client.api.AuthenticationFactory 来帮助创建认证对象,如下所示:

Authentication auth = AuthenticationFactory.TLS("/path/to/my-role.cert.pem", "/path/to/my-role.key-pk8.pem");

请参阅官方 Pulsar 文档中关于 mTLS(PEM) 的内容。

点击此处查看 mTLS(JKS)

备注

由于此选项需要 TLS 加密,而 TLS 加密已经要求你提供客户端 builder 定制器,建议直接在你提供的 TLS 定制器中的 client builder 上添加认证。你可以使用 org.apache.pulsar.client.api.AuthenticationFactory 来帮助创建认证对象,如下所示:

Authentication auth = AuthenticationFactory.create(
"org.apache.pulsar.client.impl.auth.AuthenticationKeyStoreTls",
Map.of("keyStoreType", "JKS", "keyStorePath", "/path/to/my/keystore.jks", "keyStorePassword", "clientpw"));

请参阅官方 Pulsar 文档中关于 mTLS(JKS) 的内容。

关于每个受支持插件及其所需属性的更多信息,请参阅官方 Pulsar 安全 文档。

3. 自动集群级故障转移​

Pulsar Spring Boot Starter 还会为自动集群级故障转移自动配置 PulsarClient。

你可以使用 spring.pulsar.client.failover.* 应用属性来配置集群级故障转移。

以下示例为客户端配置了一个主集群和两个备用集群。

spring:
pulsar:
client:
service-url: "pulsar://my.primary.server:6650"
failover:
delay: 30s
switch-back-delay: 15s
check-interval: 1s
backup-clusters:
- service-url: "pulsar://my.second.server:6650"
authentication:
plugin-class-name: org.apache.pulsar.client.impl.auth.AuthenticationToken
param:
token: "my-token"
- service-url: "pulsar://my.third.server:6650"
important

除客户端配置外,broker 上还有若干先决条件必须满足,才能使用此特性。

不使用 Spring Boot 自动配置时,你可以提供一个客户端定制器,为集群级故障转移配置客户端。