参考层 · 平台端细节，汇总 MQTT、数据库、HTTP API 和部署方式相关说明

后端服务

history_service 是这套系统的中枢层，负责 MQTT、数据库和 HTTP API 三件事的衔接。

一句话结论

后端不是单纯的数据转存模块，而是设备上报、历史存储和前端控制的统一入口。

主要职责

1. 订阅设备上行主题 device/stm32f103/up
2. 将解析后的遥测数据写入 PostgreSQL
3. 通过 HTTP API 向前端提供实时与历史数据
4. 将前端控制命令转换成 MQTT 下行消息，发布到 device/stm32f103/down

运行方式

本地运行

cd history_service
go mod download
go run .

Docker 运行

cd history_service
docker build -t history_service .
docker run --rm -p 5001:5001 --env-file .env history_service

GHCR 镜像

当前仓库 Docker workflow 会发布镜像到：

ghcr.io/levi882/stm32/history_service:latest

关键环境变量

1. DATABASE_URL
2. PG_SSL
3. HTTP_HOST
4. HTTP_PORT
5. MQTT_BROKER_HOST
6. MQTT_BROKER_PORT
7. MQTT_USERNAME
8. MQTT_PASSWORD
9. MQTT_TOPIC_UP
10. MQTT_TOPIC_DOWN
11. API_TOKEN
12. CORS_ALLOW_ORIGIN

/api/latest 字段语义

空气质量相关字段尤其需要区分：

字段	含义
gasPpm	由 MQ135 AO 模拟量换算得到的 ppm 估算值
gas	MQ135 硬件比较器状态，true 表示 DO 触发
gasCalibrated	MQ135 是否完成预热 / 校准
alarm	主告警状态
alarmEnabled	告警开关是否启用

说明：

1. gas 不是主告警本身
2. 当前主告警由温度、湿度和 gasPpm 软件阈值共同决定
3. gasCalibrated=false 时前端会显示“预热中”

主要 HTTP API

1. GET /api/health
2. GET /api/latest
3. GET /api/history?limit=60
4. POST /api/command/led
5. GET/POST /api/alarm/config
6. GET/POST /api/fan/config
7. GET /api/city-air
8. GET/POST /api/weather/config

数据流

1. 设备上报 MQTT 消息
2. history_service 解析并存储
3. 前端通过 HTTP 拉取展示
4. 前端控制通过 HTTP 进入后端
5. 后端把控制转换为 MQTT 下行消息发回设备