企业官网建设流程全解析

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

Pulsarfunctions-worker是 Apache Pulsar 中负责在集群模式下运行 Pulsar Functions 的逻辑组件。本指南以 Pulsar 2.3.2 版本文档为基础，结合当前仓库中的真实配置文件与源码实现，系统讲解 functions-worker 的两种部署模式（与 broker 同进程运行、独立进程运行）、关键配置参数、安全加固（TLS / 认证 / 授权）、代理路由以及常见故障排查方法。读完本文，你将能够根据自身集群环境独立完成 functions-worker 的部署、验证与运维。

Pulsar Functions 是运行在 broker 之外或之上的轻量级计算原语，而functions-worker正是承载这些函数实例、负责函数包管理与元数据调度的核心服务。根据集群规模与资源隔离需求，官方提供两种部署选项，可二选一：

• 与 broker 一起运行：作为 broker 进程的一部分启动；
• 独立运行：在独立机器上以单独进程运行。

说明：下文示意图中的--- Service Urls ---线段表示 Pulsar 客户端与 Admin 工具连接集群所用的 Pulsar service URLs。

与 broker 一起运行（Run-with-Broker）

该模式下，functions-worker 作为 broker 的一个内置服务随 broker 一起启动，整体部署架构如上图所示。启用方式是在 conf/broker.conf 中设置：

functionsWorkerEnabled=true

当前仓库的默认配置文件中，该参数位于 conf/broker.conf 的### --- Functions --- ###段落，默认值为false：

# Enable Functions Worker Service in Broker functionsWorkerEnabled=false

将其改为true后，broker 启动时即会初始化并运行 functions-worker。同时需要编辑 conf/functions_worker.yml 以定制 functions-worker 的各项行为。

配置要点

在 Run-with-Broker 模式下，由于 functions-worker 运行在 broker 内部，大部分配置（例如 configurationStore、认证设置等）会直接从 broker 配置中继承，无需重复配置。但仍需重点关注以下两个必填项：

• numFunctionPackageReplicas：函数包（function package）在元数据存储中的副本数。默认值为1，适用于 standalone 单机部署；生产环境为保证高可用，建议设置为大于或等于2。
• pulsarFunctionsCluster：设置为你的 Pulsar 集群名称（与 broker 配置中的clusterName保持一致）。

若 BookKeeper 集群启用了认证，还需配置以下 BookKeeper 客户端认证参数：

• bookkeeperClientAuthenticationPlugin：BookKeeper 客户端认证插件名；
• bookkeeperClientAuthenticationParametersName：BookKeeper 客户端认证插件参数名；
• bookkeeperClientAuthenticationParameters：BookKeeper 客户端认证插件参数值。

上述配置项在 conf/functions_worker.yml 中均有对应占位（见 "Bookie Authentication" 注释段），并在 WorkerConfig.java 中以bookkeeperClientAuthenticationPlugin（第 374 行附近）等字段解析。从源码结构看，这些字段由WorkerConfig直接映射 YAML 配置项，因此配置名必须与类字段保持一致。

启动与验证

完成 conf/functions_worker.yml 配置后，启动或重启 broker 即可。随后可用以下命令验证 functions-worker 是否正常运行：

curl <broker-ip>:8080/admin/v2/worker/cluster

若服务正常，命令会返回集群中活跃 function workers 的列表，输出形如：

[{"workerId":"<worker-id>","workerHostname":"<worker-hostname>","port":8080}]

独立运行（Run-separately）

该模式将 functions-worker 作为独立进程部署在独立机器上，部署拓扑如上图所示。

注意：独立模式下，务必确保functionsWorkerEnabled保持为false，避免误在 broker 中重复启动 functions-worker。

独立模式配置

独立运行需要显式配置以下参数（对应 conf/functions_worker.yml 中的实际默认值）：

Worker 参数

• workerId：字符串类型，在集群范围内唯一，用于标识一台 worker 机器；
• workerHostname：worker 机器的主机名；
• workerPort：worker server 监听的端口，如无特殊需求保持默认即可（仓库默认6750）；
• workerPortTls：worker server 监听的 TLS 端口，默认6751。

