[data_storage] separate TairMempool SSD storage type

Author: shaohuaxi

docs/BREAK_CHANGE.md

@@ -2,6 +2,63 @@
 
 本文档记录需要调用方、部署配置或持久化状态协同升级的不兼容变更。升级前必须按对应条目的前置条件处理，不能仅替换 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` 中 `add_storage pace` 只接受 media type 0/2；`pace_ssd` 子命令固定使用 media
+   type 5。`update_storage pace` 未指定 media type 时会读取并保留原 Storage 的 type/media，
+   包括旧的 `ST_TAIRMEMPOOL + media_type=5`，不会在修改 timeout 时静默改变介质或类型。
+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

@@ -206,7 +206,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/",
@@ -234,6 +234,10 @@ timeout，因此不会使用配置数组顺序作为隐式优先级。
                 {
                     "storage_type": "pace",
                     "capacity": 10000000000
+                },
+                {
+                    "storage_type": "pace_ssd",
+                    "capacity": 10000000000
                 }
             ]
         },
@@ -256,6 +260,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": {
@@ -283,6 +289,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

@@ -26,6 +26,24 @@ std::shared_ptr<SdkInterface> SdkFactory::CreateSdk(const DataStorageType &type,
         KVCM_LOG_WARN("sdk_backend_config or storage_config is null");
         return nullptr;
     }
+    auto sdk = CreateSdkInstance(type);
+    if (!sdk) {
+        KVCM_LOG_WARN("unsupported sdk type: %s", ToString(type).c_str());
+        return nullptr;
+    }
+    auto ec = sdk->Init(sdk_backend_config, storage_config);
+    if (ec != ER_OK) {
+        KVCM_LOG_WARN("init sdk failed, type:%s, sdk backend config: %s, storage config: %s, errorcode: %d",
+                      ToString(type).c_str(),
+                      sdk_backend_config->ToJsonString().c_str(),
+                      storage_config->ToString().c_str(),
+                      ec);
+        return nullptr;
+    }
+    return sdk;
+}
+
+std::shared_ptr<SdkInterface> SdkFactory::CreateSdkInstance(const DataStorageType &type) {
     std::shared_ptr<SdkInterface> sdk;
     switch (type) {
 #ifdef ENABLE_HF3FS
@@ -43,30 +61,17 @@ 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
     case DataStorageType::DATA_STORAGE_TYPE_NFS:
         sdk = std::make_shared<LocalFileSdk>();
         break;
     default:
-        KVCM_LOG_WARN("unsupported sdk type: %s", ToString(type).c_str());
-        return nullptr;
-    }
-    if (!sdk) {
-        KVCM_LOG_WARN("create sdk failed, sdk is null, type:%s", ToString(type).c_str());
-        return nullptr;
-    }
-    auto ec = sdk->Init(sdk_backend_config, storage_config);
-    if (ec != ER_OK) {
-        KVCM_LOG_WARN("init sdk failed, type:%s, sdk backend config: %s, storage config: %s, errorcode: %d",
-                      ToString(type).c_str(),
-                      sdk_backend_config->ToJsonString().c_str(),
-                      storage_config->ToString().c_str(),
-                      ec);
         return nullptr;
     }
     return sdk;
 }
 
-} // namespace kv_cache_manager
+} // namespace kv_cache_manager

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

@@ -12,6 +12,9 @@ class SdkFactory {
     static std::shared_ptr<SdkInterface> CreateSdk(const DataStorageType &type,
                                                    const std::shared_ptr<SdkBackendConfig> &sdk_backend_config,
                                                    const std::shared_ptr<StorageConfig> &storage_config);
+
+private:
+    static std::shared_ptr<SdkInterface> CreateSdkInstance(const DataStorageType &type);
 };
 
-} // namespace kv_cache_manager
+} // namespace kv_cache_manager

kv_cache_manager/client/src/internal/sdk/test/BUILD

@@ -57,6 +57,16 @@ cc_test(
     ],
 )
 
+cc_test(
+    name = "SdkFactoryTest",
+    srcs = ["sdk_factory_test.cc"],
+    copts = ["-fno-access-control"],
+    deps = [
+        "//kv_cache_manager/client/src/internal/sdk",
+        "//kv_cache_manager/common:unittest",
+    ],
+)
+
 cc_test(
     name = "hf3fs_sdk_test",
     srcs = select({

kv_cache_manager/client/src/internal/sdk/test/sdk_factory_test.cc

@@ -0,0 +1,22 @@
+#include <gtest/gtest.h>
+#include <typeinfo>
+
+#include "kv_cache_manager/client/src/internal/sdk/sdk_factory.h"
+#include "kv_cache_manager/common/unittest.h"
+
+using namespace kv_cache_manager;
+
+TEST(SdkFactoryTest, TairMempoolDramAndSsdCreateSameSdkType) {
+#ifdef ENABLE_TAIR_MEMPOOL
+    const auto dram_sdk = SdkFactory::CreateSdkInstance(DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL);
+    const auto ssd_sdk = SdkFactory::CreateSdkInstance(DataStorageType::DATA_STORAGE_TYPE_TAIR_MEMPOOL_SSD);
+
+    ASSERT_NE(nullptr, dram_sdk);
+    ASSERT_NE(nullptr, ssd_sdk);
+    EXPECT_EQ(SdkType::TAIR_MEMPOOL, dram_sdk->Type());
+    EXPECT_EQ(SdkType::TAIR_MEMPOOL, ssd_sdk->Type());
+    EXPECT_EQ(typeid(*dram_sdk), typeid(*ssd_sdk));
+#else
+    GTEST_SKIP() << "TairMempool SDK is disabled";
+#endif
+}