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

透析机数据接收网关部署实施文档

适用对象：实施工程师、运维工程师

适用程序：SWS-Communication 打包后的 Windows / Linux 服务程序

当前打包产物：
- Windows：dist/index-win.exe
- Linux：dist/index-linux

1. 目标说明

本程序用于接收山外山透析机通过 TCP 主动上报的数据，完成以下工作：

接收透析机 TCP 连接
解析运行参数帧 / 报警帧 / 血压帧
记录本地运行日志
按配置转发到 MQTT 或阿里云
支持 50 台及以上设备并发接入

2. 部署前准备

2.1 网络准备

实施前请确认以下条件：

服务器与透析机网络互通
透析机可以访问网关服务器的 TCP 监听地址和端口
防火墙已放行网关 TCP 监听端口
如启用 MQTT / 阿里云，上行网络可访问对应服务器

2.2 服务器建议配置

Windows

Windows Server 2016 / 2019 / 2022
至少 2 核 CPU
至少 4 GB 内存
至少 10 GB 可用磁盘空间

Linux

CentOS 7+/Rocky 8+/Ubuntu 20.04+
至少 2 核 CPU
至少 4 GB 内存
至少 10 GB 可用磁盘空间

3. 部署文件清单

建议部署目录结构如下：

SWS-Gateway/
├─ dist/
│  ├─ index-win.exe        # Windows 可执行文件
│  ├─ index-linux          # Linux 可执行文件
│  ├─ config.json          # 外部配置文件
│  └─ schema.json          # 物模型映射文件（必须放置）
├─ logs/                   # 日志目录（程序自动创建/写入）
└─ doc/                    # 可选文档目录

3.1 必须文件

实施时至少确保以下文件到位：

Windows 部署：
dist/index-win.exe
dist/config.json
dist/schema.json
Linux 部署：
dist/index-linux
dist/config.json
dist/schema.json

3.2 重要说明

当前程序启动后会从**可执行文件同目录**读取：

config.json
schema.json

因此：

config.json 必须和可执行文件放在一起
schema.json 也必须和可执行文件放在一起

否则：

程序虽然可能能启动
但属性映射会退化，影响 MQTT / 阿里云上报字段名称

4. 配置文件说明

当前程序默认使用外部 config.json 覆盖内置默认配置。

4.1 当前示例配置

{
  "tcp": {
    "host": "3.0.0.27",
    "port": 10000,
    "idleTimeoutMs": 1200000
  },
  "http": {
    "enabled": false,
    "host": "0.0.0.0",
    "port": 19001,
    "rateLimit": {
      "singleDeviceMs": 5000,
      "allDevicesMs": 60000
    }
  },
  "mqtt": {
    "enabled": true,
    "url": "mqtt.ihemodialysis.com",
    "port": 62283,
    "username": "data",
    "password": "data#2018",
    "defaultTopicPrefix": "touxiji",
    "retain": true
  },
  "aliyun": {
    "enabled": false,
    "baseURL": "https://things.icoldchain.cn/"
  }
}

4.2 关键配置项说明

TCP 接入

配置项	说明	建议
`tcp.host`	TCP 监听地址	建议设为 `0.0.0.0` 或服务器实际监听 IP
`tcp.port`	TCP 监听端口	根据现场约定，常用 `10000`
`tcp.idleTimeoutMs`	设备空闲超时	建议 `120000` ~ `1200000`

说明：如果服务器有多个网卡，建议优先使用 0.0.0.0 监听所有地址，避免只绑定某一个 IP 后导致透析机无法接入。

HTTP（可选）

配置项	说明
`http.enabled`	是否启用 HTTP 查询接口
`http.port`	HTTP 端口

当前默认可关闭，仅在联调或运维场景需要时启用。

MQTT

配置项	说明
`mqtt.enabled`	是否启用 MQTT 上报
`mqtt.url`	MQTT 服务地址
`mqtt.port`	MQTT 端口
`mqtt.username`	用户名
`mqtt.password`	密码
`mqtt.defaultTopicPrefix`	Topic 前缀
`mqtt.retain`	是否保留最后一条消息

阿里云

配置项	说明
`aliyun.enabled`	是否启用阿里云物联网
`aliyun.baseURL`	获取设备三元组的后端接口地址

5. 本地日志说明

程序已接入 winston 本地日志，默认写入日志文件。

5.1 日志目录

当前默认日志目录配置为：

../logs

这意味着：

如果可执行文件在 dist/ 目录下
日志会写到 dist 上一级目录的 logs/

例如：

SWS-Gateway/
├─ dist/
│  ├─ index-win.exe
│  ├─ config.json
│  └─ schema.json
└─ logs/
   ├─ gateway-2026-03-16.log
   └─ gateway-error-2026-03-16.log

5.2 日志文件类型

gateway-YYYY-MM-DD.log：业务全量日志
gateway-error-YYYY-MM-DD.log：错误日志

5.3 可查询内容

日志可追踪以下内容：

哪台机器什么时间连上
哪台机器发来了什么原始十六进制数据
哪台机器解析出了什么数据
什么时间 MQTT 上报成功
什么时间阿里云上报成功
哪台机器什么时间断开、在线多久、总共发了多少帧

6. Windows 部署步骤

6.1 拷贝文件

在 Windows 服务器上创建目录，例如：

