Apache Pulsar Functions 快速上手指南:从本地模式到集群模式的完整实战

原创2026-09-26 17:43:511,868 阅读
文章标签:消息队列后端流处理

Apache Pulsar Functions 快速上手指南:从本地模式到集群模式的完整实战

本指南基于 Apache Pulsar 的 functions-quickstart 教程,带你从零开始体验 Pulsar Functions:先在本地启动一个 standalone 集群,接着分别以 本地运行模式(local run mode) 和 集群模式(cluster mode) 部署一个"感叹号函数"(Exclamation Function),随后扩展到 Python、Go 两种语言的自定义函数,并掌握 Python 依赖打包(ZIP)的离线部署技巧。读完本文,你将掌握 pulsar-admin functions 的完整命令链(localrun / create / list / getstatus / get / update / delete / trigger),理解函数实例与 parallelism 的扩展原理,并具备独立编写、部署、触发、更新与删除 Pulsar Functions 的能力。

本文对应的原始文档为仓库中的 site2/website-next/versioned_docs/version-2.2.1/functions-quickstart.md,文中引用的源码、配置与示例均来自当前仓库。

前置条件

开始之前,请在你的开发机上安装 Maven(构建与运行示例函数所需)。此外,若你打算编写 Python 函数,还需要 pip;编写 Go 函数则需要 Go 工具链与 pulsar-client-go(详见下文对应章节)。

第一步:启动 standalone Pulsar 集群

运行 Pulsar Functions 的前提是有一个可用的 Pulsar 集群。最简单的方式是以 standalone(单机)模式 在本地启动:

$ wget pulsar:binary_release_url
$ tar xvfz apache-pulsar-@pulsar:version@-bin.tar.gz
$ cd apache-pulsar-@pulsar:version@
$ bin/pulsar standalone \
  --advertised-address 127.0.0.1

(其中 pulsar:binary_release_url 与 @pulsar:version@ 为发布版本占位符,实际下载时请替换为当前 Pulsar 版本的官方二进制包地址与版本号。)

standalone 模式会在单个进程中同时运行 broker 与必要的元数据服务(默认使用嵌入式 ZooKeeper 与本地 BookKeeper),并在启动时自动创建 public 租户(tenant)和 default 命名空间(namespace)。本教程后续所有函数都使用这一对租户/命名空间组合,因此无需额外创建。

关于 standalone 的说明:standalone 是 Pulsar 部署形态之一(术语参考),适合开发测试与学习。--advertised-address 127.0.0.1 用于指定集群对外广播的地址,确保本机客户端能够正确连接。

运行一个本地模式的 Pulsar Function

编写"感叹号函数"

先看一个最简单的函数:它从输入 topic 读取一条字符串消息,在末尾追加一个感叹号,再发布到输出 topic。Java 代码如下:

package org.apache.pulsar.functions.api.examples;

import java.util.function.Function;

public class ExclamationFunction implements Function<String, String> {
    @Override
    public String apply(String input) {
        return String.format("%s!", input);
    }
}

在当前的仓库中,该函数的实际实现位于 pulsar-functions/java-examples/src/main/java/org/apache/pulsar/functions/api/examples/ExclamationFunction.java。可以看到,仓库版本采用的是 Pulsar Functions API 中带 Context 的签名(String process(String input, Context context)),逻辑完全一致——这也提示我们:较新的 API 推荐通过 Context 访问消息上下文(如用户配置、当前 topic、日志等),而快速上手示例为了突出"输入→处理→输出"的最小流程,使用了更精简的 java.util.function.Function 写法。两种写法在本地运行与集群部署方式上完全相同。

本地运行模式(localrun)

下载的二进制发行包中的 examples 目录自带包含该函数及其他多个 Java 示例函数的 api-examples.jar。在本地(但独立于 Pulsar 集群进程之外)运行它:

$ bin/pulsar-admin functions localrun \
  --jar examples/api-examples.jar \
  --classname org.apache.pulsar.functions.api.examples.ExclamationFunction \
  --inputs persistent://public/default/exclamation-input \
  --output persistent://public/default/exclamation-output \
  --name exclamation

