SeaTunnel Apache Pulsar 连接器完全指南:从版本演进到 Source/Sink 实战与源码解析

原创2026-10-10 21:01:181,936 阅读
文章标签:数据集成ETL大数据数据同步变更数据捕获流处理批处理

SeaTunnel Apache Pulsar 连接器完全指南:从版本演进到 Source/Sink 实战与源码解析

本文以 SeaTunnel 仓库中 Apache Pulsar 连接器变更日志 为核心骨架,完整梳理 Pulsar Source / Sink 从 2.2.0-beta 到 2.3.12 的演进脉络,并在此基础上结合官方源连接器文档、Sink 连接器文档 与 seatunnel-connectors-v2/connector-pulsar 模块源码,系统讲解连接器架构、全部配置参数、多表读写、游标(Cursor)位点控制与精确一次写入的实现原理。读完本文,你将能够基于当前仓库版本完整掌握 Pulsar 连接器的能力边界、正确配置批式/流式/多表读写任务,并理解其底层源码实现。

一、Pulsar 连接器演进全景:一份变更日志背后的技术主线

Apache SeaTunnel 的每个连接器在 docs/zh/connectors/changelog/ 目录下都维护着一份独立的变更日志。打开 connector-pulsar.md,可以看到 Pulsar 连接器从 2.2.0-beta 到 2.3.12 的完整提交历史。将这些条目按功能主线重组,能清晰看到连接器从"可用"到"健壮、多表、高性能"的演进路径:

1.1 能力从无到有:Sink 与多格式读取的落地

  • 2.3.4 版本是 Pulsar 连接器能力的重要分水岭:[Feature][Connector-v2][PulsarSink]Add Pulsar Sink Connector 提交(Commit 543d2c5086)正式引入 Pulsar Sink 连接器,使 SeaTunnel 具备向 Pulsar 写入数据的能力,此前连接器只有 Source 方向。
  • 同版本的 [Feature][Json-format] support read format for pulsar(Commit 7d61ae93e7)虽然是 2.3.2 的条目,但意味着 JSON 格式读取能力正式打通,为后续 canal_json、avro、text 等格式矩阵奠定了格式层基础。
  • 2.3.6 版本:[Feature][Kafka] Support multi-table source read(Commit 60104602d1)将多表 Source 读取能力引入消息类连接器,Pulsar 随之获得多表读取支持。

1.2 性能与稳定性持续加固

  • 2.3.4 版本:[PulsarSource]Improve pulsar throughput performance(Commit 37461f4f3e)专项优化吞吐性能。
  • 2.3.1 版本密集修复了一批真实问题:PulsarSource consumer ack 异常(Commit 9725d675da)、topic-pattern 选项 bug(Commit aee2c580ea)、[Improve][Connector-v2][Pulsar] 设置 Pulsar 消费线程名称(Commit e567203f7d),以及统一 Pulsar Source 的异常体系(Commit 4fe9323419)。
  • 2.3.2 版本修复"无法持续消费消息"的 bug(Commit a6705cc5bf)。
  • 2.2.0-beta 版本修复 restore 时无法标记 #noMoreNewSplits 的问题(Commit 5ad69076b3),并把 Handover 组件下沉到 common 模块复用(Commit d94a874bcb)。

