lupinskilukasz/flexbit-iot-agent
GitHub: lupinskilukasz/flexbit-iot-agent
这是一个用于收集发电厂遥测数据并转发至本地时序数据库的边缘代理工具。
Stars: 0 | Forks: 0
·
Flexbit IoT Agent
用于分布式能源资源遥测的边缘盒代理
本仓库包含使用 **Docker Compose 本地运行 Flexbit IoT Agent** 所需的一切。应用镜像从 GitHub 容器仓库拉取 —— 无需源代码、无需构建步骤、您的机器上也无需安装 .NET SDK。
本仓库面向希望评估该代理、基于其 REST 和 MQTT 接口构建数据管道、或在开发期间将其用作本地数据摄入端点的合作伙伴和集成商。
## 目录
1. [您将获得什么](#1-what-you-get)
2. [架构](#2-architecture)
3. [要求](#3-requirements)
4. [快速入门](#4-quick-start)
5. [初步了解](#5-first-look-around)
6. [发送遥测数据](#6-sending-telemetry)
7. [配置参考](#7-configuration-reference)
8. [操作技术栈](#8-operating-the-stack)
9. [升级](#9-upgrading)
10. [故障排除](#10-troubleshooting)
11. [文档](#11-documentation)
12. [项目状态与路线图](#12-project-status--roadmap)
13. [支持与联系](#13-support--contact)
14. [贡献者](#14-contributors)
15. [许可证](#15-license)
## 1. 您将获得什么
该 compose 技术栈启动五个容器：
| 服务 | 镜像 | 用途 |
|-------------------|----------------------------------------|-------------------------------------------------------------|
| `agent` | `ghcr.io/lupinskilukasz/flexbit-iot-agent:
` | Flexbit IoT Agent —— REST + MQTT 数据摄入、管理界面、/metrics |
| `mosquitto` | `eclipse-mosquitto:2` | 用于设备式发布者的 MQTT 代理 |
| `influxdb` | `influxdb:3-core` | 时间序列数据库（禁用认证 —— 仅用于本地开发） |
| `influxdb-init` | `influxdb:3-core` | 一次性任务，用于创建 `telemetry` 数据库 |
| `grafana` | `grafana/grafana:11.3.0` | 可视化工具，预配置的仪表板 |
捆绑资源（位于此仓库中）：
- `docker-compose.yml` —— 编排定义文件。
- `.env.example` —— 环境变量模板。
- `mosquitto/mosquitto.conf` —— 代理配置（匿名，单个 TCP 监听器）。
- `grafana/provisioning/` —— InfluxDB 数据源 + 仪表板提供程序。
- `grafana/dashboards/iot-overview.json` —— `iot-agent-overview` 仪表板。
- `INTEGRATION.md` —— 面向合作伙伴的集成指南（REST、MQTT、管理界面、配置、诊断）。
- `CHANGELOG.md` —— 代理的已发布版本。
## 2. 架构
```
┌────────────┐ REST ┌──────────────┐
│ Producer A │──────────────▶│ │
└────────────┘ │ Agent │ line protocol ┌──────────┐
│ (Ingest → │───────────────────▶│ InfluxDB │
┌────────────┐ MQTT │ Bus → │ │ 3 │
│ Producer B │──────────────▶│ Influx) │ └─────┬────┘
└────────────┘ └──────┬───────┘ │
│ iframe │ query
┌──────▼───────┐ │
│ Grafana │◀─────────────────────────┘
└──────────────┘
```
该代理是一个模块化单体应用 (`Agent.Host`)。入站传输层 —— REST 和 MQTT —— 共享相同的验证管道，将接受的测量值推送到进程内的有界通道，一个后台写入器将通道中的数据引流到 InfluxDB。操作员界面与 API 在同一 HTTP 端口上提供服务，并嵌入了捆绑的 Grafana 仪表板。
完整的接口文档位于 [`INTEGRATION.md`](INTEGRATION.md)。
## 3. 要求
| 项目 | 版本 / 说明 |
|------------------|--------------------------------------------------------------------------|
| 操作系统 | Linux、macOS 或带 WSL2 的 Windows |
| Docker Engine | **24.0 或更新版本** |
| Docker Compose | **v2** (`docker compose` 插件，而非旧版的 `docker-compose` 二进制文件) |
| CPU | x86_64 或 arm64。代理镜像以多架构清单形式发布。 |
| 内存 | 整个技术栈需 **≥ 2 GB** 空闲内存 |
| 磁盘 | 容器镜像和持久卷需 **≥ 2 GB** 空闲空间 |
| 开放端口 | 在 `localhost` 上需要 `8080`、`1883`、`3000`、`8181` —— 见下表 |
| 出站网络 | 可访问 `ghcr.io`、`docker.io`（或 `mcr.microsoft.com` 镜像站）以拉取镜像 |
用于尝试的可选工具：
- `curl` —— 用于调用 REST API。
- `mosquitto-clients` (`mosquitto_pub`) —— 用于发布测试 MQTT 消息。
### 端口
| 端口 | 主机服务 |
|---------|---------------------------------------------|
| `8080` | 代理 REST API、管理界面、`/metrics` |
| `1883` | Mosquitto MQTT 代理（纯 TCP） |
| `3000` | Grafana |
| `8181` | InfluxDB 3 Core HTTP API |
所有端口都绑定到主机。如果其中任何端口已被占用，请编辑 `docker-compose.yml` 并调整 `ports:` 映射 —— 内部容器网络不受影响。
## 4. 快速入门
```
# 1. Clone this repository
git clone https://github.com/lupinskilukasz/flexbit-iot-agent.git
cd flexbit-iot-agent
# 2. Prepare environment variables
cp .env.example .env
# (edit .env if you want to pin a specific agent image version)
# 3. Pull the images and start the stack
docker compose pull
docker compose up -d
# 4. Verify the agent is alive
curl http://localhost:8080/health/live
# → {"status":"alive"}
curl http://localhost:8080/health/ready
# → {"status":"ready","influx":"ok","mqtt":"ok","bus":"ok"}
```
## 5. 初步了解
| URL | 您将看到的内容 |
|--------------------------------------|-----------------------------------------------------------|
| `http://localhost:8080/` | 操作员管理界面的登录屏幕 |
| `http://localhost:8080/admin` | 实时状态（登录后） |
| `http://localhost:8080/admin/grafana`| 嵌入式遥测仪表板，已过滤到您的代理 |
| `http://localhost:8080/metrics` | Prometheus 指标 |
| `http://localhost:3000/` | 直接访问 Grafana。已启用匿名查看；管理员账户为 admin / admin |
**登录。** 捆绑的构建包含一个模拟认证提供程序，它接受任何非空的用户名和密码。您选择的用户名将成为您的 `agent_id`（格式为 `site_`），并持久保存在代理的本地 LiteDB 中。请选择一个易记的名称 —— 每个测量值都会带有此标签。
## 6. 发送遥测数据
代理以两种等效方式接受测量值。
### REST —— 单次测量
```
curl -i -X POST http://localhost:8080/v1/telemetry/ \
-H 'Content-Type: application/json' \
-d '{
"field_id": "pv_inv_power_active",
"ts": "2026-04-27T08:00:00Z",
"value": 48.2
}'
```
### REST —— 批量（每请求最多 1000 项）
```
curl -i -X POST http://localhost:8080/v1/telemetry/batch \
-H 'Content-Type: application/json' \
-d '{
"measurements": [
{"field_id":"pv_inv_power_active","ts":"2026-04-27T08:00:00Z","value":48.2},
{"field_id":"pv_grid_voltage_l1", "ts":"2026-04-27T08:00:00Z","value":230.4}
]
}'
```
### MQTT
```
mosquitto_pub -h localhost -p 1883 -q 1 \
-t 'telemetry/v1/pv/inv/power/active' \
-m '{"ts":"2026-04-27T08:00:00Z","value":48.2}'
```
主题*就是*将 `_` 替换为 `/` 的 `field_id`。还提供了一个批量主题 (`telemetry/v1/batch`) —— 完整的契约请参阅 [`INTEGRATION.md`](INTEGRATION.md)，包括 `field_id` 命名规则、时间戳窗口、错误响应和存储架构。
发布测量值后，打开 `http://localhost:8080/admin/grafana`，数据点应在几秒钟内可见。
## 7. 配置参考
大多数设置都有合理的默认值，无需修改。通过 `.env` 暴露的两个可调参数是：
| 变量 | 默认值 | 含义 |
|----------------------|------------------------------------|-------------------------------------------------------------|
| `IOT_AGENT_IMAGE` | `ghcr.io/lupinskilukasz/flexbit-iot-agent:latest` | 用于拉取代理的容器镜像 |
| `INFLUX_TOKEN` | `local-dev-token` | 作为 `Influx__Token` 转发给代理。只要捆绑的 InfluxDB 以 `--without-auth` 运行，任何非空值都有效。 |
| `GRAFANA_BASE_URL` | `http://localhost:3000` | 用于在 `/admin/grafana` 上构建 iframe 的 URL。在反向代理时进行更改。 |
要超越 `.env` 的配置，可以通过 `docker-compose.yml` 中的环境变量覆盖代理的任何 `appsettings.json` 键。ASP.NET Core 将双下划线映射为冒号 —— `Api__MaxBatchSize=500` 变成 `Api:MaxBatchSize`。
完整的键列表（REST、MQTT、验证、总线、Influx、管理）位于 [`INTEGRATION.md` §6](INTEGRATION.md#6-configuration-reference)。
## 8. 操作技术栈
```
# Tail the agent logs
docker compose logs -f agent
# Tail everything
docker compose logs -f
# Restart the agent only (e.g. after changing env vars)
docker compose up -d agent
# Stop the stack, keep volumes
docker compose stop
# Stop and delete containers, keep volumes (data is preserved)
docker compose down
# Stop and delete EVERYTHING including data
docker compose down -v
```
持久状态存储在命名的 Docker 卷中：
| 卷名 | 存储内容 |
|------------------|--------------------------------------------------------|
| `mosquitto_data` | MQTT 代理的持久会话状态 |
| `mosquitto_log` | MQTT 代理日志 |
| `influxdb_data` | 时间序列数据（受 30 天保留期限制） |
| `grafana_data` | Grafana 数据库 —— 用户、仪表板、注释 |
| `agent_data` | 代理的 LiteDB（操作员身份）和死信队列 |
`docker compose down -v` 将删除以上所有内容。
## 9. 升级
要升级到新的代理版本：
```
# 1. Pin the target version in .env
# IOT_AGENT_IMAGE=ghcr.io/lupinskilukasz/flexbit-iot-agent:0.2.0
$EDITOR .env
# 2. Pull and restart only the agent
docker compose pull agent
docker compose up -d agent
```
代理的持久状态存储在 `agent_data` 卷中，并在重启后保留。版本之间的破坏性变更列于 [`CHANGELOG.md`](CHANGELOG.md)。
## 10. 故障排除
| 症状 | 可能原因 / 查看位置 |
|--------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
| `docker compose pull` 在 `ghcr.io/lupinskilukasz/flexbit-iot-agent` 上因 `denied` 失败 | 镜像为私有或标签不存在。请确认 [`CHANGELOG.md`](CHANGELOG.md) 中的标签，并确保您已通过 GHCR 认证。 |
| `curl http://localhost:8080/health/ready` 返回 503 | 捆绑的 InfluxDB 在首次启动时需要再等待 5-10 秒。如果持续出现，请运行 `docker compose logs influxdb` 和 `docker compose logs agent`。 |
| 代理日志反复显示 `Mqtt: disconnected` | Mosquitto 容器未启动 —— 通常是 1883 端口冲突。请检查 `docker compose ps` 和 `lsof -i :1883`。 |
| Grafana 显示 "no data" 但摄入计数器在增加 | 您的测量值落入了与仪表板变量过滤条件不同的 `agent_id` 下。请检查仪表板顶部的 **Agent** 下拉菜单。 |
| `/admin/grafana` iframe 为空白 | 浏览器阻止了 iframe。请确认 `docker-compose.yml` 中 `GF_SECURITY_ALLOW_EMBEDDING=true`，并且 `GRAFANA_BASE_URL` 可从同一浏览器访问，而不仅仅是从代理容器内部访问。 |
| 端口 8080 / 1883 / 3000 / 8181 已被占用 | 编辑 `docker-compose.yml` 中对应的 `ports:` 条目（例如 `"18080:8080"`）并重启。 |
| `Influx__Token` 被拒绝 | 捆绑的 InfluxDB 以禁用认证模式运行；任何非空值都有效。请确保 `.env` 与 `docker-compose.yml` 在同一目录。 |
对于运行时诊断，代理暴露了以下端点：
- `GET /health/live` —— 进程存活探测。
- `GET /health/ready` —— 组合探测（Influx、MQTT、总线填充状态）。
- `GET /metrics` —— Prometheus 文本格式指标，包括区分已摄入/无效/已持久化/已进入死信队列的 `agent_telemetry_*` 计数器。
## 11. 文档
- **[`INTEGRATION.md`](INTEGRATION.md)** —— 完整的集成商参考：REST 端点、MQTT 主题、管理界面、配置、诊断、路线图。
- **[`CHANGELOG.md`](CHANGELOG.md)** —— 已发布版本。
新的代理镜像是如何构建并推送到 GHCR 的。
## 12. 项目状态与路线图
对于单向遥测数据摄入、持久化、可视化和操作员管理，该代理已是功能完整的。路线图上的项目（描述于 [`INTEGRATION.md` §9](INTEGRATION.md#9-roadmap)）：
- 基于中央 Flexbit 平台进行真正的认证与授权（当前的 `MockAuthService` 是一个占位符）。
- 在代理与 Flexbit 平台之间建立双向通道 —— 北向状态推送、南向命令和配置。
- 原生南向协议：**OPC UA** 和 **Modbus TCP**，作为 REST 和 MQTT 之外的附加摄入模块暴露。
此处记录的 REST 和 MQTT 接口是稳定的，并且随着路线图项目的落地，它们将继续作为面向合作伙伴的入口。
## 15. 许可证
参见 [`LICENSE`](LICENSE)。标签：Docker Compose, IoT代理, .NET 10, NIDS, REST API, 代理服务, 分布式能源, 发电厂监控, 命令控制, 多人体追踪, 容器化, 工业物联网, 数据转发, 数据采集, 时间序列数据库, 本地部署, 物联网, 能源数据, 能源管理, 请求拦截, 边缘盒, 边缘计算, 遥测