配置文件说明文档

版本: v1.1.0
最后更新: 2025-12-10

---

📋 目录

1. 概述
2. homeConfig.json
3. mqtt.json
4. httpConfig.json
5. aliyun.json
6. schema.json
7. 常见问题

---

概述

系统使用多个 JSON 配置文件来管理不同模块的参数。所有配置文件都应该放在应用程序的根目录中。

配置文件加载优先级

当前工作目录 (开发环境)
        ↓
可执行文件所在目录 (pkg 打包环境)
        ↓
硬编码默认值

环境变量覆盖

某些配置可以通过环境变量覆盖：

# Socket 服务端口
PORT=10961 npm start

# HTTP 服务端口
HTTP_PORT=8080 npm start

---

homeConfig.json

用途: Socket 服务器和主服务配置

位置: 应用程序根目录

优先级: 环境变量 > homeConfig.json > 默认值

完整配置示例

{
  "socketPort": 10961,
  "description": "Socket服务器监听端口"
}

配置字段说明

字段	类型	默认值	说明	示例
socketPort	number	10961	Socket服务器监听的端口号	10961

| description | string | - | 配置文件描述（可选） | Socket服务器监听端口 |

使用方式

// 在 index.js 中
const homeConfig = JSON.parse(fs.readFileSync(homeConfigPath, 'utf8'));
const PORT = process.env.PORT || homeConfig.socketPort || 10961;

修改示例

{
  "socketPort": 9999,
  "description": "自定义Socket服务器监听端口"
}

---

mqtt.json

用途: MQTT 消息队列服务配置

位置: 应用程序根目录

依赖包: mqtt@5.13.3

完整配置示例

{
  "enabled": true,
  "brokerUrl": "mqtt://127.0.0.1:1883",
  "clientId": "dialysis-server-01",
  "username": "admin",
  "password": "admin123",
  "keepalive": 60,
  "reconnectPeriod": 5000,
  "defaultTopicPrefix": "device/data",
  "qos": 1,
  "retain": false
}

配置字段说明

字段	类型	默认值	说明	示例
enabled	boolean	true	是否启用 MQTT 功能	true/false
brokerUrl	string	mqtt://127.0.0.1:1883	MQTT Broker 服务器地址	mqtt://192.168.1.100:1883
clientId	string	dialysis-server-01	MQTT 客户端 ID（需唯一）	device-server-01
username	string	admin	MQTT 连接用户名	mqtt_user
password	string	admin123	MQTT 连接密码	secure_password_123
keepalive	number	60	心跳间隔（秒）	60
reconnectPeriod	number	5000	重连间隔（毫秒）	5000
defaultTopicPrefix	string	device/data	MQTT 主题前缀	device/dialysis
qos	number	1	QoS 级别（0/1/2）	1
retain	boolean	false	消息是否保留	false

使用方式

// 在 index.js 中
const mqttConfig = JSON.parse(fs.readFileSync(mqttConfigPath, 'utf8'));

if (mqttConfig.enabled) {
    const topic = `${mqttConfig.defaultTopicPrefix}/${deviceNo}`;
    publishMessage(topic, payload);
}

常见场景

场景1：禁用 MQTT

{
  "enabled": false
}

场景2：使用云端 MQTT（如阿里云）

{
  "enabled": true,
  "brokerUrl": "mqtt://mqtt.aliyuncs.com:1883",
  "username": "xxxxx@instance123|securemode=2,signmethod=hmacsha256",
  "password": "your_password",
  "clientId": "device_client_id"
}

---

httpConfig.json

用途: HTTP API 服务器配置

位置: 应用程序根目录

完整配置示例

{
  "port": 8080,
  "host": "0.0.0.0",
  "cors": {
    "enabled": true,
    "origin": "*"
  },
  "rateLimit": {
    "enabled": true,
    "singleDeviceInterval": 5000,
    "allDevicesInterval": 60000
  },
  "propertyMapping": {
    "enabled": true,
    "useEmbeddedSchema": true
  },
  "cache": {
    "enabled": true
  }
}

配置字段说明

基础配置

字段	类型	默认值	说明	示例
port	number	8080	HTTP 服务器监听端口	8080
host	string	0.0.0.0	服务器绑定地址（0.0.0.0 表示所有网卡）	127.0.0.1

CORS 配置

