冷热分层(Tiering)——fs 域内自动升降温
定位:fs 空间域的冷热分层——热根/冷根两级联动 + 目录域策略 + region 级温度迁移。 产品数据文件天然活在 fs 上:分层在 fs 域内做,全部产品零改动获得升降温能力 (调用方永不选根、永不感知冷热——无差别原则)。
0. 快速上手(30 秒)
// 挂载:热根/冷根/锚根(journal 载体,缺省=冷根)三根声明,成员根用现有 scheme
using var volume = TieringVolume.Mount(new TieringMountOptions()
.WithHotSpec("virtual:///data/hot") // 热根(TierVolume/local/memory:)
.WithColdSpec("local:///mnt/hdd")); // 冷根(HDD/S3 平权)
// 业务侧:普通 IFileSystem 用法——单树路径,零感知
volume.CreateDirectory("data");
using (var w = volume.Open("data/seg.0", new FileOpenOptions { Access = AccessMode.ReadWrite }))
w.Write(0, payload);
// 管理侧:降冷/升温经协调器(region 级粒度,崩溃一致)
await volume.Coordinator.DemoteAsync("data/seg.0"); // 整文件降冷
await volume.Coordinator.DemoteRegionAsync("data/seg.0", // region 降冷
offset: 1 << 20, length: 1 << 20);
await volume.Coordinator.PromoteAsync("data/seg.0"); // 整文件升温
降冷后读不变:门面句柄自动拼接(账区间读冷根、账外读热根),调用方读到的 永远是完整内容。
1. 概念(术语在此定义)
| 术语 | 含义 |
|---|---|
| 热根 | 常态数据面(洞占位与未降冷数据的真源)——温根/L0。 |
| 冷根 | 下位根域(HDD TierVolume / S3 平权)——降冷数据的真源。 |
| 锚根 | 迁移 journal 的载体(须耐久;缺省=冷根)——决策唯一权威。 |
| 目录域 | 路径前缀声明的策略子树:PinHot(永不降)/ TierAuto(按温度降升,缺省)/ ColdOnly(创建直落冷根)。子目录继承最近祖先声明。 |
| region | 迁移的几何单位(文件内一段 [offset, length))。文件级迁移 = 单 region [0, L) 特例——同一套账本与事务。 |
| 冷占位账 | 协调器账本:路径的 region 集合。有账区间=冷占位(读穿透/回迁),无账区间=热真源——洞的语义仲裁判据(E13)。 |
| 迁移事务 | 平台统一提交骨架的 fs 实例化:staged(冷副本写穿+校验,可弃)→ decided(锚根 journal 定案,原子点)→ applied(打洞/回填,幂等)。崩溃恢复自检收敛,不依赖产品。 |
| 降冷(demote) | region 内容写穿冷根 → journal 定案 → 热根打洞(洞=「内容在下位根」的天然占位标记)。 |
| 升温(promote) | 冷根该 region 读回校验 → journal 定案 → 热根回填 → 冷 region 回收。 |
冷副本形态:同 offset 稀疏镜像
冷根文件与热根文件同名同径同 offset:降冷哪些 region,冷文件哪些区间有内容, 其余是洞。region 降冷只写自己的区间——一个大文件可以只降冷尾部段,头部段保持热真源。
2. 怎么用
2.1 挂载与域策略
var policy = new DirectoryDomainPolicy();
policy.SetDomain("archive", DirectoryDomainState.ColdOnly); // 只住冷根
policy.SetDomain("hot", DirectoryDomainState.PinHot); // 永不降
policy.SetDomain("hot/sub", DirectoryDomainState.TierAuto); // 子域显式覆盖父域
using var volume = TieringVolume.Mount(new TieringMountOptions()
.WithHotSpec("virtual:///tier/hot")
.WithColdSpec("local:///mnt/hdd")
.WithAnchorSpec("local:///mnt/hdd") // 缺省=冷根,可显式指到更耐久的根
.WithPolicy(policy));
hub 根域挂载(档二——资源模型实测基线 perf/hub-resource-curve.md):Mount 产物即完整 IFileSystem,
直接作 TierHubBuilder 根域——全部成员引擎子目录挂分层根,fs 域内冷热分层产品零改动获得
(根域唯一不变式不破坏;第二 fs 例外仍仅限备份/归档外部面与 raft wal 域)。
易失热根强制配对(E10):热根为 memory 本性时必须声明耐久配对根,否则拒绝挂载——
using var volume = TieringVolume.Mount(new TieringMountOptions()
.WithHotSpec("memory:") // 易失热根(L0)
.WithHotDurabilityPairSpec("virtual:///tier/pair") // 耐久镜像根(非 memory 本性)
.WithColdSpec("local:///mnt/hdd"));
配对生效后热根变更为写穿形态:全部变更先写穿镜像根(落盘)再落易失根,掉电后 重挂载按镜像真源重建易失根(残留补删/缺失拷回/内容覆盖)。代价是热路径双写—— L0 换来的是进程崩溃不丢数据。挂载成员根为幂等动词(OpenOrCreate):已有载体打开、 新载体格式化,重挂载可行。
挂载即恢复自检(T12.3①——挂载流程内联自动调用):上次迁移半途态(决策已定案、apply 未落)
启动即收敛,无需显式调用;恢复报告经 volume.Coordinator.LastRecoveryReport 观测(幂等——
显式二次 RecoverAsync 零计数)。
2.2 迁移(协调器管理面)
var coordinator = volume.Coordinator;
// 整文件(=单 region [0,L))
await coordinator.DemoteAsync("data/seg.0");
// region 粒度(大文件分段降冷——内存封顶、崩溃粒度细)
await coordinator.DemoteRegionAsync("data/seg.0", offset, length);
// 查账(读面):region 账快照(按 Offset 升序)
TieringOwnershipTable.RegionEntry[] regions = coordinator.GetColdRegions("data/seg.0");
// 回迁:整文件 / 按 GetColdRegions 的几何精确回迁单个 region
await coordinator.PromoteAsync("data/seg.0");
await coordinator.PromoteRegionAsync("data/seg.0", regions[0].Offset, regions[0].Length);
约定:
- demote 与既有账重叠拒绝(邻接合法)——重复迁移确定性报错。
- promote 按账几何精确匹配——先
GetColdRegions再按几何调用。 - pin:hot 域降冷确定性拒绝。
Move 免疫:冷占位文件移动 = 账随文件走(journal Rebind 决策先行——冷副本随移、 热根 rename,崩溃恢复自检补齐 rename 窗),不回迁不拉回;移动到已存在目标须先删 后移(协议 v1 边界)。目录迁移子树含冷占位文件时 fail-fast(先 PromoteAsync 再移, 或逐文件 Move)。
2.3 自动升降温(温度启发式)
using var sweep = new TieringAutoSweep(volume, policy,
new TieringAutoSweepOptions()
.WithColdAfterAge(TimeSpan.FromDays(30)) // LastWriteTime 年龄阈值
.WithRegionSize(64L * 1024 * 1024)); // 降冷执行分块
// 调用方定节律(后台循环生命周期归调用方)
while (!ct.IsCancellationRequested)
{
await sweep.SweepAsync(ct);
await Task.Delay(TimeSpan.FromHours(1), ct);
}
扫描只动 TierAuto 域;PinHot 跳过;已冷幂等跳过。降冷按 RegionSize 分块逐
region 决策——单 region 崩溃只补单 region。
顺序读回迁档(缺省关闭):
sweep.EnableSequentialPromotion(thresholdBytes: 8L << 20); // 连续冷读 8MB 触发整文件回迁
读穿透句柄的冷读被观测累计,连续顺序读达阈值即经 TaskSink 异步回迁——冷数据的 顺序扫描(如压缩/校验任务)自动升回热根。
访问频率回迁档(缺省关闭):
sweep.EnableFrequencyPromotion(
hits: 16, // 滑窗内冷读命中次数阈值
window: TimeSpan.FromMinutes(5), // 统计窗口(窗口外命中出列)
cooldown: TimeSpan.FromHours(1)); // 回迁后降冷冷却
滑窗内散读(非连续)命中达到阈值即整文件回迁——随机点查驱动的热文件自动升温。
两档共用同一冷读观测缝,任一触发即进入回迁冷却(DemoteCooldown):刚回迁的
文件在该时长内不被扫描降冷(防升降温抖动的迟滞窗;过期后恢复按年龄降冷)。
2.4 句柄行为(产品视角的契约)
门面 Open 全部返回逐操作仲裁句柄:
| 动词 | 行为 |
|---|---|
| 读 | 热根读 + 账区间冷根覆盖拼接——调用方零感知;无账零仲裁直达热根。 |
| 追加(Length 处) | 恒落账外尾域——不回填不销账(续写不拉回冷数据)。 |
| 写命中账外 | 直写热根,零介入。 |
| 写完全覆盖账 region | 写热 + flush 后补作废(该 region 销账+冷回收;其余 region 账保持)。 |
| 写部分覆盖账 region | 先整 region 回迁再写(保留段内容不丢)。 |
| 打洞/截断命中账 | 级联销账+冷回收(删除语义不复活);跨界 region 先回迁保留段。 |
| 映射(Map) | 冷占位文件禁用(fail-fast——MMF 绕过逐读仲裁)。 |
运行期热迁移:句柄不持路由状态,打开先于迁移的句柄同样逐读仲裁——迁移前后 同一句柄透明。并发契约:写与迁移竞速由锚根 journal 线性化(禁双主);对同一 region 的写与降冷并发属调用方线性化责任(迁移前静默段是管理面纪律)。
3. 崩溃一致性与恢复
迁移事务三步各有注入点语义(staged 可弃 / decided 唯一权威 / applied 幂等),
崩溃后挂载自检收敛:
| 崩溃窗 | 恢复动作 |
|---|---|
| 冷副本写穿后、定案前 | 冷副本视为孤儿,GC 回收(stage 可弃)。 |
| 定案后、打洞前 | 账已 durable——补打洞(apply 幂等补齐)。 |
| 回迁定案后、回填前 | 账已移除——从冷根补齐回填(promote 回填补齐)。 |
| 写热+flush 后、补作废前 | 热内容≠冷账=写胜出——补记作废,冷副本回收。 |
| 冷回收半途 | 孤儿冷 region 按账对账打洞/删文件。 |
| Move 决策后、rename 未落(其一/双根) | 账已随决策改绑——按 Rebind 记录补齐热根/冷副本 rename。 |
fail-fast 边界:有账 region 冷根无副本 = 冷介质故障,恢复自检抛异常(数据不可 寻址不静默)。
4. 反模式
- 拿洞当删除判据:分层卷上「读到零」≠「未写/已删」——判据是账本
(
GetColdRegions)。有账区间读零只可能是管理面直开热根句柄绕过了门面。 - 绕过门面直写根文件系统:热根/冷根实例不要直接交给产品写数据(通道唯一性 是恢复自检分类判定的前提)。
- 对冷占位文件 Map:MMF 读不到冷数据(fail-fast)——冷数据走句柄读。
- 降冷正被随机写的文件:写命中即回迁,反复降冷-回迁空转——先确认段已封存 (append-only/静止段)再降冷。
- RegionSize 过小:journal 记录数与决策次数随之膨胀——与段/块几何对齐选档。
- 易失热根裸挂:memory 热根不配耐久镜像根 = 掉电丢全部热数据——挂载门禁 会拒绝(E10);不要寻找绕过,需要高带宽热层就付写穿双写代价。
- Move 冷占位文件到已存在目标 / 迁移含冷占位的目录:前者先删后移,后者先 PromoteAll——两处 fail-fast 是账键一致性边界,不是可以绕过的检查。
4.1 温度启发式装配指引(T12.3②——缺省策略参数登记)
降冷(AutoSweep):tier:auto 域内 LastWriteTime 超 ColdAfterAge(缺省 30 天)的文件按
region 分块降冷(RegionSize 缺省 64MB,DemoteCooldown 缺省 1h 防降冷-回迁空转)。
升温(双档,缺省全关——按负载形态显式开启;装配面 = TieringAutoSweep,经 Coordinator.ColdReadObserved 缝接线):
- 顺序档
EnableSequentialPromotion(thresholdBytes):冷数据被顺序读超阈值即回迁(流式回放/扫描负载); - 频率档
EnableFrequencyPromotion(hits, window?, cooldown?):滑窗内冷读命中超阈值回迁(随机热读负载)。 两档亦可经 Options(SequentialPromoteBytes/FrequencyPromoteHits)装配期直接声明。
缺省定标依据(资源模型实测基线 perf/hub-resource-curve.md.2):保守取向——误降冷代价 = 一次顺序读回迁;
误驻热代价 = 热根占满后降速;二者间缺省偏保守。调整指引:热根水位常态化 >70% 先收窄
ColdAfterAge;回迁风暴先升 DemoteCooldown。
介质选型联动(资源模型实测基线 perf/hub-resource-curve.md):热根 memory+耐久配对(E10,写穿双写)/ 冷根 local·虚拟卷(TierVolumeFs)/ 锚根 journal(独立更耐久根防 journal 分裂脑)。
5. 想深入?指路
| 想懂什么 | 去哪 |
|---|---|
| 设计稿(根域×目录域×联动模型 / 决策点 E1-E13 / 波次) | docs/archive-2026-10-16.tar.gz(fs-tiering 设计稿已随归档波打包——现行事实源=本文档与 tiering.md 使用面) |
| hub 侧挂载消费面与治理轴能力全景(能力总览) | ../products/hub-capability-overview.html |
| IO 原语层(IFileSystem/IFileHandle 全平面) | io.md |
| 打洞/稀疏语义(四介质同语义) | io.md §4.3 |
| 迁移 journal 布局(TTJ3 39B 头,含记录级 BodyCrc;TTJ1/TTJ2 旧版式向后兼容读;BinaryLayout 生成) | 源码 IO/Tiering/TieringJournalHeader.cs |
| 契约测试(region 事务/句柄仲裁/恢复注入/启发式) | tests/KernLab.Tier.Core.Tests/IO/Tiering/ |