D:\SWS-Gateway\

拷贝以下文件：

dist/index-win.exe
dist/config.json
schema.json（从项目根目录拷贝到 dist/）

建议最终结构：

D:\SWS-Gateway\
├─ dist\
│  ├─ index-win.exe
│  ├─ config.json
│  └─ schema.json
└─ logs\

6.2 首次手工启动验证

在 PowerShell 中进入 dist 目录执行：

cd D:\SWS-Gateway\dist
.\index-win.exe

正常情况下应看到：

程序启动日志
TCP server listening
如启用 MQTT，则看到 MQTT connected

6.3 防火墙放行端口

如监听 10000 端口，可执行：

New-NetFirewallRule -DisplayName "SWS Gateway TCP 10000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 10000

6.4 注册为 Windows 服务（推荐）

推荐使用 nssm 注册服务。

方式一：使用 NSSM（推荐）

下载 nssm 后执行：

nssm install SWSGateway

在弹出界面中填写：

Path：D:\SWS-Gateway\dist\index-win.exe
Startup directory：D:\SWS-Gateway\dist

安装完成后执行：

nssm start SWSGateway

查看状态：

nssm status SWSGateway

方式二：任务计划或开机自启动

如果现场不方便安装 nssm，可通过任务计划程序设置“开机自动启动”。

7. Linux 部署步骤

7.1 拷贝文件

在 Linux 服务器上建议创建目录：

/opt/sws-gateway/

拷贝以下文件：

dist/index-linux
dist/config.json
schema.json（从项目根目录拷贝到 dist/）

建议结构：

/opt/sws-gateway/
├─ dist/
│  ├─ index-linux
│  ├─ config.json
│  └─ schema.json
└─ logs/

7.2 赋予执行权限

chmod +x /opt/sws-gateway/dist/index-linux

7.3 首次手工启动验证

cd /opt/sws-gateway/dist
./index-linux

若启动正常，可看到监听日志。

7.4 配置防火墙

如使用 firewalld：

firewall-cmd --permanent --add-port=10000/tcp
firewall-cmd --reload

如使用 ufw：

ufw allow 10000/tcp

7.5 注册为 systemd 服务（推荐）

新建文件：

/etc/systemd/system/sws-gateway.service

内容如下：

[Unit]
Description=SWS Dialysis Gateway
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/sws-gateway/dist
ExecStart=/opt/sws-gateway/dist/index-linux
Restart=always
RestartSec=5
User=root
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

启用并启动：

systemctl daemon-reload
systemctl enable sws-gateway
systemctl start sws-gateway

查看状态：

systemctl status sws-gateway

查看日志：

tail -f /opt/sws-gateway/logs/gateway-$(date +%F).log

8. 实施联调步骤

建议实施工程师按以下顺序联调：

启动网关程序
确认日志中出现 TCP server listening
让一台透析机指向服务器 IP 和端口
观察日志是否出现：

Device connected
Raw TCP data received
Dialysis frame parsed
MQTT publish success 或 Aliyun postProps success

再逐步增加设备数量
最后进行整病区并发接入验证

9. 日常运维检查项

每日建议检查：

程序进程是否存活
日志是否持续有新内容
gateway-error-*.log 是否有连续错误
MQTT / 阿里云是否上报成功
是否有设备频繁断开重连

10. 常见问题排查

10.1 透析机连不上

排查顺序：

服务器 IP 是否正确
透析机端口配置是否正确
防火墙是否放行
程序是否已启动
tcp.host 是否绑定错误（建议 0.0.0.0）

10.2 程序启动了但没有数据

排查顺序：

查看是否有 Device connected
查看是否有 Raw TCP data received
如果只有连接没有数据，通常是透析机未实际开始发送
如果有原始数据但无解析结果，需核对协议或抓包

10.3 MQTT 未收到数据

排查顺序：

config.json 中 mqtt.enabled 是否为 true
查看日志中是否有 MQTT connected
查看日志中是否有 MQTT publish success
检查 Broker 地址、端口、用户名密码是否正确

10.4 阿里云未上报成功

排查顺序：

aliyun.enabled 是否为 true
后端获取三元组接口是否可访问
日志中是否有 Request Aliyun device secret
日志中是否有 Aliyun postProps success

10.5 没有日志文件

排查顺序：

检查 logs 目录权限
检查 config.log.toFile 是否为 true
检查程序工作目录和日志目录相对路径是否正确

11. 建议实施标准

正式实施时建议遵循：

Windows / Linux 均采用“服务化启动”
config.json 和 schema.json 固定随程序一起部署
日志目录单独保留，至少保留 30 天
初期上线先从 1 台、5 台、10 台逐步扩容到全病区
全病区接入前先使用压测脚本验证并发能力

12. 上线前检查清单

上线前请逐项确认：

[ ] 可执行文件已部署
[ ] config.json 已按现场修改
[ ] schema.json 已放到可执行文件同目录
[ ] TCP 监听端口已放行
[ ] MQTT / 阿里云配置已验证
[ ] 日志目录可写
[ ] 服务已设置开机自启
[ ] 已完成单机联调
[ ] 已完成多机联调
[ ] 已完成异常断网/重连测试

如需进一步交付实施工程师，建议同时附带：

docs/current-protocol-decoding.md
一份现场专用 config.json
一份《实施验收记录表》