企业官网建设流程全解析

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

本指南以 Apache Pulsar 官方文档《Authentication and authorization in Pulsar》（版本 2.2.0 文档，位于 security-authorization.md）为骨架，结合当前仓库的配置模板与源码实现展开。读完本文，你将掌握：Pulsar 中"认证（authentication）与授权（authorization）"的关系与分工；如何在 Broker 与 Proxy 上启用授权并配置 superuser 与 Proxy Roles；如何通过pulsar-admin创建租户、为命名空间与主题授予/撤销 ACL 权限；以及如何为管理端PulsarAdmin配置认证（含 TLS）。文章中的配置项默认值、命令行参数与源码行为均以当前仓库实际内容为准。

授权在 Pulsar 安全体系中的定位

在 Pulsar 中，认证 Provider（Authentication Provider）负责正确识别客户端身份，并将客户端与 角色令牌（role tokens） 关联起来。如果只启用认证而不启用授权，那么任何通过认证的角色令牌都能访问集群中的所有资源。授权（Authorization）是决定客户端"能够做什么"的过程，即根据角色令牌对特定资源（租户、命名空间、主题）执行操作的许可判定。

权限层级中的最高级角色是superusers（超级用户）：拥有最高权限的角色令牌。superuser 可以创建和销毁租户（tenant），并对所有租户资源拥有完全访问权限。

当一个 superuser 创建了 租户 时，该租户会被指定一个admin 角色（admin role）。持有 admin 角色令牌的客户端，可以创建、修改和销毁该租户下的命名空间（namespace），并可在这些命名空间上对其他角色令牌授予和撤销权限。

Broker 与 Proxy 的授权配置

在 Broker 上启用授权并指定 superuser

授权开关和 superuser 列表在 Broker 配置文件（conf/broker.conf）中设置：

authorizationEnabled=true superUserRoles=my-super-user-1,my-super-user-2

完整的参数列表见conf/broker.conf文件；各参数的默认值可参考 Broker 配置参考。

当前仓库conf/broker.conf中与该功能直接相关的参数及其默认值如下（与 ServiceConfiguration.java 中的字段默认值一一对应）：

需要说明的是：仅开启认证、未开启授权时，认证令牌即可访问全部资源——这正是必须在 Broker 上同时开启authorizationEnabled=true的原因。

典型的使用方式是：superuser 角色用于管理员、客户端以及 Broker 之间的授权。当使用跨地域复制（geo-replication）时，每个 Broker 都需要能够向其他集群的所有主题发布消息，因此 Broker 间的连接通常也要以 superuser 身份进行认证与授权。

在 Proxy 上启用授权

同样地，可以在 Proxy 配置文件（conf/proxy.conf）中启用授权：

# 在 conf/proxy.conf 中 authorizationEnabled=false # 默认关闭，需改为 true superUserRoles= authorizationProvider=org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider

在 Proxy 上启用授权后，Proxy 会在把请求转发给 Broker 之前先做一次额外的授权检查；如果 Broker 上也启用了授权，那么 Broker 在收到转发过来的请求时还会再检查一次该请求的授权。由此形成"Proxy 前置检查 + Broker 二次检查"的双重防线。

conf/proxy.conf中还有一个值得注意的参数forwardAuthorizationCredentials（默认false）：它决定是否把客户端的授权凭证转发给 Broker 以进行二次授权，且要求先启用authenticationEnabled=true才生效。

提示：conf/standalone.conf（单机模式）、conf/websocket.conf（WebSocket 服务）以及conf/functions_worker.yml（Functions Worker）中也都有authorizationEnabled/superUserRoles/proxyRoles等同类配置项，默认值均为关闭/空，可按部署形态分别开启。

Proxy Roles（代理角色）

默认情况下，Broker 把 Proxy 与 Broker 之间的连接当作普通用户连接处理：Broker 会以conf/proxy.conf中配置的角色来认证该用户（参见 在 Proxy 上启用 TLS 认证）。但用户通过 Proxy 连接集群时，通常并不想再向 Broker 单独认证一次——用户期望的是：以自己向 Proxy 认证时使用的角色身份来与集群交互。

