版本: v1.0 修改日期: 2026-05-29 完成后你将能做到：30 秒锁定对接方式 → 向厂家收齐资料 → 提交提资，技术团队即可开始配置。

阅读路径：锁定方式（第 1 节）→ 进入对应协议章节收资料 → 提交（第 11 章）。

1 30 秒锁定对接方式

向厂家提出这个问题： “贵方用什么方式向我方传数据？”

根据对方回复选择章节：

1. 西门子 PLC → 第 4 章 S7 对接
2. 电表、温控器、变频器、通用 PLC → 第 5 章 Modbus 对接
3. 对方提供接口文档或 API → 第 6 章 HTTP 接口对接
4. 设备主动向平台推送消息 → 第 7 章 MQTT 消息对接
5. 大批量消息队列（含 Topic、Broker 等概念） → 第 8 章 Kafka 对接
6. 直连对方数据库读取数据 → 第 9 章 数据库对接
7. 工业网关、opc.tcp:// 开头的接口 → 第 10 章 OPC UA 对接

对方说不清楚时：要求厂家书面说明”所支持的通讯协议名称”，不接受”能对接""有接口”等模糊表述。

2 快速索引

ℹ️ 对接周期参考：网络打通、资料齐全、账号开通后，HTTP / MQTT / Kafka / 数据库通常 1–3 个工作日完成。延期的主要原因：网络未放通、点表缺失、账号权限不足。

3 对接前必做准备

3.1 五项前置工作

1. 确认对接方式：要求厂家书面说明协议名称，不接受”能对接""有接口”等笼统表述。
2. 收齐资料：协议文档或接口说明 + 完整点表（Excel）。
3. 明确开发边界（HTTP / MQTT）：确认由哪方按谁的协议开发。
4. 验证网络连通性：我方能访问对方 IP 和端口后，再推进后续工作。
5. 资料齐全后再提交：避免技术团队因资料不全而停工。

3.2 通用必交资料

3.3 模板与规范链接

3.4 提交前核对

• 已明确对接方式并进入正确章节
• 已获取协议文档或接口说明
• 已获取完整点表（Excel）
• 已确认访问地址、端口、账号、密码
• 已完成网络连通性验证
• 已通过统一提资入口 提交资料
• 已在泛微系统发起技术服务流程

3.5 遇到问题的三步处置

1. 先排查：网络未通、资料未齐、账号未开——三类问题覆盖 80% 的卡点。
2. 对照当前协议章节的资料清单，逐项补齐。
3. 将已收集资料、网络测试结果、当前卡点一并发给相关同事，避免重复沟通。

4 S7 对接（西门子 PLC）

📎 详细手册：viSCADA S7 对接配置参数清单

4.1 你需要向厂家要什么

请协助提供以下资料（均为必填）：

• PLC 型号（如 S7-1200、S7-1500）
• IP 地址（默认端口 102）
• 机架号与槽位号
• 数据点位地址清单（含地址与数据类型）
• 读写属性（逐点注明”只读”或”读写”）
• 完整点表（Excel）

📎 模板：【附件】s7-device-address-mapping.xlsx　📌 命名：项目名-S7-采集表

4.2 操作步骤

1. 确认设备是西门子 PLC，核实型号（S7-300 / 400 / 1200 / 1500 / 200 Smart）。
2. 发送 S7 模板给厂家，要求填写完整，不接受”后续补充”。
3. 重点核对机架号与槽位号，缺失将直接导致无法连接。
4. 涉及写入控制时，要求厂家书面说明读写点的限制条件。

4.3 提资前核对

• 已确认 PLC 型号、IP、机架号、槽位号
• 已获取完整地址点表（含数据类型、读写属性）
• 已明确读写点及写入限制

5 Modbus 对接

📎 详细手册：viSCADA Modbus 对接配置参数清单

5.1 你需要向厂家要什么

📎 模板：【附件】modbus-device-register-mapping.xlsx　📌 命名：项目名-Modbus-采集表

💡 TCP 还是 RTU？ viSCADA 统一通过网络（TCP）连接设备。TCP 设备直接填 IP 和端口；RS-485（RTU）设备须先安装串口服务器，viSCADA 填写串口服务器的 IP 和端口，串口服务器安装由现场工程师负责。

5.2 操作步骤

1. 发送 Modbus 模板给厂家，要求填写，不通过电话或微信口述。
2. 确认协议类型：TCP 还是 RTU，两者所需参数不同。
3. 要求厂家逐点标注”只读”或”读写”；读写点须注明功能码。
4. 收到点表后核查五项：地址、名称、数据类型、单位、读写属性。

5.3 提资前核对

