From 747a86bb94006aaca721cfc0c0ce7061643a9ea6 Mon Sep 17 00:00:00 2001
From: chenyc <501753378@qq.com>
Date: 星期四, 20 八月 2026 12:19:35 +0800
Subject: [PATCH] gx
---
生产实施部署文档.md | 280 ++++++++++++++++++++++++++++++++++++++++++++------------
1 files changed, 220 insertions(+), 60 deletions(-)
diff --git "a/\347\224\237\344\272\247\345\256\236\346\226\275\351\203\250\347\275\262\346\226\207\346\241\243.md" "b/\347\224\237\344\272\247\345\256\236\346\226\275\351\203\250\347\275\262\346\226\207\346\241\243.md"
index 3f4a5ff..7cb96d4 100644
--- "a/\347\224\237\344\272\247\345\256\236\346\226\275\351\203\250\347\275\262\346\226\207\346\241\243.md"
+++ "b/\347\224\237\344\272\247\345\256\236\346\226\275\351\203\250\347\275\262\346\226\207\346\241\243.md"
@@ -2,61 +2,106 @@
## 1. 目标
-本文档用于指导 JHM 服务在生产环境中部署、配置和联调。
+本文档用于指导 JHM 服务在生产环境中的打包、部署、配置、联调和验收。
-当前服务支持：
+当前服务能力包括：
-- 透析机 `EE 55` 固定帧协议
-- 血压计 `AA 55` 变长协议
+- 透析机 `EE 55` 固定帧协议解析
+- 血压计 `AA 55` 变长协议解析
- MQTT 上报
-- 阿里云上报
+- 阿里云物模型上报
+- 批量聚合发送
+- 血压触发的整包立即发送
## 2. 打包产物
-执行：
+在项目根目录执行：
-```bash
+```powershell
npm run build
```
-生成目录：
+如果只需要 Windows 包：
+
+```powershell
+npm run build:win
+```
+
+如果只需要 Linux 包：
+
+```powershell
+npm run build:linux
+```
+
+打包完成后生成目录：
```text
dist/
+ 生产实施部署文档.md
win-x64/
jhm-service.exe
+ 生产实施部署文档.md
runtime/
config.json
alModel.json
+ 生产实施部署文档.md
+ logs/
+ service/
+ install-service.ps1
+ uninstall-service.ps1
linux-x64/
jhm-service
+ 生产实施部署文档.md
runtime/
config.json
alModel.json
+ 生产实施部署文档.md
+ logs/
+ service/
+ install-service.sh
+ uninstall-service.sh
+ jhm-service.service.tpl
```
+
+说明：
+
+- `runtime/` 是现场主要维护目录。
+- `logs/` 为运行日志目录。
+- `service/` 为系统服务安装脚本模板。
+- 打包脚本会先清理旧的 `build/` 和 `dist/` 目录。
## 3. 部署前检查
-部署前确认：
+部署前确认以下信息已准备完成：
-- 目标服务器 IP、系统、开放端口
-- 设备透传盒目标 TCP 地址和端口
-- `devices[].ip` 与现场实际来源 IP 一致
-- MQTT 或阿里云连接参数已准备完成
+- 目标服务器操作系统和架构是否正确
+- 目标服务器开放了业务监听端口
+- 透传盒子目标 TCP 地址和端口已配置正确
+- `devices[].ip` 与服务端实际看到的设备来源 IP 一致
+- MQTT 或阿里云连接参数已确认可用
+- `alModel.json` 与平台物模型保持一致
+- 现场是否需要血压时间字段 `M`
+- 现场是否需要“血压触发整包立即发送”
## 4. 配置文件说明
-主要修改文件：
+主要配置文件：
```text
runtime/config.json
```
-当前推荐结构：
+推荐配置结构如下：
```json
{
"send": {
+ "mode": "batch",
+ "flushIntervalMs": 60000,
+ "alignToMinute": true,
+ "includeDeviceIdField": true,
+ "deviceIdField": "n",
+ "publishOnShutdown": true,
"channels": ["aliyun"]
},
"logging": {
@@ -96,13 +141,14 @@
"protocol": {
"alModelPath": "./alModel.json",
"bloodPressure": {
- "publishTime": true
+ "publishTime": true,
+ "flushImmediately": true
}
},
"devices": [
{
"deviceId": "JHM-001",
- "ip": "192.168.33.1",
+ "ip": "169.254.233.58",
"name": "1号透析机"
}
]
@@ -111,41 +157,51 @@
### 4.1 `send`
-- `channels`：可选 `mqtt`、`aliyun`
+- `mode`：发送模式，支持 `batch` 和 `immediate`
+- `flushIntervalMs`：批量发送周期，单位毫秒，当前推荐 `60000`
+- `alignToMinute`：是否按整分钟对齐发送
+- `includeDeviceIdField`：发送时是否在 payload 中带设备编号字段
+- `deviceIdField`：设备编号字段名，当前默认 `n`
+- `publishOnShutdown`：停机前是否补发一次缓存数据
+- `channels`：发送通道，可选 `mqtt`、`aliyun`
+
+常见组合：
+
- 只发 MQTT：`["mqtt"]`
- 只发阿里云：`["aliyun"]`
-- 双发：`["mqtt", "aliyun"]`
+- 双通道发送：`["mqtt", "aliyun"]`
### 4.2 `logging`
-- `enabled`：是否写本地日志
-- `console`：是否输出控制台
+- `enabled`：是否写本地日志文件
+- `console`：是否输出控制台日志
- `dir`：日志目录
-- `filePrefix`：日志文件前缀
-- `level`：`debug/info/warn/error`
+- `filePrefix`：日志文件名前缀
+- `level`：日志级别，支持 `debug`、`info`、`warn`、`error`
### 4.3 `tcp`
-- `host`：监听地址，生产建议 `0.0.0.0`
+- `host`：监听地址，生产推荐 `0.0.0.0`
- `port`：TCP 监听端口
- `maxConnections`：最大连接数
-- `socketTimeoutMs`：连接超时时间
+- `socketTimeoutMs`：连接空闲超时时间
- `keepAlive`：是否启用 KeepAlive
-- `keepAliveDelayMs`：KeepAlive 延迟
-- `noDelay`：是否关闭 Nagle
+- `keepAliveDelayMs`：KeepAlive 首次探测延迟
+- `noDelay`：是否关闭 Nagle 算法
- `backlog`：监听队列长度
-- `maxBufferBytes`：解码缓冲区上限
+- `maxBufferBytes`：单连接解码缓冲区上限
### 4.4 `mqtt`
-- `protocol`：通常为 `mqtt`
+- `protocol`：通常填写 `mqtt`
- `host`：Broker 地址
- `port`：Broker 端口
- `username`：用户名
- `password`：密码
-- `defaultTopicPrefix`：topic 前缀
+- `defaultTopicPrefix`：Topic 前缀
+- `topicTemplate`：如使用模板模式，可替代默认前缀模式
-topic 规则：
+默认 Topic 规则：
```text
{defaultTopicPrefix}/{deviceId}
@@ -157,27 +213,51 @@
- `tupleApiBaseUrl`：三元组接口基础地址
- `tupleApiPath`：三元组接口路径
- `autoRegister`：是否允许自动注册
-- `registerRetryMs`：失败重试冷却时间
-- `connectTimeoutMs`：连接超时时间
+- `registerRetryMs`：三元组请求失败后的冷却重试时间
+- `connectTimeoutMs`：阿里云设备连接超时时间
### 4.6 `protocol`
-- `alModelPath`：模型文件路径
-- `bloodPressure.publishTime`：是否发布血压监测时间 `M`
+- `alModelPath`：物模型文件路径
+- `bloodPressure.publishTime`：是否上报血压时间字段 `M`
+- `bloodPressure.flushImmediately`：血压报文到达后是否立即触发一次整包发送
-规则：
+`publishTime` 规则：
-- `true`：发布 `N/O/P/M`
-- `false`：只发布 `N/O/P`
+- `true`：上报 `N/O/P/M`
+- `false`：仅上报 `N/O/P`
- 未配置时默认 `true`
-如果现场平台未接血压时间字段，建议配置：
+`flushImmediately` 规则：
+
+- `true`：血压到达后，先缓存 `N/O/P/M`，再立即发送当前设备缓存中的整包物模型
+- `false`：血压仅进入缓存，继续等待定时批量发送
+- 未配置时默认 `true`
+
+如果平台不接收血压时间字段，可配置：
```json
-"protocol": {
- "alModelPath": "./alModel.json",
- "bloodPressure": {
- "publishTime": false
+{
+ "protocol": {
+ "alModelPath": "./alModel.json",
+ "bloodPressure": {
+ "publishTime": false,
+ "flushImmediately": true
+ }
+ }
+}
+```
+
+如果现场明确要求“只按分钟发送，不要血压即时触发”，可配置：
+
+```json
+{
+ "protocol": {
+ "alModelPath": "./alModel.json",
+ "bloodPressure": {
+ "publishTime": true,
+ "flushImmediately": false
+ }
}
}
```
@@ -190,27 +270,34 @@
- `ip`
- `name`
-注意：
+注意事项：
-- `ip` 必须与服务端实际看到的客户端 IP 一致
-- 如果经过 NAT，要填写 NAT 后服务端看到的 IP
+- `ip` 必须与服务端实际看到的客户端来源 IP 完全一致
+- 如果经过 NAT，需要填写 NAT 后服务端可见的来源 IP
+- 如果现场使用备注字段，也建议同步补齐 `name`，便于日志识别
-## 5. 血压计协议补充
+## 5. 发送行为说明
-血压计示例报文：
+### 5.1 普通透析机指标
+
+透析机指标默认先进入聚合器缓存，在批量模式下按 `flushIntervalMs` 周期整包发送。
+
+### 5.2 血压报文
+
+血压报文示例：
```text
AA 55 0E BA 00 78 50 59 08 08 08 08 08 10
```
-解析含义：
+解析结果：
- `00 78`：收缩压 `N`
- `50`：舒张压 `O`
- `59`：脉搏 `P`
-- 后 5 字节：时间 `M`
+- 后 5 个时间字节：时间 `M`
-发布时间开启时：
+当 `publishTime=true` 时，血压指标示例：
```json
{
@@ -221,7 +308,7 @@
}
```
-发布时间关闭时：
+当 `publishTime=false` 时，血压指标示例：
```json
{
@@ -231,7 +318,38 @@
}
```
-## 6. Windows 部署
+当 `flushImmediately=true` 时，行为如下：
+
+1. 血压数据先写入缓存。
+2. 立即触发一次当前设备的整包物模型发送。
+3. 原有 1 分钟批量发送机制继续保留，不冲突。
+
+这样做的好处：
+
+- 血压结果更快到平台
+- 平台收到的仍然是完整物模型，不是单独的血压字段
+- 定时发送继续兜底，避免其他指标长时间不落地
+
+## 6. 模拟与联调
+
+项目内置 TCP 模拟器：
+
+```powershell
+npm run start:simulator -- --host 127.0.0.1 --port 9000
+```
+
+说明：
+
+- 当前 `start:simulator` 默认会带透析机报文和血压报文混合发送
+- 如仅需发送血压，可执行 `npm run start:simulator:bp`
+
+自定义血压参数示例：
+
+```powershell
+npm run start:simulator -- --bp-systolic 135 --bp-diastolic 88 --bp-pulse 76
+```
+
+## 7. Windows 部署
建议目录：
@@ -246,7 +364,21 @@
.\jhm-service.exe --config .\runtime\config.json
```
-## 7. Linux 部署
+如需安装为服务，可使用：
+
+```powershell
+cd .\service
+.\install-service.ps1
+```
+
+卸载服务：
+
+```powershell
+cd .\service
+.\uninstall-service.ps1
+```
+
+## 8. Linux 部署
建议目录：
@@ -262,7 +394,32 @@
./jhm-service --config ./runtime/config.json
```
-## 8. 验证建议
+如需安装为 systemd 服务，可参考：
+
+```bash
+cd ./service
+chmod +x ./install-service.sh ./uninstall-service.sh
+./install-service.sh
+```
+
+## 9. 运行日志说明
+
+当前服务运行日志统一输出中文，默认写入：
+
+```text
+runtime/logs 或配置中的 logging.dir
+```
+
+重点关注以下日志：
+
+- TCP 监听成功
+- 设备连接和断开
+- 收到指标
+- 血压报文触发整包立即发送
+- MQTT 发布成功或失败
+- 阿里云属性上报成功或失败
+
+## 10. 验收建议
部署完成后建议执行：
@@ -271,10 +428,13 @@
npm run verify:commands
```
-重点确认：
+现场重点确认：
-- TCP 端口监听正常
-- 设备连接日志正常
-- 原透析机数据解析正常
+- TCP 监听正常
+- 设备接入 IP 匹配正常
+- 透析机 `EE 55` 报文解析正常
- 血压计 `AA 55` 报文解析正常
-- `M` 字段是否符合现场需求
+- 血压到达后是否按预期立即整包发送
+- 1 分钟批量发送是否仍正常执行
+- MQTT 或阿里云上报结果正常
+- 日志文件持续输出正常
--
Gitblit v1.8.0