# 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 稳定性参数

```json
"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 失败队列参数

```json
"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 目录与权限

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

> 若启用阿里云物模型：

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

## 5.2 创建服务文件

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

```ini
[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 启动与开机自启

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

## 5.4 运维常用命令

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

---

## 6. Windows 部署（NSSM 推荐）

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

## 6.1 目录准备

```powershell
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\
```

> 若启用阿里云物模型：

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

## 6.2 安装服务（NSSM）

```powershell
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 运维常用命令

```powershell
nssm restart ArtisGateway
nssm stop ArtisGateway
Get-Service ArtisGateway
```

---

## 7. 健康检查与巡检

## 7.1 HTTP 健康探针

```powershell
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 长期不可达，应检查：

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

---

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

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

---

## 9. 回滚流程

1. 停止服务
2. 恢复上一个版本可执行文件
3. 启动服务
4. 检查 `/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`，避免恢复时突发流量过大。