用 Kafka 打印标签：让流成为触发器

流已经存在

你的 ERP 或 MES 已经向 Kafka 发布订单事件、拣货消息和序列号。通常这个流止步于屏幕，由一个人按下打印。

Data Streaming 选项卡让流成为触发器：订阅一个 topic，每条消息就会用标签设计渲染并发送到打印机。没有中间件、没有轮询作业、没有打印服务器。

两种部署：

• 云 - 平台自己消费 topic（Confluent Cloud、MSK，任何可通过互联网访问的 broker）。
• 本地部署 - 你网络内的 broker，由 zplCloud CLI agent 消费。Broker 凭证永远不会离开你的网络。

订阅绑定什么

四样东西：一个 topic、一个标签设计、一台打印机，以及在云模式下还有 broker 连接配置。对每条消息，平台：

1. 将值解析为 JSON，把对象键作为字段 binding，

2. 用与设计器相同的引擎渲染设计，

3. 将生成的 ZPL 发送到打印机（Weblink，或 CLI agent 上经 TCP 9100 / USB 的远程打印机）。

如果值不是 JSON，整段文本绑定到 $message - 对单字段标签足够。

连接配置

配置是一个 键=值; 字符串，静态存储时以 AES 加密：

BootstrapServers=pkc-xxxxx.eu-central-1.aws.confluent.cloud:9092;
GroupId=zplCloudPrinter;
SecurityProtocol=SaslSsl;SaslMechanism=Plain;
SaslUsername=<api-key>;SaslPassword=<api-secret>

当你未设置时应用的默认值：

AutoOffsetReset=Earliest 是重放 topic 的刻意选择。只有当你确实需要时才设置：对于有历史的 topic，首次启动会打印全部内容。

支持 SCRAM（SaslMechanism=ScramSha256 / ScramSha512）和自定义 CA（SslCaLocation=…）。未知键原样透传给消费者配置。

对于本地 broker，改为在 agent 上注册：

zplcloud proxy --agent "Lager" \
  --kafka LOKAL="BootstrapServers=10.0.0.10:9092;GroupId=zplCloudConsumer"

agent 报告 Kafka brokers: LOKAL。当订阅需要时，平台要求 agent 运行消费者 - broker 保持对互联网不可达。

交付语义，精确说明

这是大多数流式集成含糊其辞的部分，所以这里给出精确实现：

• 消费者以 30 秒超时轮询。
• 收到消息时：渲染、打印，然后仅当打印成功才 Commit(msg)。
• 如果打印失败，offset 不提交，消费者停止。 订阅切换到断开状态并显示 Print failed: <error>。它不会跳过消息，也不会在重试循环中空转。
• 因为默认是 AutoOffsetReset=Latest，失败后重启不会自动重新投递失败消息。如果希望在重启时重试失败消息，请在配置中放 AutoOffsetReset=Earliest - 那么未提交的 offset 会被重新拾取。

理由是：一张没有打印出来的标签是一个必须有人看到的操作事实。静默推进会丢失一张实体标签；永远重试会卡死分区。停止使它可见，并让 offset 留在原处。

ConsumeException - broker 不可达、认证被拒、topic 消失 - 处理方式不同。那不是打印失败，所以消费者以从 5 秒起、上限 60 秒的指数退避重试，订阅上会显示最后一次 broker 错误。

空闲保活

如果 60 秒内没有消息到达，平台会向目标打印机发送唤醒命令。Link-OS 打印机会进入低功耗状态；没有保活，安静期后的第一条消息在打印前要付出唤醒延迟。保活只碰打印机，不碰 topic - 不会消费或提交任何 offset。

创建订阅

按开始。订阅随后显示实时状态 - 已连接、最后消息时间、最后 offset、消息计数 - 以及记录近期消息值及其打印结果的日志。

消息形态

{ "ean": "40063813", "qty": 2, "dest": "Ramp 4" }

键按名称映射到 binding。没有 binding 使用的键被忽略；没有匹配键的 binding 渲染为空。在上线前用真实消息设计标签 - 设计器中的 测试数据 接受粘贴的 JSON。

重启行为

平台重启时活跃订阅会重启，本地订阅在 CLI agent 重连时重启。夜间维护窗口或断线不需要任何人再按开始 - 除了上述例外：被打印失败停止的订阅会保持停止，直到你修好打印机并启动它。

套餐

数据流按量计费。Starter 将其包含用于测试，上限为每月 100 张流式标签。Pro 包含 2 个流式端点（Kafka / Azure Service Bus）；每个额外端点每月 € 10。参见定价页面。

相关

• zplCloud CLI - agent、brokers、服务安装
• 作为 Docker 容器的 Agent
• Cloud Integration / Connections