izgon

# IzgoN IzgoN 是一款增量同步服务器，专为反复上报相似状态的设备集群设计。每个节点无需每轮上传完整负载，而是 POST 当前状态；IzgoN 将其与上次记录的状态进行比对，返回 `NO_CHANGE`（零字节负载）、最小化的 JSON 增量，或当增量比原始状态更大时返回完整状态。 ## 核心功能 - **增量同步**：仅将变更字段返回给设备，大幅减少回复负载。 - **条件同步（v1.4.0+）**：未发生变化的设备可发送简短的校验令牌替代完整报告，报告本身无需通过网络传输。 - **节省度量**：仪表盘和 `/api/metrics` 端点实时展示双向（回复和上行）的字节节省量。 - **基准测试工具**：`benchmark.py`（仅依赖标准库）可回放您的真实报告以测量数据节省效果，并支持合成模式用于测试。 - **自适应轮询建议**：服务器在连续收到多次相同报告后，可建议延长上报间隔，并明确说明数据陈旧的权衡。 - **静默告警**：当节点停止上报及恢复上报时，通过 Webhook 发送通知。 - **批量同步**：离线期间缓存的设备可在一次请求中刷新整个队列。 - **免费额度**：无需许可证密钥即可使用 10,000 次同步，足够进行评估。 ## 工作原理 节点在 `state` 中发送其状态（若未变化则仅发送 `checksum`）。服务器返回以下四种状态之一： - `NO_CHANGE` — 无变化，发送零字节。 - `SYNC_REQUIRED` — 仅返回变更的键；客户端进行合并。 - `FULL_STATE` — 返回完整新状态（当增量更大时）。 - `SEND_STATE` — 服务器无基线或校验码未知；客户端必须重新发送完整状态。 嵌套对象递归进行差异比较；列表作为整体进行比较（这是有意为之的限制）。可选的 `epoch` 令牌可在服务器重启或镜像丢失后强制返回完整状态，防止静默失步。 ## 快速开始 docker run -p 8000:8000 -e DATAPULSE_API_KEY=change-me ghcr.io/izgamber/izgon:latest 或使用 Docker Compose（包含 Redis 用于持久化基线）： git clone https://github.com/izGamber/IZgoN.git cd IZgoN cp .env.example .env docker compose up -d 仪表盘地址：`http://localhost:8000`。发送状态： curl -X POST http://localhost:8000/api/nodes/sensor-01/sync \ -H "Content-Type: application/json" \ -H "X-API-Key: dev-local-key" \ -d '{"state": {"temp": 21.5, "hum": 60, "batt": 98}}' 重复发送相同状态 → 返回 `NO_CHANGE`，零增量字节。修改一个字段 → 仅返回该字段。 ## 使用您的真实数据进行基准测试 python3 benchmark.py --payload-file my-reports.json 支持 JSON 数组或 JSON Lines 格式，自动检测设备 ID 字段，并根据您的数据测量变化率。合成模式：`python3 benchmark.py --nodes 50 --rounds 100 --change-rate 0.05`。 实测节省效果（5% 变化率）：回复方向约 94%，上行方向约 40%（按 SIM 计），轮询客户端约 65%。在 70% 变化率下，节省率降至约 35% — 这是诚实的边界。 ## API 端点 | 方法 | 路径 | 认证 | 用途 | |---|---|---|---| | POST | `/api/nodes/{id}/sync` | API 密钥 | 提交状态或校验码，获取增量/完整状态/NO_CHANGE | | POST | `/api/nodes/{id}/sync/batch` | API 密钥 | 在一次请求中回放缓存队列 | | GET | `/api/nodes` | API 密钥 | 列出节点和基线（分页） | | GET | `/api/metrics` | 无 | 实时字节节省总量 | | GET | `/api/license` | 无 | 当前层级及剩余免费同步次数 | | GET | `/healthz` | 无 | Redis 可达性、存储模式 | | GET | `/` | 无 | 仪表盘 | ## 配置 所有设置通过环境变量完成（参见 `.env.example`）。关键配置项： - `DATAPULSE_REDIS_URL` — 用于基线的 Redis 连接 - `DATAPULSE_API_KEY` — 认证密钥（默认 `dev-local-key`，请修改） - `DATAPULSE_FREE_TIER_LIMIT` — 触发 402 前的免费同步次数（默认 10000） - `DATAPULSE_LICENSE_KEY` — 付费许可证密钥（Ed25519 签名，离线验证） - `DATAPULSE_ALERT_URL` / `DATAPULSE_ALERT_AFTER` — 静默告警 - `DATAPULSE_ADAPTIVE` — 启用/禁用轮询间隔建议 - `DATAPULSE_MAX_STATE_DEPTH` / `DATAPULSE_MAX_STATE_BYTES` — 负载限制 ## 安全说明 - API 密钥保护所有写操作；采用恒定时间比较。 - `/api/metrics` 和 `/healthz` 设计上无需认证。 - CORS 默认为 `*`；生产环境中请收窄范围。 - 无内置速率限制；请置于反向代理之后。 - 状态深度上限为 32，大小上限为 1 MB。 ## 限制 - 列表不逐元素进行差异比较；修改一个元素会发送整个列表。 - 负载缩小时可能触发 `FULL_STATE`（该次同步无节省）。 - 任何节点的首次报告始终为完整状态。 - 基线存储在 Redis 中；若被清除，节点需重新同步一次。 - 单实例，无集群支持。 - 暂无客户端 SDK；集成方式为普通 HTTP POST。 ## 许可证与定价 源码可见，非开源。免费额度：10,000 次同步。商业许可证：一次性付费，无订阅，离线 Ed25519 签名验证。无电话回传。 ## 状态 版本 1.4.2。由一人开发维护。在线演示地址：`https://izgon-api.onrender.com`（首次请求可能需要 20–40 秒唤醒）。