IndustryKit

IndustryKit 是独立的只读工业数据采集器，部署在能够访问设备网络的 Linux 或 Windows 主机上。它从 PLC、仪表、OPC UA Server、MQTT Broker 和 SNMP 设备采集数据，并通过 Dataway 上报为指标（metric）或日志（logging）。

IndustryKit 不提供写寄存器、写线圈、PLC 控制、SNMP SET 或远程配置功能。

功能概览¶

一个 IndustryKit 进程可以配置多个 source。Modbus、OPC UA、S7 和 SNMP 通过 point 定义采集地址及输出字段；MQTT 通过 topic 和 fields 定义消息映射。不同 source 可以使用 不同的 measurement。

运行要求¶

• 提供 Linux amd64/arm64 和 Windows amd64/arm64 发布包，在线安装脚本会自动识别架构。
• Linux 安装器要求正在运行 systemd，本文 Linux 命令默认以 root 用户执行。
• Windows 要求 Windows 10、Windows Server 2016 或更高版本，并使用管理员 Windows PowerShell 5.1 或更高版本。
• 部署主机必须能够访问目标设备或 Broker 的协议端口，并能通过 HTTP/HTTPS 访问 Dataway。
• 设备地址从 IndustryKit 所在主机解释；127.0.0.1 只表示该主机自身。跨机连接模拟器或设备时，对端还需监听可访问地址并放通防火墙。
• 连接受保护设备时，需要提前准备设备账号、SNMP v3 凭据或 TLS 证书等信息。
• Modbus TCP、经典 S7、OPC UA None 和 MQTT tcp:// 本身不提供链路加密，应仅用于可信工业网络、VPN 或受防火墙限制的网段。
• 当前不提供官方容器镜像。

安装¶

首次安装必须提供包含 token query 参数的完整 Dataway URL。可选设置 INDUSTRYKIT_COLLECTOR_ID 指定采集器 实例 ID；未设置时使用主机名。ID 支持中文等 Unicode 字符，不能全为空白或包含控制字符。 Dataway URL 使用 http:// 或 https:// 绝对地址，必须包含唯一且非空的 token query 参数， 不得包含 userinfo 或 fragment；写入路径由 IndustryKit 自动追加。

INDUSTRYKIT_DATAWAY_URL="https://openway.guance.com?token=<DATAWAY_TOKEN>" \
  sh -c "$(curl -fsSL https://static.guance.com/industrykit/install.sh)"

Remove-Item -ErrorAction SilentlyContinue Env:INDUSTRYKIT_*;
$env:INDUSTRYKIT_DATAWAY_URL = "https://openway.guance.com?token=<DATAWAY_TOKEN>";
Set-ExecutionPolicy Bypass -Scope Process -Force;
Import-Module BitsTransfer;
Start-BitsTransfer -Source https://static.guance.com/industrykit/install.ps1 -Destination .install.ps1;
powershell ./.install.ps1;

安装目录¶

Linux 安装需要管理员权限，但服务默认以非 root 的 industrykit 用户运行。Modbus RTU 还需为该用户授予串口权限，详见 Modbus Linux 串口权限。

Linux 配置目录、数据根目录和日志目录为 0755，配置及样例为 0644，普通用户可浏览 目录、读取配置，修改配置仍需管理员权限。新建日志文件保留日志库的 0600 权限；新建 WAL 分类目录及数据文件沿用 diskcache 的 0750 / 0640，查看其内容可能仍需管理员权限。

Windows 安装目录、配置、日志、WAL 和 PKI 沿用父目录的权限，不额外限制为管理员专属。 实际读写权限取决于系统设置；安装、升级和服务管理仍需管理员权限。保存配置时若提示拒绝 访问，请以管理员身份启动编辑器。

配置并启动¶

安装生成的 industrykit.toml 已包含 Dataway、日志、WAL 和采集器 ID，并附带五种协议的 注释示例。默认没有生效的 [[sources]]，此时启动进程不会采集设备数据。

配置格式版本使用 version = 1。公共配置字段如下，设备协议字段见后面的协议文档。

[collector]¶

[logging]¶

日志最长保留 30 天，该时间目前不可配置。

这里的 [logging] 是 IndustryKit 自身运行日志，不是设备数据的 category = "logging"。

[dataway] 与可选的 [dataway.tls]¶

TLS 证书使用相对路径时，以主配置文件所在目录为基准。

[dataway.batch]¶

点数、大小或等待时间任一条件先达到，当前批次就会进入 WAL 等待发送。

[dataway.wal]¶

Dataway 返回成功响应后才会删除 WAL 记录；容量已满时拒绝新批次，超过保留时间的记录在消费时丢弃。

