[data_storage] separate TairMempool SSD storage type

Author: shaohuaxi

docs/BREAK_CHANGE.md

@@ -2,6 +2,62 @@
 
 本文档记录需要调用方、部署配置或持久化状态协同升级的不兼容变更。升级前必须按对应条目的前置条件处理，不能仅替换 KVCM 二进制。
 
+## TairMempool SSD 独立 Storage Type
+
+Introduced by: PR #293
+
+TairMempool DRAM 继续使用 `ST_TAIRMEMPOOL`/`pace`，LocalSSD 新增
+`ST_TAIRMEMPOOL_SSD`/`pace_ssd`。两者仍共享 `pace://` 数据面协议，但 KVCM 从此分别统计
+quota 和类型水位，使 DRAM 高水位能够触发到 SSD 的自动迁移。
+
+### 不兼容内容
+
+- Proto/领域枚举新增 `ST_TAIRMEMPOOL_SSD = 9`，配置 JSON 新增持久化类型字符串
+  `"pace_ssd"`，写入策略新增 `CPS_ALWAYS_TAIR_MEMPOOL_SSD = 9` 和
+  `CPS_PREFER_TAIR_MEMPOOL_SSD = 10`。
+- 老 Worker Client 不认识 `pace_ssd`。Manager 把新 Storage 配置下发给老 Worker 后，老
+  Client 会把它解析为 UNKNOWN，并可能以 `ER_INVALID_SDKBACKEND_CONFIG` 结束整个
+  TransferClient 初始化，而不只是跳过 SSD backend。
+- 老 KVCM Server 不认识 Registry 中的 `"type":"pace_ssd"`。直接回滚旧二进制会导致该
+  Storage backend 恢复失败，Registry recovery 无法完成并持续重试。
+- Storage 类型属于持久化 CacheLocation 和用量账本的一部分，不支持同名 Storage 从
+  `pace` 原地改成 `pace_ssd`。服务端现在拒绝涉及 TairMempool DRAM/SSD 的原地类型变更；
+  修改 timeout、domain 等同类型参数仍可使用 `update_storage`。
+- 开源占位 backend 已按 `StorageConfig.type()` 返回类型。实际部署使用的 PACE backend 也
+  必须返回配置中的类型，并在构造 URI 时固定使用 `pace` scheme；若仍硬编码
+  `ST_TAIRMEMPOOL` 或使用 `ToString(GetType())` 构造 scheme，独立计量会静默失效或生成
+  不兼容的 `pace_ssd://` URI。
+
+### 启用前置条件和顺序
+
+1. 先升级所有 Worker Client，使其能够解析类型 9、创建对应 TairMempool SDK，并继续识别
+   `pace://` URI。在确认集群不存在老 Client 后再进入下一步。
+2. 升级全部 KVCM Server 和实际 PACE backend，确认 backend 的 `GetType()` 等于
+   `StorageConfig.type()`，DRAM/SSD 生成的 URI scheme 均为 `pace`。
+3. 为 SSD **新建不同名称**的 `pace_ssd` Storage。不要对已有 `pace` Storage 执行类型更新。
+   `kvcm_ops` 中 `pace` 只接受 media type 0/2；`pace_ssd` 子命令固定使用 media type 5，
+   add/update 请求都会显式携带 StorageType，避免修改 timeout 时静默降回 DRAM 类型。
+4. 在每个启用迁移的 Instance Group 中，为 `pace` 与 `pace_ssd` 分别配置正数
+   `quota_config.capacity`。类型水位只遍历显式 quota；缺少源类型 quota 时迁移不会触发，
+   缺少 SSD quota 时 SSD 没有独立水位和类型容量保护。
+5. 迁移规则继续以 DRAM Storage 为 `source_storage_name`、新 SSD Storage 为
+   `target_storage_name`。SSD 只作迁移目标时无需加入 `storage_candidates`；直接写 SSD 时
+   才加入候选并选用 SSD 专用 CachePreferStrategy。
+6. 用空 Instance Group 或测试 Instance 验证一次 DRAM 写入与 DRAM→SSD 迁移：新 Location
+   分别记录 type 3/type 9，DRAM 用量下降、SSD 用量上升，且 Worker 能读写 `pace://` URI。
+
+旧的 `ST_TAIRMEMPOOL + media_type=5` 配置仍可读取并继续按旧类型计量，但不能通过原地改类型
+获得独立水位。迁移方式是新建 `pace_ssd` Storage，将新迁移流量切到它；旧 Storage 必须保留
+到历史 Location 排空，避免 GC/读取找不到原 backend。
+
+### 回滚说明
+
+创建任何 `pace_ssd` Registry 配置前，可以直接回滚，因为新类型尚未进入持久化状态。创建后
+不能直接换回不认识类型 9 的旧 Server/Client。回滚前必须停止新写入和迁移，删除或排空所有
+type 9 CacheLocation，确认其物理数据已清理，再删除 `pace_ssd` Storage 与相关 quota/迁移配置；
+之后才能回滚二进制。仅把新 Storage 改名或原地改回 `pace` 不能修复已有 Location 的类型和
+用量，且服务端会拒绝这种类型更新。
+
 ## Vineyard 事件上报升级为 EventReportBackend
 
 Introduced by: PR #249

