架构和概念
项目总览和文档导航见：Fluxon 文档首页
本页解释其他文档中反复出现的核心概念和配置字段。当其他页面提到这些字段时，可以回到本页对照理解。
系统全景架构
组件视角的全景图，用来定位各组件的职责和依赖关系。
- 控制面/元数据：
etcd + master，负责成员、租约、路由、连接状态等集群控制面元数据。 - 数据面：
shared memory + transfer engine，负责同机共享内存复用和跨节点数据搬运。 - KV：Fluxon 的基础读写与 RPC 能力；
owner提供内存池，external以 zero-contribution 模式附着使用。 - MQ：建立在 KV 之上的消息队列能力，复用同一套服务平面与共享内存池。
- FluxonFS：建立在 KV 之上的远端文件访问能力；访问控制与 object UI 身份状态由
fluxon_fs.master_panel.access_db_path指向的 access DB 持久化，目录传输调度状态由fluxon_fs.master_panel.transfer_state_store持久化。 - FluxonOps：建立在 KV 之上的部署与运维控制面，负责 workload 提交、状态收敛、HTTP API 和 Web 面板。
分布式部署架构
进程角色与依赖关系的部署图。
控制面（Control Plane）：
- Fluxon KV Master：集群管理、路由、协调。
- ETCD：元数据存储（成员状态、MQ 状态、offset、连接信息等）。
- Prometheus / GreptimeDB：指标采集与存储，供监控面板查询。
每台机器（Machine）：
- Fluxon KV Owner：数据面资源提供者，贡献共享内存池，同机进程通过 SHM / Busypolling / Epoll UDS 访问。
- Fluxon KV External：不贡献内存，附着到 Owner 的共享内存池，面向业务提供接入能力。典型用途包括 MQ producer / consumer、KVCache for LLM、FluxonFS、FluxonOps。
跨机传输：
- High Performance P2P：Owner 之间通过 RDMA / DPDK / SPDK / WebSocket / TCP / QUIC 传输数据，支持 busy polling 优先和跨集群 relay。
角色
| 角色 | 职责 |
|---|---|
| master | 控制面入口：成员管理、路由、租约、监控广播 |
| owner_client | 数据面资源提供者：贡献共享内存池，供同机进程附着 |
| external_client | 用户侧接入点：不贡献内存，附着到 owner 的内存池。Fluxon 内部典型以这种方式接入的组件包括 MQ producer / consumer、KVCache for LLM、FluxonFS、FluxonOps。 |
核心配置字段
cluster_name — 集群的逻辑名称，用于隔离不同集群的元数据（etcd keyspace 前缀）。同一集群内所有组件必须一致，否则面板看不到成员。
instance_key — 进程实例的唯一标识（即 member id）。用于成员注册、RPC 寻址、日志/监控。同一 cluster_name 内必须唯一。
node_id / member_id — 接口中的目标定位字段，通常与 instance_key 值一致。
etcd_endpoints — etcd 访问地址列表。不同组件对格式要求可能不同（有的要 http:// 前缀，有的要 host:port）。连不上 etcd 时 MQ 和面板功能不可用。
prometheus_base_url — 面板的 metrics 数据源地址（Prometheus-compatible HTTP API）。面板只查询不采集，不可达时指标显示 N/A。
shared_memory_path — 共享内存目录，同机进程通过它附着到同一内存池；这是 mmap / data plane 的本机 authority。
shared_file_path — 共享文件目录，shared.json、日志、profile 等本机共享文件位于这里；这是 file / metadata attachment 的本机 authority。
log_dir — master 自己的日志目录 authority。master 运行时会在这个目录下继续派生 cluster 级日志和 profile 子目录。
contribute_to_cluster_pool_size — 内存贡献配置。owner_client 设置非 0 值提供内存池，external_client 不填或设为 0 来复用 owner 的内存池。
MQ 相关概念
unique_key 与 chan_id — channel 的两类标识。unique_key 是稳定的逻辑名称（适合复用），chan_id 是已存在的实例 id（适合直接绑定）。两者映射存储在 etcd 中。详细用法见 MQ 接口。