企业官网建设流程全解析

• 消息队列
• 后端
• 流处理

作为企业级分布式消息中间件，Apache Pulsar 经常承担业务关键数据的存储与流转职责，其安全体系的完备程度直接决定了整个消息系统的可信边界。本文以 Pulsar 2.2.0 的安全概览文档（security-overview.md）为骨架，系统讲解 Pulsar 的安全默认状态、可插拔认证机制、认证凭证的过期与刷新原理、Role Tokens 的授权模型，以及当前支持的四类认证提供方，并结合仓库源码（pulsar-broker-common、pulsar-broker模块）与 conf/broker.conf 配置项逐一佐证。读完本文，你将掌握 Pulsar 安全体系的最小可用配置方法、理解 broker 侧认证生命周期管理的底层实现，并能依据实际业务场景在 TLS、Athenz、Kerberos、JWT 等认证方案中做出正确选型。

Pulsar 的安全默认状态：为什么要主动加固

Pulsar 的默认安装不启用任何加密、认证与授权，任何客户端都可以通过明文的服务 URL（plain text service URLs）直接与 Pulsar 通信。从 conf/broker.conf 的默认值可以清楚地看到这一点：

# Enable authentication authenticationEnabled=false # Authentication provider name list, which is comma separated list of class names authenticationProviders= # Enforce authorization authorizationEnabled=false # Role names that are treated as "super-user", meaning they will be able to do all admin # operations and publish/consume from all topics superUserRoles=

也就是说，如果直接把集群暴露给不可信网络，任何人均可访问集群中的全部资源。官方文档给出的加固思路是：必须确保通过明文服务 URL 访问 Pulsar 的客户端仅限于可信客户端，具体手段包括：

• 网络分段（Network segmentation）：通过防火墙、VPC、安全组等手段，将 broker、proxy 的明文服务端口限制在可信网段内；
• 授权 ACL：借助授权机制，仅允许受信任的 IP / 角色访问。

如果两者都不采用，集群就处于"全开放"状态，任何人可以读写任意 topic、执行管理操作——这是 Pulsar 部署中最常见的风险来源。

可插拔认证机制：从单提供方到多提供方

Pulsar 支持可插拔（pluggable）的认证机制，客户端使用该机制与 broker、proxy 完成身份验证。更关键的是，Pulsar 还允许同时配置多个认证来源，让不同的客户端使用不同的认证方式连接同一集群。

这一能力的源码基础是pulsar-broker-common模块中的认证抽象层：

• AuthenticationProvider.java：认证提供方的顶层接口，定义了initialize(ServiceConfiguration config)（初始化）、getAuthMethodName()（返回该提供方支持的认证方法名）、authenticate(AuthenticationDataSource authData)（校验凭证并返回角色字符串）、newAuthState(...)（创建认证状态）等核心方法；
• AuthenticationProviderList.java：一个包装了多个认证提供方的组合实现，它会按顺序逐个尝试各个 provider，只要其中一个校验通过即返回成功；全部失败时才抛出最后的认证异常。这正是"一个 broker 同时支持多种认证来源"的实现机制；
• AuthenticationService.java：broker 启动时根据配置中的authenticationProviders列表，通过反射实例化各个 provider，并以getAuthMethodName()作为 key 进行组织管理。

对应的配置项是 broker 配置中的authenticationProviders（见 conf/broker.conf），它是一个以逗号分隔的类名列表。例如同时启用 TLS 与 JWT 认证：

authenticationEnabled=true authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderTls,org.apache.pulsar.broker.authentication.AuthenticationProviderToken

从pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/目录可以看到，仓库中已内置的提供方实现包括AuthenticationProviderTls（TLS 客户端证书认证）、AuthenticationProviderToken（JWT Token 认证）、AuthenticationProviderBasic（HTTP Basic 认证）等，它们与文档列出的四类认证方案一一对应（详见下文）。

认证生命周期：连接建立、Principal 存储与凭证刷新

连接建立时的凭证校验

当客户端与 broker 建立连接时，broker 会立即校验认证凭证。校验逻辑位于 ServerCnx.java 的handleConnect流程中：如果service.isAuthenticationEnabled()为真，则读取CommandConnect携带的认证数据，调用认证服务完成身份确认，并生成对应的AuthenticationState状态对象。

一次性认证与 Principal 存储

值得特别注意的是：连接完成初始认证后，broker 并不会在后续通信中反复重新认证。认证得到的"principal" token（即角色令牌）会被持久存储在连接上，用于后续的授权判断。也就是说，"认证"只发生一次（连接建立时），"授权"则贯穿连接的整个生命周期——每一次对 topic、namespace 的操作都基于该连接上已存储的 principal 进行 ACL 判定。

凭证过期的定期检查与强制重新认证

虽然连接不会主动重新认证，但凭证本身可能过期。为此，broker 会周期性检查每一个ServerCnx对象的过期状态。检查频率由 broker 配置authenticationRefreshCheckSeconds控制，默认值为60 秒（见 conf/broker.conf 与 ServiceConfiguration.java）：

# Interval of time for checking for expired authentication credentials authenticationRefreshCheckSeconds=60

