hub 原生能力总览(治理轴五支柱+管理面)
本文是 hub 模式(治理轴)消费面的单页总览:跨结构一致性事务、统一路由与命名、 统一数据管理、目录自持久、数据权限五件能力的契约定义与入口索引。 每件能力的使用细节与反模式在详情分册(tierhub.md / hub-tuning.md / product-consistency.md / tiering.md), 本文只收口"有什么、契约是什么、细节去哪看"。
定位
hub 模式 = 治理轴:跨域治理(跨结构事务/统一路由/统一管理/目录自持久)。 与直连模式的差异轴是保证范围(直连 = 单域自治,hub = 跨域治理),不是稳定程度—— 两模式坐在同一条 raft 基座上,组内一致性完全相同。
hub 不在数据热路径上:hub.Kv(name) 按名解析一次拿门面,此后与直连完全同径——
两模式热路径等价,hub 的价值在装配期与治理面,不在数据面。
能力随承载梯递增:
| 承载梯 | hub 形态 |
|---|---|
| 单机 | 实例袋子+按名解析(与直连几乎等价) |
| raft | +名字目录/承载位标记 |
| group raft | +跨结构事务域/动态成员跨组原子性/扩容三档/全局档/共享资源池(★ 真增值所在) |
目录自持久为 hub 级能力(单机与 raft 档同样生效——不依赖 group raft)。
支柱① 跨结构一致性事务
契约:成员注册即归 hub 事务域(参与面↔协调者 1:1 装配期收口),跨成员写入同批 Prepare-all → Confirm-all 原子;2PC 提交点语义、崩溃窗口、恢复对账成文。
双形态按成员承载位装配期定型:
| 形态 | 声明 | 事务入口 | 内核 |
|---|---|---|---|
| 纯 standalone 域(缺省) | 无需声明 | hub.OpenSession() |
SessionManager 域管理器(内存档——域 seq 全成员共享单调,hub.LastCommittedSeq 读面) |
| 跨节点域(含 raft 承载成员) | WithRaftDomain+WithRaftMember |
hub.OpenTransaction() |
统一事务内核 TransactionKernel(staged → 家组决策定案(原子锚点)→ Confirm-all;raft 档决策日志) |
- 同事务混排两路径:本地参与面经 LocalDriver 物化委托、跨节点参与面经组提案驱动, 同一事务统一提交。
- 耐久铁律(装配期强制):含 raft 承载参与面的域必须 raft 档决策日志——违者启动即拒。
- 世代守卫:
hub.CoordinatorEpoch(家组重建 +1)是 force-abort 逃生门的判据——旧世代 迟到决策被参与组拒绝。 - 事务面互斥(fail-fast 不悬挂):跨节点域
OpenSession即拒(本地参与面归内核协调); 纯 standalone 域OpenTransaction即拒(指路 OpenSession)。
使用细节(会话/内核/集群装配/动态成员与事务域交互):tierhub.md 事务域章; 提交点语义与崩溃窗口的产品面机理(Prepare 悬空/Confirm 提交点/恢复对账):product-consistency.md。
支柱② 统一路由与命名
契约:按名解析目录+分片 View 契约面——同键恒同分片(路由守恒)+跨分片读三聚合 (扇出拼接/求和/有序归并),集内同驻不变量。
按名解析目录:
- 成员描述符集合
hub.Members(Name/Kind/Shards/参与面清单/承载位——CarrierStandalone/Raft+RaftGroupId),目录读面即拓扑事实。 - 每 Kind 一个泛型解析入口(
hub.Kv<TKey>(name)/hub.Queue(name)/hub.Blob(name)… 终端 Kind 10 种+各 Kind 分片档——HubMemberKind为唯一事实源),零反射工厂。 - 命名纪律:成员名域内唯一;
{name}.dlq为死信收编保留名;各 With 的 Options 名字段与 成员名一致性前置校验——失败零目录污染。
分片 View 契约面(WithXxxShard → hub.XxxShard(name)):
- 路由守恒:分片单元 = 路由键(Kv=记录键),键内不分片——一路由键的所有数据恒住
同一成员。路由 = 调用方供给的确定性哈希(
ShardKeyHash.Fnv1a64;Kv 分片必填,字节路由键 分片缺省同款)+IShardRouter(缺省取模);哈希跨重启必须确定性,否则路由守恒破坏。 - 集内同驻不变量:同路由键恒同分片是跨分片操作不破坏单成员语义的实现机制;
分片实例存储身份 =
{成员名}.s{i}。 - 跨分片读三聚合(机制在 Runtime
ShardMerge,视图仅委托):
| 聚合 | 语义 | 代表面 |
|---|---|---|
| 扇出拼接 | 各分片流依序拼接 | HGetAllAsync / SMembersAsync(无序契约,分片序产出) |
| 求和 | 各分片计数相加(路由守恒推论:分片间无重复成员) | HLenAsync / SCardAsync / ZCardAsync / ZCountAsync |
| 有序归并 | 各分片有序流归并为全序 | ZSet ZRangeByScoreAsync/ZRangeAsync——(score, member 哈希) 全序与单实例契约同形;ZRange 全局排名 = 归并开窗(大窗口走 ZRangeByScore 更省) |
使用细节(成员接入矩阵/分片全 Kind/路由器替换):tierhub.md 分片路由章。
支柱③ 统一数据管理
契约:全局策略档(8 公共轴一旋钮全成员)+共享资源池+一个 fs 域管全部业务数据+ 冷热分层档位+动态成员/扩容三档/组迁移编排。
| 管理面 | 契约 | 入口 |
|---|---|---|
| 全局策略档 | HubPolicyDefaults 8 公共轴一旋钮全成员:过期/保留扫描间隔、checkpoint 周期、meta 回扫、watch 通道容量、段增长上限、Log 提交间隔、Queue 缓冲确认批阈值/驻留时间。解析链:产品缺省 → hub 全局档(只填 null 轴)→ 成员委托恒最终(类型系统 init-only 保证) |
TierHubOptions.WithPolicy(...) |
| 共享资源池 | 引擎 worker 调度器共享档:Auto(成员数交叉点 16 自动选)/SharedGroup(threadCount)(线程账 = f(共享组数) ≠ O(成员数))/Isolated(重载隔离逃生口) |
TierHubOptions.WithWorkerPolicy(...) |
| 资源收敛档 | LowResource = 段增长上限全局收敛(大成员数/低资源宿主的磁盘足迹消除——资源收敛档,非提速档) |
TierHubOptions.WithResourceProfile(...) |
| 一个 fs 域 | TierHubBuilder(fs) 根域单树管全部业务数据;装配期为每成员包 MemberScopedFileSystem(成员名族前缀边界——越界 AccessDenied,族间互斥);raft 通道例外:组持久真相域(wal+快照)独域且须真实盘 |
TierHubBuilder 根域参数 |
| 冷热分层档位 | 机制在 fs 层(TieringVolume.Mount 分层门面)——挂作 hub 根域即得,全部成员零改动获得升降温:热根/冷根/锚根三根声明、目录域策略(PinHot/TierAuto/ColdOnly)、region 级迁移事务(崩溃一致)、温度启发式(年龄降冷+顺序/频率双回迁档) |
tiering.md |
| 动态成员 | AddXxxAsync 运行期加成员(同名并发单飞;已存在=返回既有);raft 通道 AddRaftXxxAsync 九件全 Kind,事务参与面运行期并入事务域(路由快照原子交换) |
tierhub.md 成员接入矩阵 |
| 扩容三档 | ClusterMemberRole 三态:Voter(缺省,计多数派)/Learner(日志照常复制不投票——加副本不动写入可用性,兼 Standby 引导形态)/Witness(投票但不存全量日志体——第三票防脑裂)。扩容/换角色只改 ClusterConfig(成员表+Role),产品调用面零改动 |
raft 成员装配 options |
| 组迁移编排 | 组辖权 = raft leader;副本门面统一 MoveGroupHomeAsync(target) / TakeoverGroupHomeAsync();数据安全前提 = 目标已追平(matchIndex == commitIndex),未追平确定性拒绝 |
tierhub.md 集群模式章 |
资源配置/初始化值全表/调优速查/足迹速查:hub-tuning.md。
支柱④ 目录自持久(落地中)
契约边界(目标态):
- hub 只持久「目录元数据」:成员描述符(名字/Kind/承载位/groupId)+分片元数据 → hub 根域;
- 不持久共识态:组成员事实源仍是
ClusterConfig+raft wal/快照(一条真相,不双写); - 不持久业务数据:raft 成员恢复 = 目录重放 → 重装配 → 引擎自 wal/快照重放收敛 (产品引擎 = 可丢弃物化背书);
- 边界不守的退化形态 = hub 目录滑向「第二个注册中心」——体系膨胀红线。
状态:已落地。目录描述符写穿透 hub 根域($directory 引擎);重启经恢复面呈现
(RecoveredMembers / DismissRecoveredMemberAsync),静态成员按声明重推导幂等覆写。
支柱⑤ 数据权限(已落地——HubAccessPolicy)
契约:权限是治理面——ACL/租户策略模型以 hub 为策略落地点(对标 Redis ACL / Kafka authorizer);直连模式由宿主进程边界承担(嵌入式库同位)。
底座:Core.Net 授权钩子已备——INodeAuthorizer(链路准入 AuthorizeLink +
域级请求准入 AuthorizeRequest)与 IAuditSink 审计面。
状态:已落地(Products.Net HubAccessPolicy)。三层判定(链路 / 域 / key 前缀 ACL +
租户/成员准入),注入经 TierRaftHostOptions.AccessPolicy;使用详见
hub-permissions.md。当前接线面 = Kv/VarKv 判例件,
余七产品待铺开。
与直连的选型判据
一句话判据:要跨域保证 → hub;只要单域能力 → 直连;两者不互斥(同进程混布)。
| 场景 | 推荐 | 理由 |
|---|---|---|
| 单产品嵌入式/库形态、参数深度定制 | 直连 | 装配轻、零治理开销、注入面全开 |
| 单节点共识持久化(单选民组) | 直连 | 一个 Builder 起一个持久化结构 |
| 产品专属集群形态(Queue 多组、Blob swarm、专属拓扑) | 直连 | 产品自治正典 |
| 多产品共存、统一命名空间一次装配 | hub | 目录/按名解析 |
| 跨结构一致性事务 | hub | 事务域(直连无打包形态) |
| 统一治理(全局旋钮/资源池/统一域/分层档位) | hub | 治理轴增值 |
| 数据权限/租户管控 | hub | 权限是治理面(⑤落地后) |
| group raft 规模化运维(动态扩缩/组迁移编排) | hub | 跨组原子性+扩容三档 |
| 混合形态 | 混布 | standalone+raft 混合成员同进程 |
直连 raft 挂载的一等入口(TierXxxReplicaBuilder——与 hub spec 同一份装配代码,
双入口产出门面行为一致)见 direct-connect.md。
文档地图
| 想懂什么 | 去哪 |
|---|---|
| hub 域装配/事务域/分片/集群模式使用细节与反模式 | tierhub.md |
| 资源/初始化/调优消费面(三级配置链/全表/速查) | hub-tuning.md |
| 2PC 提交点语义/崩溃窗口/恢复对账机理 | product-consistency.md |
| 冷热分层机制(挂 hub 根域即得) | tiering.md |
| 直连 raft 挂载(ReplicaBuilder/读档三档) | direct-connect.md |
| 产品 × raft 一致性语义 | raft-consistency.md |
| 模式模型/功能矩阵/设计性排除登记(内部设计稿,不随包发布) | docs/design/product-mode-model-design.md(§3B 契约定义/§3C 选型指引) |