Apache Pulsar Functions 快速上手指南:从本地模式到集群模式的完整实战
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!)并发布到输出 topicpersistent://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。
按以下步骤操作:
- 创建 Go 文件
$ touch helloFunc.go
- 编写处理函数:为输入 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) 等)。
- 编译代码
$ go build -o examplepulsar helloFunc.go
- 部署 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 无需联网 |
如果想继续深入,可在当前仓库中阅读以下资源:
- functions 用户指南 与 Pulsar Functions API 参考:了解函数配置项、SerDe、窗口函数与有状态函数等进阶能力;
- pulsar-admin functions 命令参考:完整的 CLI 参数说明;
- 函数实现源码:pulsar-functions(Java/Python 运行时与 worker)、pulsar-function-go(Go 运行时)、java-examples(更多示例函数,如 ExclamationFunction.java);
- 命令实现源码:pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdFunctions.java,可对照查看每个子命令的参数定义与底层调用。
提示:当前仓库对应较早期的 Pulsar 版本(本文档位于
version-2.2.1版本目录),部分命令参数(如--classname的大小写变体、--trigger-value等)在新版本中可能调整,实际使用请以你部署的 Pulsar 版本对应的文档为准。