# 配置文件说明文档

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

---

## 📋 目录

1. [概述](#概述)
2. [homeConfig.json](#homeconfigjson)
3. [mqtt.json](#mqttjson)
4. [httpConfig.json](#httpconfigjson)
5. [aliyun.json](#aliyunjson)
6. [schema.json](#schemajson)
7. [常见问题](#常见问题)

---

## 概述

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

### 配置文件加载优先级

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

### 环境变量覆盖

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

```bash
# Socket 服务端口
PORT=10961 npm start

# HTTP 服务端口
HTTP_PORT=8080 npm start
```

---

## homeConfig.json

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

**位置**: 应用程序根目录

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

### 完整配置示例

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

### 配置字段说明

| 字段 | 类型 | 默认值 | 说明 | 示例 |
|------|------|--------|------|------|
| `socketPort` | number | 10961 | Socket服务器监听的端口号 | 10961 |
| `description` | string | - | 配置文件描述（可选） | Socket服务器监听端口 |

### 使用方式

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

### 修改示例

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

---

## mqtt.json

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

**位置**: 应用程序根目录

**依赖包**: `mqtt@5.13.3`

### 完整配置示例

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

### 使用方式

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

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

### 常见场景

#### 场景1：禁用 MQTT
```json
{
  "enabled": false
}
```

#### 场景2：使用云端 MQTT（如阿里云）
```json
{
  "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 服务器配置

**位置**: 应用程序根目录

### 完整配置示例

```json
{
  "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 | 是否启用数据缓存 | 建议启用以提升性能 |

### 使用方式

```javascript
// 在 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);
    }
});
```

### 修改示例

#### 仅本地访问
```json
{
  "port": 8080,
  "host": "127.0.0.1",
  "cors": {
    "enabled": false
  }
}
```

#### 生产环境高性能配置
```json
{
  "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`

### 完整配置示例

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

### 使用方式

```javascript
// 在 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
    });
}
```

### 禁用阿里云

```json
{
  "enabled": false
}
```

### 注意事项

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

---

## schema.json

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

**位置**: 应用程序根目录

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

### 完整配置示例（部分）

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

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

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

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

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

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

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

### Q4: 环境变量如何设置？

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

```bash
# 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 服务是否运行

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

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

**A**: 修改 `httpConfig.json`：

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

或使用环境变量：

```bash
HTTP_PORT=9000 npm start
```

### Q7: 限流规则是什么？

**A**: 在 `httpConfig.json` 中配置：

```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**: 使用环境变量覆盖：

```bash
# 实例 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  
**维护者**: 技术团队