Table of Contents

TierHub 使用指南

TierHub = 产品家族域装配根——实例目录 + 按名解析 + 分片路由 + 生命周期治理 + 事务域归属。 上层"服务版本 / 本地版本"的差异收口为成员描述符里的承载位字段(standalone / raft), 解析面与事务面两种承载无差别。 hub 五件原生能力的契约总览与直连选型判据见 hub 原生能力总览。

定位(是什么 / 不是什么)

  • 是:终端产品全家的统一入口(Kv/VarKv/Queue+Dlq/Hash/Set/ZSet/Series/Log/Blob—— 终端 Kind 共 10 种;HubMemberKind 为唯一事实源,另有各 Kind 的 Sharded 分片档)—— "不应该每种都直接 new"的完整答案:装配收口一处、承载方式变成配置、成员间事务同域原子。
  • 不是:数据面(引擎与结构机制全在 Runtime 积木)、传输与组装配(raft 侧由调用方经 Products.Net 装配后登记进 hub——hub 不自建传输)、请求转发代理(非 leader 语义由各 集群形态产品自带)、自动再平衡(拓扑变更走显式 API)。

快速开始

var fs = TierFs.New("memory:");          // 或 TierFs.New("local:///path/to/volume")

// ── 三段式①②:Options → Builder With 链声明成员(全家 Builder 同款惯例)──
var builder = new TierHubBuilder(fs, TierHubOptions.Default.WithHubName("app"))
    .WithKv<long>("orders")                                     // hub 接管命名(Options 名字段不适用)
    .WithKvShard<long>("tenants", shards: 4,
        shardHash: static key => ShardKeyHash.Fnv1a64(key))     // Kv 分片哈希必填(路由守恒)
    .WithQueue("events")
    .WithHash("profiles")
    .WithLog("audit");

// ── 三段式③:StartAsync(成员按声明序串行装配 + 事务域接管;失败就地逆序清理零残留)──
await using var hub = await builder.StartAsync();

// 解析面:按名强类型(每 Kind 一个泛型入口——零反射工厂)
var orders = hub.Kv<long>("orders");
await orders.PutAsync(42, "hello"u8.ToArray());

var tenantKv = hub.KvShard<long>("tenants");   // 分片路由句柄
var shard = tenantKv.Route(42);                // 同键恒同成员(路由守恒)

var events = hub.Queue("events");              // dlq 收编成员:hub.Queue("events.dlq")
var audit = hub.Log("audit");
await audit.AppendAsync("{\"event\":\"placed\"}"u8.ToArray());

核心语义

成员与描述符

  • hub.Members → 描述符集合(Name/Kind/Shards/参与面清单 + 承载位——含 dlq 收编成员)。
  • 描述符承载位:Carrier(Standalone / Raft)+ RaftGroupId(raft 承载成员的参与组号)—— 目录读面即拓扑事实,调用面无差别(同 Kind 同解析入口)。
  • 成员名域内唯一;{name}.dlq 为死信收编保留名(WithQueue 显式拒绝);$ 前缀系 hub 自留 命名空间(目录自持久引擎,见下节——Builder/动态注册双闸拒绝)。
  • 命名一致性前置校验(按 Kind 两口径):hub 接管命名的 Kind(Kv/VarKv/Log——Options 名字段 被静默覆写为成员名,无校验);干跑拒绝的 Kind(Queue/Collections/ZSet/Series/Blob—— Options 名字段须与成员名一致,校验失败即刻拒绝零目录污染)。

目录自持久(重启恢复——治理面不失忆)

契约边界(product-mode-model-design §2D 拍板④):hub 只持久目录元数据——成员描述符 (名字/Kind/承载位/组号 + 分片数)写穿透 hub 根域(Builder 传入的 fs,保留引擎名 $directory);不持久共识态(组成员事实源仍是 ClusterConfig+raft wal/快照,零双写); 不持久业务数据(产品引擎=可丢弃物化,自 wal/快照收敛)。静态成员每次启动按声明 重推导(声明即目录,幂等覆写);动态成员注册条目写穿透,重启后经恢复面呈现。