各参数含义:

  • --jar:函数包路径(Java 函数为 JAR 文件)。从 CmdFunctions.java 的参数定义看,它还支持 http/https/file/function 形式的 URL 路径,便于 worker 远程拉取包。
  • --classname:函数主类全限定名。
  • --inputs:输入 topic;可通过逗号分隔同时指定多个输入 topic,如 --inputs topic1,topic2。
  • --output:输出 topic(不指定则函数不产生输出)。
  • --name:函数名称,用于后续管理。

localrun 的底层机制:从源码看,localrun 命令(CmdFunctions.java 中的 LocalRunner)会把你传入的参数序列化为 FunctionConfig,并以 JSON 形式通过 $PULSAR_HOME/bin/function-localrunner 脚本启动一个独立的本地进程。也就是说:local run 模式下,函数进程与 Pulsar 集群是分离的——函数通过 Pulsar 客户端与 broker 通信、消费与生产消息,但其生命周期不受集群管理,方便开发与调试。

验证链路:消费输出 topic

另开一个终端,用 pulsar-client 订阅输出 topic(--num-messages 0 表示持续监听、不限条数):

$ bin/pulsar-client consume persistent://public/default/exclamation-output \
  --subscription-name my-subscription \
  --num-messages 0

生产一条输入消息

再开一个终端,向输入 topic 生产消息:

$ bin/pulsar-client produce persistent://public/default/exclamation-input \
  --num-produce 1 \
  --messages "Hello world"

消息被函数成功处理后,消费端会看到:

----- got message -----
Hello world!

函数处理完毕后,在运行 localrun 的终端按 Ctrl+C 即可关闭函数。

处理流程说明

  • 你发布到输入 topic persistent://public/default/exclamation-input 的 Hello world 消息被传递给感叹号函数;
  • 函数处理消息(结果为 Hello world!)并发布到输出 topic persistent://public/default/exclamation-output;
  • 若函数未运行,发布到输入 topic 的消息数据会被 Apache BookKeeper 持久化存储,直到有消费者消费并确认(ack)该消息——这正是 Pulsar 消息持久化与背压保障的体现。

运行一个集群模式的 Pulsar Function

本地运行模式适合开发与测试;真实部署时应使用集群模式——函数运行在 Pulsar 集群内部,通过统一的 pulsar-admin functions 接口进行管理。

创建函数(create)

把刚才的感叹号函数部署进集群(而非在集群外运行):

$ bin/pulsar-admin functions create \
  --jar examples/api-examples.jar \
  --classname org.apache.pulsar.functions.api.examples.ExclamationFunction \
  --inputs persistent://public/default/exclamation-input \
  --output persistent://public/default/exclamation-output \
  --name exclamation

成功会输出 Created successfully。从源码看,create(CmdFunctions.java 中的 CreateFunction)会调用 admin 客户端的 functions().createFunction(...) 将函数配置注册到集群。

列出函数(list)

$ bin/pulsar-admin functions list \
  --tenant public \
  --namespace default

输出中可以看到 exclamation 函数。

查看函数状态(getstatus)

$ bin/pulsar-admin functions getstatus \
  --tenant public \
  --namespace default \
  --name exclamation

返回 JSON 显示实例正在运行:

{
  "functionStatusList": [
    {
      "running": true,
      "instanceId": "0"
    }
  ]
}

可见当前集群中有 1 个实例(instanceId 为 0)在运行。getstatus 命令(GetFunctionStatus)支持用 --instance-id 指定查看某个实例,否则返回全部实例状态。

获取函数配置(get)

$ bin/pulsar-admin functions get \
  --tenant public \
  --namespace default \
  --name exclamation

返回:

{
  "tenant": "public",
  "namespace": "default",
  "name": "exclamation",
  "className": "org.apache.pulsar.functions.api.examples.ExclamationFunction",
  "output": "persistent://public/default/exclamation-output",
  "autoAck": true,
  "inputs": [
    "persistent://public/default/exclamation-input"
  ],
  "parallelism": 1
}

