Kafka Trigger 触发器节点
Kafka{:target=_blank .external-link} 是一个开源的分布式事件流平台,可用于高性能数据管道、流分析、数据集成和关键任务应用程序。
提示
Credentials 凭证
您可以在Kafka 凭据文档找到该节点的身份验证信息。
提示
Schema Registry 模式注册表
要使用经过身份验证的 Confluent Schema Registry(例如 Confluent Cloud)解码消息,请在节点中启用 Use Schema Registry 使用 Schema Registry 并添加 Schema Registry 凭据。
警告
版本 1 的消息压缩
Kafka Trigger 版本 1 可以消费未压缩的消息和使用 GZIP 压缩的消息。它无法解码使用 LZ4、Snappy 或 Zstd(Confluent 和 JVM 生产者的常见默认设置)压缩的消息:消费此类主题会失败,并出现不支持压缩格式的错误。要消费该主题,请将生产者配置为使用 GZIP 或不压缩,或切换到可解码全部四种格式的 Kafka Trigger 版本 2。
提示
Examples and templates 示例和模板
有关帮助您入门的使用示例和模板,请参阅 n8n 的 Kafka 触发器集成 页面。
Kafka Trigger 版本 2
提示
Feature availability 功能可用性
n8n 2.45.0 起默认使用 Kafka Trigger 版本 2:从节点面板添加的触发器使用版本 2。从 n8n 2.36.0 开始,选择启用的工作流即可使用版本 2。现有工作流会继续使用创建时的版本,直到你手动切换。
版本 2 在全新且持续维护的 Kafka 引擎上运行。该触发器保留版本 1 的字段和凭据,但有以下差异:
- 它可解码使用 GZIP、LZ4、Snappy 或 Zstd 压缩的消息。版本 1 只能处理未压缩和 GZIP 消息。
- 它会在发布工作流时检查主题和消费者组。如果通过精确名称指定的主题不存在,或 broker 拒绝该消费者组,发布将失败并报错,而不是让触发器不消费任何消息。
- 手动执行(选择 Listen for test event 监听测试事件时)会加入名为
<group-id>-n8n-manual-<uuid>的临时消费者组,即使开启 Read Messages From Beginning 从开头读取消息,也绝不会重放主题。它们不再从已发布工作流中抢占消息。对于使用访问控制列表(ACL)的集群,请为<group-id>-n8n-manual-授予前缀组 ACL;也可跳过测试,改为发布工作流并检查其执行。 - 如果 Schema Registry 无法解码某条消息,版本 2 会保留其未读状态,并在 Retry Delay on Error 出错时的重试延迟后重试,因此在注册表不可用时不会丢失消息。版本 1 会将原始消息传递给工作流并提交 offset。
Kafka Trigger 版本 2 中删除或更改的选项
版本 2 不提供版本 1 的以下三个选项:
- Auto Commit Threshold 自动提交阈值:新引擎没有对应设置。
- Each Batch Auto Resolve 每批次自动解析:该选项会将没有任何执行处理的消息标记为已读。
- Allow Topic Creation 允许创建主题:该选项在版本 1 中也不起作用。
其他所有选项保留原名称和默认值,其中三个选项的行为有所不同:
- Rebalance Timeout 重新平衡超时现在设置单个批次可以处理多长时间,之后消费者组会移除该消费者。只有工作流未设置自身的执行超时时,n8n 才会使用此值;工作流超时优先。
- 当 Heartbeat Interval 心跳间隔超过 Session Timeout 会话超时的三分之一时,n8n 会自动降低心跳间隔,以防 broker 移除消费者。
- Retry Delay on Error 出错时的重试延迟还会控制 Schema Registry 无法解码的消息的重试节奏。版本 1 仅在 offset 解析失败后使用此选项。
将工作流切换到 Kafka Trigger 版本 2
从节点面板添加的触发器已是版本 2。编辑器没有版本选择器,因此如需迁移现有的版本 1 工作流:
- 下载工作流(Workflow menu > Download),并保持该文件不变:它将作为回滚点。
- 在该文件的副本中,将 Kafka Trigger 节点的版本设置为
"typeVersion": 2,并按照选择消费者组 ID 中的说明设置消费者组 ID。 - 将副本导入新的空工作流(Workflow menu > Import from File)。导入会将节点添加到画布上已有节点旁边,因此不要导入到仍包含版本 1 触发器的工作流。
- 如果导入清除了 Kafka 凭据,请在节点上重新选择。如果使用相同的组 ID 迁移,请先取消发布版本 1 工作流,然后发布版本 2 工作流。
有关菜单的详细信息,请参阅导出和导入工作流。
n8n 会在每次构建时检查版本 2 的原生组件是否能在官方 n8n Docker 镜像中加载,涉及 amd64 和 arm64 两种架构。不会检查 npm 或自定义镜像等其他安装方式。
选择消费者组 ID
版本 1 和版本 2 使用不同的客户端库,无法共同组成消费者组,因此请根据目标设置消费者组 ID:
- 如需同时运行两个触发器,请为版本 2 触发器指定独立的消费者组 ID。可使用此方式对比它们,或在版本 1 继续工作时试用版本 2。此时两者完全独立:各自接收主题中的每条消息,保留自己的读取位置,启动新触发器不会干扰已运行的触发器。
- 如需从版本 1 迁移到版本 2,请保留相同的组 ID,但每次只运行一个触发器:先取消发布版本 1 工作流,再发布版本 2 工作流。它会从旧触发器停止的位置恢复,因此不会跳过任何消息,包括两个触发器都未运行时到达的消息。只有在取消发布版本 1 时执行仍在运行的消息可能重新运行。此时不要指定新组 ID:新组没有保存的位置,因此它会根据 Read Messages From Beginning 从开头读取消息设置跳过积压消息或重放整个主题。
- 不要使用相同的组 ID 发布两个触发器。它们根本无法形成消费者组。无论如何,现有触发器都会继续工作:配置错误的后果是新触发器绝不触发,而不是生产工作流中断。后发布的版本 2 触发器会因显式错误而发布失败。如果后发布版本 1 触发器,broker 会拒绝它,在取消发布两者之一前它不会收到任何消息。请在发布前设置组 ID,而不是依赖该错误。
回滚到 Kafka Trigger 版本 1.3
回滚不会丢失读取位置:取消发布版本 2 工作流时,其消费者会离开组,后台不会继续运行任何内容。只要 broker 仍保留空组的 offset(默认七天),已提交的读取位置就会保留在 broker 上并与组 ID 关联。
编辑器没有用于更改现有节点版本的控件。如果原始版本 1 工作流仍存在,请取消发布版本 2 工作流,然后重新发布原工作流。否则,请使用以下任一方法。如果仍有切换步骤 1 中导出的文件,请优先使用第一种方法。对于从版本 2 开始且没有版本 1 导出文件的工作流,请使用第二种方法。
- 恢复导出文件:取消发布版本 2 工作流。然后,将切换步骤 1 中的文件导入新的空工作流(Workflow menu > Import from File);如果计划保留了历史版本,也可从工作流历史记录恢复上一版。如果导入清除了 Kafka 凭据,请重新选择,然后发布恢复的工作流。
- 编辑工作流 JSON:取消发布版本 2 工作流并下载(Workflow menu > Download)。在该文件的副本中,将 Kafka Trigger 节点设置为
"typeVersion": 1.3并保留相同的消费者组 ID,然后将副本导入新的空工作流。如果导入清除了 Kafka 凭据,请重新选择,然后发布恢复的工作流。从节点面板添加的触发器是版本 2,因此添加新触发器无法回滚。
消费者组之后的行为取决于你之前如何运行版本 2:
- 如果使用不同的组 ID 并行运行两个触发器,则无需使用上述任一方法:取消发布或删除版本 2 工作流即可。原触发器从未受到影响。
- 如果使用共享组 ID 进行迁移,回滚的触发器会重新加入该组,并从已提交的位置恢复,包括切换期间到达的消息。
- 如果使用新组 ID 切换,回滚的触发器会再次传递版本 2 已处理的消息。版本 2 运行期间,旧组的读取位置没有移动。