docs/configuration.md

@@ -177,7 +177,7 @@ timeout，因此不会使用配置数组顺序作为隐式优先级。
 ```TEXT
 {
     "storage_config": {
-        "type": "file", # 后端类型，可选值file,pace,mooncake,hf3fs,vcns_hf3fs
+        "type": "file", # 后端类型，可选值file,pace,pace_ssd,mooncake,hf3fs,vcns_hf3fs
         "global_unique_name": "nfs_01", # storage backend的名字，需要全局唯一
         "storage_spec": { # storage spec 需根据不同backend类型相应配置，TODO：具体每个type的spec配置文档
             "root_path": "/tmp/nfs/",
@@ -205,6 +205,10 @@ timeout，因此不会使用配置数组顺序作为隐式优先级。
                 {
                     "storage_type": "pace",
                     "capacity": 10000000000
+                },
+                {
+                    "storage_type": "pace_ssd",
+                    "capacity": 10000000000
                 }
             ]
         },
@@ -227,6 +231,8 @@ timeout，因此不会使用配置数组顺序作为隐式优先级。
             # CPS_PREFER_TAIR_MEMPOOL = 6,
             # CPS_ALWAYS_VCNS_3FS = 7,
             # CPS_PREFER_VCNS_3FS = 8,
+            # CPS_ALWAYS_TAIR_MEMPOOL_SSD = 9,
+            # CPS_PREFER_TAIR_MEMPOOL_SSD = 10,
             # };
             "cache_prefer_strategy": 2,
             "meta_indexer_config": {
@@ -254,6 +260,28 @@ timeout，因此不会使用配置数组顺序作为隐式优先级。
 }
 ```
 