get 命令返回的是 FunctionConfig 的完整序列化结果,涵盖租户、命名空间、类名、输入/输出 topic、是否自动确认(autoAck)以及并行度(parallelism)等关键配置。

横向扩展:更新并行度(update)

目前只有 1 个函数实例在运行。用 update 命令将并行度提升到 3:

$ bin/pulsar-admin functions update \
  --jar examples/api-examples.jar \
  --classname org.apache.pulsar.functions.api.examples.ExclamationFunction \
  --inputs persistent://public/default/exclamation-input \
  --output persistent://public/default/exclamation-output \
  --tenant public \
  --namespace default \
  --name exclamation \
  --parallelism 3

输出 Updated successfully。再次执行 get,可以看到 parallelism 已变为 3,即集群中同时运行 3 个函数实例:

{
  "tenant": "public",
  "namespace": "default",
  "name": "exclamation",
  "className": "org.apache.pulsar.functions.api.examples.ExclamationFunction",
  "output": "persistent://public/default/exclamation-output",
  "autoAck": true,
  "inputs": [
    "persistent://public/default/exclamation-input"
  ],
  "parallelism": 3
}

parallelism 的含义:--parallelism 决定函数的并发实例数(CmdFunctions.java 参数定义)。每个实例独立消费输入 topic 的一部分消息(配合 Pulsar topic 分区实现并行处理),是提升函数吞吐的核心手段。集群模式下还支持 --cpu、--ram、--disk 等资源配额参数(源码中 Resources 相关定义)。

删除函数(delete)

$ bin/pulsar-admin functions delete \
  --tenant public \
  --namespace default \
  --name exclamation

输出 Deleted successfully,即表示你已经成功完成了一次"创建 → 查看 → 更新 → 删除"的集群模式函数全生命周期管理。

编写并运行 Python 函数

运行 Python 函数需要先安装 Pulsar 客户端:

$ pip install pulsar-client

编写反转字符串函数

创建一个 reverse.py:

$ touch reverse.py

写入如下内容:

def process(input):
    return input[::-1]

process 方法即 Pulsar Python 函数的处理逻辑入口——此处用 Python 切片语法把每条输入字符串反转。

部署并触发函数

用 create 命令部署(注意:Python 函数用 --py 指定主文件,--classname 为函数模块名):

$ bin/pulsar-admin functions create \
  --py reverse.py \
  --classname reverse \
  --inputs persistent://public/default/backwards \
  --output persistent://public/default/forwards \
  --tenant public \
  --namespace default \
  --name reverse

输出 Created successfully 后,函数即可接收消息。由于该函数运行在集群模式下,可以直接用 trigger 命令向函数注入一条消息并拿到返回结果:

$ bin/pulsar-admin functions trigger \
  --name reverse \
  --tenant public \
  --namespace default \
  --trigger-value "sdrawrof won si tub sdrawkcab saw gnirts sihT"

输出:

This string was backwards but is now forwards

trigger 命令(TriggerFunction)支持 --trigger-value(内联触发值)与 --trigger-file(从文件读取触发数据)两种方式,也可以配合 --topic 指定向哪个输入 topic 注入数据。

至此,你已经创建了一个新的 Pulsar Function,在 standalone 集群中以集群模式部署,并通过 trigger 完成了触发验证。

编写并运行 Go 函数

Go 函数依赖 pulsar-client-go(本仓库中的对应实现位于 pulsar-function-go),使用前请确保已构建好 pulsar-client-go。

按以下步骤操作:

  1. 创建 Go 文件
$ touch helloFunc.go
  1. 编写处理函数:为输入 topic 的每条消息追加一个值为 110 的字节,再投递到输出 topic。
package main

import (
	"context"

	"github.com/apache/pulsar/pulsar-function-go/pf"
)

func HandleResponse(ctx context.Context, in []byte) ([]byte, error) {
	res := append(in, 110)
	return res, nil
}

func main() {
	pf.Start(HandleResponse)
}

其中 pf.Start(实现在 pulsar-function-go/pf/function.go)负责注册处理函数并启动 Go 函数实例;从源码注释可见,pf.Start 支持多种函数签名形态(如 func(input) (output, error)、func(context.Context, input) (output, error) 等)。

  1. 编译代码
