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)读写面即时可用;事务参与面不并入运行中事务域(域归属装配期收口)。
生命周期治理(引擎风暴判例三件套强制形态)
- 同名并发创建 → 单飞(
AddKvAsync动态成员:仅一个装配,其余等待同一结果); - 装配链任何一步失败 → 已建成员就地逆序 Dispose,目录零残留;
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 面只暴露哈希委托)。
反模式
- 绕过 hub 直呼成员引擎写路径再混用域会话/内核事务——参与面↔协调者 1:1 装配期收口: 成员入域后其写入走域管线/内核事务(直呼引擎写=绕过原子边界)。
- 分片哈希用非确定性函数(随进程漂移的哈希/Random)——路由守恒破坏:同键跨重启 落不同成员。哈希必须确定性(键二进制表示的稳定函数)。
- Options 命名字段与成员名不一致——校验前置直接拒绝(按名解析即存储身份); 不要试图"注册名 A 指向配置名 B"。
- 关闭后继续使用解析面——关闭中 fail-fast 是契约(不悬挂);长生命周期持有解析结果
的组件须感知 hub 关闭(捕获
InvalidOperationException与ObjectDisposedException两种终态)。 - 把 hub 当分布式协调器——组拓扑/成员变更/跨节点路由归管理面与 raft 层;hub 是 域装配根:raft 侧装配好登记进来,hub 不自建传输、不转发数据面。
- 混合域继续用 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(内部设计稿,不随包发布)。