// 第一运行:动态注册(写穿透 hub 根域)
var hub1 = await new TierHubBuilder(fs).WithKv<long>("orders").StartAsync();
await hub1.AddQueueAsync("events", _ => new TierQueueOptions { QueueName = "events" });
await hub1.DisposeAsync();

// 重启(同卷再 StartAsync):静态成员重推导;上次动态成员经恢复面呈现描述符事实源
var hub2 = await new TierHubBuilder(fs).WithKv<long>("orders").StartAsync();
foreach (var pending in hub2.RecoveredMembers)      // Name/Kind/Shards/Carrier/RaftGroupId
{
    // 按描述符重装配(Kind 分派到对应 AddXxxAsync——参与面清单系装配事实,重装配再生)
    // 或显式放弃:await hub2.DismissRecoveredMemberAsync(pending.Name);
}
  • hub.RecoveredMembers:未重装配的动态成员描述符(Ordinal 名序;{name}.dlq 随主成员折叠 不单独呈现)。重装配 = 同名 AddXxxAsync(覆写条目并摘出恢复面);放弃 = DismissRecoveredMemberAsync(name)(连带同族 dlq 删条目)。
  • 幂等重启:不消费的恢复条目跨重启保留(条目=事实源,随根域存续直到被消费)。
  • 优雅停机不清条目——条目生命周期 = 注册写入 / 同名覆写 / 显式放弃;清条目即重启失忆。
  • 边界红线:目录持久化不新增治理语义(无租约/通知/跨节点协调)——不是注册中心; 恢复面不派生任何共识决策(组成员事实源只在 raft 域)。

分片路由(sharded——集内同驻不变量)

  • 分片单元 = 路由键(Kv=记录键),键内不分片(一路由键的所有数据恒住同一成员—— Redis Cluster 同构;跨成员聚合走事务/查询面,不在路由层散收)。
  • 路由 = 调用方供给的确定性哈希(ShardKeyHash.Fnv1a64)+ IShardRouter(缺省取模—— 替换属 ShardedSet 结构面,hub Builder API 只暴露哈希委托)—— 哈希函数跨重启必须确定性(同键恒同成员)。
  • Queue/Series/Log singleton 起步(topic/库/日志名即实例内寻址)。

事务域(双形态——按成员承载位装配期定型)

纯 standalone 域(全部成员 standalone——缺省):OpenSession 面, 成员注册即归 hub 事务域(参与面↔协调者 1:1 装配期收口)。

using var session = hub.OpenSession("place-order");
session.Stage(() =>
{
    // 物化委托:域管线线程执行——跨成员写入同批 Prepare-all → Confirm-all(共享 seq)
});
await session.CommitAsync();   // 域 seq 全成员共享单调(hub.LastCommittedSeq 读面)

跨节点事务域(含 raft 承载成员——WithRaftDomain 声明):OpenTransaction 面 (统一事务内核,raft 档决策日志)。本地参与面经 LocalDriver、跨节点参与面经组提案驱动, 同一事务混排两条路径;提交 = Stage-all → 家组决策定案(原子锚点)→ Confirm-all。

// raft 侧先行:调用方经 Products.Net 装配家组与参与组(传输/组句柄归调用方所有),
// 产出 raft 档决策日志与组提案驱动后登记进 hub——hub 零 raft 依赖。
var builder = new TierHubBuilder(fs)
    .WithKv<long>("orders")                                        // 本地成员(standalone 承载)
    .WithRaftDomain(homeDecisionLog, homeGroupId: 0x0F01,          // 家组决策日志(raft 档)
        coordinatorEpoch: 0)                                       // 协调者世代(家组重建 +1)
    .WithRaftMember("events", HubMemberKind.Queue, queueReplica,   // 跨节点成员(raft 承载)
        raftGroupId: 0x0F02, groupDriver);                         // 实例=集群形态产品句柄