[[sources]] 通用字段¶

Point 通用字段¶

Modbus、OPC UA、S7 和 SNMP 的 [[sources.<type>.points]] 共用以下字段；MQTT 使用 topic 映射，字段见 MQTT 配置。

collector_id、protocol 和 source_id 是系统自动添加的固定标签，不能在 tags 中配置。

选择需要的协议文档，将完整 source 示例取消注释或复制到配置文件，并替换设备地址、 点位、<...> 凭据占位值和证书路径：

每个 source 还必须配置与 type 同名的协议子表。输出映射如下：

修改配置后先执行校验，校验通过后启动服务：

industrykit validate --config /etc/industrykit/industrykit.toml
systemctl start industrykit
systemctl status industrykit --no-pager

$IndustryKit = "$env:ProgramFiles\IndustryKit\industrykit.exe"
$Config = "$env:ProgramFiles\IndustryKit\industrykit.toml"
& $IndustryKit validate --config $Config
& $IndustryKit service start
Get-Service industrykit

开机自启为可选项：Linux 执行 systemctl enable industrykit；Windows 在管理员 PowerShell 中执行 Set-Service -Name industrykit -StartupType Automatic。

配置只在启动时读取，后续修改配置需要重启服务。

配置支持 ${ENV_NAME} 变量引用，但 systemd 和 Windows 服务不会自动继承当前终端中的 临时环境变量。使用该写法时，应通过对应服务管理器持久配置环境变量；否则直接在 TOML 中 填写实际值。配置含有凭据，请根据本机安全要求检查并设置读取权限。

验证采集与上报¶

服务启动后，先检查本地健康端点：

curl -fsS http://127.0.0.1:19090/healthz
curl -fsS http://127.0.0.1:19090/readyz
curl -fsS http://127.0.0.1:19090/metrics

(Invoke-WebRequest -UseBasicParsing http://127.0.0.1:19090/healthz).Content
(Invoke-WebRequest -UseBasicParsing http://127.0.0.1:19090/readyz).Content
(Invoke-WebRequest -UseBasicParsing http://127.0.0.1:19090/metrics).Content

重点关注以下自身指标：

/readyz 只表示进程和 WAL 可以继续接收数据，不代表设备一定在线。判断完整链路时，应同时 检查 source 状态、样本数、Dataway 发送数和运行日志。Modbus、S7、SNMP 或 OPC UA poll 至少等待一轮 interval；OPC UA subscribe 等待节点更新；MQTT 则需要发布端产生匹配消息。 随后在观测云中查询 source 配置的 measurement；category = "logging" 的数据在日志中查询。

查看运行日志：

tail -f /var/log/industrykit/industrykit.log

Get-Content "$env:ProgramData\IndustryKit\logs\industrykit.log" -Wait

升级¶

升级必须显式设置 INDUSTRYKIT_UPGRADE=1。默认升级保留现有 Dataway；提供新的完整 URL 时只更新 [dataway].url。

INDUSTRYKIT_UPGRADE=1 \
  sh -c "$(curl -fsSL https://static.guance.com/industrykit/install.sh)"

Remove-Item -ErrorAction SilentlyContinue Env:INDUSTRYKIT_*;
$env:INDUSTRYKIT_UPGRADE = "1";
Set-ExecutionPolicy Bypass -Scope Process -Force;
Import-Module BitsTransfer;
Start-BitsTransfer -Source https://static.guance.com/industrykit/install.ps1 -Destination .install.ps1;
powershell ./.install.ps1;

$env:INDUSTRYKIT_DATAWAY_URL = "https://openway.guance.com?token=<DATAWAY_TOKEN>";

升级到指定版本时，使用 install-<VERSION>.sh 或 install-<VERSION>.ps1。升级会替换 程序；Linux 同时刷新 systemd unit，Windows 校验并沿用已有 SCM 服务定义。现有配置、WAL、 日志、Linux enable 状态和 Windows 启动类型会保留；升级前正在运行的服务会重启，原本停止 的服务仍保持停止。

服务与命令¶

service uninstall 只注销服务，不删除程序、配置、WAL 或日志。Linux 注销后可重新执行 安装命令（不带 INDUSTRYKIT_UPGRADE），保留已有配置并重新注册服务，仍需手动启动。 已有配置时可省略 Dataway 参数；提供时只更新 [dataway].url。Windows 暂不支持保留文件直接重装。

注意事项¶

• validate 只校验配置结构和参数，不连接设备、Broker 或 Dataway。
• 点位地址、Node ID、DB offset 和 OID 并不由 IndustryKit 自动发现，应以设备手册、工程配置或现场扫描结果为准。