Table of Contents

hub 资源与调优配置指南

hub 装配的资源/初始化/调优唯一消费面指南:三级配置链怎么用、每产品初始化值全表、 什么资源场景选什么档、性能调优怎么定参。性能数据实测见 perf/hub-resource-curve.md (成员规模资源曲线)与 perf/hub-scheduler-ab.md(调度共享/独占 A/B)。

1. 三级配置链(hub 怎么配置每种产品)

全部成员配置经同一条解析链,优先级从低到高:

产品缺省(Options record 缺省值,注释登记出处)
  ↓ hub 全局档覆盖(TierHubOptions.Policy / ResourceProfile——调一个旋钮全部成员生效)
  ↓ 成员委托最后覆盖(WithXxx(name, o => o.WithYyy(...))——单成员特例)
  • hub 全局档只填 null 轴:HubPolicyDefaults 的非 null 轴覆盖产品缺省,null 轴不碰; ResourceProfile 再往 Policy 的 null 轴补(LowResource 档收敛段几何)。
  • 成员委托恒最终:WithKv(name, o => o.WithXxx(...)) 拿到的是「产品缺省 + 全局档已应用」 的基线,改完即终值——单成员特例不受全局档影响。
  • 类型系统保证:Options 属性 init-only,委托内只能走 WithXxx,不可能写坏。
var hub = await new TierHubBuilder(
        TierFs.New("local:///var/tier"),
        TierHubOptions.Default
            .WithResourceProfile(HubResourceProfile.LowResource)      // 段几何按档收敛(§4)
            .WithPolicy(p => p.WithExpiryScanInterval(TimeSpan.FromMinutes(1)))
            .WithWorkerPolicy(HubWorkerPolicy.Auto()))                // 缺省——按成员数交叉点选共享/独占
    // ── 成员级(特例覆盖)──
    .WithKv<long>("orders", o => o.WithSegmentGrowthLimit(64L << 20))   // 单成员特例
    .StartAsync();

2. hub 级旋钮全表(TierHubOptions)

旋钮 缺省 说明 / 何时调
WorkerPolicy Auto 引擎 worker 调度器共享档。Auto=成员数 >16(AutoCrossMembers)选共享组,否则独占;SharedGroup(threadCount)=强制共享(低资源宿主/大成员数);Isolated()=强制独占(重载隔离)。依据:A/B 实测 N=8 独占吞吐优 5.4×、N=32 共享反超 +17%、N=128 独占线程切换吞吐崩半——小规模重载留独占,上规模一律共享
Policy 全 null 公共策略轴全局档:ExpiryScanInterval(Kv/VarKv 过期 + Collections/Series 保留扫描)、CheckpointInterval(Kv 检查点泵)、MetaFlushInterval(Kv meta 回扫)、WatchChannelCapacity(订阅通道)、SegmentGrowthLimit(Kv/VarKv/Blob 段上限)、CommitInterval(Log 提交)、BufferedAckBatchSize/CommitInterval(Queue)
ResourceProfile Default LowResource=段增长上限收敛 32MB(低资源宿主/大成员数——256MB 段 × 引擎束 × N 的磁盘足迹 DiskFull 实证);只补 null 轴
Clock System 全成员单例时钟(测试假钟注入/跳变演练一处生效)

3. 每产品初始化值全表

缺省值 = 性能与稳定的测算平衡点(出处登记在各 Options 注释 + hub-resource-model-design §5)。 「何时调」给出偏离缺省的典型场景——没写到的原因 = 保持缺省。

TierKv / TierVarKv(键值族——record With 链)

轴 缺省 何时调
SegmentGrowthLimit 256MB hub 大成员数必调(磁盘足迹主项——256MB × 3 引擎 × N;128 成员 = 96GB DiskFull 实证)——用 ResourceProfile.LowResource 全局收敛 32MB,勿逐成员
RingPageSize 256KB 写吞吐微调(增量 flush 写穿粒度:256KB=9µs/1MB=44µs,实测见 perf/tierkv.md)——缺省已定标,勿动
RingMemorySize 64MB 读集工作集预算(懒分配非预占);读热点远超预算时升
RingColdReadRatio 0.25 冷读缓存页帧比(PageCount/4);随机冷读密集可升
IndexKind Hash 范围扫描需求选 BTree/有序族(-btree 引擎追加)
ExpiryScanInterval 60s 过期扫描周期(集群档由 hub 辖权循环接管,此轴失效)

