[common] document and test Redis DB isolation (alibaba#243)

Author: wangxiyu191

docs/configuration.md

@@ -19,9 +19,21 @@ Example:
 /home/admin/kv_cache_manager/bin/kv_cache_manager_bin \
     -c '/home/admin/kv_cache_manager/etc/default_server_config.conf' \
     -l '/home/admin/kv_cache_manager/etc/default_logger_config.conf' \
-    -e 'kvcm.registry_storage.uri=redis://:foo@bar:6379?cluster_name=placeholder'
+    -e 'kvcm.registry_storage.uri=redis://your_auth_token@redis-host:6379/?db=1&cluster_name=placeholder'
 ```
 
+### Redis URI
+
+Registry、Meta 和 Coordination Redis 后端共用以下 URI 格式：
+
+```TEXT
+redis://[auth_token@]host:port/?db=<non-negative-integer>[&param=value...]
+```
+
+- `auth_token` 会作为 Redis `AUTH` 命令的单个参数传入；`auth=...` query 参数不会用于认证。
+- `db` 必须放在 query 参数中；未配置时使用 DB 0。`redis://host:port/1` 中的 `/1` 是 path，不能用于选择 DB。
+- `db > 0` 依赖 Redis 服务端支持 `SELECT`。Redis Cluster 不支持多逻辑 DB，此时应使用 DB 0，并通过 `cluster_name` 和 key 前缀隔离，或使用独立 Redis 实例。
+
 ## KVCacheManager Server Config
 
 KVCM server可识别的配置参数列表如下。可通过配置文件、启动参数--env、系统环境变量进行配置。
@@ -35,10 +47,11 @@ CacheReclaimer 异步删除相关参数的生命周期语义见
 ## 3. 通过环境变量配置，set_env(kvcm.service.rpc_port, 6381)
 
 # 指定系统Registry自身数据存储位置
-# kvcm.registry_storage.uri=redis://127.0.0.1:6379?auth=123456
+# cluster_name必填；db必须通过query参数指定
+# kvcm.registry_storage.uri=redis://your_auth_token@127.0.0.1:6379/?db=1&cluster_name=kvcm_cluster
 
 # 指定协调后端服务的URI（用于多节点选主、节点信息存储等）。Redis选主key按cluster_name隔离。
-# kvcm.coordination.uri=redis://127.0.0.1:6379?auth=123456&cluster_name=kvcm_app_0
+# kvcm.coordination.uri=redis://your_auth_token@127.0.0.1:6379/?db=2&cluster_name=kvcm_app_0
 # 旧配置 kvcm.distributed_lock.uri 仍可使用（向后兼容），但新配置优先
 
 # 指定选主时当前节点使用的node_id（如果不指定会自动生成）
@@ -172,6 +185,9 @@ kvcm.event.event_publishers_configs
                 "mutex_shard_num": 16,
                 "batch_key_size": 16,
                 "meta_storage_backend_config": { # 控制meta indexer的storage backend，可选local本地文件或者redis
+                    # Redis示例：
+                    # "storage_type": "redis",
+                    # "storage_uri": "redis://your_auth_token@redis-host:6379/?db=3&client_max_pool_size=16"
                     "storage_type": "local",
                     "storage_uri": ""
                 },

docs/design/ha_leader_elector.md

@@ -58,7 +58,9 @@ KVCacheManager 支持多节点高可用（HA）部署模式。多个 KVCM 实例
 |---|---|---|
 | CoordinationMemoryBackend | `memory://` | 单进程测试 |
 | CoordinationFileBackend | `file:///path/to/dir` | 单机开发/测试 |
-| CoordinationRedisBackend | `redis://[password@]host:port[?params]` | 生产环境 |
+| CoordinationRedisBackend | `redis://[auth_token@]host:port/?db=<index>[&params]` | 生产环境 |
+
+Redis DB 只能通过 query 参数 `db` 指定，未配置时使用 DB 0；URI path（例如 `/1`）不会选择 DB。`db > 0` 要求 Redis 服务端支持 `SELECT`，因此不适用于 Redis Cluster。
 
 ### 3.2 LeaderElector
 
@@ -251,7 +253,7 @@ kvcm.leader_elector.loop_interval_ms=100
 **多节点 HA（Redis，生产）：**
 
 ```
-kvcm.coordination.uri=redis://your_password@redis-host:6379?timeout_ms=5000&retry_count=3&cluster_name=kvcm_app_0
+kvcm.coordination.uri=redis://your_auth_token@redis-host:6379/?db=2&timeout_ms=5000&retry_count=3&cluster_name=kvcm_app_0
 kvcm.leader_elector.lease_ms=10000
 kvcm.leader_elector.loop_interval_ms=100
 kvcm.service.advertised_host=10.0.0.1

kv_cache_manager/config/coordination_backend.h

@@ -24,7 +24,7 @@ class CoordinationBackend {
      *
      * @param standard_uri Standardized URI for configuring backend connection parameters
      *                     For local backend: file:///path/to/lock/dir
-     *                     For Redis backend: redis://host:port/db
+     *                     For Redis backend: redis://[auth_token@]host:port/?db=<index>[&param=value...]
      * @return ErrorCode error code
      *         - EC_OK: Initialization successful
      *         - EC_BADARGS: Invalid arguments (e.g., unsupported URI protocol)
@@ -141,4 +141,4 @@ class CoordinationBackend {
     virtual ErrorCode GetValue(const std::string &key, std::string &out_value) = 0;
 };
 
-} // namespace kv_cache_manager
+} // namespace kv_cache_manager

kv_cache_manager/config/test/BUILD

@@ -110,6 +110,8 @@ cc_test(
     ],
     deps = [
         ":coordination_backend_test_base",
+        "//kv_cache_manager/common:redis_client_ext",
+        "//kv_cache_manager/common:standard_uri",
         "//kv_cache_manager/common:unittest",
         "//kv_cache_manager/config:coordination_backend",
     ],

kv_cache_manager/config/test/coordination_redis_backend_test.cc

@@ -300,4 +300,48 @@ TEST_F(CoordinationRedisDiffClusterNameTest, TestLeaderElectionKeyIsolation) {
     ASSERT_EQ(EC_OK, backend_cluster_b_->Unlock(leader_lock_key, "node_b"));
 }
 
-} // namespace kv_cache_manager
+TEST(CoordinationRedisDbIsolationTest, SameKeysAreIsolatedByDb) {
+    const std::string uri_prefix = "redis://test_redis_user:test_redis_password@localhost:6379/"
+                                   "?timeout_ms=1000&retry_count=3&client_min_pool_size=1&client_max_pool_size=2";
+    const std::string cluster_name = "coordination_db_isolation_test";
+    const std::string uri_db0 = uri_prefix + "&db=0&cluster_name=" + cluster_name;
+    const std::string uri_db1 = uri_prefix + "&db=1&cluster_name=" + cluster_name;
+    const std::string key = "same_key";
+    const std::string lock_key = "same_lock";
+
+    RedisClientExt cleanup_db0(StandardUri::FromUri(uri_db0));
+    RedisClientExt cleanup_db1(StandardUri::FromUri(uri_db1));
+    ASSERT_TRUE(cleanup_db0.Open());
+    ASSERT_TRUE(cleanup_db1.Open());
+    const std::string redis_key = "kvcm_" + cluster_name + "_kv:" + key;
+    const std::string redis_lock_key = "kvcm_" + cluster_name + "_lock:" + lock_key;
+    cleanup_db0.Del(redis_key);
+    cleanup_db1.Del(redis_key);
+    cleanup_db0.Del(redis_lock_key);
+    cleanup_db1.Del(redis_lock_key);
+
+    auto backend_db0 = CoordinationBackendFactory::CreateAndInitCoordinationBackend(uri_db0);
+    auto backend_db1 = CoordinationBackendFactory::CreateAndInitCoordinationBackend(uri_db1);
+    ASSERT_NE(nullptr, backend_db0);
+    ASSERT_NE(nullptr, backend_db1);
+
+    ASSERT_EQ(EC_OK, backend_db1->SetValue(key, "db1"));
+    std::string value;
+    EXPECT_EQ(EC_NOENT, backend_db0->GetValue(key, value));
+    ASSERT_EQ(EC_OK, backend_db0->SetValue(key, "db0"));
+    ASSERT_EQ(EC_OK, backend_db0->GetValue(key, value));
+    EXPECT_EQ("db0", value);
+    ASSERT_EQ(EC_OK, backend_db1->GetValue(key, value));
+    EXPECT_EQ("db1", value);
+
+    // Locks use the same selected connection DB as coordination KV data.
+    ASSERT_EQ(EC_OK, backend_db0->TryLock(lock_key, "holder_db0", 5000));
+    ASSERT_EQ(EC_OK, backend_db1->TryLock(lock_key, "holder_db1", 5000));
+    ASSERT_EQ(EC_OK, backend_db0->Unlock(lock_key, "holder_db0"));
+    ASSERT_EQ(EC_OK, backend_db1->Unlock(lock_key, "holder_db1"));
+
+    cleanup_db0.Del(redis_key);
+    cleanup_db1.Del(redis_key);
+}
+
+} // namespace kv_cache_manager

kv_cache_manager/config/test/registry_manager_redis_backend_test.cc

@@ -8,6 +8,7 @@
 #include "kv_cache_manager/config/instance_group.h"
 #include "kv_cache_manager/config/instance_info.h"
 #include "kv_cache_manager/config/registry_manager.h"
+#include "kv_cache_manager/config/registry_storage_backend_factory.h"
 #include "kv_cache_manager/data_storage/data_storage_manager.h"
 #include "kv_cache_manager/data_storage/storage_config.h"
 #include "kv_cache_manager/metrics/metrics_registry.h"
@@ -99,6 +100,33 @@ TEST_F(RegistryManagerRedisBackendTest, TestInit) {
     ASSERT_FALSE(registry_manager_->Init());
 }
 
+TEST_F(RegistryManagerRedisBackendTest, TestRedisDbIsolation) {
+    const std::string uri_prefix =
+        "redis://test_redis_user:test_redis_password@localhost:6379/?timeout_ms=1000&retry_count=3";
+    const std::string cluster_name = "registry_db_isolation_test";
+    const std::string key = "same_key";
+
+    auto backend_db0 =
+        RegistryStorageBackendFactory::CreateAndInitStorageBackend(uri_prefix + "&db=0&cluster_name=" + cluster_name);
+    auto backend_db1 =
+        RegistryStorageBackendFactory::CreateAndInitStorageBackend(uri_prefix + "&db=1&cluster_name=" + cluster_name);
+    ASSERT_NE(nullptr, backend_db0);
+    ASSERT_NE(nullptr, backend_db1);
+
+    // Use the same cluster name and key so Redis DB is the only isolation boundary.
+    backend_db0->Delete(key);
+    backend_db1->Delete(key);
+    const std::map<std::string, std::string> expected{{"field", "db1"}};
+    ASSERT_EQ(EC_OK, backend_db1->Save(key, expected));
+
+    std::map<std::string, std::string> actual;
+    EXPECT_EQ(EC_NOENT, backend_db0->Load(key, actual));
+    ASSERT_EQ(EC_OK, backend_db1->Load(key, actual));
+    EXPECT_EQ(expected, actual);
+
+    EXPECT_EQ(EC_OK, backend_db1->Delete(key));
+}
+
 TEST_F(RegistryManagerRedisBackendTest, TestRecover) {
     // do init
     ASSERT_TRUE(InitRegistryManager());

kv_cache_manager/meta/test/meta_redis_backend_real_service_test.cc

@@ -71,6 +71,46 @@ TEST_F(MetaRedisBackendRealServiceTest, TestOpenAndClose) {
     ASSERT_TRUE(meta_redis_backend_->client_pool_ == nullptr);
 }
 
+TEST_F(MetaRedisBackendRealServiceTest, TestRedisDbIsolation) {
+    auto make_config = [](int64_t db) {
+        auto config = std::make_shared<MetaStorageBackendConfig>();
+        config->SetStorageType(META_REDIS_BACKEND_TYPE_STR);
+        config->SetStorageUri("redis://test_redis_user:test_redis_password@localhost:6379/"
+                              "?client_max_pool_size=2&db=" +
+                              std::to_string(db));
+        return config;
+    };
+
+    MetaRedisBackend backend_db0;
+    MetaRedisBackend backend_db1;
+    ASSERT_EQ(EC_OK, backend_db0.Init("test_redis_db_isolation", make_config(0)));
+    ASSERT_EQ(EC_OK, backend_db1.Init("test_redis_db_isolation", make_config(1)));
+    ASSERT_EQ(EC_OK, backend_db0.Open());
+    ASSERT_EQ(EC_OK, backend_db1.Open());
+
+    // Use the same instance and cache key so Redis DB is the only isolation boundary.
+    const KeyTypeVec keys{987654321};
+    backend_db0.Delete(nullptr, keys);
+    backend_db1.Delete(nullptr, keys);
+    const FieldMapVec expected{{{"field", "db1"}}};
+    ASSERT_EQ(std::vector<ErrorCode>{EC_OK},
+              backend_db1.Put(nullptr, keys, CacheLocationMapVector(keys.size()), expected));
+
+    std::vector<bool> exists;
+    ASSERT_EQ(std::vector<ErrorCode>{EC_OK}, backend_db0.Exists(nullptr, keys, exists));
+    EXPECT_EQ(std::vector<bool>{false}, exists);
+    ASSERT_EQ(std::vector<ErrorCode>{EC_OK}, backend_db1.Exists(nullptr, keys, exists));
+    EXPECT_EQ(std::vector<bool>{true}, exists);
+
+    FieldMapVec actual;
+    ASSERT_EQ(std::vector<ErrorCode>{EC_OK}, backend_db1.GetProperties(nullptr, keys, {"field"}, actual));
+    EXPECT_EQ(expected, actual);
+
+    EXPECT_EQ(std::vector<ErrorCode>{EC_OK}, backend_db1.Delete(nullptr, keys));
+    EXPECT_EQ(EC_OK, backend_db0.Close());
+    EXPECT_EQ(EC_OK, backend_db1.Close());
+}
+
 TEST_F(MetaRedisBackendRealServiceTest, TestMultiThreadSimple) {
     ASSERT_EQ(EC_OK, meta_redis_backend_->Init("test_multi_thread_simple", meta_storage_backend_config_));
     ASSERT_EQ(EC_OK, meta_redis_backend_->Open());