以上四项在 conf/functions_worker.yml 中默认配置为：

workerId: standalone workerHostname: localhost workerPort: 6750 workerPortTls: 6751

对应源码定义位于 WorkerConfig.java：workerId（第 100 行）、workerHostname（第 105 行）、workerPort（第 110 行）、workerPortTls（第 115 行）。

函数包参数

• numFunctionPackageReplicas：函数包副本数，默认1。

函数元数据参数

• pulsarServiceUrl：Pulsar broker 集群的 service URL（仓库默认pulsar://localhost:6650，TLS 场景使用pulsar+ssl://localhost:6651/）；
• pulsarWebServiceUrl：Pulsar broker 集群的 web service URL（仓库默认http://localhost:8080，TLS 场景使用https://localhost:8443/）；
• pulsarFunctionsCluster：设置为 Pulsar 集群名称（与 broker 配置中的clusterName一致）。

元数据管理相关配置在 conf/functions_worker.yml 中的默认值为：

pulsarFunctionsNamespace: public/functions pulsarFunctionsCluster: standalone functionMetadataTopicName: metadata clusterCoordinationTopicName: coordinate

如果 broker 集群启用了认证，functions-worker 与 broker 通信时还应配置认证插件及参数：

• clientAuthenticationPlugin
• clientAuthenticationParameters

安全设置

若要为 functions-worker 启用安全能力，通常需要依次完成：

1. 启用 TLS 传输加密
2. 启用认证 Provider
3. 启用授权 Provider

启用 TLS 传输加密

tlsEnabled: true tlsCertificateFilePath: /path/to/functions-worker.cert.pem tlsKeyFilePath: /path/to/functions-worker.key-pk8.pem tlsTrustCertsFilePath: /path/to/ca.cert.pem

在 conf/functions_worker.yml 中，TLS 相关配置默认关闭（tlsEnabled: false），同时提供了tlsAllowInsecureConnection、tlsEnableHostnameVerification、tlsCertRefreshCheckDurationSec（默认 300 秒）等增强选项。TLS 的详细原理与证书体系可参考仓库中的 Transport Encryption using TLS 文档。

启用认证 Provider

authenticationEnabled: true authenticationProviders: [ provider1, provider2 ]

注意：请将provider1, provider2替换为你要启用的实际 Provider 列表。

若使用SASL 认证 Provider，可在properties下补充saslJaasClientAllowedIds与saslJaasBrokerSectionName：

properties: saslJaasClientAllowedIds: .*pulsar.* saslJaasBrokerSectionName: Broker

若使用Token 认证 Provider，可在properties下补充 token 校验相关配置：

properties: tokenSecretKey: file://my/secret.key # If using public/private # tokenPublicKey: file:///path/to/public.key

仓库的 conf/functions_worker.yml 中已内置 SASL 相关默认值（saslJaasClientAllowedIds: .*pulsar.*、saslJaasServerSectionName: PulsarFunction），并注释了tokenPublicKey/tokenPublicAlg等 Token 配置样例，可作为实际部署的参考起点。

启用授权 Provider

启用授权需要配置authorizationEnabled与configurationStoreServers——认证 Provider 通过连接configurationStoreServers获取命名空间策略（namespace policies）：

authorizationEnabled: true configurationStoreServers: <configuration-store-servers>

同时应配置超级用户（superuser）角色列表，超级用户可访问任意 admin API：

superUserRoles: - role1 - role2 - role3

仓库默认配置中authenticationEnabled、authorizationEnabled均为false，authorizationProvider默认使用org.apache.pulsar.broker.authorization.PulsarAuthorizationProvider，superUserRoles、proxyRoles默认为空列表，详见 conf/functions_worker.yml。

BookKeeper 认证

若 BookKeeper 集群启用了认证，独立模式下同样需要配置：

