编辑 | blame | 历史 | 原始文档

JH2028 新协议 TCP 网关服务实施部署文档

1. 文档目的

本文档用于指导现场实施人员部署已经打包完成的 JH2028 新协议 TCP 网关服务。

本项目部署后承担以下职责：

作为 TCP 服务端接收设备数据盒子上报的数据。
按设备数据盒子的来源 IP 匹配设备编号。
解析 JH2028 2026-05-11 版 55 AA 新协议报文。
将解析后的数据上报到 MQTT 和/或阿里云。
提供设备中央监测大屏页面。

说明：

本服务是独立新项目，不依赖老项目运行。
本服务不兼容旧版 EE 55 协议。
现场部署优先使用 dist 目录下已经打包好的可执行文件，不需要在现场安装 Node.js 或执行 npm install。

2. 部署包说明

当前项目已经生成 Windows 和 Linux 两类部署包：

dist/
  win-x64/
    jh2028-service.exe
    配置说明.md
    runtime/
      config.json
      alModel.json
      dashboard/
    logs/
  linux-x64/
    jh2028-service
    配置说明.md
    runtime/
      config.json
      alModel.json
      dashboard/
    logs/

目录说明：

路径	说明
`jh2028-service.exe`	Windows 服务程序
`jh2028-service`	Linux 服务程序
`runtime/config.json`	主配置文件，现场主要修改此文件
`runtime/alModel.json`	阿里云物模型字段文件，一般不修改
`runtime/dashboard/`	大屏静态页面文件
`logs/`	日志目录
`配置说明.md`	配置字段说明

3. 部署前准备

部署前请确认以下信息：

项目	说明
服务器系统	Windows x64 或 Linux x64
服务器固定 IP	设备数据盒子需要连接该 IP
TCP 服务端口	默认 `9000`，设备数据盒子连接此端口
大屏访问端口	默认 `9100`，浏览器访问此端口
设备数据盒子 IP	每台设备数据盒子的来源 IP 需要写入配置
MQTT 地址	如启用 MQTT，需要确认地址、端口、账号、密码、Topic 前缀
阿里云三元组接口	如启用阿里云，需要确认接口域名和路径
防火墙策略	服务器需要放通 TCP 服务端口和大屏端口

建议现场网络关系：

设备数据盒子  --->  服务器IP:9000  --->  JH2028 TCP 网关服务
浏览器        --->  服务器IP:9100  --->  设备中央监测大屏
网关服务      --->  MQTT / 阿里云平台

4. Windows 部署

4.1 上传部署包

将 dist/win-x64 整个目录上传到服务器，例如：

D:\jh2028-service\win-x64

不要只复制 jh2028-service.exe，必须同时保留 runtime 目录。

4.2 修改配置

编辑：

D:\jh2028-service\win-x64\runtime\config.json

现场通常需要修改：

tcp.port
dashboard.port
devices
mqtt.host
mqtt.port
mqtt.username
mqtt.password
mqtt.defaultTopicPrefix
aliyun.tupleApiBaseUrl
aliyun.tupleApiPath

设备配置示例：

{
  "devices": [
    {
      "deviceId": "JH-001",
      "ip": "192.168.1.10",
      "name": "1号透析机"
    },
    {
      "deviceId": "JH-002",
      "ip": "192.168.1.11",
      "name": "2号透析机"
    }
  ]
}

注意：

ip 是设备数据盒子的来源 IP，不是服务器 IP。
同一个 IP 不要配置给多台设备。
当前服务按来源 IP 匹配设备，不从报文中解析设备编号。

4.3 手动启动

打开 PowerShell，执行：

cd D:\jh2028-service\win-x64
.\jh2028-service.exe --config .\runtime\config.json

看到类似日志表示启动成功：

[APP] 配置加载完成 TCP=0.0.0.0:9000
[TCP] 已开始监听 0.0.0.0:9000
[DASHBOARD] 已开始监听 0.0.0.0:9100

4.4 配置 Windows 开机自启

推荐使用 NSSM 或 Windows 任务计划程序托管进程。

方案一：NSSM

安装服务：

nssm install jh2028-service

在弹窗中填写：

Path: D:\jh2028-service\win-x64\jh2028-service.exe
Startup directory: D:\jh2028-service\win-x64
Arguments: --config .\runtime\config.json