await using var hub = await builder.StartAsync();

await using var txn = hub.OpenTransaction();
txn.Stage("kv:orders:ring", () => { /* 本地物化委托 */ });
txn.Stage("events", commandBatch);             // 跨节点:命令批 → 组提案(staged 进组日志)
await txn.CommitAsync();                       // 家组决策定案 → 本地 Confirm + 参与组落地
  • 耐久铁律(装配期强制):含 raft 承载参与面的域必须 raft 档决策日志——违者启动即拒。
  • 家组与世代:hub.RaftHomeGroupId / hub.CoordinatorEpoch 目录登记读面;世代是 force-abort 逃生门的守卫判据(家组永久丢失重建后 +1,旧世代迟到决策被参与组拒绝)。
  • 事务面互斥:跨节点域的本地参与面归内核协调(1:1)——OpenSession 即 fail-fast; 纯 standalone 域 OpenTransaction 同理 fail-fast(指路 OpenSession)。
  • raft 成员资源归属:传输/组/实例由调用方装配并所有(WithRaftMember 的 dispose 委托 缺省 no-op)——hub 停机不连带 raft 侧。
  • 动态成员(AddKvAsync)读写面即时可用;事务参与面不并入运行中事务域(域归属装配期收口)。

生命周期治理(引擎风暴判例三件套强制形态)

  1. 同名并发创建 → 单飞(AddKvAsync 动态成员:仅一个装配,其余等待同一结果);
  2. 装配链任何一步失败 → 已建成员就地逆序 Dispose,目录零残留;
  3. DisposeAsync 逆序停成员 + 事务域停机,失败聚合;关闭中解析/新增请求 fail-fast (InvalidOperationException 即刻抛,不悬挂;停机窗竞态落在装配完成之后 = ObjectDisposedException—— 两个异常类型都要接)。

怎么选(直连 Builder vs hub 域;承载位怎么切)

术语口径(全仓正式口径——product-mode-model(设计稿已归档)): 承载模式(单机 / raft / group raft——group raft 是能力梯非第三枚举值)× 使用模式 (直连 / hub)两轴正交;差异轴是保证范围(单域自治 vs 跨域治理),不是稳定程度。 raft 承载的直连一等入口见 direct-connect.md。

直连产品 Builder TierHub 域
单产品单实例、无跨成员事务 ✅ 够用 重了
多成员 + 跨成员原子 各自 Session 域手工注册参与面 ✅ 注册即归域,OpenSession 即原子
本地 + raft 成员混排同一事务 内核×驱动手工拼装 ✅ WithRaftDomain/WithRaftMember,OpenTransaction 混排
家族统一启停/观测 调用方自持清单 ✅ 目录/逆序停机/描述符
本地切 raft 承载 换集群形态产品装配 ✅ 描述符一处变化,解析面零改动

成员接入矩阵

With 方法 Kind 解析入口 形态
WithKv<TKey> Kv hub.Kv<TKey>(name) singleton
WithKvShard<TKey> KvShard hub.KvShard<TKey>(name) sharded(哈希必填)
WithQueue Queue(+QueueDlq 收编) hub.Queue(name) singleton;实例内多 topic
WithHash Hash hub.Hash(name) singleton
WithSet Set hub.Set(name) singleton
WithZSet ZSet hub.ZSet(name) singleton
WithSeries Series hub.Series(name) singleton;实例内多序列
WithLog Log hub.Log(name) singleton;帧化记录日志

动态成员:await hub.AddKvAsync<long>("dyn", options)(单飞并发创建;已存在=返回既有)。 跨节点成员:WithRaftMember(name, kind, instance, raftGroupId, transactionDriver)—— Kind=KvShard 系分片形态不支持 raft 承载(sharded×raft 设计性排除,见「集群模式」章 D1); QueueDlq 不支持(死信收编系 standalone 形态专属)。TierWAL 排除(raft 底座,非终端产品)。