• bookkeeperClientAuthenticationPlugin：BookKeeper 客户端认证插件名；
• bookkeeperClientAuthenticationParametersName：BookKeeper 客户端认证插件参数名；
• bookkeeperClientAuthenticationParameters：BookKeeper 客户端认证插件参数值。

启动 functions-worker

完成 conf/functions_worker.yml 配置后，执行以下命令启动：

bin/pulsar functions-worker

从源码结构看，该命令最终会进入 PulsarWorkerService.java 的main入口，由WorkerServiceLoader加载并初始化 worker 服务（包括函数调度、元数据管理与运行时管理等）。

为 functions-worker 配置代理

当 functions-worker 独立成集群后，admin REST 端点被拆分为两部分：functions、function-worker、source、sink端点由 functions-worker 集群提供，其余端点仍由 broker 集群提供。因此，你需要让pulsar-admin按端点类型选择正确的 service URL。

为了统一管理入口，可以启动一个 proxy 集群，将 admin REST 请求按规则路由到对应集群。若尚未部署 proxy 集群，可参照仓库 deployment 目录 或集群部署文档先行搭建。在已有 proxy 集群的情况下，编辑 conf/proxy.conf，将 functions 相关管理请求指向 functions-worker 集群：

functionWorkerWebServiceURL=<pulsar-functions-worker-web-service-url> functionWorkerWebServiceURLTLS=<pulsar-functions-worker-web-service-url>

仓库默认 conf/proxy.conf 中这两个字段为空，并带有注释说明“如果 functions workers 部署在独立集群，请配置以下两个设置指向 functions workers 集群”，启用时填入对应的 HTTP 与 HTTPS 地址即可。

两种模式对比与选型建议

如上所述，functions-worker 既可以与 broker 同进程运行，也可以独立运行。与 broker 一起运行更为便捷，但独立集群运行能为Process或Thread模式下的函数提供更好的资源隔离。

推荐使用 Run-with-Broker 模式：

• a) 函数以Process或Thread模式运行时不需要资源隔离；
• b) 已将 functions-worker 配置为在 Kubernetes 上运行函数（此时资源隔离问题由 Kubernetes 解决）。

推荐使用 Run-separately 模式：

• a) 环境中没有 Kubernetes 集群；
• b) 希望将函数运行与 broker 服务完全分离。

常见问题排查

错误信息：Namespace missing local cluster name in clusters list

Failed to get partitioned topic metadata: org.apache.pulsar.client.api.PulsarClientException$BrokerMetadataException: Namespace missing local cluster name in clusters list: local_cluster=xyz ns=public/functions clusters=[standalone]

该错误通常由以下两种情况触发：

• a) broker 以functionsWorkerEnabled=true启动，但 conf/functions_worker.yml 中的pulsarFunctionsCluster未设置为正确的集群名；
• b) 配置了跨地域复制（geo-replication）的 Pulsar 集群中，一个集群的 broker 运行正常，而另一个集群的 broker 工作异常。

解决方法

1. 查询public/functions命名空间当前的集群列表：

bin/pulsar-admin namespaces get-clusters public/functions

2. 检查目标集群是否已在列表中；若不在，将其加入并更新集群列表：

bin/pulsar-admin namespaces set-clusters --cluster=<existing-clusters>,<new-cluster> public/functions

3. 在 conf/functions_worker.yml 中将pulsarFunctionsCluster修正为正确的集群名。

小结

本文围绕 Pulsar 2.3.2 的 functions-worker 部署主线，完整覆盖了 Run-with-Broker 与 Run-separately 两种模式的配置要点、安全加固（TLS / SASL / Token 认证、授权与超级用户）、代理路由以及典型故障处理流程。在实际部署时，建议先对照 conf/functions_worker.yml 检查pulsarFunctionsCluster、numFunctionPackageReplicas、workerId等关键项，再结合集群是否启用 TLS 与认证决定安全配置的取舍；若需要进一步了解 TLS 传输加密、Token 认证或集群初始化，可继续阅读仓库中 security-tls-transport 与 security-token-admin 等配套文档。

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