Apache Pulsar 传输加密（TLS）完整指南：从证书签发到 Broker / Proxy / 客户端全链路配置
发布时间：2026/9/28 3:00:30 作者：尧图编辑部 阅读量：1,286
消息队列后端流处理【免费下载链接】pulsarApache Pulsar - distributed pub-sub messaging system项目地址https://gitcode.com/gh_mirrors/pulsar28/pulsar点击查看免费下载本文基于 Apache Pulsar 2.3.2 版本安全文档security-tls-transport.md整理而成并结合当前仓库的conf/broker.conf、conf/proxy.conf、conf/client.conf以及ServiceConfiguration.java等源码进行深入展开。默认情况下Pulsar 客户端与 Broker 之间以明文传输数据启用 TLS 后所有流量都会被加密抵御中间人窃听。读完本文你将掌握TLS 在 Pulsar 中的角色与信任模型、如何用 OpenSSL 签发 CA / Broker / 客户端证书、如何配置 Broker 与 Proxy 的 TLS 监听端口与协议/密码套件策略以及 Java、Python、C 客户端和 CLI 工具接入 TLS 的完整参数。TLS 概览Pulsar 为什么需要它Apache Pulsar 默认情况下客户端与 Pulsar 服务之间的通信是明文plain text的也就是说所有数据都以可读形式在网络上传输。启用 TLS 之后这段流量会被加密从而防止中间人man-in-the-middle攻击者窃听数据内容。TLS 在 Pulsar 中承担两类职责传输加密transport encryption本文的主题保证数据在链路上不可被窃听TLS 认证authentication基于证书验证身份其详细配置见 security-tls-authentication.md也可以在 TLS 传输加密之上叠加 Athenz 认证机制。需要注意启用 TLS 会带来一定的性能开销加密/解密计算成本在规划集群容量时应纳入考虑。TLS 核心概念与信任模型TLS 属于公钥密码体系public key cryptography每个密钥对key pair包含一个公钥public key和一个私钥private key消息用公钥加密只有持有私钥的一方才能解密。在 Pulsar 的 TLS 传输加密场景中需要两类密钥对服务端密钥对server key pairsBroker / Proxy 使用向客户端证明自己身份证书颁发机构certificate authorityCA用来给其他证书签名的信任根。第三类密钥对客户端密钥对client key pairs则用于客户端认证。整个信任模型的要点CA 私钥必须存放在极其安全的位置完全加密、断网、离线隔离的机器CA 的公钥称为信任证书trust cert可以自由分发给所有相关方对于客户端和服务端密钥对管理员先生成私钥和证书请求certificate request再用 CA 私钥对请求签名生成证书certificate——证书即该密钥对的公钥在传输加密中客户端用trust cert验证所连接的服务器持有由该 CA 签名的密钥对。中间人攻击者没有 CA 私钥无法伪造这样的密钥对因此无法冒充服务器在 TLS 认证场景中服务器用trust cert验证客户端持有 CA 签发的密钥对并且客户端证书的 Common NameCN会被用作客户端的 role token参见 security-overview.md。使用 OpenSSL 签发 TLS 证书为 Pulsar 签发 TLS 证书需要依次创建三个部分证书颁发机构CA、服务器证书server certificate、客户端证书client certificate。下面的步骤是从 openssl.cnf 配置模板出发的精简指南。第一步创建证书颁发机构CACA 会被用来同时签署 Broker 证书和客户端证书确保各方彼此信任。CA 应当存放在非常安全的位置理想情况下完全断网、离线隔离、全盘加密。首先为 CA 创建目录并把 openssl 配置文件放入其中你可能需要按公司名称、部门等修改配置中的默认答案随后把 CA 目录路径导出到环境变量CA_HOME配置文件依赖该变量定位其余文件和目录mkdir my-ca cd my-ca wget https://raw.githubusercontent.com/apache/pulsar/master/site2/website/static/examples/openssl.cnf export CA_HOME$(pwd)创建 CA 所需的目录结构、密钥和证书mkdir certs crl newcerts private chmod 700 private/ touch index.txt echo 1000 serial openssl genrsa -aes256 -out private/ca.key.pem 4096 chmod 400 private/ca.key.pem openssl req -config openssl.cnf -key private/ca.key.pem \ -new -x509 -days 7300 -sha256 -extensions v3_ca \ -out certs/ca.cert.pem chmod 444 certs/ca.cert.pem回答完命令提示的问题后CA 相关文件会保存在./my-ca目录中其中certs/ca.cert.pemCA 的公钥证书用于分发给所有相关方private/ca.key.pemCA 的私钥仅在为 Broker 或客户端签发新证书时需要必须妥善保管。第二步生成服务器证书Broker / ProxyCA 证书创建完成后就可以创建证书请求并用 CA 签名。下面的命令会询问几个问题然后生成证书。当询问Common Name时应当填写Broker 的主机名hostname也可以使用通配符来匹配一组 Broker 主机名例如*.broker.usw.example.com这样同一张证书可以复用在多台机器上。提示有些场景下无法或没有必要匹配主机名——例如 Broker 使用随机生成的主机名或者你打算通过 IP 直连主机。此时客户端应配置为关闭 TLS 主机名校验详见下文客户端配置中的主机名校验小节。先生成密钥openssl genrsa -out broker.key.pem 2048Broker 要求密钥为PKCS 8格式因此需要转换openssl pkcs8 -topk8 -inform PEM -outform PEM \ -in broker.key.pem -out broker.key-pk8.pem -nocrypt生成证书请求openssl req -config openssl.cnf \ -key broker.key.pem -new -sha256 -out broker.csr.pem用 CA 对请求签名openssl ca -config openssl.cnf -extensions server_cert \ -days 1000 -notext -md sha256 \ -in broker.csr.pem -out broker.cert.pem至此你得到了一张证书broker.cert.pem和一个密钥broker.key-pk8.pem配合ca.cert.pem即可为 Broker 和 Proxy 节点配置 TLS 传输加密。第三步客户端证书用于 TLS 认证客户端证书用于客户端认证其签发流程与服务器证书一致生成密钥 → 生成证书请求 → 用 CA 签名。注意签名的扩展名不同应使用client_cert之类的客户端扩展。本文聚焦传输加密客户端证书的细节参见认证文档。Broker 配置开启 TLS 监听要启用 TLS 传输加密需要修改 Pulsar 安装目录conf下的 broker.conf。将以下配置写入文件按实际证书路径替换tlsEnabledtrue tlsCertificateFilePath/path/to/broker.cert.pem tlsKeyFilePath/path/to/broker.key-pk8.pem tlsTrustCertsFilePath/path/to/ca.cert.pem对应源码中这些参数定义在 ServiceConfiguration.javatlsEnabled默认falsetlsCertRefreshCheckDurationSec默认300秒。同时还需要为 TLS 流量指定监听端口当前仓库的 broker.conf 中# Broker data port for TLS - By default TLS is disabled brokerServicePortTls # Port to use to serve HTTPS request - By default TLS is disabled webServicePortTls即 Broker 二进制协议客户端生产/消费的 TLS 端口是brokerServicePortTls惯例 6651Web 服务管理 REST API的 TLS 端口是webServicePortTls惯例 8443两者默认为空TLS 关闭。tlsCertificateFilePath、tlsKeyFilePath、tlsTrustCertsFilePath分别对应证书、私钥PKCS 8 PEM 格式和信任证书路径。关于tlsTrustCertsFilePathbroker.conf 注释说明该证书用于校验连接客户端出示的证书是否由该 CA 签名校验失败则视为不受信任并断开连接。另外还有几个值得注意的关联参数同一配置文件内tlsAllowInsecureConnectionfalse为true时证书无法用tlsTrustCertsFilePath验证的客户端仍可连接但其证书不会用于客户端认证生产环境应保持falsetlsHostnameVerificationEnabledfalseBroker 与其他 Broker 建 TLS 连接时是否校验主机名tlsRequireTrustedClientCertOnConnectfalse为true时强制所有连接客户端执行 TLS 客户端认证即要求可信客户端证书tlsCertRefreshCheckDurationSec300证书刷新检查周期秒设为 0 表示每个新连接都检查tlsProvider指定 TLS Provider使用 CACert 认证时可选OPENSSL或JDK使用 KeyStore 时可选SunJSSE、Conscrypt等KeyStore 系列参数tlsEnabledWithKeyStore、tlsKeyStoreTypeJKS、tlsKeyStore、tlsTrustStore等用于以 JKS/PKCS12 密钥库方式配置 TLS。完整的参数列表与默认值参见 reference-configuration.md 的 Broker 一节。TLS 协议版本与密码套件策略Broker以及 Proxy可以要求特定的 TLS 协议版本和密码套件cipher用于阻止客户端请求降级到可能存在弱点的旧协议版本或弱密码套件tlsProtocolsTLSv1.2,TLSv1.1 tlsCiphersTLS_DH_RSA_WITH_AES_256_GCM_SHA384,TLS_DH_RSA_WITH_AES_256_CBC_SHAtlsProtocols与tlsCiphers均可取多个值用逗号分隔。具体可选值取决于所用的 TLS ProviderPulsar 优先使用 OpenSSL若不可用则回退到 JDK 实现这一策略在pulsar-common的 NettyServerSslContextBuilder.java 与 NettyClientSslContextRefresher.java 中通过 Netty 的SslProvider体现。OpenSSL 目前支持SSL2、SSL3、TLSv1、TLSv1.1、TLSv1.2等协议版本支持的密码套件列表可用openssl ciphers -tls_v2命令查询JDK 8 的协议与密码套件标准名称见官方 Standard Names 文档。注意虽然原文档时代TLSv1.2,TLSv1.1是常见配置但当前仓库 broker.conf 中tlsProtocols给出的示例为[TLSv1.3, TLSv1.2]tlsCiphers示例为[TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256]说明 TLSv1.3 已得到支持建议优先使用更强的新协议与 GCM 类套件。Proxy 配置双向 TLS 接力Proxy 需要在两个方向分别配置 TLS客户端 → Proxy客户端连接到 Proxy 的 TLS 配置Proxy → BrokerProxy 与 Broker 之间通信的 TLS 配置。对应 proxy.conf 的配置块# For clients connecting to the proxy tlsEnabledInProxytrue tlsCertificateFilePath/path/to/broker.cert.pem tlsKeyFilePath/path/to/broker.key-pk8.pem tlsTrustCertsFilePath/path/to/ca.cert.pem # For the proxy to connect to brokers tlsEnabledWithBrokertrue brokerClientTrustCertsFilePath/path/to/ca.cert.pem在 proxy.conf 中tlsEnabledInProxy标注为Deprecated推荐改用servicePortTls与webServicePortTls两个 TLS 监听端口参数对应二进制协议与 Web 服务tlsEnabledWithBrokerfalse是否在与 Broker 通信时启用 TLSbrokerClientTrustCertsFilePathProxy 作为客户端连接 Broker 时使用的信任证书路径tlsAllowInsecureConnectionfalse、tlsHostnameVerificationEnabledfalse、tlsProtocols、tlsCiphers等参数语义与 Broker 侧一致此外 Proxy 还有brokerClientAuthenticationPlugin/brokerClientAuthenticationParameters用于配置 Proxy 向 Broker 认证的方式。客户端配置启用 TLS 传输加密后客户端需要改用以下协议与端口Web 服务 URLhttps:// 端口8443Broker 服务 URLpulsarssl:// 端口6651。由于上文签发的服务器证书不属于任何默认信任链trust chain你还需要指定 trust cert 的路径推荐或者允许客户端信任未经验证的服务器证书。主机名校验Hostname verification主机名校验是 TLS 的一项安全特性当服务器的CommonName与客户端正在连接的主机名不匹配时客户端可以拒绝连接。Pulsar 客户端默认关闭主机名校验因为它要求每个 Broker 都有 DNS 记录和唯一证书。在允许客户端连接证书未经认可的 CA 签名的服务器这一点上allowInsecureConnection默认关闭且生产环境应始终保持关闭只要allowInsecureConnection保持关闭中间人攻击就需要攻击者先取得 CA 的访问权。一个适合开启主机名校验的典型场景多个 Proxy 节点位于 VIP 之后且 VIP 有 DNS 记录例如pulsar.mycompany.com。此时可以为pulsar.mycompany.com作为 CommonName 签发一张 TLS 证书然后在客户端开启主机名校验。说明Java 客户端可以显式配置主机名校验默认关闭可省略C/Python 客户端在当前版本暂不开放该配置项详见下文各客户端示例。CLI 工具配置pulsar-admin、pulsar-perf、pulsar-client等命令行工具共用 Pulsar 安装目录conf下的 client.conf。要使用 TLS需要向该文件加入以下参数webServiceUrlhttps://broker.example.com:8443/ brokerServiceUrlpulsarssl://broker.example.com:6651/ useTlstrue tlsAllowInsecureConnectionfalse tlsTrustCertsFilePath/path/to/ca.cert.pem tlsEnableHostnameVerificationfalseclient.conf 中对应的默认值为webServiceUrlhttp://localhost:8080/、brokerServiceUrlpulsar://localhost:6650/、tlsAllowInsecureConnectionfalse、tlsEnableHostnameVerificationfalse、tlsTrustCertsFilePath空。若还需叠加 TLS 客户端认证可配置authPluginorg.apache.pulsar.client.impl.auth.AuthenticationTls与authParamstlsCertFile:/path/to/client-cert.pem,tlsKeyFile:/path/to/client-key.pem同为该文件内已提供的注释示例。Java 客户端import org.apache.pulsar.client.api.PulsarClient; PulsarClient client PulsarClient.builder() .serviceUrl(pulsarssl://broker.example.com:6651/) .enableTls(true) .tlsTrustCertsFilePath(/path/to/ca.cert.pem) .enableTlsHostnameVerification(false) // false by default, in any case .allowTlsInsecureConnection(false) // false by default, in any case .build();上述 builder 方法均定义在 ClientBuilderImpl.java 中对应底层配置项在 ClientConfigurationData.java如tlsTrustCertsFilePath默认空字符串。另外从源码看enableTls也可以通过 serviceUrl 前缀自动推导当 URL 以pulsarssl或https开头时ClientBuilderImpl.java 会自动开启 TLS。Python 客户端from pulsar import Client client Client(pulsarssl://broker.example.com:6651/, tls_hostname_verificationTrue, tls_trust_certs_file_path/path/to/ca.cert.pem, tls_allow_insecure_connectionFalse) # defaults to false from v2.2.0 onwardsC 客户端#include pulsar/Client.h ClientConfiguration config ClientConfiguration(); config.setUseTls(true); // shouldnt be needed soon config.setTlsTrustCertsFilePath(caPath); config.setTlsAllowInsecureConnection(false); config.setAuth(pulsar::AuthTls::create(clientPublicKeyPath, clientPrivateKeyPath)); config.setValidateHostName(true);其中config.setAuth(...)一段属于 TLS 客户端认证的配置只有同时启用证书认证时才需要。验证与测试启用 TLS 后建议从端到端验证配置是否正确检查监听端口确认 Broker/Proxy 已监听brokerServicePortTls6651与webServicePortTls8443使用 CLI 工具连通性测试修改conf/client.conf后运行pulsar-admin或pulsar-client连接pulsarssl://地址观察是否握手成功参考仓库测试用例当前仓库的 Broker 测试模块中有一系列 TLS 相关测试可供参考例如 TlsProducerConsumerTest.java、TlsHostVerification.java、AuthenticationTlsHostnameVerificationTest.java 以及 TlsSniTest.java它们演示了 TLS 生产/消费、主机名校验、SNI 等场景的完整测试路径证书刷新Broker 侧tlsCertRefreshCheckDurationSec控制证书热刷新周期证书轮换后无需重启即可生效。相关文档TLS 客户端认证在传输加密之上叠加基于证书的身份认证Athenz 认证在 TLS 传输加密之上使用其他认证机制安全总览Pulsar 安全模型与 role token 机制Broker 配置参考conf/broker.conf全部参数与默认值CLI 工具参考pulsar-admin、pulsar-perf、pulsar-client用法术语表Broker、Proxy 等核心概念定义。赞分享消息队列后端流处理【免费下载链接】pulsarApache Pulsar - distributed pub-sub messaging system项目地址https://gitcode.com/gh_mirrors/pulsar28/pulsar点击查看免费下载相关推荐Apache Pulsar 传输加密Transport Encryption using TLS完整配置指南从证书签发到 Broker/Proxy/客户端全链路落地Apache Pulsar 传输加密Transport Encryption using TLS完整配置指南从证书签发到 Broker/Proxy/客户端消息队列后端流处理Apache Pulsar 传输加密TLS完整配置指南从证书签发到 Broker、Proxy 与多语言客户端实战Apache Pulsar 传输加密TLS完整配置指南从证书签发到 Broker、Proxy 与多语言客户端实战 Apache Pulsar 默认以明文方消息队列后端流处理Apache Pulsar TLS 传输加密实践从证书生成到 Broker、Proxy 与多语言客户端全链路配置Apache Pulsar TLS 传输加密实践从证书生成到 Broker、Proxy 与多语言客户端全链路配置 本篇指南围绕 Apache Pulsar 的消息队列后端流处理上一篇brpc协程与线程混合编程终极指南与避坑技巧下一篇TensorFlow models cognitive_planning基于 Active Vision 数据集的语义目标导航训练与评估全解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 