TierQueue(队列——10 引擎/成员的放大器,装配前先看 §5 足迹)

轴 缺省 何时调
SegmentGrowthLimit 64MB 同 Kv 口径(×10 引擎放大)
PageSize 1MB 页粒度(同 RingPageSize 逻辑)
MemorySize 64MB 页池预算
MaxInFlight 4096 在途投递上界(消费堆积反压)
BufferedAckBatchSize / BufferedAckCommitInterval 1 / 关 缓冲确认批量化(吞吐 ↔ 持久窗口;hub Policy 轴全局调)

TierHash / TierSet / TierZSet(集合族——合册)

轴 缺省 何时调
SegmentGrowthLimit 64MB 同 Kv 口径
PageSize / MemorySize 1MB / 64MB 页粒度/预算
DomainTtl 关 域级 TTL(开启装 RetentionWorker;集群档共识化)

TierTimeSeries(时序)

RetentionTime(缺省 7 天)/MaxBytes/RetentionScanInterval(1 分钟)——保留策略三件套 (集群档经辖权循环共识化);段/页/池同集合族口径。

TierLog(帧化日志——单引擎)

轴 缺省 何时调
Settings.CommitInterval 10ms 持久性窗口(崩溃窗口 ≤10ms;1ms 实测仅 0.8MB/s——低延迟场景付吞吐代价)
Settings.MaxUnflushedBytes/Count 64KB / 1000 攒批阈值(吞吐优先放大)

TierBlob(大对象)

轴 缺省 何时调
SegmentGrowthLimit 64MB GB/TB 大对象跨段扩容口径
MaxBytes 不限 容量上限守护(Put/导入/快照导入三通道同闸 fail-fast——多租户必设)
SessionBufferSize 128KB 写会话双缓冲

4. 资源档位怎么选(场景 → 配置)

场景 配置组合
开发/测试/CI 全缺省 + memory: 根域——零配置开箱
单机生产(成员 ≤16,重载隔离诉求) 缺省(Auto 档自动选独占)+ local:///virtual:// 根域 + 按需 MaxBytes
单机生产(成员 >16) 缺省(Auto 自动切共享组——线程账 O(核数))+ virtual:// 引擎卷
大成员数 hub(32~128+)/低资源宿主 WithResourceProfile(HubResourceProfile.LowResource)(段收敛 32MB——DiskFull 消除)+ SharedGroup 显式
大对象/冷温数据 根域换 TieringVolume.Mount 分层门面(tierhub.md/tiering.md §2.1——热根 mem+耐久配对,冷根 local/虚拟卷)
多租户容量隔离 各 Blob 成员 WithMaxBytes(...)(三通道同闸)

介质本性自动档(无需配置):mem 介质引擎不物理预分配段(分配税在内存无意义—— 装配守卫按介质本性判断);磁盘介质预分配保留(fallocate 前移分配税,写路径纯顺序)。

集群模式(raft 承载 hub——AddRaft* 九件)

集群装配的配置分四层,各管一段:

层 载体 管什么
hub 级 TierHubOptions 事务域/时钟。★ 配置链边界:Policy/ResourceProfile 派发只作用于 standalone 通道;raft 通道成员经 AddRaftXxxAsync 的 options 参数直配
宿主级 TierRaftHostOptions GroupFileSystemFactory(每组 fs 域 = raft wal + 快照持久真相,须真实盘介质)、GroupDefaults(节点缺省模板)、ReconcileInterval、Security(mTLS)
节点级 TierRaftNodeOptions Wal(段几何/提交间隔)、Raft(选举/心跳/复制)、Apply、Swarm(快照安装分发)、快照轴、ResourceProfile(LowResource 档)
成员级 AddRaftXxxAsync(options…) 产品 Options(防发散闸门自动应用——引擎本地过期/retention 扫描强制关,过期决定权经共识)

集群特有初始化值(缺省 + 何时调):

轴 缺省 何时调
GroupFileSystemFactory 必供 raft 持久真相域——必须真实盘(local/virtual,勿 memory——wal 丢=数据丢)
Raft.ElectionTimeoutMin/Max 150/300ms 跨机部署按网络 RTT 放大(跨 DC 建议 ×4~10)
Raft.HeartbeatInterval 50ms 心跳频率(放大选举窗同步放大)
Raft.InFlightCapacity 4096 复制在途上界(复制延迟瓶颈首调)
Wal.SegmentGrowthLimit 256MB raft wal 段(组 fs 域独立计足迹)
Wal.CommitInterval 10ms wal 攒批(=提交持久窗口)
SnapshotGrowthThresholdEntries / SnapshotMinInterval 引擎口径 快照触发阈值(防频繁快照)
AntiEntropyInterval 关 反熵周期(快照对账——大集群/高 churn 开启)
ResourceProfile HighPerformance LowResource 档=页 4MB→1MB + 快照段 64MB→8MB + worker 收敛 1(低资源节点)
HighResolutionTimer true(Windows) 选举/心跳时序精度(生产保持开)

