Pulsar 客户端

当您使用 Pulsar Spring Boot Starter 时，您将获得PulsarClient自动配置。spring-doc.cadn.net.cn

默认情况下，应用程序会尝试连接到本地 Pulsar 实例pulsar://localhost:6650. 这可以通过设置spring.pulsar.client.service-url属性设置为不同的值。spring-doc.cadn.net.cn

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

您可以通过指定任何spring.pulsar.client.*应用程序属性。spring-doc.cadn.net.cn

如果您不使用Starters，则需要配置并注册PulsarClient你自己。有一个DefaultPulsarClientFactory它接受可用于帮助解决此问题的构建器定制器。

1. TLS 加密（SSL）

默认情况下，Pulsar 客户端以纯文本形式与 Pulsar 服务通信。以下部分介绍如何配置 Pulsar 客户端以使用 TLS 加密（SSL）。前提条件是代理还配置为使用 TLS 加密。spring-doc.cadn.net.cn

Spring Boot 自动配置当前不支持任何 TLS/SSL 配置属性。您可以改为提供PulsarClientBuilderCustomizer在 Pulsar 客户端构建器上设置必要的属性。 Pulsar 支持隐私增强邮件（PEM）和 Java 密钥库（JKS）证书格式。spring-doc.cadn.net.cn

按照以下步骤配置 TLS：spring-doc.cadn.net.cn

调整 Pulsar 客户端服务 url 以使用pulsar+ssl://方案和 TLS 端口（通常6651).spring-doc.cadn.net.cn
调整管理客户端服务 url 以使用https://方案和 TLS Web 端口（通常8443).spring-doc.cadn.net.cn
提供客户端构建器定制器，用于在构建器上设置相关属性。spring-doc.cadn.net.cn
- 基于PEM的 Samples spring-doc.cadn.net.cn
- 基于 JKS 的示例 spring-doc.cadn.net.cn

您可以在官方 Pulsar TLS 加密文档中找到有关上述内容的更多信息。spring-doc.cadn.net.cn

2. 认证

要连接到需要身份验证的 Pulsar 集群，您需要指定要使用的身份验证插件以及指定插件所需的任何参数。 使用 Spring Boot 自动配置时，您可以通过配置属性设置插件和插件参数（在大多数情况下）。spring-doc.cadn.net.cn

您需要确保在spring.pulsar.client.authentication.param.*完全符合您的身份验证插件（通常是驼峰式大小写）所期望的。 Spring Boot 不会尝试对这些条目进行任何类型的宽松绑定。spring-doc.cadn.net.cn

例如，如果要为AuthenticationOAuth2您必须使用的身份验证插件spring.pulsar.client.authentication.param.issuerUrl. 如果您使用其他表单，例如issuerurl或issuer-url，则该设置将不会应用于插件。spring-doc.cadn.net.cn

将环境变量用于身份验证参数通常会出现问题，因为在转换过程中会丢失区分大小写。例如，考虑以下内容issuerUrl通过环境变量设置的 auth 参数：spring-doc.cadn.net.cn

SPRING_PULSAR_CLIENT_AUTHENTICATION_PARAM_ISSUERURL=https://some.server.com

当 Spring Boot 加载此属性时，它将使用issuerurl（小写）而不是预期的issuerUrl（驼峰式）。您可以通过使用 env var 的值作为application.yml中相关 auth 属性的值来绕过此限制。继续上面的例子：spring-doc.cadn.net.cn

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

当不使用 Spring Boot 自动配置时，您可以使用org.apache.pulsar.client.api.AuthenticationFactory创建身份验证，然后直接在您提供给客户端工厂的客户端定制器中的 Pulsar 客户端构建器上进行设置。spring-doc.cadn.net.cn

以下列表显示了如何配置每个受支持的身份验证机制。spring-doc.cadn.net.cn

点击这里查看雅典

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

这也需要 TLS 加密。

点击这里查看Tokens

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

点击这里查看基本

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 定制器中的客户端构建器上添加身份验证。您可以使用org.apache.pulsar.client.api.AuthenticationFactory以帮助创建身份验证对象，如下所示：

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

请参阅有关 mTLS （PEM）的官方 Pulsar 文档。spring-doc.cadn.net.cn

单击此处查看 mTLS （JKS）

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

请参阅有关 mTLS （JKS）的官方 Pulsar 文档。spring-doc.cadn.net.cn

您可以在官方 Pulsar 安全文档中找到有关每个支持插件及其所需属性的更多信息。spring-doc.cadn.net.cn

3. 自动集群级故障转移

Pulsar Spring Boot Starter 还会自动配置PulsarClient用于自动集群级故障转移。spring-doc.cadn.net.cn

您可以使用spring.pulsar.client.failover.*应用程序属性来配置集群级故障转移。spring-doc.cadn.net.cn

以下示例使用主集群和两个备份集群配置客户端。spring-doc.cadn.net.cn

application.yml

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"

除了客户端配置之外，代理上还必须满足一些前提条件才能使用此功能。

当不使用 Spring Boot 自动配置时，您可以提供一个客户端定制器，用于配置客户端以进行集群级故障转移。spring-doc.cadn.net.cn

Pulsar 客户端

1. TLS 加密 （SSL）

2. 认证

3. 自动集群级故障转移

1. TLS 加密（SSL）