# JH2028 新协议服务配置说明

本文档用于说明打包产物中的 `runtime/config.json` 应该如何配置。

## 1. 目录说明

Windows 打包目录示例：

```text
win-x64/
  jh2028-service.exe        服务程序
  配置说明.md               本说明文件
  runtime/
    config.json             主配置文件，现场主要修改这个文件
    alModel.json            阿里云物模型字段，不建议随意修改
    dashboard/              设备中央监测大屏页面文件
  logs/                     预留日志目录
```

Linux 打包目录示例：

```text
linux-x64/
  jh2028-service            服务程序
  配置说明.md               本说明文件
  runtime/
    config.json             主配置文件，现场主要修改这个文件
    alModel.json            阿里云物模型字段，不建议随意修改
    dashboard/              设备中央监测大屏页面文件
  logs/                     预留日志目录
```

注意：如果启动命令指定 `--config ./runtime/config.json`，则 `config.json` 中相对路径会按 `runtime/` 目录计算。

## 2. TCP 服务配置

```json
{
  "tcp": {
    "host": "0.0.0.0",
    "port": 9000,
    "maxConnections": 100,
    "socketTimeoutMs": 120000,
    "keepAlive": true,
    "keepAliveDelayMs": 10000,
    "noDelay": true,
    "backlog": 128,
    "maxBufferBytes": 8192
  }
}
```

字段说明：

- `host`：服务监听地址。一般保持 `0.0.0.0`，表示监听所有网卡。
- `port`：TCP 服务端口，设备数据盒子需要连接这个端口。
- `maxConnections`：最大连接数。
- `socketTimeoutMs`：连接长时间无数据后的超时时间，单位毫秒。
- `keepAlive`：是否启用 TCP KeepAlive。
- `maxBufferBytes`：单连接缓存区上限，防止异常数据撑爆内存。

当前通讯角色：

```text
本程序 = TCP 服务端
设备数据盒子 = TCP 客户端
设备数据盒子主动连接 本程序IP:9000
```

## 3. 设备列表配置

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

字段说明：

- `deviceId`：设备编号，也是 MQTT Topic 和阿里云 `deviceName` 使用的设备标识。
- `ip`：设备数据盒子的来源 IP。程序收到 TCP 连接后按这个 IP 匹配设备。
- `name`：大屏展示名称。

现场新增设备时，在 `devices` 数组中增加一项即可。

注意：

- 当前不从报文中解析设备编号。
- 同一个 IP 不要配置给多台设备。
- 设备盒子 IP 变化后，需要同步修改这里的 `ip`。

## 4. 大屏配置

```json
{
  "dashboard": {
    "enabled": true,
    "host": "0.0.0.0",
    "port": 9100,
    "title": "JH2028 设备中央监测大屏",
    "staleDataMs": 180000
  }
}
```

字段说明：

- `enabled`：是否启用大屏。
- `host`：大屏监听地址，一般保持 `0.0.0.0`。
- `port`：大屏访问端口。
- `title`：页面标题。
- `staleDataMs`：超过多久没收到数据后，大屏显示数据超时。

浏览器访问地址：

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

不要在浏览器里打开：

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

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

## 5. 上报通道配置

```json
{
  "send": {
    "channels": ["mqtt", "aliyun"],
    "includeDeviceIdField": true,
    "deviceIdField": "n"
  }
}
```

字段说明：

- `channels`：启用哪些上报通道。
- `includeDeviceIdField`：上报数据中是否包含设备编号字段。
- `deviceIdField`：设备编号字段名，当前沿用老项目字段 `n`。

可选组合：

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

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

## 6. MQTT 配置

```json
{
  "mqtt": {
    "protocol": "mqtt",
    "host": "mqtt.ihemodialysis.com",
    "port": 62283,
    "username": "data",
    "password": "data#2018",
    "defaultTopicPrefix": "touxiji"
  }
}
```

字段说明：

- `protocol`：通常为 `mqtt`。
- `host`：MQTT 服务器地址。
- `port`：MQTT 端口。
- `username` / `password`：MQTT 账号密码。
- `defaultTopicPrefix`：默认 Topic 前缀。

当前 Topic 规则沿用老项目：

```text
defaultTopicPrefix/deviceId
```

例如：

```text
touxiji/JH-001
```

## 7. 阿里云配置

```json
{
  "aliyun": {
    "enabled": true,
    "tupleApiBaseUrl": "https://things.icoldchain.cn",
    "tupleApiPath": "/device/info/getAliyunDeviceSecret",
    "autoRegister": true,
    "registerRetryMs": 60000,
    "connectTimeoutMs": 15000
  }
}
```

字段说明：

- `tupleApiBaseUrl`：获取阿里云三元组接口域名。
- `tupleApiPath`：获取阿里云三元组接口路径。
- `autoRegister`：是否允许后端自动注册设备。
- `registerRetryMs`：获取三元组失败后的重试间隔。
- `connectTimeoutMs`：阿里云连接超时时间。

阿里云设备名规则：

```text
deviceName = deviceId
```

## 8. 日志配置

```json
{
  "logging": {
    "enabled": true,
    "console": true,
    "dir": "./logs",
    "filePrefix": "jh2028-service",
    "level": "info",
    "logRawHex": false
  }
}
```

字段说明：

- `enabled`：是否启用日志。
- `console`：是否输出到控制台。
- `dir`：日志目录。相对路径会按配置文件所在目录计算。
- `filePrefix`：日志文件名前缀。
- `level`：日志级别，常用 `info`。
- `logRawHex`：是否记录原始十六进制报文。联调排查时可临时改为 `true`。

## 9. 协议配置

```json
{
  "protocol": {
    "name": "jh2028-20260511",
    "alModelPath": "./alModel.json"
  }
}
```

字段说明：

- `name`：协议名称，仅用于标识。
- `alModelPath`：物模型字段文件路径。

一般不需要修改。

## 10. 启动命令

Windows：

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

Linux：

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

## 11. 现场最常修改项

通常只需要改这些字段：

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

其余字段建议保持默认，除非现场网络或平台规则有明确变化。