网关 API
开发预览
本页按提交 b1a16cbc 实际注册的路由和解析器编写（ApiRouter + 各 RouteGroup），不沿用项目旧文档的端点总数或未实现字段。路由存在不等于端到端工作流完成，尤其是驱动注册、MQTT 反向控制、恢复出厂和 OTA。
1. 基础地址与响应
默认基础地址：
http://<gateway-ip>:8080除 Prometheus 指标等明确说明的接口外，JSON 响应统一包装为：
{
"code": 200,
"msg": "ok",
"data": {}
}创建成功通常使用 HTTP 201 和 msg: "created"；错误使用相应 HTTP 状态码及 msg（400 参数错误 / 401 未授权 / 404 不存在 / 409 冲突 / 500、502、503 服务端错误）。GET /api/metrics 直接返回 text/plain 指标，不使用上述 JSON 包装。
2. 登录与 Token
POST /api/auth/login 无需既有 Token，请求：
{
"username": "admin",
"password": "<changed-password>"
}curl -fsS http://127.0.0.1:8080/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"<changed-password>"}'成功时 data 包含 token、username、role、createdAt 和 expiresAt。受保护路由使用：
Authorization: Bearer <token>初始默认密码为 admin123，必须立即修改；当前中间件验证 Token 存在与有效性，不应宣称所有路由都执行了角色级授权。
无需 Token 的接口（认证白名单与免认证端点）：
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /api/auth/login | 登录并获取 Token |
POST | /api/auth/logout | 登出（位于白名单） |
GET | /api/health | 进程健康、版本、运行时间、MQTT 和 Tag 数量 |
GET | /api/metrics | Prometheus 文本指标 |
这些无认证端点应通过网络边界限制暴露。
3. 概览 API
| 方法 | 路径 | 当前行为 |
|---|---|---|
GET | /api/health | 健康检查（免认证）：状态、版本、运行时间、MQTT 连接、Tag 数 |
GET | /api/overview/status | 系统状态：CPU/内存/温度/磁盘使用率与时间戳 |
GET | /api/overview/devices | 内部设备 total/online/offline 统计 |
GET | /api/overview/traffic | MQTT 字节、消息、发布、订阅和重连统计 |
4. 设备与 Tag 管理 API
| 方法 | 路径 | 当前行为 |
|---|---|---|
GET | /api/devices | 子设备列表 |
POST | /api/devices | 新增子设备，成功为 201；ID 重复返回 409 |
PUT | /api/devices/:id | 替换设备模型，路由 ID 覆盖请求 ID；不存在返回 404 |
DELETE | /api/devices/:id | 删除设备并清理 TagEngine 中的关联 Tag |
GET | /api/devices/:id/tags | 指定设备的 Tag 列表 |
POST | /api/devices/:id/tags | 新增 Tag，路由设备 ID 覆盖请求设备 ID |
PUT | /api/devices/:id/tags/:tagId | 修改 Tag，路由 ID 覆盖请求 ID |
DELETE | /api/devices/:id/tags/:tagId | 删除 Tag |
设备新增示例：
{
"deviceId": "modbus-dev-001",
"productId": "demo-product",
"deviceNum": "modbus-001",
"deviceName": "Modbus development device 001",
"protocolType": "modbus"
}Tag 新增示例：
{
"id": "holding-0",
"name": "Holding register 0",
"sourceType": 0,
"slaveAddr": 1,
"registerAddr": 0,
"registerCount": 1,
"scale": 1,
"offset": 0,
"pollIntervalMs": 1000,
"reportOnChange": false,
"enabled": true
}sourceType: 0 为 Modbus，寄存器为零基地址。请求解析器不读取 dataType、functionCode 或字节序字段，详见配置。设备或 Tag 创建成功不代表驱动已经注册，详见快速开始的当前阻塞。
5. GPIO API
| 方法 | 路径 | 当前行为 |
|---|---|---|
GET | /api/gpio/di | DI 通道状态列表（channel/name/state/changed/timestamp） |
GET | /api/gpio/do | DO 通道状态列表 |
POST | /api/gpio/do/:channel | DO 控制，请求体 {"state": true} |
GET | /api/gpio/ai | AI 通道值（rawValue/engValue/unit） |
真实 GPIO 依赖编译时 FASTBEE_ENABLE_GPIO=ON 与 libgpiod；默认构建使用模拟后端。
6. MQTT API
| 方法 | 路径 | 当前行为 |
|---|---|---|
GET | /api/mqtt/config | 返回连接配置摘要；活动字段名包括 useTls，初始化客户端时还包括 keepAlive |
PUT | /api/mqtt/config | 仅更新 broker、port、clientId、username、password 并保存，不重连 |
GET | /api/mqtt/status | 返回连接状态、Broker、消息/错误/重连统计 |
Web 的"保存并重连"文案以及提交的 TLS、KeepAlive、QoS 字段不代表活动 PUT 已处理这些行为。只读配置挂载还可能导致保存失败。
注意：源码中存在证书管理路由实现（POST/GET/DELETE /api/mqtt/certificates），但当前注册流程未挂载该路由组，不能当作可用端点。
7. 系统管理 API
| 方法 | 路径 | 注意事项 |
|---|---|---|
GET | /api/system/info | 版本、构建时间、平台、主机名和运行时间 |
POST | /api/system/reboot | 返回后约 1 秒真实执行系统重启命令，必须严格限制 Token 和网络 |
POST | /api/system/factory-reset | 占位：只记录日志并返回 {"resetting":true}，没有完成配置清理 |
GET | /api/system/config | 导出配置（经 ConfigManager，真实可用） |
POST | /api/system/config | 导入配置（经 ConfigManager，真实可用） |
POST | /api/system/upgrade | 占位：只检查 multipart 中的 firmware 字段并返回文件名、大小和 uploading，未完成 OTA 安装、验证或回滚 |
GET | /api/system/time | 当前时间 |
POST | /api/system/time/sync | NTP 同步，可传 server、timeoutMs |
GET / POST | /api/system/timezone | 读取或设置时区 |
恢复出厂与 OTA 的响应不能作为生产成功证据。
8. 认证与用户 API
| 方法 | 路径 | 当前行为 |
|---|---|---|
POST | /api/auth/login | 登录（SHA-256 口令散列校验），返回 Token |
POST | /api/auth/logout | 注销当前 Token |
GET | /api/users | 用户列表 |
POST | /api/users | 新增用户（username/password/role，角色如 admin/operator/viewer），成功为 201 |
PUT | /api/users/:id | 修改用户角色、启用状态或密码 |
角色权限模型（admin/operator/viewer）已定义，但当前中间件只验证 Token，不等于路由级角色授权已完备。
9. 调试 API
| 方法 | 路径 | 当前行为与风险 |
|---|---|---|
GET | /api/debug/tags | 执行一次全量 pollOnce()，返回 Tag 和引擎统计 |
POST | /api/debug/read | 忽略请求的设备/Tag ID，执行全量 pollOnce() |
POST | /api/debug/write | 按 tagId 和 value 调用 TagEngine::writeTag()，仍需注册驱动 |
POST | /api/debug/ping | 将 host 拼接进系统命令，存在命令注入风险 |
GET | /api/debug/logs | 返回内存日志尾部约 50 条 |
手工写请求：
{
"tagId": "holding-0",
"value": 1
}value 可为布尔、整数、浮点或字符串。Stub 的 success: true 可能只是模拟结果，不能证明物理写入。生产代码没有调用 subscribeFunction，所以该接口也不是 MQTT 云端反向控制的替代品。
调试接口安全
不要把 /api/debug/* 暴露到不受信任网络。尤其 /api/debug/ping 存在命令注入风险，应先修复或隔离；全量读取和写入也应评估现场总线负载与物理影响。
10. 告警 API（alerts）
告警管理器（AlertManager）的活跃告警与历史接口：
| 方法 | 路径 | 当前行为 |
|---|---|---|
GET | /api/alerts | 活跃告警列表 |
POST | /api/alerts | 手动触发告警（source/level/message/extra），成功为 201 |
POST | /api/alerts/:id/ack | 确认告警 |
POST | /api/alerts/:id/silence | 消音告警 |
DELETE | /api/alerts/:id | 清除告警 |
DELETE | /api/alerts | 清除所有已确认告警 |
GET | /api/alerts/history | 告警历史，支持 ?limit=（默认 100） |
GET | /api/alerts/stats | 告警统计 |
11. 报警引擎 API（alarms）
工业报警规则与活跃报警接口（注意路径为复数 /api/alarms，与项目旧文档的 /api/alarm 不同）：
| 方法 | 路径 | 当前行为 |
|---|---|---|
GET | /api/alarms/rules | 报警规则列表 |
POST | /api/alarms/rules | 创建报警规则（字段见配置第 8 节），成功为 201 |
PUT | /api/alarms/rules/:id | 更新报警规则，URL 中 ID 优先 |
DELETE | /api/alarms/rules/:id | 删除报警规则 |
GET | /api/alarms/rules/by-tag/:tagId | 按 Tag 查询规则 |
GET | /api/alarms/active | 活跃报警列表 |
GET | /api/alarms/active/by-tag/:tagId | 按 Tag 查询活跃报警 |
POST | /api/alarms/:ruleId/ack | 确认报警 |
POST | /api/alarms/:ruleId/silence | 消音报警 |
GET | /api/alarms/stats | 报警统计 |
GET | /api/alarms/export | 导出所有规则 |
POST | /api/alarms/import | 导入规则（replace 控制是否整体替换） |
12. 外设管理 API（peripherals）
外设配置中心接口（外设模型详见外设与联动）：
| 方法 | 路径 | 当前行为 |
|---|---|---|
GET | /api/peripherals | 外设列表 |
POST | /api/peripherals | 新增外设（ID 唯一、引脚冲突校验），成功为 201 |
PUT | /api/peripherals/:id | 更新外设（ID 不可改） |
DELETE | /api/peripherals/:id | 删除外设 |
POST | /api/peripherals/:id/enable | 启用外设（校验引脚冲突） |
POST | /api/peripherals/:id/disable | 禁用外设 |
POST | /api/peripherals/:id/test | 测试动作：DO 翻转 / LED 点亮 / 蜂鸣器试鸣，其他类型返回 400 |
GET | /api/peripherals/export | 导出外设配置 |
POST | /api/peripherals/import | 导入外设配置 |
13. 外设执行规则 API（periph-exec）
联动规则引擎接口（触发器/动作模型详见外设与联动）：
| 方法 | 路径 | 当前行为 |
|---|---|---|
GET | /api/periph-exec | 规则列表（含最近执行时间与结果） |
POST | /api/periph-exec | 创建规则，成功为 201 |
PUT | /api/periph-exec/:id | 更新规则 |
DELETE | /api/periph-exec/:id | 删除规则 |
POST | /api/periph-exec/:id/enable | 启用/禁用（请求体 {"enabled": false}） |
POST | /api/periph-exec/:id/run-once | 手动执行一次（可带 {"value": "..."}） |
GET | /api/periph-exec/results | 最近执行结果 |
GET | /api/periph-exec/export | 导出规则 |
POST | /api/periph-exec/import | 导入规则 |
14. 驱动健康与 Tag 聚合 API
| 方法 | 路径 | 当前行为 |
|---|---|---|
GET | /api/drivers/health | 全部驱动健康摘要（total/healthy/isolated 与各驱动统计） |
GET | /api/drivers/:name/health | 单个驱动健康详情；未找到返回 404 |
GET | /api/aggregator/rules | 聚合规则列表 |
GET | /api/aggregator/rules/:id/result | 聚合结果（value/sampleCount/lastUpdateMs/valid） |
当前没有注册创建聚合规则的接口；驱动健康数据需结合"驱动尚未注册到 TagEngine"的前提解读。
15. Prometheus 指标 API
| 方法 | 路径 | 当前行为 |
|---|---|---|
GET | /api/metrics | Prometheus 文本指标（免认证），含运行时间、系统资源、Tag 数、MQTT 统计等 |