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

## 1. 文档目的

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

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

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

说明：

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

## 2. 部署包说明

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

```text
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 服务端口和大屏端口 |

建议现场网络关系：

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

## 4. Windows 部署

### 4.1 上传部署包

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

```text
D:\jh2028-service\win-x64
```

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

### 4.2 修改配置

编辑：

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

现场通常需要修改：

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

设备配置示例：

```json
{
  "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，执行：

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

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

```text
[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

安装服务：

```powershell
nssm install jh2028-service
```

在弹窗中填写：

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

启动服务：

```powershell
nssm start jh2028-service
```

停止服务：

```powershell
nssm stop jh2028-service
```

删除服务：

```powershell
nssm remove jh2028-service confirm
```

#### 方案二：任务计划程序

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

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

### 4.5 Windows 防火墙放通

以管理员 PowerShell 执行：

```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` 整个目录上传到服务器，例如：

```text
/opt/jh2028-service/linux-x64
```

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

### 5.2 修改配置

编辑：

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

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

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

### 5.3 手动启动

执行：

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

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

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

### 5.4 配置 systemd 服务

创建服务文件：

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

写入：

```ini
[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
```

加载并启动：

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

查看状态：

```bash
sudo systemctl status jh2028-service
```

查看实时日志：

```bash
journalctl -u jh2028-service -f
```

停止服务：

```bash
sudo systemctl stop jh2028-service
```

重启服务：

```bash
sudo systemctl restart jh2028-service
```

### 5.5 Linux 防火墙放通

如使用 firewalld：

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

如使用 ufw：

```bash
sudo ufw allow 9000/tcp
sudo ufw allow 9100/tcp
```

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

## 6. 配置重点说明

### 6.1 TCP 服务配置

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

建议：

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

### 6.2 大屏配置

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

浏览器访问：

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

不要在浏览器打开：

```text
http://0.0.0.0:9100
```

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

### 6.3 上报通道配置

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

可选值：

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

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

### 6.4 日志配置

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

说明：

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

## 7. 部署验证

### 7.1 检查进程

Windows：

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

Linux：

```bash
ps -ef | grep jh2028-service
```

### 7.2 检查端口监听

Windows：

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

Linux：

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

### 7.3 检查大屏

浏览器打开：

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

验证点：

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

### 7.4 检查设备接入

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

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

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

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

### 7.5 检查上报

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

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

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

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

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

## 8. 常见问题处理

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

现象：

```text
未找到配置文件: ...
```

处理：

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

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

现象：

```text
EADDRINUSE
```

处理：

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

### 8.3 设备无法连接

处理顺序：

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

### 8.4 大屏打不开

处理顺序：

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

### 8.5 收到数据但没有上报

处理顺序：

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

## 9. 升级部署

升级前建议备份：

```text
runtime/config.json
runtime/alModel.json
logs/
```

升级步骤：

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

注意：

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

## 10. 回滚方案

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

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

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

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

## 11. 交付检查清单

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