From 7885cede659f3255be56f77c1eef2ada7387d6f1 Mon Sep 17 00:00:00 2001
From: chenyc <501753378@qq.com>
Date: 星期日, 22 三月 2026 16:23:21 +0800
Subject: [PATCH] 初始化项目
---
docs/实施部署文档.md | 506 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 506 insertions(+), 0 deletions(-)
diff --git "a/docs/\345\256\236\346\226\275\351\203\250\347\275\262\346\226\207\346\241\243.md" "b/docs/\345\256\236\346\226\275\351\203\250\347\275\262\346\226\207\346\241\243.md"
new file mode 100644
index 0000000..c374440
--- /dev/null
+++ "b/docs/\345\256\236\346\226\275\351\203\250\347\275\262\346\226\207\346\241\243.md"
@@ -0,0 +1,506 @@
+# 透析机数据接收网关部署实施文档
+
+> 适用对象：实施工程师、运维工程师
+>
+> 适用程序：`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`
+- 一份《实施验收记录表》
--
Gitblit v1.8.0