sharded 全 Kind(hub 完备化 W1+W2):

With 方法 Kind 解析入口 路由键
WithVarKv / WithVarKvShard VarKv / VarKvShard hub.VarKv(name) / hub.VarKvShard(name) 键字节(FNV-1a 64)
WithHashShard HashShard hub.HashShard(name) field 字节
WithSetShard SetShard hub.SetShard(name) member 字节
WithZSetShard ZSetShard hub.ZSetShard(name) member 字节
WithQueueShard QueueShard hub.QueueShard(name) 逻辑队列名(同名整体同驻一桶)
WithSeriesShard SeriesShard hub.SeriesShard(name) 库键字节
WithLogShard LogShard hub.LogShard(name) 日志名(同名同驻一桶)
WithBlob Blob hub.Blob(name) singleton(对象表参与者并入事务域)

动态版:AddVarKvAsync / AddHashShardAsync / AddSetShardAsync / AddZSetShardAsync / AddQueueShardAsync / AddSeriesShardAsync / AddLogShardAsync / AddBlobAsync(单飞同款)。 分片实例存储身份 = {成员名}.s{i};路由 = IShardRouter 缺省取模 + ShardKeyHash.Fnv1a64 确定性哈希——路由守恒 = 同键恒同分片(hub API 面只暴露哈希委托)。

反模式

  1. 绕过 hub 直呼成员引擎写路径再混用域会话/内核事务——参与面↔协调者 1:1 装配期收口: 成员入域后其写入走域管线/内核事务(直呼引擎写=绕过原子边界)。
  2. 分片哈希用非确定性函数(随进程漂移的哈希/Random)——路由守恒破坏:同键跨重启 落不同成员。哈希必须确定性(键二进制表示的稳定函数)。
  3. Options 命名字段与成员名不一致——校验前置直接拒绝(按名解析即存储身份); 不要试图"注册名 A 指向配置名 B"。
  4. 关闭后继续使用解析面——关闭中 fail-fast 是契约(不悬挂);长生命周期持有解析结果 的组件须感知 hub 关闭(捕获 InvalidOperationException 与 ObjectDisposedException 两种终态)。
  5. 把 hub 当分布式协调器——组拓扑/成员变更/跨节点路由归管理面与 raft 层;hub 是 域装配根:raft 侧装配好登记进来,hub 不自建传输、不转发数据面。
  6. 混合域继续用 OpenSession——跨节点域的本地参与面归内核协调,OpenSession 即刻 fail-fast;事务统一定口 OpenTransaction(两承载混排同一事务的正确入口)。

配置参考

资源/初始化/调优的完整消费面指南 = hub-tuning.md (三级配置链/每产品初始化值全表/档位选择/调优速查)——本节只列 hub 自身旋钮。

TierHubOptions 缺省 说明
HubName tier-hub 域名(域管理器/诊断身份)
Resolution ForwardCommit 事务域悬挂裁决(纯 standalone 内存档域声明;跨节点域恢复=问决策日志,此声明不参与)

hub 读面:LastCommittedSeq(域已提交水位)/ RaftHomeGroupId(家组号,0=纯 standalone)/ CoordinatorEpoch(协调者世代——force-abort 守卫判据)。

集群模式(端到端章)

单一事实源(D4)——Products.Net 的 raft-node/raft-consistency 文档交叉链接本节, 不另立集群分册。集群资源配置与调优(四层配置结构/集群初始化值表/调优速查) = hub-tuning.md §4.5。

装配(WithRaftDomain):跨节点事务域须先声明 raft 档决策日志——

var hub = await new TierHubBuilder(fs)
    .WithRaftDomain(decisionLog, homeGroupId: 0x21, coordinatorEpoch: 7)
    .WithKv<long>("orders")                       // 本地成员:事务参与经 LocalDriver
    .WithRaftMember("remote-log", HubMemberKind.Log, raftLogInstance,
                    raftGroupId: 0x22, driver)    // raft 承载成员:事务参与经组提案
    .StartAsync();

