版本: v1.0 修改日期: 2026-05-29 文档定位：本手册面向项目经理，只讲”该做什么、向厂家要什么、怎么判断资料齐了”。技术细节由技术团队负责。
完成后你将能够：向厂家收齐全部 Kafka 对接资料，通过提资入口提交，技术团队即可开始配置。
阅读路径：确认适用场景（第 1 节）→ 收资料（第 3 节）→ 自查提交（第 6 节）。
1 确认是否走本手册
1.1 适用场景
满足以下任一条件，走本手册：
- 大型工厂、智慧城市、车联网等数据量极大的场景
- 数据频率高，每秒几千甚至几万条消息
- 对方答复”我们用 Kafka 推数据""我们的消息总线是 Kafka”
- 客户已有大数据平台（如阿里云 EMR、华为云 MRS、Cloudera 等）
1.2 不走本手册的情况
| 现场情况 | 应走方式 |
|---|---|
| 设备主动推送、数据量小 | MQTT 对接 |
| 软件系统间偶尔调用接口 | HTTP 对接 |
| 直接采集硬件设备 | S7 / Modbus / OPC UA 对接 |
2 术语速览
| 术语 | 通俗解释 | 类比 |
|---|---|---|
| Kafka | 一条超大型”消息传送带”系统 | 工业流水线 |
| Broker | Kafka 集群中的单个服务器；Kafka 通常由多台 Broker 组成 | 流水线上的工人 |
| Bootstrap Servers | 集群入口地址，通常是多个 broker 地址用逗号分隔 | 多个总机号 |
| Topic | 传送带上的”通道”，不同通道传不同类型数据 | 频道 |
| SASL / SSL | Kafka 的安全机制（SASL=登录验证；SSL=加密传输） | 门禁卡 + 加密通话 |
3 资料清单（可直接发给厂家）
📌 提交命名格式：项目名-Kafka-接口清单
以下资料均为必填，缺一不可：
- Bootstrap Servers（集群入口，多地址逗号分隔）
- 安全机制（PLAINTEXT / SASL_PLAINTEXT / SSL / SASL_SSL）
- 认证凭证（用户名密码 / 证书）——有认证时必填
- Topic 名称
- 至少 1 条完整消息示例
- 完整点表（含字段名、所属 Topic、单位、读写属性）
4 操作步骤
步骤 1：确认数据流向
向厂家明确确认数据流向是 厂家 Kafka → viSCADA（我方作为消费者）。本手册不覆盖反向场景，如有反向需求请联系技术团队。
步骤 2：要求提供所有 Broker 地址
Kafka 集群通常由 3 台或更多 Broker 组成。务必让厂家提供所有 Broker 的地址，用逗号分隔，例如：
broker1.example.com:9092,broker2.example.com:9092,broker3.example.com:9092⚠️ 不接受只给一个地址——单点故障时会直接断连。
步骤 3：明确认证信息三要素
不接受”有账号”这种含糊回复。必须明确：
- 安全机制：PLAINTEXT（无）/ SASL_PLAINTEXT（只有登录）/ SSL（只有加密）/ SASL_SSL（全开）
- SASL 机制类型（若启用 SASL）：PLAIN / SCRAM-SHA-256 / SCRAM-SHA-512 / GSSAPI
- 实际凭证：用户名 + 密码 或 证书文件 + 密钥
步骤 4：索取真实消息示例
要求厂家提供至少 1 条真实的完整消息样本（JSON 格式）。
⚠️ 不接受”等联调时抓包看”——抓不到包、字段对不上是常见问题。
5 资料收集表
| 分类 | 字段 | 是否必填 | 填写要求 |
|---|---|---|---|
| 集群 | Bootstrap Servers | 必填 | 多地址逗号分隔，如 broker1:9092,broker2:9092 |
| 安全 | 安全机制 | 必填 | PLAINTEXT / SASL_PLAINTEXT / SSL / SASL_SSL |
| 安全 | SASL 机制类型 | 启用 SASL 必填 | PLAIN / SCRAM-SHA-256 / SCRAM-SHA-512 / GSSAPI |
| 安全 | 用户名 / 密码 | SASL 时必填 | 建议为对接专用账号 |
| 安全 | 证书 / 密钥 | SSL 时必填 | 含 ca.crt、client.crt、client.key（如适用） |
| Topic | Topic 名称 | 必填 | 大小写敏感，逐字抄写 |
| 消息 | 完整消息示例 | 必填 | 至少 1 条真实样本 |
| 点表 | 完整点表 | 必填 | 优先提供可编辑 Excel，其他格式可接受，但内容须清晰准确 |
6 提交前自查清单
- 已获取 Bootstrap Servers（多地址，逗号分隔）
- 已确认安全机制（PLAINTEXT / SASL / SSL / SASL_SSL）
- SASL 已确认机制类型与实际凭证
- SSL 已获取证书文件
- 已获取 Topic 名称
- 已获取至少 1 条完整消息示例
- 已获取完整点表
- 已确认 网络放通：viSCADA → 厂家 Kafka 集群（所有 broker 地址都通）
- 已通过 统一提资入口 提交资料
- 已在泛微系统发起技术服务流程
7 常见问题与处置
⚠️ 缺少完整消息示例
- 后果：没有真实样本，字段无法落地配置，技术团队无法解析消息结构。
- 处置：要求厂家提供至少 1 条完整 JSON 消息，不接受”联调时抓包看”。
⚠️ 只说”有认证”，不说机制
- 后果：不知道是 SASL_PLAINTEXT 还是 SASL_SSL，不知道是 PLAIN 还是 SCRAM-SHA-256，连接配置无从下手，必然失败。
- 处置：要求厂家明确三要素：安全机制 + SASL 机制类型 + 凭证，缺一不可。
⚠️ Bootstrap Servers 只给一个地址
- 后果：Kafka 是集群，单地址等于单点——那台机器一挂，我方就断连，且无法自动切换到其他 broker。
- 处置：要求提供全部 broker 地址，逗号分隔。
⚠️ Kafka 内网地址在外网无法解析
- 后果：厂家内部用
broker1.internal:9092能连，但我方在外网连不上——因为这个地址只在厂家内网解析。- 处置：提资时确认：“贵方提供的 broker 地址在我方网络环境下能否解析？“必要时要求厂家提供外网映射地址。
⚠️ 网络仅放通了部分 broker
- 后果：客户网络管理员只放通了第一个 broker，其他 broker 不通，会导致连接初步成功但消费时报错。
- 处置：必须放通所有 broker 地址，逐一测试连通性。
8 遇到问题的三步处置
- 先排查：网络部分未通、认证机制不匹配、消息格式无法解码——三类问题覆盖 80% 的卡点。
- 对照清单：参考第 3 节资料清单，逐项确认是否到位。
- 同步技术团队：将已收集资料、网络测试结果、连接报错日志、当前卡点整理后一并发送，避免反复沟通。
9 关联资料
Last updated on