+TairMempool DRAM 使用 `pace`（proto `ST_TAIRMEMPOOL`），LocalSSD 使用
+`pace_ssd`（proto `ST_TAIRMEMPOOL_SSD`，同时要求 `media_type=5`）。两类 storage
+仍使用 `pace://` 数据面 URI，但 quota、类型水位和迁移触发用量分别统计。旧的
+`ST_TAIRMEMPOOL + media_type=5` 配置仍可读取，迁移到新类型后才能获得独立 SSD 水位。
+
+启用独立 SSD 类型时还需遵守以下配置约束：
+
+- 使用 `kvcm_ops add_storage ... pace_ssd` 创建一个新的、全局唯一的 Storage；不要把已有
+  `pace` Storage 原地更新为 `pace_ssd`。Storage 类型会写入 CacheLocation 和用量账本，
+  服务端会拒绝同名 Storage 的类型变更。
+- Instance Group 的 `quota.quota_config` 必须同时为 `pace` 和 `pace_ssd` 配置正容量。
+  类型水位只遍历这里显式出现的类型；缺少 `pace_ssd` 时不会形成 SSD 类型水位和容量上限，
+  缺少迁移源 `pace` 时迁移规则不会触发。
+- SSD 仅作为迁移目标时，不要求放入 `storage_candidates`；迁移规则按
+  `target_storage_name` 精确选择它。若需要把普通新写入直接落到 SSD，则必须把 SSD Storage
+  放入 `storage_candidates`，并使用 `CPS_ALWAYS_TAIR_MEMPOOL_SSD` 或
+  `CPS_PREFER_TAIR_MEMPOOL_SSD`。
+- `pace` 和 `pace_ssd` 的数据面 URI scheme 都是 `pace://`。`pace_ssd` 只用于配置、计量
+  和选择，不能生成 `pace_ssd://` URI。
+
+详细升级顺序和回滚限制见 [Breaking Changes](BREAK_CHANGE.md#tairmempool-ssd-独立-storage-type)。
+
 ## Logger Config
 
 ```TEXT

kv_cache_manager/client/src/internal/config/sdk_config.cc

@@ -103,7 +103,7 @@ std::string MooncakeSdkConfig::ToString() const {
     return oss.str();
 }
 
-TairMempoolSdkConfig::TairMempoolSdkConfig() { set_type(DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL); }
+TairMempoolSdkConfig::TairMempoolSdkConfig(DataStorageType type) { set_type(type); }
 
 bool TairMempoolSdkConfig::FromRapidValue(const rapidjson::Value &rapid_value) {
     return SdkBackendConfig::FromRapidValue(rapid_value);
@@ -146,7 +146,8 @@ bool SdkWrapperConfig::FromRapidValue(const rapidjson::Value &rapid_value) {
                 sdk_backend_config = std::make_shared<MooncakeSdkConfig>();
                 break;
             case DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL:
-                sdk_backend_config = std::make_shared<TairMempoolSdkConfig>();
+            case DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL_SSD:
+                sdk_backend_config = std::make_shared<TairMempoolSdkConfig>(type);
                 break;
             case DataStorageType::DATA_STORAGE_TYPE_NFS:
                 sdk_backend_config = std::make_shared<NfsSdkConfig>();

kv_cache_manager/client/src/internal/config/sdk_config.h

@@ -150,7 +150,7 @@ class MooncakeSdkConfig : public SdkBackendConfig {
 
 class TairMempoolSdkConfig : public SdkBackendConfig {
 public:
-    TairMempoolSdkConfig();
+    explicit TairMempoolSdkConfig(DataStorageType type = DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL);
     bool FromRapidValue(const rapidjson::Value &rapid_value) override;
     void ToRapidWriter(rapidjson::Writer<rapidjson::StringBuffer> &writer) const noexcept override;
 
@@ -205,6 +205,8 @@ class SdkWrapperConfig : public Jsonizable {
         {DataStorageType::DATA_STORAGE_TYPE_HF3FS, std::make_shared<Hf3fsSdkConfig>()},
         {DataStorageType::DATA_STORAGE_TYPE_VCNS_HF3FS, std::make_shared<Hf3fsSdkConfig>()},
         {DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL, std::make_shared<TairMempoolSdkConfig>()},
+        {DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL_SSD,
+         std::make_shared<TairMempoolSdkConfig>(DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL_SSD)},
         {DataStorageType::DATA_STORAGE_TYPE_NFS, std::make_shared<NfsSdkConfig>()}};
     SdkTimeoutConfig timeout_config_;
 };

kv_cache_manager/client/src/internal/config/test/client_config_test.cc

@@ -54,8 +54,7 @@ TEST_F(ClientConfigTest, TestClientConfigTairMemPoolSuccess) {
     auto sdk_wrapper_config = client_config.sdk_wrapper_config();
     ASSERT_TRUE(sdk_wrapper_config);
     auto sdk_backend_configs_map = sdk_wrapper_config->sdk_backend_configs_map();
-    // 默认就加了3个
-    ASSERT_EQ(4, sdk_backend_configs_map.size());
+    ASSERT_EQ(5, sdk_backend_configs_map.size());
     auto tair_mempool_config = sdk_backend_configs_map[DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL];
     ASSERT_TRUE(tair_mempool_config);
     ASSERT_EQ("logs/pace_client.log", tair_mempool_config->sdk_log_file_path());

kv_cache_manager/client/src/internal/config/test/sdk_config_test.cc

@@ -107,13 +107,37 @@ TEST_F(SdkBackendConfigTest, TestSdkWrapperConfigGetSdkConfig) {
     auto tair_config = sdk_wrapper_config.GetSdkBackendConfig(DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL);
     ASSERT_NE(tair_config, nullptr);
 
+    auto tair_ssd_config = sdk_wrapper_config.GetSdkBackendConfig(DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL_SSD);
+    ASSERT_NE(tair_ssd_config, nullptr);
+    EXPECT_EQ(DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL_SSD, tair_ssd_config->type());
+
     auto nfs_config = sdk_wrapper_config.GetSdkBackendConfig(DataStorageType::DATA_STORAGE_TYPE_NFS);
     ASSERT_NE(nfs_config, nullptr);
 
     auto unknown_config = sdk_wrapper_config.GetSdkBackendConfig(DataStorageType::DATA_STORAGE_TYPE_UNKNOWN);
     ASSERT_EQ(unknown_config, nullptr);
 }
 
+TEST_F(SdkBackendConfigTest, TestSdkWrapperConfigParsesTairMempoolSsd) {
+    SdkWrapperConfig sdk_wrapper_config;
+    ASSERT_TRUE(sdk_wrapper_config.FromJsonString(R"({
+        "thread_num": 8,
+        "queue_size": 2000,
+        "sdk_backend_configs": [{
+            "type": "pace_ssd",
+            "sdk_log_file_path": "logs/pace_ssd_client.log",
+            "sdk_log_level": "INFO",
+            "spec_byte_sizes_per_block": {}
+        }],
+        "timeout_config": {"put_timeout_ms": 15000, "get_timeout_ms": 15000}
+    })"));
+
+    const auto config = sdk_wrapper_config.GetSdkBackendConfig(DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL_SSD);
+    ASSERT_NE(nullptr, config);
+    EXPECT_EQ(DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL_SSD, config->type());
+    EXPECT_EQ("logs/pace_ssd_client.log", config->sdk_log_file_path());
+}
+
 TEST_F(SdkBackendConfigTest, TestDuplicatedSdkConfig) {
     SdkWrapperConfig sdk_wrapper_config;
     std::string file_content = getFileContent("sdk_wrapper_config_duplicated_sdk_config.json");

kv_cache_manager/client/src/internal/sdk/sdk_factory.cc

@@ -43,6 +43,7 @@ std::shared_ptr<SdkInterface> SdkFactory::CreateSdk(const DataStorageType &type,
 #endif
 #ifdef ENABLE_TAIR_MEMPOOL
     case DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL:
+    case DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL_SSD:
         sdk = std::make_shared<TairMempoolSdk>();
         break;
 #endif
@@ -69,4 +70,4 @@ std::shared_ptr<SdkInterface> SdkFactory::CreateSdk(const DataStorageType &type,
     return sdk;
 }
 
-} // namespace kv_cache_manager
+} // namespace kv_cache_manager

kv_cache_manager/config/cache_config.h

@@ -32,6 +32,8 @@ enum class CachePreferStrategy {
     CPS_PREFER_TAIR_MEMPOOL = 6,
     CPS_ALWAYS_VCNS_3FS = 7,
     CPS_PREFER_VCNS_3FS = 8,
+    CPS_ALWAYS_TAIR_MEMPOOL_SSD = 9,
+    CPS_PREFER_TAIR_MEMPOOL_SSD = 10,
 };
 
 /*

kv_cache_manager/config/registry_manager.cc

@@ -186,6 +186,18 @@ ErrorCode RegistryManager::UpdateStorage(RequestContext *request_context,
     std::unique_lock<std::shared_mutex> lock(mutex_);
     const auto &trace_id = request_context->request_id();
     const auto &global_unique_name = storage_config.global_unique_name();
+    const auto current_backend = data_storage_manager_->GetDataStorageBackend(global_unique_name);
+    const auto current_type = current_backend == nullptr ? DataStorageType::DATA_STORAGE_TYPE_UNKNOWN
+                                                         : current_backend->GetStorageConfig().type();
+    if (current_backend != nullptr && current_type != storage_config.type() &&
+        (IsTairMempoolStorageType(current_type) || IsTairMempoolStorageType(storage_config.type()))) {
+        PREFIX_LOG_S(WARN,
+                     "update storage rejected: TairMempool storage type is immutable, current type: [%d], requested "
+                     "type: [%d]",
+                     static_cast<int>(current_type),
+                     static_cast<int>(storage_config.type()));
+        return EC_BADARGS;
+    }
     // 重建期间短暂不可用
     auto ec = RemoveStorage(request_context, global_unique_name);
     RETURN_IF_EC_NOT_OK_WITH_LOG_S(WARN, ec, "update storage failed: remove storage failed");

kv_cache_manager/config/test/instance_group_test.cc

@@ -230,4 +230,43 @@ TEST_F(InstanceGroupTest, EventReportStorageSpecProtoRoundTripPreservesSnapshotS
     EXPECT_EQ(8765, restored_spec->snapshot_delta_drain_timeout_ms());
 }
 
+TEST_F(InstanceGroupTest, TairMempoolSsdStorageProtoRoundTripPreservesTypeAndMedia) {
+    auto spec = std::make_shared<TairMemPoolStorageSpec>();
+    spec->set_domain("pace.meta");
+    spec->set_timeout(5000);
+    spec->set_service_discovery_url("spectrum://pace-meta");
+    spec->set_media_type(kTairMemPoolMediaTypeSsd);
+    StorageConfig original(DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL_SSD, "pace_ssd_1", spec);
+
+    proto::admin::StorageConfig proto_config;
+    ProtoConvert::StorageConfigToProto(original, &proto_config);
+    ASSERT_TRUE(proto_config.has_tair_mem_pool());
+    EXPECT_EQ(proto::admin::ST_TAIRMEMPOOL_SSD, proto_config.storage_type());
+    EXPECT_EQ(kTairMemPoolMediaTypeSsd, proto_config.tair_mem_pool().media_type());
+
+    StorageConfig restored;
+    ProtoConvert::StorageFromProto(&proto_config, restored);
+    EXPECT_EQ(DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL_SSD, restored.type());
+    const auto restored_spec = std::dynamic_pointer_cast<TairMemPoolStorageSpec>(restored.storage_spec());
+    ASSERT_NE(nullptr, restored_spec);
+    EXPECT_EQ(kTairMemPoolMediaTypeSsd, restored_spec->media_type());
+    EXPECT_EQ("spectrum://pace-meta", restored_spec->service_discovery_url());
+}
+
+TEST_F(InstanceGroupTest, LegacyTairMempoolProtoWithoutStorageTypeRemainsDramType) {
+    proto::admin::StorageConfig legacy;
+    legacy.set_global_unique_name("legacy_pace");
+    auto *spec = legacy.mutable_tair_mem_pool();
+    spec->set_domain("pace.meta");
+    spec->set_timeout(5000);
+    spec->set_media_type(kTairMemPoolMediaTypeSsd);
+
+    StorageConfig restored;
+    ProtoConvert::StorageFromProto(&legacy, restored);
+    EXPECT_EQ(DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL, restored.type());
+    const auto restored_spec = std::dynamic_pointer_cast<TairMemPoolStorageSpec>(restored.storage_spec());
+    ASSERT_NE(nullptr, restored_spec);
+    EXPECT_EQ(kTairMemPoolMediaTypeSsd, restored_spec->media_type());
+}
+
 } // namespace kv_cache_manager