$ go build -o examplepulsar helloFunc.go
  1. 部署 Go 函数
$ bin/pulsar-admin functions create \
  --go examplepulsar \
  --inputs persistent://public/default/backwards \
  --output persistent://public/default/forwards \
  --tenant public \
  --namespace default \
  --name gofunc

输出 Created successfully 后,启动一个生产者向 backwards 输入 topic 生产消息、同时启动一个消费者从 forwards 输出 topic 消费,即可看到所有消息末尾都被追加了 110 字节。

注意:Go 函数使用 --go 指定可执行文件,且不需要指定 --classname——因为 Go 语言没有 Java/Python 那样的 Class 概念。另外,确保 --go 指定的可执行文件具备执行权限。

打包 Python 函数依赖(离线部署)

在离线环境下向集群部署 Python 函数时,需要把依赖预先打包进 ZIP 文件。

客户端要求

客户端机器需安装:

pip \\ required for getting python dependencies
zip \\ for building zip archives

准备 Python 依赖

编写 requirements.txt 声明依赖(示例):

sh==1.12.14

将 Pulsar Function 源码放入 src 目录。随后用 pip download 把依赖下载到 deps 目录:

pip download \
--only-binary :all: \
--platform manylinux1_x86_64 \
--python-version 27 \
--implementation cp \
--abi cp27m -r requirements.txt -d deps

示例输出:

Collecting sh==1.12.14 (from -r requirements.txt (line 1))
  Using cached https://files.pythonhosted.org/packages/4a/22/17b22ef5b049f12080f5815c41bf94de3c229217609e469001a8f80c1b3d/sh-1.12.14-py2.py3-none-any.whl
  Saved ./deps/sh-1.12.14-py2.py3-none-any.whl
Successfully downloaded sh

提示:pulsar-client 无需作为依赖打包——它已预装在 Pulsar worker 节点上。下载依赖时需按目标 worker 的运行平台(--platform、--python-version、--implementation、--abi)指定对应的二进制轮子,示例面向 Python 2.7 / manylinux1 环境;若 worker 为 Python 3 环境,请相应调整这些参数。

打包

创建一个目标目录(例如 exclamation),把 src 与 deps 复制进去,再压缩为 ZIP:

cp -R deps exclamation/
cp -R src exclamation/

ls -la exclamation/
total 7
drwxr-xr-x   5 a.ahmed  staff  160 Nov  6 17:51 .
drwxr-xr-x  12 a.ahmed  staff  384 Nov  6 17:52 ..
drwxr-xr-x   3 a.ahmed  staff   96 Nov  6 17:51 deps
drwxr-xr-x   3 a.ahmed  staff   96 Nov  6 17:51 src

zip -r exclamation.zip exclamation

打包出 exclamation.zip 后,即可在 Pulsar worker 上部署该函数。由于所有依赖都已包含在 ZIP 内,worker 无需联网下载任何包,从而实现离线部署。

小结与深入阅读

本文走完了 Pulsar Functions 的完整入门路径:

环节 关键命令 核心要点
启动集群 bin/pulsar standalone 自动创建 public/default 租户与命名空间
本地运行 functions localrun 函数进程独立于集群运行,适合开发调试
集群部署 functions create 函数运行在集群内,受集群统一管理
运维管理 list / getstatus / get / update / delete 查询、扩缩容(parallelism)、下线
触发验证 functions trigger 向集群内函数注入数据并获取输出
多语言 --py / --go Python 用 process 入口,Go 用 pf.Start 注册
离线部署 pip download + zip 依赖随 ZIP 打包,worker 无需联网

如果想继续深入,可在当前仓库中阅读以下资源:

提示:当前仓库对应较早期的 Pulsar 版本(本文档位于 version-2.2.1 版本目录),部分命令参数(如 --classname 的大小写变体、--trigger-value 等)在新版本中可能调整,实际使用请以你部署的 Pulsar 版本对应的文档为准。

登录后查看全文
pulsar