启动服务：

nssm start jh2028-service

停止服务：

nssm stop jh2028-service

删除服务：

nssm remove jh2028-service confirm

方案二：任务计划程序

可创建一个“计算机启动时”触发的任务：

程序: D:\jh2028-service\win-x64\jh2028-service.exe
参数: --config .\runtime\config.json
起始于: D:\jh2028-service\win-x64

4.5 Windows 防火墙放通

以管理员 PowerShell 执行：

New-NetFirewallRule -DisplayName "JH2028 TCP 9000" -Direction Inbound -Protocol TCP -LocalPort 9000 -Action Allow
New-NetFirewallRule -DisplayName "JH2028 Dashboard 9100" -Direction Inbound -Protocol TCP -LocalPort 9100 -Action Allow

如现场修改了端口，请替换为实际端口。

5. Linux 部署

5.1 上传部署包

将 dist/linux-x64 整个目录上传到服务器，例如：

/opt/jh2028-service/linux-x64

不要只复制 jh2028-service，必须同时保留 runtime 目录。

5.2 修改配置

编辑：

vi /opt/jh2028-service/linux-x64/runtime/config.json

配置内容与 Windows 相同，重点确认：

tcp.port
dashboard.port
devices
mqtt
aliyun
send.channels

5.3 手动启动

执行：

cd /opt/jh2028-service/linux-x64
chmod +x ./jh2028-service
./jh2028-service --config ./runtime/config.json

看到类似日志表示启动成功：

[APP] 配置加载完成 TCP=0.0.0.0:9000
[TCP] 已开始监听 0.0.0.0:9000
[DASHBOARD] 已开始监听 0.0.0.0:9100

5.4 配置 systemd 服务

创建服务文件：

sudo vi /etc/systemd/system/jh2028-service.service

写入：

[Unit]
Description=JH2028 TCP Gateway Service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/jh2028-service/linux-x64
ExecStart=/opt/jh2028-service/linux-x64/jh2028-service --config ./runtime/config.json
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

加载并启动：

sudo systemctl daemon-reload
sudo systemctl enable jh2028-service
sudo systemctl start jh2028-service

查看状态：

sudo systemctl status jh2028-service

查看实时日志：

journalctl -u jh2028-service -f

停止服务：

sudo systemctl stop jh2028-service

重启服务：

sudo systemctl restart jh2028-service

5.5 Linux 防火墙放通

如使用 firewalld：

sudo firewall-cmd --add-port=9000/tcp --permanent
sudo firewall-cmd --add-port=9100/tcp --permanent
sudo firewall-cmd --reload

如使用 ufw：

sudo ufw allow 9000/tcp
sudo ufw allow 9100/tcp

如现场修改了端口，请替换为实际端口。

6. 配置重点说明

6.1 TCP 服务配置

{
  "tcp": {
    "host": "0.0.0.0",
    "port": 9000
  }
}

建议：

host 保持 0.0.0.0，表示监听服务器所有网卡。
port 与设备数据盒子连接端口保持一致。

6.2 大屏配置

{
  "dashboard": {
    "enabled": true,
    "host": "0.0.0.0",
    "port": 9100
  }
}

浏览器访问：

本机访问：http://127.0.0.1:9100
局域网访问：http://服务器真实IP:9100

不要在浏览器打开：

http://0.0.0.0:9100

0.0.0.0 只表示服务监听地址，不是浏览器访问地址。

6.3 上报通道配置

{
  "send": {
    "channels": ["mqtt", "aliyun"]
  }
}

可选值：

["mqtt"]           只上报 MQTT
["aliyun"]         只上报阿里云
["mqtt","aliyun"]  同时上报 MQTT 和阿里云

注意：上传失败只记录日志，不做补发。

6.4 日志配置

{
  "logging": {
    "dir": "./logs",
    "level": "info",
    "logRawHex": false
  }
}

说明：

日志文件按日期生成，例如 jh2028-service-20260519.log。
当启动命令使用 --config ./runtime/config.json 时，./logs 会按 runtime 目录计算。
联调排查原始报文时，可临时将 logRawHex 改为 true，排查完成后建议改回 false。

7. 部署验证