Pulsar 通过Proxy Roles机制实现这一目标。Proxy Roles 在 Broker 配置文件conf/broker.conf中指定：如果某个与 Broker 完成认证的客户端其角色是proxyRoles中的一员，那么来自该客户端的所有请求都必须额外携带"该客户端向 Proxy 认证时的角色"信息，这个信息被称为original principal（原始主体）。如果缺少 original principal，该客户端将无法访问任何资源。

因此，要让资源可以通过 Proxy 被访问，必须同时授权 proxy role 和 original principal 两者。管理员有两种做法：

方式一（更安全）：每次授权资源时都同时授予 proxy role。例如，proxy role 名为proxy1，则当 superuser 创建租户时，应把proxy1一并指定为 admin 角色之一；当某个角色被授予在命名空间上 produce/consume 的权限时，如果该客户端要通过 Proxy 生产/消费，则也应当给proxy1授予相同权限。

方式二：把 proxy role 直接设为 superuser。这样 Proxy 可以访问所有资源。客户端仍然需要向 Proxy 认证，所有经由 Proxy 发出的请求，其角色都会被降级为已认证客户端的 original principal。风险在于：一旦 Proxy 被攻破，攻击者就能获得整个集群的完全访问权限。

在conf/broker.conf中指定 proxy roles：

proxyRoles=my-proxy-role # 如果你想让 superuser 也能使用该 proxy（见上文方式二） superUserRoles=my-super-user-1,my-super-user-2,my-proxy-role

源码层面的双重校验逻辑（可参见 AuthorizationService.java）：当请求的clientRole命中proxyRoles时，isSuperUser与各类allowXxxOperationAsync都会把"proxy role 是否被授权"和"original principal 是否被授权"两者做 AND 合并——任一未授权即拒绝。而 isValidOriginalPrincipal 则校验角色组合的合法性：

• 当authenticatedPrincipal命中proxyRoles时，originalPrincipal必须存在且不能也是 proxy role；
• 当非 proxy role 携带了originalPrincipal时，会记录告警日志（originalPrincipal只允许等于自身角色，且未来版本将不再允许该行为）。

这从代码层面印证了文档中的约束：Proxy 场景下"proxy role + original principal"二者缺一不可。

租户管理（Administer tenants）

Pulsar 实例 的管理员或某种自助服务门户，通常会负责为业务方供给一个 Pulsar 租户。租户管理使用pulsar-admin工具完成。

创建一个新租户

下面是一个创建租户的示例命令：

$ bin/pulsar-admin tenants create my-tenant \ --admin-roles my-admin-role \ --allowed-clusters us-west,us-east

该命令创建了一个名为my-tenant的新租户，允许其使用us-west和us-east两个集群。

一个能够成功认证为my-admin-role角色的客户端，就被允许对该租户执行所有管理任务。

对应命令的 CLI 实现位于 CmdTenants.java，参数细节如下：

同时pulsar-admin tenants update也支持--admin-roles/--allowed-clusters，用于在保留现有配置的基础上增量修改租户的管理角色与可用集群。

Pulsar 中主题名称的结构恰好体现了租户、集群与命名空间之间的层级关系：

persistent://tenant/namespace/topic

即persistent://租户/命名空间/主题，这也解释了为何租户是授权边界的第一层：授予了租户 admin 角色，即可管理其下所有命名空间与主题。

管理权限（Manage permissions）

可以使用 Pulsar Admin Tools（权限管理 API） 来管理 Pulsar 中的权限。

通过pulsar-admin可以针对命名空间与主题分别执行权限的授予与撤销。以命名空间为例，CLI 实现位于 CmdNamespaces.java：

# 授予：给角色 my-client-role 授予在 my-tenant/my-ns 上 produce 与 consume 的权限 $ bin/pulsar-admin namespaces grant-permission my-tenant/my-ns \ --role my-client-role \ --actions produce,consume # 撤销：移除角色 my-client-role 在该命名空间上的所有权限 $ bin/pulsar-admin namespaces revoke-permission my-tenant/my-ns \ --role my-client-role