事务统一定口 hub.OpenTransaction()(纯 standalone 域继续用 OpenSession;混合域 fail-fast——force-abort 世代守卫判据 = CoordinatorEpoch)。

*raft 承载成员(AddRaft 九件全 Kind)**:Products.Net 扩展 TierHubRaftAssemblyExtensions 提供九件——AddRaftKvAsync<TKey> / AddRaftBytesKvAsync(VarKv 档)/ AddRaftQueueAsync / AddRaftHashAsync / AddRaftSetAsync / AddRaftZSetAsync / AddRaftTimeSeriesAsync / AddRaftLogAsync / AddRaftBlobAsync——引擎 + 状态机适配器 + raft 组装配 hub 代拼 (写经组提案全组一致 → 读本地 read-local;副本门面 TierXxxReplica 收口消费面)。 协议域号分配(COORDINATION.md 单一真源):0x60 Queue / 0x61 VarKv / 0x63 Hash / 0x64 Set / 0x65 ZSet / 0x66 Series / 0x67 Log / 0x68 Kv / 0x69 Blob(0x62 事务参与域)。 sharded×raft = 设计性排除(D1):每分片一 raft 组 = 组数随分片数爆炸,跨组事务协调 复杂度非线性(Redis Cluster 同位:分片是组内概念);重开条件 = 真实跨节点分片需求 + 独立设计稿。

动态成员与事务域交互(T9.1/T9.2):动态 AddRaft* 的事务驱动经 TransactionKernel.RegisterRuntime 追加并入运行中事务域(路由快照原子交换——在途事务 持旧快照不受影响);参与集合在 Prepare 点冻结。hub 内核缺省(纯 standalone)时跳过。

参与面口径(拍板⑧——raft 档置空):raft 承载成员参与面统一置空(复制即共识, 无独立 2PC 面——GetParticipant 系列明示 NotSupportedException);standalone 成员 参与面照常并入 hub 事务域。

分片路由与集内同驻:路由守恒(同路由键恒同分片,确定性哈希 + 纯函数路由器)是 集内同驻不变量的实现机制——跨分片操作(跨键事务/多键原子)不因分片而破坏单成员语义。 Collections/ZSet 跨分片读走扇出面(拼接/求和/有序归并——(score, member 哈希) 全序与 单实例契约同形);ZRange 全局排名 = 归并开窗(大窗口走 ZRangeByScore 更省)。

故障语义:非 leader 写 = NotLeaderException 提案转发/显式重定向(禁止静默本地写); 关闭中解析/新增 fail-fast(不悬挂);raft 承载成员提案失败随 raft 组选举恢复,hub 事务内核按 决策日志裁决悬挂。

组辖权迁移(T9.3):副本门面统一 MoveGroupHomeAsync(target) / TakeoverGroupHomeAsync() ——组辖权 = raft leader(Queue 的消费组辖权 MoveGroupHomeAsync 为先例原语,正交保留); 数据安全前提 = 目标已追平(matchIndex == commitIndex),未追平确定性拒绝。

成员作用域 fs(T12.4):装配期为每成员包 MemberScopedFileSystem(成员名族前缀边界—— {name}/{name}/…/{name}.…/{name}-… 同族,族间互斥 + 最长匹配族优先):成员越界路径 AccessDenied,绕过包装器的原始根域访问零变化(零破坏语义)。

深入

  • 集群形态产品(raft 承载实例,如队列副本 TierQueueReplica): src/KernLab.Tier.Products.Net/docs/(raft-node/raft-consistency)· src/KernLab.Tier.Core.Net/docs/(raft-architecture)· product-consistency.md(一致性档位)。
  • 设计文档:tierhub-aggregation / tierhub-distributed-transaction(内部设计稿,不随包发布)。