7.1 检查进程

Windows：

Get-Process | Where-Object { $_.ProcessName -like "*jh2028*" }

Linux：

ps -ef | grep jh2028-service

7.2 检查端口监听

Windows：

netstat -ano | findstr ":9000"
netstat -ano | findstr ":9100"

Linux：

ss -lntp | grep -E "9000|9100"

7.3 检查大屏

浏览器打开：

http://服务器真实IP:9100

验证点：

页面能正常打开。
设备列表显示正确。
设备连接后状态变为在线。
收到数据后指标刷新。

7.4 检查设备接入

设备数据盒子连接服务器后，日志应出现：

[TCP] 设备已连接 设备=JH-001 IP=192.168.1.10
[TCP] 收到原始数据 设备=JH-001 字节数=...
[TCP] 解析到指标 设备=JH-001 类型=...

如果出现以下日志，说明设备 IP 未配置或配置不一致：

[TCP] 未配置设备接入 IP=...

7.5 检查上报

MQTT 上报成功时，日志中会出现 MQTT 发布相关记录。

阿里云上报失败时，日志中会出现：

[APP] 阿里云上报失败 设备=...

MQTT 上报失败时，日志中会出现：

[APP] MQTT 上报失败 设备=...

8. 常见问题处理

8.1 服务启动失败：未找到配置文件

现象：

未找到配置文件: ...

处理：

确认启动命令中的 --config 路径正确。
确认当前工作目录是部署包目录。
Windows 推荐在 win-x64 目录下执行启动命令。
Linux systemd 需要正确设置 WorkingDirectory。

8.2 服务启动失败：端口被占用

现象：

EADDRINUSE

处理：

检查 9000 或 9100 是否已被其他程序占用。
停止占用端口的程序，或修改 runtime/config.json 中的端口。
修改端口后同步调整防火墙和设备数据盒子连接配置。

8.3 设备无法连接

处理顺序：

确认设备数据盒子连接的是服务器真实 IP 和 tcp.port。
确认服务器防火墙已放通 TCP 端口。
确认设备数据盒子和服务器网络互通。
确认 devices[].ip 是设备数据盒子的来源 IP。
查看日志是否出现“未配置设备接入”。

8.4 大屏打不开

处理顺序：

确认服务已启动。
确认 dashboard.enabled 为 true。
确认 dashboard.port 未被占用。
确认防火墙放通大屏端口。
使用 http://服务器真实IP:9100 访问，不要使用 http://0.0.0.0:9100。

8.5 收到数据但没有上报

处理顺序：

确认 send.channels 已启用对应通道。
确认 MQTT 或阿里云配置正确。
查看日志中的 MQTT / 阿里云失败信息。
确认服务器可以访问 MQTT 或阿里云接口地址。
如需排查原始报文，临时开启 logging.logRawHex=true。

9. 升级部署

升级前建议备份：

runtime/config.json
runtime/alModel.json
logs/

升级步骤：

停止当前服务。
备份当前部署目录。
上传新的 win-x64 或 linux-x64 部署包。
将旧版本 runtime/config.json 中的现场配置迁移到新版本。
如物模型有调整，再确认 runtime/alModel.json。
启动服务。
按“部署验证”章节完成验证。

注意：

不建议直接覆盖整个 runtime 目录，避免覆盖现场配置。
如果新版本配置字段有变化，以新版本 config.json 为准，将现场值迁移进去。

10. 回滚方案

如升级后现场异常，可按以下步骤回滚：

停止新版本服务。
恢复升级前备份的部署目录。
启动旧版本服务。
检查端口监听、大屏访问、设备连接和上报日志。

建议每次升级保留至少一个可用旧版本目录，例如：

D:\jh2028-service\backup\win-x64-20260519
/opt/jh2028-service/backup/linux-x64-20260519

11. 交付检查清单

检查项	结果
部署包完整，包含可执行文件、`runtime`、`logs`
`runtime/config.json` 已按现场设备和平台信息修改
TCP 端口已放通
大屏端口已放通
服务已配置开机自启
服务进程运行正常
TCP 端口监听正常
大屏可以通过服务器真实 IP 访问
设备连接日志正常
数据解析日志正常
MQTT 或阿里云上报验证正常
已备份最终配置文件