集群资源足迹:每 raft 组 = wal 引擎(组 fs 域)+ 产品引擎束(业务根域)+ 提交流/传输线程; 成员级引擎束口径与 standalone 相同(§6),raft 增量 = wal 段预分配(组域)+ 协议线程。

集群调优速查:

症状 首调
选举抖动/误切主 放大 ElectionTimeout 窗 + 确认 HighResolutionTimer;跨机 RTT 大时同步放大心跳
复制延迟 InFlightCapacity 升;ReplicationAck 口径复核(Majority=安全,leader 本地=低延迟)
落后副本追不上 确认 Swarm 装配面(快照安装通道)+ SnapshotBlockSize
快照过于频繁 SnapshotGrowthThresholdEntries 升 + SnapshotMinInterval 节流
低配节点拖垮全组 该节点 ResourceProfile.LowResource + Wal 几何收缩

集群语义(事务域/动态成员/组辖权迁移/作用域隔离/故障重定向)见 tierhub.md「集群模式」章。

5. 性能调优速查(症状 → 参数)

症状 首调 次调
写吞吐不足(Kv 族) RingPageSize 保持 256KB(勿升巨页——flush 写穿退化 ms 级) CommitInterval/攒批轴;独占↔共享调度对照(perf/hub-scheduler-ab.md)
磁盘写放大/空间涨 ResourceProfile.LowResource(段收敛) Queue/Collections 成员数盘点(组数=引擎放大器,§5 足迹速查)
内存工作集高 Ring 懒分配=预算非预占——核减 RingMemorySize 冷读比例下调;Queue 组数收敛(dense 域模型合册)
读穿透慢(冷数据) RingColdReadRatio 升 / ColdCacheCapacity 显式 分层根域(§4 档二)——温度启发式接管
线程账爆炸 确认 WorkerPolicy 共享档(hub.SharedWorkers 读面核验) 成员数 >16 本应共享——显式 SharedGroup(2) 兜底
过期/回收滞后 Policy.WithExpiryScanInterval(...) 全局调 集群档确认辖权循环在 leader(副本零本地判定)
集群写延迟/复制滞后/选主抖动 见 §4.5 集群调优速查(InFlight/选举窗/HighResolutionTimer) —

6. 足迹速查(容量规划输入)

  • 磁盘:段预分配 × 引擎束 × N。Kv=3 引擎(256MB 段=0.75GB×N / 32MB 段=0.09GB×N); Queue=10 引擎 ×3.3 倍;Collections=4、ZSet=5、Series=4、Log/Blob=1~2。
  • 线程:共享档=O(核数)(N=128 实测 24 恒定);独占档=kv 12.1/成员、Queue 40.1/成员 (T0.4 曲线)。句柄:独占 N=128 实测 5704 → 共享 575。
  • 内存:Ring 预算懒分配非预占——真实工作集 ≈ 热数据页 + 冷缓存 0.25×页数。

7. 反模式

  1. 逐成员写同一参数:32 个成员各写 WithSegmentGrowthLimit(32MB)——用 hub 全局档/档位一次做全。
  2. mem 介质调预分配/独占:物理预分配与专属线程组的优势都在磁盘(分配税/IO 阻塞)—— 内存介质装配守卫已按本性处理,勿手动绕。
  3. LowResource 档当性能档:它是资源收敛档(DiskFull 消除),不是提速档。
  4. 绕过 WithXxx 直写属性:init-only 类型层面不可能——委托里写 o.X = v 编译即错。

8. 想深入

  • hub 五件原生能力总览(治理轴五支柱+管理面):hub-capability-overview.md
  • 资源曲线/调度 A/B 实测:perf/hub-resource-curve.md · perf/hub-scheduler-ab.md
  • 分层根域:src/KernLab.Tier.Core/docs/tiering.md
  • 产品各论:tierkv/tierqueue/tiercollections/tierseries/tierlog/tierblob/tiervarkv.md