KernLab.Tier 系统整体架构与搭建

本文回答三件事：整套系统怎么分层、两种搭建形态（嵌入式 / 用底层搭服务中心）、 从零怎么用怎么搭。深入到各层机制与二进制格式见文末"深入入口"。

1. 系统整体架构（分层）

KernLab.Tier.Products        产品组合层（TierKv / TierQueue / TierWAL / TierTimeSeries / TierBlob——官方配方）
KernLab.Tier.Products.Net    raft × TierWAL 官方节点（TierRaftNode / TierWalRaftStore / TierRaftHost）
────────────────────────────────────────────────────────────
KernLab.Tier.Core.Net        网络与共识层（raft 全家 · 三形态通道 · 多介质 · P2P · Swarm · Security）
KernLab.Tier.Runtime         存储运行时（StorageEngine + 结构层：Ring/Log/Index/Meta/Snapshot + 2PC 事务）
KernLab.Tier.Core            内核基础设施（IO 底座 · 生命周期 · 线程调度 · 原语 · 可观测）
KernLab.Tier.Contracts       契约层（引擎 IO/生命周期/恢复/结构/事务——零依赖）
────────────────────────────────────────────────────────────
KernLab.Tier.CodeGen(+Analyzers)   源生成器横切（[WireMessage]/[BinaryLayout] 声明即代码，零运行时反射）
  • 依赖单向无环（编译期锁死）：Contracts → Core → Runtime → Products；网络支柱 Core → Core.Net → Products.Net；Core.Net 零产品知识（永不依赖 Products）。
  • "底层存储" = Contracts + Core + Runtime（引擎/结构/2PC——自定义存储模型的积木）； "网络与共识" = Core.Net（raft/传输/通道）；"产品" = Products(+Net)（官方配方）。

2. 两种搭建形态

KernLab.Tier 既可作为嵌入式存储底座打进你的进程，也可作为分布式服务中心的底层 原语自己搭集群。选型看"要不要跨进程一致性"。

2.1 嵌入式（应用进程内）

单进程直接使用，无网络、无集群——把 KernLab.Tier 当存储内核/产品库内嵌：

// 最小例子：存储引擎（换 URI 即换介质，代码不变）
using var vol = TierFs.New("memory:");          // memory: / local:// / virtual:// ...
await using var engine = await new StorageEngineOptions("demo").Builder(vol).StartAsync();
var addr = await engine.AppendAsync(payload, CancellationToken.None);   // WAL 语义追加

嵌入式三种深度：

深度 用什么 入口
存储内核 存储引擎 + Ring/Log/Index/Meta/Snapshot 结构积木，自组存储模型 存储引擎指南 · 结构导览
单机产品 TierKv / TierQueue / TierWAL / TierTimeSeries / TierBlob（官方配方，含恢复/检查点/2PC） 产品使用指南 等
内嵌复制组 TierQueueReplica 同进程多副本（raft 组，进程内传输）——单进程内的一致性 raft 论文核心保证

2.2 服务中心（用底层搭分布式服务）

跨进程/跨机一致性——用 Core.Net + Products.Net 搭集群服务：

形态 怎么搭 入口
raft 节点集群 TierRaftNode × N 节点，TCP 集群（listen + peers 表一行组装） raft-node.md
多组服务中心 TierRaftHost 一个传输上挂 N 个 raft 组（Multi-Raft） raft-node.md
队列复制组 TierQueueReplica × N 节点（raft × 队列——辖权/epoch 单写者） raft 论文核心保证
自组 Core.Net 服务 用底层传输 + raft 引擎 + 三形态通道自建协议服务（请求回调/流式/数据报） net.md · raft 共识架构

服务中心形态的共识语义（复制完成档三选一 / 线性读 / 成员变更 / 快照追赶）与传输选型 （TCP/QUIC/UDS/InProcess）见各层使用指南。

3. 从零搭建路径（决策速查）

要跨进程一致性吗？
├─ 否 → 嵌入式：选存储内核 / 单机产品 / 内嵌复制组（§2.1）→ 选介质（TierFs）→ 装配启动
└─ 是 → 服务中心：
        ├─ 队列服务 → TierQueueReplica 复制组（raft × 队列）
        └─ 通用 KV/自定义 → TierRaftNode 集群（raft × TierWAL）或自组 Core.Net
              └─ 节点数：3/5 奇数（多数派）→ 传输形态（TCP 集群 / 注入）→ 快照/反熵装配

4. 深入入口（架构与格式手册）

从实现面判断"稳定性 / 高性能 / 有序性 / 持久化 / 互操作性"怎么保证：

文档 回答什么 层
raft 共识架构与稳定性 论文五安全性质逐条实现映射 · 活性 · 有序性（提交全序/日志序/apply 序）· 高性能设计 Core.Net
网络/传输层架构 三形态收发（数据报/请求回调/流式）· 寻址与准入 · TCP/QUIC/UDS/InProcess 介质 · 身份安全三档 Core.Net
P2P/gossip 架构 HyParView 双视图会员收敛 · φ 故障检测 · 广播去重/TTL/防环防风暴 Core.Net
持久化稳定性架构 IO → 引擎 → WAL 三层崩溃一致性 · 三层水位体系 · 端到端持久化保证链 · 分工矩阵 Runtime
产品一致性架构 TierKv / TierTimeSeries / TierBlob 真源/派生分层 · 2PC 提交点 · 崩溃窗口 · 恢复对账 Products
raft 论文核心保证 TierQueueReplica 一致性语义 · 辖权 fencing · exactly-once vs at-least-once 精确边界 Products.Net
二进制格式单元说明 全系列二进制格式互操作手册——存储结构 + 产品封装 + 网络线格式，逐字节布局 + CRC/校验 + 版本演进 Runtime（跨存储 × 线格式）
Edit this page