Pulsar 客户端 - Spring for Apache Pulsar 1.1.1-SNAPSHOT 中文文档 | Spring官方文档中文翻译 | Spring for Apache Pulsar 中文翻译

当您使用 Pulsar Spring Boot Starter 时，您将获得自动配置。PulsarClient

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

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

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

如果您不使用启动器，则需要自行配置和注册。有一个接受构建器定制器，可用于帮助解决此问题。PulsarClientDefaultPulsarClientFactory

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

如果您不使用启动器，则需要自行配置和注册。有一个接受构建器定制器，可用于帮助解决此问题。PulsarClientDefaultPulsarClientFactory

1. TLS加密（SSL）

默认情况下，Pulsar 客户端以纯文本形式与 Pulsar 服务进行通信。下面介绍如何配置 Pulsar 客户端使用 TLS 加密（SSL）。先决条件是代理也已配置为使用 TLS 加密。

Spring Boot 自动配置当前不支持任何 TLS/SSL 配置属性。你可以改为提供一个在 Pulsar 客户端构建器上设置必要属性的属性。 Pulsar 支持隐私增强邮件（PEM）和 Java KeyStore （JKS）证书格式。PulsarClientBuilderCustomizer

按照以下步骤配置 TLS：

调整 Pulsar 客户端服务 url 以使用方案和 TLS 端口（通常为）。pulsar+ssl://6651
调整管理客户端服务 URL 以使用方案和 TLS Web 端口（通常为）。https://8443
提供客户端构建器定制器，用于设置构建器上的相关属性。
- 基于 PEM 的样品
- 基于 JKS 的示例

您可以在官方 Pulsar TLS 加密文档中找到有关上述内容的更多信息。

2. 身份验证

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

您需要确保下定义的名称与您的身份验证插件（通常是驼峰大小写）所期望的名称完全匹配。 Spring Boot 不会尝试对这些条目进行任何形式的宽松绑定。spring.pulsar.client.authentication.param.*

例如，如果要配置身份验证插件的颁发者 URL，则必须使用 . 如果您使用其他形式，例如或，则该设置将不会应用于插件。AuthenticationOAuth2spring.pulsar.client.authentication.param.issuerUrlissuerurlissuer-url

将环境变量用于身份验证参数通常是有问题的，因为在转换过程中会丢失区分大小写。例如，考虑通过环境变量设置的以下身份验证参数：issuerUrl

SPRING_PULSAR_CLIENT_AUTHENTICATION_PARAM_ISSUERURL=https://some.server.com

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

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

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

以下清单显示了如何配置每个受支持的身份验证机制。

点击这里查看雅典娜

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

This also requires TLS encryption.

点击这里获取令牌

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 加密已要求您提供客户端生成器定制器，因此建议直接在提供的 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 文档。

单击此处获取 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 文档。

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

将环境变量用于身份验证参数通常是有问题的，因为在转换过程中会丢失区分大小写。例如，考虑通过环境变量设置的以下身份验证参数：issuerUrl

SPRING_PULSAR_CLIENT_AUTHENTICATION_PARAM_ISSUERURL=https://some.server.com

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

这也需要 TLS 加密。

3. 自动群集级故障转移

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

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

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

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 自动配置时，可以提供客户端定制器，用于配置客户端以进行群集级故障转移。

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