1.3 配置模型走向规范化

  • 2.3.0 版本:[Feature][Connector][pulsar] expose configurable options in Pulsar(Commit 200faa7c29)将大量 Pulsar 底层选项暴露为可配置项;随后修复 conditional options(Commit 0066affacf)与 OptionRule 全连接器一致性(Commit 226dc6a119)。
  • 2.2.0-beta 版本:[Improve][Connector-V2] Pulsar support user-defined schema(Commit 16cabe6a35)与 pulsar source options 文档(Commit 59ce8a2b32)。
  • 2.3.10 ~ 2.3.12 版本走向 API 与基础设施优化:restruct connector common options(Commit f3499a6eeb)、[Improve][API] Optimize the enumerator API semantics and reduce lock calls at the connector level(Commit 9212a77140,2.3.12)、[improve] pulsar options(Commit 26a2160c80,2.3.12)。
  • 2.3.11 版本:Feature][Checkpoint] 为 source/sink state 类补充 serialVersionUID 缺失检查脚本(Commit 4f5adeb1c7),保证状态类序列化兼容性——这正是 [PulsarSplitEnumeratorState 等 checkpoint 状态类的质量保障措施。

阅读建议:变更日志中每个条目都附有原始提交 ID,需要追查某个具体修复的完整 diff 时,可直接在仓库 git 历史中按该 ID 检索。

二、连接器能力总览:引擎支持与特性矩阵

根据 Pulsar 源连接器文档 与 Pulsar Sink 连接器文档,连接器在 Spark、Flink、SeaTunnel Zeta 三种引擎下均可运行。

Source 侧关键特性:

特性 支持状态
批读取(Batch) ✅
流读取(Streaming) ✅
精确一次(Exactly-Once) ✅
列投影(Column Projection) ❌
并行读取(Parallelism) ✅
用户自定义 Split ❌
多表读取(Multi-Table) ✅

Sink 侧关键特性:

特性 支持状态
精确一次(Exactly-Once) ✅
多表写入(Multi-Table) ✅
定时刷新 ❌

其中"多表读取/写入"正是 2.3.6 与 2.3.4 两次功能提交的直接产物,也是本连接器区别于传统单 topic 连接器的核心能力。

三、Pulsar Source 实战:参数全解与配置示例

3.1 Source 参数总表

以下参数表完整继承自官方文档,并结合 PulsarSourceOptions.java 源码中的默认值与校验逻辑逐项展开:

名称 类型 是否必填 默认值 描述
topic String 否 - 单表读取的 topic 名称,支持逗号分隔多个。只能与 topic-pattern、tables_configs 三选一
topic-pattern String 否 - 匹配 topic 名称的正则表达式。与 topic、tables_configs 三选一
table_path String 否 - 多表模式中单个配置项对应的逻辑表标识
tables_configs Array 否 - 多表读取配置,每个 item 可覆盖全局默认值。与 topic、topic-pattern 三选一
topic-discovery.interval Long 否 -1 发现新 topic 分区的间隔(毫秒),非正值禁用。仅 topic-pattern 模式下生效
subscription.name String 单表必填 / 多表必配 - 消费者订阅名
client.service-url String 是 - 客户端服务 URL,如 pulsar://localhost:6650
admin.service-url String 是 - 管理端 HTTP URL,如 http://localhost:8080
auth.plugin-class String 否 - 认证插件类名
auth.params String 否 - 认证插件参数
poll.timeout Integer 否 100 单次拉取最长等待时间(毫秒)
poll.interval Long 否 50 两次拉取间隔(毫秒)
poll.batch.size Integer 否 500 单次拉取最大消息数
cursor.startup.mode Enum 否 LATEST 启动位点:EARLIEST / LATEST / SUBSCRIPTION / TIMESTAMP
cursor.startup.timestamp Long 否 - TIMESTAMP 模式下的起始时间戳(毫秒)
cursor.reset.mode Enum SUBSCRIPTION 时必填 - 订阅位点重置策略:EARLIEST / LATEST
cursor.stop.mode Enum 否 NEVER 停止位点:NEVER(流式)/ LATEST(批式)/ TIMESTAMP(批式)
cursor.stop.timestamp Long 否 - TIMESTAMP 模式下的停止时间戳(毫秒)
schema Config 否 - 字段名与字段类型定义
format String 否 json json / canal_json / avro / text(text 仅单表)
field_delimiter String 否 , text 格式字段分隔符
common-options - 否 - Source 通用参数,见 Source Common Options

源码中的默认值与校验依据:以上默认值(topic-discovery.interval=-1、poll.timeout=100、poll.interval=50、poll.batch.size=500、cursor.startup.mode=LATEST、cursor.stop.mode=NEVER、format=json、field_delimiter=,)均直接定义在 PulsarSourceOptions.java 与 PulsarBaseOptions.java 中,可通过 Options.key(...).defaultValue(...) 声明直观核对。

3.2 三种 topic 指定方式的互斥约束

从 PulsarSourceFactory.optionRule() 可以看到,topic、topic-pattern、tables_configs 被声明为 exclusive(互斥)关系;同时 subscription.name 与 client.service-url、admin.service-url 都是非空校验的必填项。配置校验失败会抛出 CONFIG_VALIDATION_FAILED 错误,例如:

  • 单表模式必须配置 subscription.name(见 PulsarSourceFactory.validateSourceOptions);
  • cursor.startup.mode=TIMESTAMP 时必须同时配置 cursor.startup.timestamp;
  • cursor.startup.mode=SUBSCRIPTION 时必须配置 cursor.reset.mode;
  • cursor.stop.mode=TIMESTAMP 时必须配置 cursor.stop.timestamp。

这些条件校验逻辑统一由 PulsarMultiTableConfig.validateTableConfig 在 PulsarMultiTableConfig.java 中执行,并有 PulsarMultiTableConfigTest 单元测试逐项覆盖。

3.3 典型配置示例

示例一:单 Topic 批式读取(cursor.stop.mode = LATEST 界定批边界):

env {
  parallelism = 1
  job.mode = "BATCH"
}

source {
  Pulsar {
    topic = "topic-it"
    subscription.name = "seatunnel"
    client.service-url = "pulsar://localhost:6650"
    admin.service-url = "http://localhost:8080"
    cursor.startup.mode = "EARLIEST"
    cursor.stop.mode = "LATEST"
    format = json
    schema = {
      fields {
        c_string = string
        c_boolean = boolean
        c_int = int
        c_bigint = bigint
        c_double = double
        c_timestamp = timestamp
      }
    }
  }
}

示例二:流式持续读取(cursor.stop.mode = NEVER 表示无界,配合 checkpoint 实现容错):

env {
  parallelism = 2
  job.mode = "STREAMING"
  checkpoint.interval = 10000
}

source {
  Pulsar {
    topic = "persistent://public/default/events"
    subscription.name = "seatunnel-stream"
    client.service-url = "pulsar://localhost:6650"
    admin.service-url = "http://localhost:8080"
    cursor.startup.mode = "LATEST"
    cursor.stop.mode = "NEVER"
    format = json
    schema = {
      fields {
        event_id = string
        user_id = bigint
        payload = string
      }
    }
  }
}

示例三:text 格式(单表模式,用 field_delimiter 拆分字段):

source {
  Pulsar {
    topic = "text-events"
    subscription.name = "seatunnel-text-sub"
    client.service-url = "pulsar://localhost:6650"
    admin.service-url = "http://localhost:8080"
    cursor.startup.mode = "EARLIEST"
    cursor.stop.mode = "LATEST"
    format = text
    field_delimiter = "|"
    schema = {
      fields {
        id = int
        name = string
      }
    }
  }
}

示例四:canal_json 格式(对接 Canal 变更事件数据流):

source {
  Pulsar {
    topic = "test-cdc_mds"
    subscription.name = "seatunnel-cdc-sub"
    client.service-url = "pulsar://localhost:6650"
    admin.service-url = "http://localhost:8080"
    cursor.startup.mode = "EARLIEST"
    cursor.stop.mode = "LATEST"
    format = canal_json
    schema = {
      fields {
        id = int
        name = string
        description = string
        weight = string
      }
    }
  }
}

示例五:avro 格式(必须配置 schema,见 PulsarMultiTableConfig.validateAvroSchema 的强制校验):

env {
  parallelism = 1
  job.mode = "BATCH"
}

source {
  Pulsar {
    topic = "test_avro_topic"
    subscription.name = "seatunnel-avro"
    client.service-url = "pulsar://localhost:6650"
    admin.service-url = "http://localhost:8080"
    cursor.startup.mode = "EARLIEST"
    cursor.stop.mode = "LATEST"
    format = avro
    schema = {
      fields {
        id = bigint
        c_string = string
        c_int = int
        c_double = double
        c_timestamp = timestamp
      }
    }
  }
}

3.4 多表读取:tables_configs 详解

多表读取是 2.3.6 版本引入的核心能力(对应 Feature][Kafka] Support multi-table source read 提交),每个 item 可覆盖全局默认的 format、cursor 相关参数和 subscription.name。关键约束(源码级依据均在 [PulsarMultiTableConfig.java 中):

  1. 每个 item 必须且只能配置 topic 或 topic-pattern 之一,否则抛 "must specify exactly one of 'topic' or 'topic-pattern'";
  2. 使用 topic-pattern 时 table_path 必填;
  3. subscription.name 必须在全局或 item 内存在(item 内优先级更高,测试用例 验证了"无全局订阅名、仅 item 配置"的合法场景);
  4. 多表模式仅支持 JSON、CANAL_JSON、AVRO,TEXT 会被拒绝(见 validateFormat 与对应测试 shouldRejectTextFormatInTablesConfigs);
  5. 显式 topic 与任何 topic-pattern 不允许重叠(validateTopicOverlap);
  6. 多个 topic-pattern 同时匹配同一 topic 时,按 tables_configs 声明顺序选择第一个,因此更具体的 pattern 应放在更通用 pattern 之前;这一确定性路由由 MultiTablePartitionDiscoverer 在运行时解析,测试 shouldAllowOverlappingTopicPatternsForDeterministicRuntimeRouting 验证了重叠 pattern 不会导致作业失败。
  7. batch 模式限制:多表配置必须全部有界;只要配置了多于一张表且任意一张表使用 cursor.stop.mode = NEVER,整个 Source 即视为无界,在 batch 作业中会直接报错(见 PulsarSource.setJobContext)。

多表读取配置示例:

source {
  Pulsar {
    client.service-url = "pulsar://localhost:6650"
    admin.service-url = "http://localhost:8080"
    cursor.startup.mode = "EARLIEST"
    cursor.stop.mode = "LATEST"
    format = "json"

    tables_configs = [
      {
        table_path = "db.orders"
        topic = "persistent://public/default/orders"
        subscription.name = "sub-orders"
        schema = {
          fields {
            order_id = int
            amount = double
          }
        }
      },
      {
        table_path = "db.users"
        topic-pattern = "persistent://public/default/users-.*"
        subscription.name = "sub-users"
        schema = {
          fields {
            user_id = int
            name = string
          }
        }
      }
    ]
  }
}

源码归一化模型:PulsarMultiTableConfig.of() 将"无 tables_configs 的单表配置"也转换为只含一个 item 的 tableConfigs 列表(见 parseSingleTable),使下游运行时(枚举器、Reader、反序列化)共用同一套多表代码路径——这正是 2.3.12 中"enumerator API 语义优化"等重构得以低成本落地的基础。

3.5 topic-pattern 动态发现

组合使用 topic-pattern 与 topic-discovery.interval 可以自动发现新增 topic:

source {
  Pulsar {
    topic-pattern = "persistent://public/default/orders-.*"
    subscription.name = "seatunnel-orders"
    client.service-url = "pulsar://localhost:6650"
    admin.service-url = "http://localhost:8080"
    topic-discovery.interval = 30000
    cursor.startup.mode = "EARLIEST"
    cursor.stop.mode = "LATEST"
    format = json
    schema = {
      fields {
        order_id = bigint
        amount = double
      }
    }
  }
}

注意两个边界约束(源码依据见 PulsarSource.validateBoundedDiscovery):

  • topic-discovery.interval 仅在使用 topic-pattern 时生效;
  • 有界(BOUNDED)作业不支持动态分区发现:当作业有界且配置了正值的 discovery interval 时会抛 "Bounded streams do not support dynamic partition discovery.",即动态发现只适用于无界流式作业。

四、Pulsar Sink 实战:参数全解与配置示例

4.1 Sink 参数总表

参数定义位于 PulsarSinkOptions.java,完整参数如下:

名称 类型 是否必填 默认值 描述
topic String 否 - 目标 topic。单表必配;多表数据带表标识时可省略
client.service-url String 是 - 客户端服务地址,如 pulsar://localhost:6650
admin.service-url String 是 - 管理端 HTTP 地址,如 http://localhost:8080
auth.plugin-class String 否 - 认证插件类名
auth.params String 否 - 认证参数,与 auth.plugin-class 一起配置
format String 否 json 数据格式:json / text / avro
field_delimiter String 否 , text 格式字段分隔符
semantics Enum 否 AT_LEAST_ONCE NON / AT_LEAST_ONCE / EXACTLY_ONCE
transaction_timeout Int 否 600 Pulsar 事务超时(秒),仅 EXACTLY_ONCE 生效
pulsar.config Map 否 - 透传给 Pulsar producer 的额外参数
message.routing.mode Enum 否 RoundRobinPartition SinglePartition / RoundRobinPartition
partition_key_fields Array 否 - 用于生成消息 key 的字段
multi_table_sink_replica Int 否 1 多表写入时的写入器副本数
common-options Config 否 - Sink 通用参数,见 Sink Common Options

4.2 三种一致性语义的实现机制

semantics 枚举定义在 PulsarSemantics.java,三种语义在 PulsarSinkWriter 中分别落地:

  • NON:直接 sendAsync() 发送,不与 checkpoint 协调,不计数 pendingMessages。作业重启、重试或网络异常后数据可能重复或丢失。
  • AT_LEAST_ONCE(默认):每条消息 sendAsync() 后通过 pendingMessages 计数与 sendMessageException 记录异步发送结果;snapshotState 时调用 flushPendingMessages() 等待全部发送完成再触发 checkpoint,实现"至少一次"。
  • EXACTLY_ONCE:基于 Pulsar 事务两阶段提交(2PC)。流程如下:
    1. PulsarConfigUtil.createClient 在构建 client 时调用 enableTransaction(true) 开启事务能力(PulsarConfigUtil.java);
    2. Writer 启动即创建事务 this.transaction = createTransaction(),发送时把事务注入 TypedMessageBuilder(createTypedMessageBuilder);
    3. prepareCommit() 返回携带 TxnID 的 PulsarCommitInfo,snapshotState 记录 TxnID 并新建下一个事务;
    4. 引擎侧由 PulsarSinkCommitter 通过 TransactionCoordinatorClient.commit(txnID) 提交;失败路径调用 abort()。

两个重要前置条件(源码注释与文档一致):

  • Pulsar 集群必须开启事务能力;
  • transaction_timeout(默认 600 秒)必须大于 checkpoint 间隔,否则事务会在提交前被自动中止;
  • 事务模式下 producer 必须禁用 sendTimeout(producerBuilder.sendTimeout(0, TimeUnit.SECONDS)),这是 Pulsar 官方对事务消息生产者硬性要求,见 PulsarConfigUtil.createProducer。

精确一次写入配置示例:

env {
  parallelism = 1
  job.mode = "STREAMING"
  checkpoint.interval = 10000
}

sink {
  Pulsar {
    topic = "orders"
    client.service-url = "pulsar://localhost:6650"
    admin.service-url = "http://localhost:8080"
    semantics = "EXACTLY_ONCE"
    transaction_timeout = 600
    format = json
  }
}

4.3 多表写入与动态路由

Sink 实现了 SupportMultiTableSink 接口(PulsarSink.java)。核心路由逻辑在 PulsarSinkWriter.resolveTopic:

  • 优先使用 SeaTunnelRow.getTableId() 作为目标 topic(多表/整库同步场景);
  • 若行数据无表标识,则回退使用全局 topic;
  • 两者都没有时抛出 Topic must be configured when SeaTunnelRow.getTableId() is null。

每个 topic 对应独立的 Producer,缓存在 producerMap 中按需懒创建。配置示例:

sink {
  Pulsar {
    client.service-url = "pulsar://localhost:6650"
    admin.service-url = "http://localhost:8080"
    multi_table_sink_replica = 2
    format = json
  }
}

4.4 消息 Key、路由模式与 producer 透传参数

partition_key_fields:指定用哪些字段生成消息 key。实现见 PulsarSinkWriter.createKeySerializationSchema:所选字段必须存在于上游行类型中,否则抛 "Partition key field not found";生成的 key 为 JSON 形式,例如上游有 name、age 字段,配置 partition_key_fields = ["name"] 会生成 {"name":"Jack"}。

message.routing.mode(对应 Pulsar 客户端 MessageRoutingMode 枚举):

  • SinglePartition:无 key 时随机选一个分区写入全部消息;有 key 时按 key 哈希选分区。
  • RoundRobinPartition(默认):无 key 时轮询写各分区;注意 Pulsar 的轮询发生在批处理延迟边界上,并非逐条轮询。

配置示例:

sink {
  Pulsar {
    topic = "orders"
    client.service-url = "pulsar://localhost:6650"
    admin.service-url = "http://localhost:8080"
    partition_key_fields = ["order_id"]
    message.routing.mode = "SinglePartition"
    format = json
  }
}

pulsar.config:通过 Map 形式透传 producer 属性(producerBuilder.properties(...),见 PulsarConfigUtil.createProducer),可用于调整超时、批大小、压缩等:

sink {
  Pulsar {
    topic = "topic_test"
    client.service-url = "pulsar://localhost:6650"
    admin.service-url = "http://localhost:8080"
    format = json
    pulsar.config = {
      sendTimeoutMs = 30000
      batchingMaxMessages = 1000
    }
  }
}

4.5 完整写入示例(FakeSource → Pulsar)

env {
  parallelism = 1
  job.mode = "BATCH"
}

source {
  FakeSource {
    plugin_output = "fake"
    row.num = 10
    schema = {
      fields {
        c_string = string
        c_int = int
        c_bigint = bigint
        c_double = double
        c_timestamp = timestamp
      }
    }
  }
}

sink {
  Pulsar {
    topic = "topic_test"
    client.service-url = "pulsar://localhost:6650"
    admin.service-url = "http://localhost:8080"
    format = json
    pulsar.config = {
      sendTimeoutMs = 30000
    }
  }
}

五、源码级原理:连接器运行时解剖

5.1 整体架构:Source 三组件协作模型

Pulsar Source 遵循 SeaTunnel 的 SeaTunnelSource 三组件模型,核心类关系如下:

  • PulsarSource(源码):入口类,实现 SupportParallelism,负责构建三类配置(Admin/Client/Consumer)与反序列化 schema,并分发创建 Reader 与 Enumerator。getBoundedness() 依据各表的 StopCursor 是否为 NeverStopCursor 动态判定有界/无界。
  • PulsarSplitEnumerator(源码):通过 PulsarDiscoverer 发现 topic 分区,把每个 TopicPartition 包装为 PulsarPartitionSplit 推送给对应 reader。关键逻辑:
    • 分区均匀分配:getSplitOwner 用 HashUtils.bucketIndex(topic.hashCode() * 31, numReaders) 计算起点,再按分区号递增取模,保证同一 topic 的连续分区散落到不同 reader;
    • 动态发现:open() 中当 partitionDiscoveryIntervalMs > 0 时启动名为 pulsar-split-discovery-executor 的守护线程,周期性调用 discoverySplits()(对应 topic-discovery.interval);
    • 状态快照:snapshotState 记录已分配分区集合为 PulsarSplitEnumeratorState,restoreEnumerator 时从 checkpoint 恢复——这正是 2.2.0-beta 修复 "restore 时无法标记 noMoreNewSplits" 与 2.3.12 优化 enumerator API/减少锁调用的落点。
  • PulsarSourceReader(源码):为每个 split 创建独立的 PulsarSplitReaderThread(消费线程命名规则为 "Pulsar Source Data Consumer + 分区号",正是 2.3.1 版本 "Set the name of the pulsar consumption thread" 提交的产物),线程通过 Handover 队列把消息交给 Reader 的 pollNext() 反序列化并下发。

5.2 游标(Cursor)体系:位点控制的设计

游标是 Pulsar Source 位点控制的核心抽象,按"启动/停止"分为两族,全部位于 source/enumerator/cursor/ 包下:

启动游标(StartCursor)——对应 cursor.startup.mode:

枚举值 实现类 语义
EARLIEST MessageIdStartCursor(earliest 构造) 从最早未消费位点开始
LATEST MessageIdStartCursor(latest 构造) 从最新位点开始
SUBSCRIPTION SubscriptionStartCursor 从指定订阅的已提交位点开始,需配合 cursor.reset.mode
TIMESTAMP TimestampStartCursor 从指定毫秒时间戳开始

停止游标(StopCursor)——对应 cursor.stop.mode:

枚举值 实现类 语义
NEVER NeverStopCursor 无界流式
LATEST LatestMessageStopCursor 有界,读到最新消息即止;prepare(pulsarAdmin, partition) 通过 admin API 探测分区当前最新 messageId
TIMESTAMP TimestampStopCursor 有界,读到指定时间戳即止

5.3 精确一次(Exactly-Once)消费链路

Source 侧精确一次依赖 checkpoint 与 Pulsar cursor(订阅位点)协同:

  1. pollNext() 在 checkpoint 锁内更新 split 的 latestConsumedId(PulsarSourceReader.pollNext);
  2. snapshotState(checkpointId) 把各 split 最新消费 MessageId 放入 pendingCursorsToCommit;
  3. checkpoint 完成时 notifyCheckpointComplete 取出该批 cursor 调用 committingCursor,由 PulsarSplitReaderThread 向 Pulsar 提交消费位点(对应 2.3.1 修复的 "consumer ack 异常" 提交)。

故障恢复:Reader 从 PulsarPartitionSplit 快照恢复 split 状态与位点;Enumerator 从 PulsarSplitEnumeratorState 恢复已分配分区。两份状态类均实现了 Serializable 并带 serialVersionUID,这正是 2.3.11 新增 serialVersionUID 缺失检查脚本的原因。

5.4 认证与类加载安全

  • 认证:auth.plugin-class + auth.params 通过 AuthenticationFactory.create(...) 创建 Pulsar 认证对象,未配置时使用 AuthenticationDisabled.INSTANCE(PulsarConfigUtil.createAuthentication)。TLS 场景下 client.service-url 使用 pulsar+ssl:// 协议。文档 FAQ 中示例认证插件类为 org.apache.pulsar.client.impl.auth.AuthenticationToken。
  • 类加载安全:连接器关闭 client/consumer/producer/admin 时,Pulsar 及其 shaded Netty/Jersey 栈可能从线程上下文类加载器懒解析实现类,因此 PulsarConfigUtil.runWithConnectorClassLoader 会在关闭动作期间临时切换回连接器类加载器,避免在引擎线程中发生 NoClassDefFoundError。

六、测试与验证体系

仓库为该连接器提供了完整的单元测试与 e2e 测试,可作为理解行为与复现问题的参考:

单元测试(seatunnel-connectors-v2/connector-pulsar/src/test/):

端到端测试(seatunnel-e2e/seatunnel-connector-v2-e2e/connector-pulsar-e2e/,基于 Testcontainers 拉起真实 Pulsar 容器):

  • PulsarMultiTableIT.java:向两个 topic 生产数据后运行多表→Assert 作业验证读取;
  • PulsarBatchIT:批式读写;PulsarFormatIT:多格式验证;CanalToPulsarIT:Canal 变更事件链路;PulsarSinkIT:Sink 写入。

七、常见问题(FAQ)

Q1:如何处理分区 Topic 与动态分区发现?

订阅分区 Topic 或使用 topic-pattern 时,SeaTunnel 通过 PulsarAdmin 自动感知分区信息,由 PulsarSplitEnumerator 将分区作为 split 均匀分配给各并发 reader;topic-discovery.interval 控制新分区探测频率。注意有界作业不支持动态发现。

Q2:支持哪些消费位点恢复与订阅模式?

cursor.startup.mode 支持 EARLIEST(最早未消费位点)、LATEST(最新位点)、SUBSCRIPTION(订阅已提交位点,需配 cursor.reset.mode)、TIMESTAMP(指定毫秒时间戳)。消费者在 checkpoint 时同步保存 MessageId,故障时可精准回溯(见 5.3 节)。

Q3:如何连接开启安全认证的 Pulsar 集群?

通过 auth.plugin-class 声明认证插件实现类(如 org.apache.pulsar.client.impl.auth.AuthenticationToken),并在 auth.params 传入 Token 等凭据;若启用 TLS,client.service-url 需使用 pulsar+ssl:// 协议。

Q4:Sink 如何保证精确一次?

semantics = "EXACTLY_ONCE" 时基于 Pulsar 事务 2PC:Writer 侧事务写入、Committer 侧通过 TransactionCoordinatorClient.commit(txnID) 协同提交。前置条件:集群开启事务、transaction_timeout 大于 checkpoint 间隔。

Q5:Sink 支持动态多表路由吗?

支持。多表/整库同步时若未配置全局 topic,PulsarSinkWriter.resolveTopic 会按每行数据的表标识路由到同名 topic;数据无表标识且未配 topic 时任务报配置错误。

Q6:Sink 支持哪些序列化格式?

format 支持 json(默认)、text(可配 field_delimiter)、avro。avro 格式下 schema 由上游行类型自动推导,无需在 Sink 侧额外配置 schema。

八、结语

从 2.2.0-beta 的"基础可用",到 2.3.4 补齐 Sink、2.3.6 引入多表读取、2.3.12 完成 enumerator 语义优化与选项重构,Apache SeaTunnel 的 Pulsar 连接器已经形成一套覆盖批/流、单表/多表、至少一次/精确一次的完整能力矩阵。本文以 connector-pulsar.md 变更日志 为时间轴,串联官方Source/Sink 文档与 connector-pulsar 模块源码,给出了可直接复用的全部配置示例与底层实现依据。在实际使用中,建议优先参考 PulsarSourceOptions.java、PulsarSinkOptions.java 中的默认值与描述信息,并结合本仓库 e2e 测试用例验证连通性后再上线生产环境。

登录后查看全文
seatunnel