字段	类型	默认值	说明	示例
cors.enabled	boolean	true	是否启用 CORS 跨域	true
cors.origin	string	*	允许的来源（* 表示所有）	https://example.com

限流配置

字段	类型	默认值	说明	备注
rateLimit.enabled	boolean	true	是否启用限流	生产环境建议启用
rateLimit.singleDeviceInterval	number	5000	单个设备查询限流间隔（毫秒）	同一设备 5 秒最多 1 次
rateLimit.allDevicesInterval	number	60000	全局查询限流间隔（毫秒）	所有设备 60 秒最多 1 次

属性映射配置

字段	类型	默认值	说明	备注
propertyMapping.enabled	boolean	true	是否启用属性映射	推荐启用
propertyMapping.useEmbeddedSchema	boolean	true	是否使用内嵌 schema	false 时使用 schema.json

缓存配置

字段	类型	默认值	说明	备注
cache.enabled	boolean	true	是否启用数据缓存	建议启用以提升性能

使用方式

// 在 httpServer.js 中
const httpConfig = JSON.parse(fs.readFileSync(httpConfigPath, 'utf8'));
const server = http.createServer((req, res) => {
    if (httpConfig.cors.enabled) {
        res.setHeader('Access-Control-Allow-Origin', httpConfig.cors.origin);
    }
});

修改示例

仅本地访问

{
  "port": 8080,
  "host": "127.0.0.1",
  "cors": {
    "enabled": false
  }
}

生产环境高性能配置

{
  "port": 8080,
  "host": "0.0.0.0",
  "cors": {
    "enabled": true,
    "origin": "https://your-domain.com"
  },
  "rateLimit": {
    "enabled": true,
    "singleDeviceInterval": 5000,
    "allDevicesInterval": 60000
  },
  "cache": {
    "enabled": true
  }
}

---

aliyun.json

用途: 阿里云 IoT 平台集成配置

位置: 应用程序根目录

依赖包: aliyun-iot-device-sdk

完整配置示例

{
  "enabled": true,
  "region": "cn-shanghai",
  "productKey": "your_product_key",
  "description": "阿里云IoT设备连接配置（需从阿里云控制台获取）"
}

配置字段说明

字段	类型	默认值	说明	示例
enabled	boolean	true	是否启用阿里云功能	true/false
region	string	cn-shanghai	阿里云服务区域	cn-shanghai, cn-beijing

| productKey | string | - | 阿里云产品 Key（从控制台获取） | a1xxxxxxxxxxxxb |
| description | string | - | 配置说明（可选） | 阿里云IoT配置 |

使用方式

// 在 index.js 中
const aliyunConfig = JSON.parse(fs.readFileSync(aliyunConfigPath, 'utf8'));

if (aliyunConfig.enabled) {
    // 连接到阿里云 IoT 平台
    const device = aliyunIot.device({
        ProductKey: aliyunConfig.productKey,
        DeviceName: deviceName,
        DeviceSecret: deviceSecret
    });
}

禁用阿里云

{
  "enabled": false
}

注意事项

⚠️ 安全提示:
- 不要将真实的 productKey 提交到公开代码仓库
- 生产环境建议使用环境变量替代敏感信息
- 确保配置文件的访问权限受限

---

schema.json

用途: 设备属性 TSL（Thing Specification Language）定义

位置: 应用程序根目录

备注: 68 个属性的完整定义，与 propertyMapper.js 中的定义同步

完整配置示例（部分）

{
  "version": "1.0.0",
  "properties": [
    {
      "identifier": "A",
      "name": "脱水目标量",
      "dataType": "float",
      "accessMode": "r",
      "unit": "kg",
      "description": "患者脱水目标量"
    },
    {
      "identifier": "B",
      "name": "脱水量",
      "dataType": "float",
      "accessMode": "r",
      "unit": "kg",
      "description": "当前已脱水的量"
    },
    {
      "identifier": "R",
      "name": "收缩压下限",
      "dataType": "int",
      "accessMode": "r",
      "unit": "mmHg",
      "description": "血压收缩压下限"
    },
    {
      "identifier": "IPAddress",
      "name": "IP地址",
      "dataType": "string",
      "accessMode": "r",
      "description": "设备连接的IP地址"
    }
  ]
}

属性字段说明