--actions支持的取值（来自源码中的命令描述）包括：produce、consume、sources、sinks、functions、packages。对应的主题级命令为pulsar-admin topics grant-permission/pulsar-admin topics revoke-permission（实现见 CmdPersistentTopics.java 与 CmdTopics.java）。

此外，Pulsar 还支持订阅级（subscription）权限：pulsar-admin namespaces grant-subscription-permission/revoke-subscription-permission/get-permission-on-subscription，用于控制哪些角色可以访问订阅的管理 API。

底层实现（可参见默认授权 Provider PulsarAuthorizationProvider.java）：

• 默认的PulsarAuthorizationProvider把授权策略（ACL）存储在元数据存储（MetadataStore，如 ZooKeeper）中，通过pulsarResources读写租户/命名空间的 policy 数据；
• 生产/消费等操作在 checkPermission 中按"命名空间级 ACL → 主题级 ACL → 通配符匹配"的顺序判定：先看该角色在命名空间级namespaceAuthentication中是否具备对应AuthAction，再看主题级topicAuthentication中是否授权，最后（若authorizationAllowWildcardsMatching=true）做前缀/后缀通配匹配；分区主题还会回退检查其分区主题（partitioned topic）本身的策略；
• 判定通过后还会执行 checkCluster 的集群校验：本地集群或全局主题（global）放行，其他集群须确认其存在于集群列表中；
• 消费检查（canConsumeAsync）还会校验订阅级授权列表，以及在subscription_auth_mode=Prefix模式下要求订阅名必须以角色名称为前缀；
• 在 AuthorizationService 层面，superuser 拥有最短路径豁免：canProduceAsync/canConsumeAsync/canLookupAsync都会先调用provider.isSuperUser(...)，命中 superuser 则直接放行，否则才继续走上述 ACL 判定。

管理端 PulsarAdmin 的认证配置

除了面向用户的pulsar-adminCLI，程序化管理接口PulsarAdmin同样需要携带认证信息。下面的 Java 代码演示如何构建一个带认证的管理客户端：

PulsarAdmin admin = PulsarAdmin.builder() .serviceHttpUrl("http://broker:8080") .authentication("com.org.MyAuthPluginClass", "param1:value1") .build();

若要使用 TLS：

PulsarAdmin admin = PulsarAdmin.builder() .serviceHttpUrl("https://broker:8080") .authentication("com.org.MyAuthPluginClass", "param1:value1") .tlsTrustCertsFilePath("/path/to/trust/cert") .build();

要点说明：

• serviceHttpUrl指向 Broker 的 Web 服务地址；使用 TLS 时协议切换为https；
• authentication接受两个参数：认证插件类的完全限定名（如 Pulsar 内置的org.apache.pulsar.client.impl.auth.AuthenticationToken等，可参照认证 Provider 文档）以及插件所需的参数字符串（形如param1:value1，具体格式取决于插件，例如 Token 认证的token:xxx）；
• TLS 场景下通过tlsTrustCertsFilePath指定信任证书路径，用于校验服务端证书链。

小结

Pulsar 的授权体系以"角色令牌"为身份载体，以"租户 → 命名空间 → 主题"为资源层级，通过authorizationEnabled+superUserRoles+proxyRoles三项核心配置构建起完整的访问控制模型。在引入 Proxy 时，务必理解"proxy role 与 original principal 必须同时被授权"这一关键约束，并按安全等级选择"逐资源授予 proxy role"或"proxy role 设为 superuser"两种策略。配合pulsar-admin的租户/权限管理命令与带认证的PulsarAdmin管理端，即可在生产环境中落地一套完整、可审计的多租户 ACL 方案。

延伸阅读（同一版本文档目录）：

• 安全总览：认证 Provider、角色令牌与过期刷新机制
• 多租户概念：租户/命名空间/集群的层次关系
• 权限管理 API：以 Admin API 视角管理 ACL
• Broker 配置参考：authorizationEnabled等参数的完整说明
• pulsar-admin 工具参考：全部 CLI 子命令

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