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

> 适用对象：实施工程师、运维工程师
>
> 适用程序：`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. 部署文件清单

建议部署目录结构如下：

```text
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 当前示例配置

```json
{
  "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/`

例如：

```text
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 服务器上创建目录，例如：

```text
D:\SWS-Gateway\
```

拷贝以下文件：

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

建议最终结构：

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

## 6.2 首次手工启动验证

在 PowerShell 中进入 `dist` 目录执行：

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

正常情况下应看到：

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

## 6.3 防火墙放行端口

如监听 `10000` 端口，可执行：

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

## 6.4 注册为 Windows 服务（推荐）

推荐使用 `nssm` 注册服务。

### 方式一：使用 NSSM（推荐）

下载 `nssm` 后执行：

```powershell
nssm install SWSGateway
```

在弹出界面中填写：

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

安装完成后执行：

```powershell
nssm start SWSGateway
```

查看状态：

```powershell
nssm status SWSGateway
```

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

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

## 7. Linux 部署步骤

## 7.1 拷贝文件

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

```bash
/opt/sws-gateway/
```

拷贝以下文件：

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

建议结构：

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

## 7.2 赋予执行权限

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

## 7.3 首次手工启动验证

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

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

## 7.4 配置防火墙

如使用 `firewalld`：

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

如使用 `ufw`：

```bash
ufw allow 10000/tcp
```

## 7.5 注册为 systemd 服务（推荐）

新建文件：

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

内容如下：

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

启用并启动：

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

查看状态：

```bash
systemctl status sws-gateway
```

查看日志：

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

## 8. 实施联调步骤

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

1. 启动网关程序
2. 确认日志中出现 `TCP server listening`
3. 让一台透析机指向服务器 IP 和端口
4. 观察日志是否出现：
   - `Device connected`
   - `Raw TCP data received`
   - `Dialysis frame parsed`
   - `MQTT publish success` 或 `Aliyun postProps success`
5. 再逐步增加设备数量
6. 最后进行整病区并发接入验证

## 9. 日常运维检查项

每日建议检查：

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

## 10. 常见问题排查

### 10.1 透析机连不上

排查顺序：

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

### 10.2 程序启动了但没有数据

排查顺序：

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

### 10.3 MQTT 未收到数据

排查顺序：

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

### 10.4 阿里云未上报成功

排查顺序：

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

### 10.5 没有日志文件

排查顺序：

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

## 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`
- 一份《实施验收记录表》