字段	类型	说明	示例
identifier	string	属性唯一标识符（A-Z, a-z, C53-C55 等）	A, B, C, IPAddress
name	string	属性中文名称（用户可读）	脱水目标量
dataType	string	数据类型（int, float, string, bool）	float
accessMode	string	访问模式（r 读, w 写, rw 读写）	r
unit	string	单位（可选）	kg, mmHg, bpm
description	string	属性描述（可选）	患者脱水目标量

完整属性列表（68 个）

详见 schema.json 文件的完整内容。主要分类：

• A-Z (26 个): 基本生命体征和治疗参数
• a-z (26 个): 扩展参数
• C53-C55 (3 个): 特殊参数
• 特殊字段 (13 个): deviceName, IPAddress, deviceType 等

---

常见问题

Q1: 启动时报错 "找不到配置文件"

A: 确保以下文件存在于应用程序同目录：
- homeConfig.json ✅
- mqtt.json ✅
- httpConfig.json ✅
- aliyun.json ✅
- schema.json ✅

Q2: 我想禁用某个功能，应该怎么做？

A: 在对应的配置文件中设置 enabled: false：

// 禁用 MQTT
{ "enabled": false }

// 禁用阿里云
{ "enabled": false }

// 禁用 CORS
{ "cors": { "enabled": false } }

Q3: 配置文件修改后需要重启吗？

A: 是的，需要重启应用程序才能加载新的配置：

npm run pkg    # 重新打包
npm start      # 重新启动

Q4: 环境变量如何设置？

A: 在启动命令前设置环境变量：

# Windows PowerShell
$env:PORT=10961; npm start

# Windows CMD
set PORT=10961 && npm start

# Linux/Mac
PORT=10961 npm start

Q5: MQTT 连接失败怎么办？

A: 检查以下内容：
1. Broker URL 是否正确
2. 用户名和密码是否正确
3. 防火墙是否允许 MQTT 端口（通常 1883）
4. MQTT Broker 服务是否运行

{
  "brokerUrl": "mqtt://your_broker_ip:1883",
  "username": "your_username",
  "password": "your_password"
}

Q6: 如何修改 HTTP 服务端口？

A: 修改 httpConfig.json：

{
  "port": 8080,
  "host": "0.0.0.0"
}

或使用环境变量：

HTTP_PORT=9000 npm start

Q7: 限流规则是什么？

A: 在 httpConfig.json 中配置：

{
  "rateLimit": {
    "enabled": true,
    "singleDeviceInterval": 5000,      // 单个设备 5 秒内最多 1 次
    "allDevicesInterval": 60000        // 全部设备 60 秒内最多 1 次
  }
}

Q8: 如何在生产环境中安全地使用配置文件？

A: 建议做法：

1. 敏感信息使用环境变量:
   bash MQTT_PASSWORD=xxx ALIYUN_KEY=xxx npm start

2. 配置文件不提交敏感信息:
   json { "password": "${MQTT_PASSWORD}" }

3. 限制文件权限:
   bash chmod 600 homeConfig.json mqtt.json

4. 定期更新密码

Q9: 多个实例如何使用不同的配置？

A: 使用环境变量覆盖：

# 实例 1
PORT=10961 HTTP_PORT=8080 npm start

# 实例 2
PORT=10962 HTTP_PORT=8081 npm start

---

快速参考表

配置文件概览

文件名	用途	必需	可禁用
homeConfig.json	Socket 端口配置	✅	❌
mqtt.json	MQTT 服务配置	✅	✅
httpConfig.json	HTTP API 配置	✅	❌
aliyun.json	阿里云 IoT 配置	✅	✅
schema.json	属性定义	✅	❌

服务启动流程

启动应用
  ↓
读取 homeConfig.json → 启动 Socket 服务
  ↓
读取 mqtt.json → 初始化 MQTT（若启用）
  ↓
读取 httpConfig.json → 启动 HTTP 服务
  ↓
读取 aliyun.json → 连接阿里云（若启用）
  ↓
读取 schema.json → 初始化属性映射
  ↓
系统运行 ✅

---

更新日志

v1.1.0 (2025-12-10)

• 新增 homeConfig.json Socket 端口配置
• 更新所有配置文件说明
• 添加常见问题解答
• 增加安全建议

v1.0.0 (2025-12-08)

• 初始版本

---

最后更新: 2025-12-10
版本: v1.1.0
维护者: 技术团队