• 已确认协议类型（TCP / RTU）及连接地址
• 已获取从站地址（确认同线路无重复）及完整点表
• 已明确读写点的功能码

6 HTTP 接口对接

📎 详细手册：viSCADA HTTP 接口对接配置参数清单

6.1 先做一件事：确认谁来开发

HTTP 对接有两种模式，必须提前书面确认，不得含糊：

⚠️ 模式确定后不得随意变更。

6.2 你需要向厂家要什么

📌 命名：项目名-HTTP-接口清单

6.3 操作步骤

1. 由项目经理向客户或厂家确认开发边界（模式 A 或 B），通过邮件留痕。
2. 模式 B：发送 viSCADA 南向 HTTP 规范 给对方，后续开发由对方承担。
3. 模式 A：获取带版本号的正式接口文档，不接受口头描述或截图。
4. 要求厂家书面说明鉴权四要素：类型、传递位置、字段格式、Token 规则。
5. 分别索取测试环境与生产环境的地址和凭证。

6.4 提资前核对

• 已书面确认开发边界（模式 A 或 B）
• 模式 A 已获取带版本号的正式接口文档；模式 B 已发送 viSCADA 南向 HTTP 规范
• 已明确鉴权四要素（类型、传递位置、字段格式、Token 规则）
• 已获取完整点表及测试与生产环境的地址和凭证

7 MQTT 消息对接

📎 详细手册：viSCADA MQTT 消息对接配置参数清单

7.1 核心概念

💡 面向项目经理的通俗理解

• Broker：消息中转站，所有设备通过它收发消息，相当于邮局。
• Topic：消息”频道”，不同频道传递不同内容（采集数据 / 控制指令）。
• clientId：设备在 Broker 的”身份证号”，全局唯一，不可重复。

7.2 第一步：确定方案

MQTT 对接前，必须先确定方案。方案决定了谁提供 Broker、谁定义格式，以及后续所有资料清单。

方案说明：

🅰️1 方案 A1：厂家向我方 Broker 推数据，沿用厂家原有格式。Broker 由实施同事提供，我方负责解析。

🅰️2 方案 A2（最推荐）：厂家向我方 Broker 推数据，格式按 viSCADA 南向 MQTT 规范。厂家负责开发上报逻辑，我方无需适配。

🅱️ 方案 B：厂家已有成熟 MQTT 平台，viSCADA 作为客户端接入厂家 Broker 读取数据。

⚠️ 方案确定后不得随意变更。对接前须由项目经理向厂家确认 A1 / A2 / B，邮件留痕。

7.3 按方案收资料

📌 命名：项目名-MQTT-接口清单

图例：⭕ 我方提供给厂家 ｜ ✅ 厂家提供给我方

关键要求：

1. Topic 三件套齐备：上报（采集）、下发（控制）、应答（回执）须逐条标注方向。
2. 报文示例不可省略：每类 Topic 至少 1 条完整 JSON 样例，不接受”联调时抓包看”。
3. A2 方案下点表仍由厂家提供：点位清单只有厂家清楚。

7.4 操作流程

① 项目经理向厂家确认方案 A1 / A2 / B
        │
        ├── A1：联系实施同事获取 Broker 信息 + 专属凭证 → 发给厂家 → 要求回传 Topic、报文、点表
        ├── A2：联系实施同事获取 Broker 信息 + 专属凭证 → 按规范分配 Topic → 发给厂家 → 要求回传点表
        └── B：按 7.3 清单向厂家索取全部资料
        │
② 对照 7.5 核对清单逐项勾验
        │
③ 确认[网络放通](/docs/troubleshooting/807-network-connectivity-test)方向正确（A1/A2：厂家→我方；B：viSCADA→厂家）
        │
④ 资料齐备后提交进入联调

7.5 提资前核对

🔷 通用项

• 已确认方案 A1 / A2 / B 并邮件留痕
• 已获取上报、下发、应答 Topic（方向已标注）
• 已获取每类 Topic 的完整 JSON 示例
• 已获取完整点表（含编码、Topic、读写属性、单位、采集周期）

🅰️ 方案 A（A1 / A2 通用）

• 已向实施同事获取 Broker 地址、端口
• 已获取并发送给厂家专属用户名、密码、clientId
• 已确认网络放通：厂家 → 我方 Broker

🅰️2 方案 A2 额外项

• 已附送 viSCADA 南向 MQTT 规范
• 已按规范分配并下发 Topic 清单给厂家

🅱️ 方案 B

• 已获取厂家 Broker 地址、端口
• 已获取鉴权凭证（如厂家有测试环境请备注说明）
• 已确认 clientId 命名规则
• 已获取厂家对接文档
• 已确认网络放通：viSCADA → 厂家 Broker

7.6 点表与报文示例（A2 方案参考格式）

