概述与架构
IEDB 集群支持多节点部署，实现读写分离、自动故障转移和高可用。集群通过 Raft 共识协议协调节点，支持共享存储（S3/MinIO/Azure）和本地存储两种模式。
快速开始
集群功能需要企业许可证。将许可证密钥添加到配置文件中：
# iedb.toml
[license]
key = "IEDB-XXXX-XXXX-XXXX-XXXX"
或通过环境变量：
export IEDB_LICENSE_KEY="IEDB-XXXX-XXXX-XXXX-XXXX"
从 OSS 升级到 Enterprise 无需数据迁移——添加许可证密钥，启用所需功能，重启即可。
架构概览
==============================================================================
IotEdgeDB Cluster Architecture Overview
==============================================================================
+============================================================================+
| Client Layer |
| HTTP API (Fiber) ---- Line Protocol / MsgPack / TLE / SQL |
+=============+==========================================+===================+
| |
+------v------+ +--------v--------+
| Write Path | | Query Path |
+------+------+ +--------+--------+
| |
+=============v==========================================v===================+
| Router Layer |
| |
| RouteWrite() -> ShardRouter -> Primary Writer |
| RouteQuery() -> ShardRouter -> Reader / Replica |
| ScatterGather -> parallel fan-out to multi-shard |
+=============+==========================================+===================+
| |
+=============v==========================================v===================+
| Coordinator Layer |
| |
| +----------------------------------------------------------------+ |
| | Raft Consensus (Hashicorp Raft + BoltDB) | |
| | FSM: Node Registry + File Manifest + Writer/Compactor Lease | |
| +----------------------------------------------------------------+ |
| |
| +----------------+ +----------------+ +----------------+ |
| | Writer | | Reader | | Compactor | |
| | - Primary | | - Read-only | | - Parquet | |
| | - Standby | | - WAL recv | | compaction | |
| +-------+--------+ +-------+--------+ | - Lease mgmt | |
| | | +-------+--------+ |
+===========v===================v===================v========================+
| | |
+=============v====================v===================v=====================+
| Replication Layer (3 Phases) |
| |
| Phase 1: WAL Stream (Writer -> Reader, real-time) |
| Phase 2: Parquet P2P (SHA-256 + resume, peer-to-peer) |
| Phase 3: Startup Catch-up (Manifest reconciliation + pull) |
+=============+====================+===================+=====================+
| | |
+=============v====================v===================v=====================+
| Storage Layer |
| |
| Local Disk / S3 / MinIO / Azure Blob |
| Parquet Files + Arrow In-Memory Buffer |
+============================================================================+
节点角色
| 角色 | 写入 | 查询 | 压缩 | Raft 投票 |
|---|---|---|---|---|
writer | ✅ | ✅ | - | ✅ |
reader | - | ✅ | - | - |
compactor | - | - | ✅ | - |
standalone | ✅ | ✅ | ✅ | - |
Writer 子状态：
primary— 当前活跃主节点，处理所有写入standby— 热备节点，随时可接管
网络端口
| 端口 | 用途 | 说明 |
|---|---|---|
8000 | HTTP API | 客户端读写查询入口 |
9100 | Coordinator | 节点发现、加入、心跳通信 |
9200 | Raft Transport | Raft 共识协议内部通信 |
所有端口均支持 TLS 加密。建议生产环境配置
advertise_addr明确对外广播 IP。
共享存储 vs 本地存储
| 共享存储（S3/MinIO/Azure） | 本地存储 | |
|---|---|---|
| 部署复杂度 | 低 — 共用一套存储 | 中 — 需配置节点间复制 |
| Reader 读取 | DuckDB httpfs 直接读 S3 | 通过 Raft 文件清单 + P2P 拉取 |
| WAL 复制 | 可选（降低读延迟） | 必须开启 |
| 故障恢复 | 新节点直接读共享存储 | 需从其他节点同步全部文件 |
| 适用场景 | 云部署、K8s 环境 | 边缘机房、单机柜部署 |
最小拓扑
生产环境推荐至少 4 节点 起步：
| 角色 | 数量 | 说明 |
|---|---|---|
writer | 2 | 一主一备，支持自动故障转移 |
reader | 1 | 承担查询负载，可随时扩容 |
compactor | 1 | 后台压缩任务，可由 Writer 兼任 |
最少可用 2 Writer + 1 Reader 起跑（Compactor 由 Writer 自动接管）。
节点发现
集群通过静态种子列表（seeds）实现节点发现，无需依赖外部服务：
- 首个节点 设置
raft_bootstrap = true，启动后即为集群 Leader - 后续节点 配置
seeds = ["writer-ip:9100"]，启动时自动向种子发送JoinRequest - 种子节点验证
cluster_name和shared_secret后，将新节点注册到 Raft FSM - 新节点从 Leader 同步 Raft 日志和文件清单，完成加入
节点间通过 Coordinator 端口 (:9100) 周期发送心跳（默认 5s），连续 3 次失败标记为不健康。