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

Jb-Communication 网关部署实施文档（Windows / Linux）

适用对象：实施工程师、运维工程师
适用版本：当前仓库 gateway.js 打包产物（gateway-win.exe / gateway-linux）

1. 目标与范围

本程序用于连接透析机 TCP 数据流，解析后转发到 MQTT/阿里云 IoT，并提供：

本地日志（按天滚动）
本地最新缓存
MQTT 失败本地队列（断网可恢复）
健康探针（HTTP）

本文档用于生产环境一次性部署与后续运维。

2. 交付物清单

将以下文件放到目标机同一部署目录（建议：D:\apps\artis-gateway 或 /opt/artis-gateway）：

gateway-win.exe（Windows）或 gateway-linux（Linux）
gateway.config.json
阿里物模型.json（仅当 services.aliyunIot.enabled=true 时需要）

程序运行后自动创建：

logs/（运行日志）
cache/latest-device-cache.json（最新值缓存）
cache/mqtt-failed-queue.json（MQTT 失败队列）

3. 网络与端口要求

3.1 入站（网关机器）

透析机 -> 网关：TCP 3021（或配置中的设备端口）

3.2 出站（网关机器）

网关 -> MQTT Broker：例如 1883 / 62283
网关 -> 三元组接口（可选）：如 http://x.x.x.x:8080
健康探针（本机）：默认 127.0.0.1:18080

4. 配置文件关键项（`gateway.config.json`）

4.1 稳定性参数

"reconnectPolicy": {
  "baseMs": 5000,
  "maxMs": 300000,
  "factor": 2,
  "jitterRatio": 0.2
},
"maxBufferBytes": 8388608,
"healthProbe": {
  "enabled": true,
  "host": "127.0.0.1",
  "port": 18080,
  "staleFrameMs": 180000
}

说明：

baseMs：首次重连等待时间
factor：指数退避倍率
maxMs：最长重连等待
jitterRatio：抖动比例，防止多机同秒重连风暴
maxBufferBytes：单设备接收缓存上限，超限自动截断保护内存
staleFrameMs：超过该时间无新帧则健康状态降级

4.2 MQTT 失败队列参数

"services": {
  "mqtt": {
    "failureQueue": {
      "enabled": true,
      "filePath": "./cache/mqtt-failed-queue.json",
      "maxItems": 5000,
      "retryIntervalMs": 5000,
      "retryBatchSize": 100,
      "dedupeEnabled": true,
      "dedupeFields": ["topic", "deviceKey", "frameTimestamp"]
    }
  }
}

说明：

发布失败自动入队并落盘
恢复连接后自动重试
按 dedupeFields 去重，避免重复帧无限堆积

5. Linux 部署（systemd）

5.1 目录与权限

sudo mkdir -p /opt/artis-gateway
sudo cp gateway-linux gateway.config.json /opt/artis-gateway/
sudo chmod +x /opt/artis-gateway/gateway-linux

若启用阿里云物模型：

sudo cp 阿里物模型.json /opt/artis-gateway/

5.2 创建服务文件

创建 /etc/systemd/system/artis-gateway.service：

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

[Service]
Type=simple
WorkingDirectory=/opt/artis-gateway
ExecStart=/opt/artis-gateway/gateway-linux --config /opt/artis-gateway/gateway.config.json
Restart=always
RestartSec=5
User=root

[Install]
WantedBy=multi-user.target

5.3 启动与开机自启

sudo systemctl daemon-reload
sudo systemctl enable artis-gateway
sudo systemctl start artis-gateway
sudo systemctl status artis-gateway

5.4 运维常用命令

sudo systemctl restart artis-gateway
sudo systemctl stop artis-gateway
sudo journalctl -u artis-gateway -f

6. Windows 部署（NSSM 推荐）

说明：Windows 建议用 NSSM 注册服务，避免计划任务不稳定。

6.1 目录准备

New-Item -ItemType Directory -Force D:\apps\artis-gateway | Out-Null
Copy-Item .\gateway-win.exe D:\apps\artis-gateway\
Copy-Item .\gateway.config.json D:\apps\artis-gateway\

若启用阿里云物模型：

Copy-Item .\阿里物模型.json D:\apps\artis-gateway\

6.2 安装服务（NSSM）

nssm install ArtisGateway D:\apps\artis-gateway\gateway-win.exe --config D:\apps\artis-gateway\gateway.config.json
nssm set ArtisGateway AppDirectory D:\apps\artis-gateway
nssm set ArtisGateway Start SERVICE_AUTO_START
nssm start ArtisGateway

6.3 运维常用命令

nssm restart ArtisGateway
nssm stop ArtisGateway
Get-Service ArtisGateway

7. 健康检查与巡检

7.1 HTTP 健康探针

Invoke-WebRequest -UseBasicParsing http://127.0.0.1:18080/health

200：status=ok
503：status=degraded（无连接或长时间无新帧）

7.2 日志检查

文本日志：logs/gateway-YYYY-MM-DD.log
结构化日志：logs/gateway-YYYY-MM-DD.jsonl

重点关注事件：

device_connected / device_closed
mqtt_publish_success / mqtt_publish_failed
mqtt_queue_enqueued / mqtt_queue_drained
device_buffer_trimmed

7.3 队列与缓存检查

最新缓存：cache/latest-device-cache.json
失败队列：cache/mqtt-failed-queue.json

队列持续增长说明 MQTT 长期不可达，应检查：

Broker 地址/端口
用户名密码
防火墙/路由策略

8. 发布升级流程（建议）

备份旧版本目录（至少保留上一个版本）
停止服务
替换可执行文件（gateway-win.exe / gateway-linux）
保留原有 gateway.config.json、cache/、logs/
启动服务
检查 /health 与 5 分钟日志

9. 回滚流程

停止服务
恢复上一个版本可执行文件
启动服务
检查 /health 与日志

回滚时不要删除 cache/mqtt-failed-queue.json，避免离线期间数据丢失。

10. 常见问题处理

Q1：服务启动后立刻退出

检查 gateway.config.json 路径是否正确
检查 JSON 格式是否合法（逗号、引号）

Q2：有连接无上报

看日志是否出现 mqtt_publish_failed
检查 MQTT 认证与网络
查看失败队列是否持续增长

Q3：健康探针返回 503

可能设备未连接或 staleFrameMs 内无新帧
先查 device_connected / device_data_received 事件

Q4：内存上涨

检查是否有 device_buffer_trimmed 告警
适当减小 maxBufferBytes 或排查异常流量输入

11. 实施验收清单

[ ] 服务已设为开机自启
[ ] gateway.config.json 已按现场设备修改
[ ] MQTT 连通，日志可见 mqtt_publish_success
[ ] 健康探针 /health 返回 200
[ ] 断开 MQTT 后队列会增长，恢复后会回落
[ ] 日志目录按天产生文件

12. 建议阈值（可直接参考）

reconnectPolicy.baseMs: 5000
reconnectPolicy.maxMs: 300000
maxBufferBytes: 8388608（8MB）
failureQueue.maxItems: 5000
failureQueue.retryBatchSize: 100
healthProbe.staleFrameMs: 180000（3分钟）

如现场网络极不稳定，可将 retryBatchSize 降到 20~50，避免恢复时突发流量过大。