一旦检测到凭证过期，broker 会强制对连接重新认证；若重新认证失败，broker 将直接断开该客户端连接。这一机制的实现位于 ServerCnx.java：

• maybeScheduleAuthenticationCredentialsRefresh()使用 Netty event loop 的scheduleAtFixedRate以authenticationRefreshCheckSeconds为周期启动定时任务；
• refreshAuthenticationCredentials()首先通过authState.isExpired()判断凭证是否仍有效，若有效则直接返回（无任何额外开销）；
• 若已过期，则区分两种情况：客户端支持认证刷新（supportsAuthenticationRefresh()）时，调用authState.refreshAuthentication()获取 broker 侧 challenge 数据，通过Commands.newAuthChallenge向客户端发起挑战，进入重新认证握手；客户端不支持认证刷新时，broker 直接关闭连接（ctx.close()）。

状态机的底层契约定义在 AuthenticationState.java：isExpired()默认返回false（表示该认证方式无过期概念），refreshAuthentication()默认返回AuthData.REFRESH_AUTH_DATA。各认证提供方可覆写这两个方法，实现各自凭证的过期判定与刷新协议（例如 JWT Token 认证即可实现基于过期时间的自动刷新）。

此外，在刷新流程中还内置了安全约束：刷新后的角色不得改变，若authRole与刷新前不一致，broker 会记录告警并关闭连接（见 ServerCnx.java），防止认证刷新被利用来提升权限。

代理场景的凭证转发约束

在启用 proxy 的场景下，若originalPrincipal存在但originalAuthState为空（即 proxy 未转发原始客户端凭证），broker 在凭证过期时无法重新校验用户凭证，也会直接关闭连接（见 ServerCnx.java）。这提醒我们：启用认证刷新的部署中，proxy 必须正确转发原始认证数据，否则长连接会在凭证到期时被强制断开。

Role Tokens：认证与授权之间的桥梁

在 Pulsar 中，role（角色）是一个字符串，例如admin或app1，它可以代表单个客户端，也可以代表多个客户端（即多个客户端共享同一角色）。角色用于控制客户端对特定 topic 的生产/消费权限、对 tenant 配置的管理权限等。

认证与授权通过Role Token衔接起来：

1. 认证阶段：Pulsar 使用某个 Authentication Provider 确立客户端身份；
2. 角色分配：认证成功后，为该客户端分配一个role token（即上文所述的 principal）；
3. 授权阶段：该 role token 被用于 Authorization and ACLs，判定该客户端被授权执行哪些操作。

从源码看，"认证返回角色"正是AuthenticationProvider.authenticate()与AuthenticationState.getAuthRole()的语义所在：前者在认证成功时返回 role 字符串，后者在认证完成后对外暴露该角色（见 AuthenticationProvider.java 与 AuthenticationState.java）。

认证提供方（Authentication Providers）

当前（对应 2.2.0 版本文档）Pulsar 支持以下四类认证提供方：

说明：2.2.0 版本文档列出的四类提供方均为可独立启用的方案。仓库根目录下pulsar-broker-auth-athenz、pulsar-broker-auth-sasl、pulsar-client-auth-athenz、pulsar-client-auth-sasl等独立模块表明，Athenz 与 Kerberos 认证在工程实现上以独立模块形式存在，broker 侧与客户端侧相互配套。

最小安全加固实践清单

综合上述原理，落地一份可操作的安全加固清单如下：

1. 先做网络隔离：将 broker / proxy 的明文服务端口限制在可信网络内，或直接关闭明文端口只开放 TLS 端口；
2. 开启认证：在 conf/broker.conf 中设置authenticationEnabled=true，并按需在authenticationProviders中填入一个或多个提供方类名（多个用逗号分隔）；
3. 开启授权并指定超级用户：设置authorizationEnabled=true，并在superUserRoles中填写管理员角色；需要转发客户端身份时，还需正确配置proxyRoles（详见 security-authorization.md）；
4. 评估凭证刷新策略：对支持过期机制的凭证（如 JWT），结合authenticationRefreshCheckSeconds的默认 60s 周期设计刷新流程；同时确认 proxy 场景下原始凭证会被正确转发，避免长连接被强制断开；
5. 为 broker 与 proxy 配置自身的客户端凭证：broker 与 broker 之间、broker 与 proxy 之间也会建立连接（如同步元数据、geo-replication），需要通过brokerClientAuthenticationPlugin与brokerClientAuthenticationParameters（见 conf/broker.conf）为这些内部连接配置认证凭证。

总结

Pulsar 的安全体系以"可插拔认证 + 角色授权 + 生命周期管理"为三条主线：默认全开放的状态要求部署者主动做网络隔离与 ACL 限制；AuthenticationProvider抽象与AuthenticationProviderList组合实现让多认证来源共存成为可能；连接建立时的单次认证配合authenticationRefreshCheckSeconds驱动的周期性凭证过期检查，在"不打断正常通信"与"保障凭证新鲜度"之间取得了平衡。理解这些底层机制，是正确配置 TLS、Athenz、Kerberos 或 JWT 认证、设计高可用安全集群的前提。需要深入某一具体认证方案的配置细节时，可继续阅读仓库中对应的分册文档：TLS 认证、Athenz、Kerberos、JWT。

• 消息队列
• 后端
• 流处理