点表样例：

上报报文（telemetry）：

{
  "deviceId": "DEV-001",
  "ts": 1744416000000,
  "data": { "temp": 25.6, "humidity": 62.3 }
}

下发指令（command）：

{
  "deviceId": "DEV-001",
  "ts": 1744416000000,
  "cmdId": "cmd-20260412-001",
  "data": { "relay_1": true }
}

应答回执（command/ack）：

{
  "deviceId": "DEV-001",
  "ts": 1744416001200,
  "cmdId": "cmd-20260412-001",
  "result": "success",
  "data": { "relay_1": true }
}

📌 A1 与 B 方案的点表和报文由厂家提供，格式以厂家对接文档为准，上表仅作 A2 方案参考。

8 Kafka 对接

📎 详细手册：viSCADA Kafka 对接配置参数清单

8.1 你需要向厂家要什么

Kafka 对接的关键在于一次性收齐 Topic、安全机制、完整消息示例。仅提供服务器地址远不足以开展对接。

📌 命名：项目名-Kafka-接口清单

💡 Bootstrap Servers 必须是多个 broker 地址，逗号分隔，例如：broker1:9092,broker2:9092,broker3:9092。不接受只给一个地址。

8.2 操作步骤

1. 要求厂家提供所有 broker 地址，逗号分隔，不接受单一地址。
2. 要求厂家明确认证三要素：安全机制 + SASL 机制类型 + 实际凭证，不接受”有账号”等模糊表述。
3. 要求厂家提供至少 1 条真实的完整 JSON 消息样本。

8.3 提资前核对

• 已获取 Bootstrap Servers（多地址，逗号分隔）及 Topic 名称
• 已确认安全机制、SASL 机制类型、实际凭证
• 已获取至少 1 条完整消息示例及完整点表

9 数据库对接

📎 详细手册：viSCADA 数据库对接配置参数清单

9.1 适用场景

仅在以下情况使用本章：

• 客户已有业务系统（ERP、MES 等），数据存在数据库里
• 客户说”你们直接连我们数据库读数据吧”
• 没有合适接口或消息系统，数据库读取是唯一可行方式

ℹ️ 若对方有接口或消息系统，优先走 HTTP / MQTT / Kafka，不建议直连数据库。

9.2 你需要向厂家要什么

📌 命名：项目名-Database-接口清单

9.3 操作步骤

1. 确认数据库类型，不同数据库连接方式和端口不同，见下表。
2. 要求厂家提供专用账号或只读账号，不建议使用超级管理员账号。
3. 逐张表确认：表名、表类型（实时 / 历史）、可识别设备的字段。
4. 账号到手后，实际登录一次，确认能查到约定的表。

常见数据库默认端口：

💡 实时表 vs. 历史表：实时表每个设备一行，最新值覆盖旧值；历史表每次上报新增一行，按时间堆积。两类表采集方式不同，须逐张确认。

⚠️ Oracle 版本要求：现场 viSCADA 的 Telegraf 版本须 ≥ 1.29.0。

9.4 提资前核对

• 已确认数据库类型、主机/IP、端口及连接参数（实例名/库名/Schema）
• 已获取专用账号或只读账号并实际登录验证
• 已确认每张表的类型（实时/历史）及可映射到 device_name 的字段
• 已获取表结构说明与完整点表

9.5 填写示例

10 OPC UA 对接

📎 详细手册：viSCADA OPC UA 对接配置参数清单

10.1 你需要向厂家要什么

📌 命名：项目名-OPCUA-接口清单

💡 建议厂家先用 UaExpert 自测：UaExpert 是免费的 OPC UA 调试工具。厂家用它连接自己的 Server，验证能否读到数据，并导出节点清单交付，可大幅节省联调时间。

10.2 操作步骤

1. 确认地址格式：标准 OPC UA 地址以 opc.tcp:// 开头，如 opc.tcp://192.168.1.10:4840。
2. 确认认证方式（匿名 / 用户名密码 / 证书），三者所需资料完全不同。
3. 要求厂家提供完整 NodeId（如 ns=2;s=Line1.Temperature），不接受仅提供中文名称。
4. 要求厂家先用 UaExpert 自测通过，并导出节点清单交付。
5. 分别索取测试与生产环境的地址和凭证。

10.3 点表示例

10.4 提资前核对

• 已获取 endpoint_url（opc.tcp:// 格式）及认证凭证
• 已确认安全策略与安全模式（如适用）
• 已获取完整 NodeId 点表（含 tag_name、nodeid、data_type、access）
• 已建议厂家先用 UaExpert 自测并分别获取测试与生产环境凭证

11 统一提资入口

资料齐全后，通过以下入口提交：

附录：版本记录