百度智能云云数据库 Redis 提供两种产品形态：

• 云数据库 Redis 标准版：单机 / 主从架构，不引入代理层，不做数据分片。客户端按原生 Redis 使用，不涉及跨 slot、事务受限等分片约束。
• 云数据库 Redis 集群版：由多个分片节点组成，通过集群代理对外提供统一的实例连接地址。客户端只连接该地址即可，无需感知后端分片；分片节点不对外暴露。

本文根据主流 Redis 客户端与开发框架的兼容性验证结果，给出两种形态下的推荐接入方式。

连接示例中的占位符，请替换为控制台提供的实例连接地址、端口、用户名与密码。标准版与集群版均使用控制台展示的「实例连接地址」。 请按业务使用的客户端或框架，直接查阅下面对应的章节。

使用集群版时，多 key 命令、事务和 Lua 脚本涉及的 key 必须规划到同一 slot（通过 hash tag 约束）。

一、客户端最佳实践

1.1 redis-py

已验证版本：redis-py 7.0.1（Python 3.9）。

最佳实践：连接实例连接地址，按 standalone 模式使用，并显式配置 RESP2。

1import redis
2
3client = redis.Redis(
4    host="<实例连接地址>",
5    port=<端口>,
6    username="<用户名>",
7    password="<密码>",
8    protocol=2,
9    decode_responses=True,
10)

额外配置：

• 显式配置 protocol=2。
• 认证使用传统 AUTH username password 路径。

使用注意：

• 不要使用 protocol=3，也不要依赖 HELLO ... AUTH。
• 设置 client_name 可使用 CLIENT SETNAME；客户端上报 CLIENT SETINFO 时可能返回不支持，但当前版本通常会容忍该错误。
• Pipeline 只表示批量发送，不会让跨 slot 多 key 操作获得单机 Redis 的原子语义。

推荐理由：

redis-py 7.0.1 的集群版 standalone RESP2 路径已验证通过。相比 RESP3，显式 RESP2 可跳过 HELLO 协议协商，接入行为更稳定、更可预期。

1.2 node-redis

已验证版本：node-redis 6.0.0（Node.js v26.3.0）。

最佳实践：连接实例连接地址，按 standalone 模式使用，并强制配置 RESP: 2。

1import { createClient } from "redis";
2
3const client = createClient({
4  socket: {
5    host: "<实例连接地址>",
6    port: <端口>,
7  },
8  username: "<用户名>",
9  password: "<密码>",
10  RESP: 2,
11});
12
13await client.connect();

额外配置：

• RESP: 2 是必需配置，不能省略。

使用注意：

• 不要启用依赖 RESP3 的 client-side caching、maintenance notifications 等能力。
• node-redis 升级后需重新确认 RESP 配置项与默认协议行为。
• 多 key Lua、事务与批量命令必须保证 key 同 slot。

推荐理由：

node-redis 6.0.0 默认使用 RESP3，会在 connect() 阶段发送 HELLO 3。显式配置 RESP: 2 即可跳过这一协商步骤，让接入更平稳——配置后已验证的 23 个 standalone 用例全部通过。

1.3 ioredis

已验证版本：ioredis 5.11.1（Node.js v26.3.0）。

最佳实践：连接实例连接地址，使用 ioredis standalone 模式。

1import Redis from "ioredis";
2
3const client = new Redis({
4  host: "<实例连接地址>",
5  port: <端口>,
6  username: "<用户名>",
7  password: "<密码>",
8  enableReadyCheck: true,
9});

额外配置：

• 不使用 Redis.Cluster。
• 不配置 Sentinel 节点发现。

使用注意：

• ioredis ready check 会发送 INFO，不要在客户端侧禁用正常的 INFO 解析流程。
• CLIENT SETINFO 失败目前通常会被客户端忽略。
• 如果业务使用 Lua 或多个 key，需自行规划统一 hash tag。

推荐理由：

ioredis 集群版 standalone 路径已验证通过，接入顺畅。集群版的高可用已由实例连接地址（VIP）承担，客户端无需再消费拓扑信息，因此采用 standalone 连接即可获得最稳定的表现，也无需关注拓扑刷新、读从与 failover 的细节。

1.4 go-redis

已验证版本：go-redis 9.17.0。

最佳实践：连接实例连接地址，使用 redis.Client standalone 模式，并显式配置 Protocol: 2。

1rdb := redis.NewClient(&redis.Options{
2    Addr:     "<实例连接地址>:<端口>",
3    Username: "<用户名>",
4    Password: "<密码>",
5    Protocol: 2,
6})

额外配置：

• 使用 redis.NewClient，不使用 NewClusterClient 或 Sentinel failover client。
• 显式配置 Protocol: 2。

使用注意：

• 不要依赖客户端在 HELLO 3 失败后的自动 fallback；客户端升级可能改变 fallback 行为。
• 不启用未经验证的 RESP3 client-side caching 等能力。
• 多 key 事务与 Lua 需保证 key 同 slot。

推荐理由：

go-redis 9.17.0 默认路径可以连通。显式指定 RESP2 可以让接入行为不受客户端版本与 fallback 策略变化的影响，更加稳定可控；standalone 连接则让高可用完全交由实例连接地址（VIP）承担，客户端无需关心后端拓扑，接入更简洁。

1.5 redigo

已验证版本：redigo 1.9.3。

最佳实践：连接实例连接地址，使用 standalone 模式，配合普通连接池与固定地址。

1pool := &redis.Pool{
2    Dial: func() (redis.Conn, error) {
3        return redis.Dial(
4            "tcp",
5            "<实例连接地址>:<端口>",
6            redis.DialUsername("<用户名>"),
7            redis.DialPassword("<密码>"),
8        )
9    },
10}

额外配置：

• 无需配置协议协商；redigo 默认不发送 HELLO 3。

使用注意：

• 事务、Lua 与多 key 命令需保证 key 同 slot。
• 不要依赖 Redis Cluster 节点发现、Sentinel failover 或服务端管理命令。
• 使用连接池时需配置合理的连接超时、空闲连接检查与失败重试。

推荐理由：

redigo 的集群版 standalone 连接、读写、Pipeline、事务、Lua、阻塞命令与重连路径均验证顺畅。standalone 连接已能覆盖全部业务场景，高可用由实例连接地址（VIP）承担，是最简洁稳妥的接入方式。

1.6 Lettuce

已验证版本：Lettuce 6.8.1.RELEASE（JDK 17）。

最佳实践：连接实例连接地址，使用 standalone RedisClient，并显式固定 RESP2。

1RedisURI redisUri = RedisURI.Builder.redis("<实例连接地址>", <端口>)
2    .withAuthentication("<用户名>", "<密码>")
3    .build();
4
5RedisClient client = RedisClient.create(redisUri);
6client.setOptions(ClientOptions.builder()
7    .protocolVersion(ProtocolVersion.RESP2)
8    .build());

额外配置：

• 使用 standalone RedisClient，不使用 RedisClusterClient。
• 显式配置 ProtocolVersion.RESP2。

使用注意：

• 不依赖 HELLO 3 失败后的客户端 fallback。
• 如果上层使用 Spring Session，还必须配置 ConfigureRedisAction.NO_OP。
• 不启用未经验证的读从路由、动态拓扑刷新与 Sentinel failover。

推荐理由：

Lettuce 集群版 standalone 路径已验证通过，显式 RESP2 可避免协议协商差异，接入更平稳。集群版的高可用已由实例连接地址（VIP）承担，采用 standalone 连接即可稳定使用，客户端无需自行消费拓扑与 failover 信息。

1.7 Jedis

已验证版本：Jedis 7.0.0（JDK 17）。

最佳实践：连接实例连接地址，使用 JedisPooled 或普通连接池的 standalone 模式。

1DefaultJedisClientConfig config = DefaultJedisClientConfig.builder()
2    .user("<用户名>")
3    .password("<密码>")
4    .build();
5
6JedisPooled client = new JedisPooled(
7    new HostAndPort("<实例连接地址>", <端口>),
8    config
9);

额外配置：

• 不使用 JedisCluster。
• 不使用 Sentinel 自动发现。

使用注意：

• 不依赖 Cluster 拓扑、读从路由与自动 failover。
• 多 key 事务与脚本仍需保证 key 同 slot。
• 连接池需配置合理的超时、健康检查与重试。

推荐理由：

Jedis 集群版 standalone 默认路径验证顺畅。standalone 连接已能满足业务需要，高可用由实例连接地址（VIP）承担，客户端无需自行维护 Cluster 拓扑与读从路由，接入更简洁稳妥。

1.8 Redisson

已验证版本：Redisson 3.52.0（JDK 17）。

最佳实践：连接实例连接地址，使用 singleServerConfig。

1Config config = new Config();
2config.useSingleServer()
3    .setAddress("redis://<实例连接地址>:<端口>")
4    .setUsername("<用户名>")
5    .setPassword("<密码>");
6
7RedissonClient client = Redisson.create(config);

额外配置：

• 使用 singleServerConfig。
• 不使用 clusterServersConfig 或 sentinelServersConfig。

使用注意：

• 分布式锁、MapCache、Topic 等业务语义应按实际版本做回归测试。
• 不要通过 checkSentinelsList=false 把 Sentinel 初始化成功当作 HA 能力证明。
• 多 key 高层对象仍需关注 key 是否同 slot。

推荐理由：

Redisson 连接集群版的 standalone 高层 API、锁、Pub/Sub、Lua 与恢复路径已验证通过。集群版的高可用由实例连接地址（VIP）承担，客户端无需消费拓扑信息，因此使用 singleServerConfig 即可稳定接入，也最为简洁——既不必依赖 Sentinel 初始化检查，也无需自行处理读从与动态拓扑。

二、框架最佳实践

框架可能自动使用事务、Lua、多 key、Cluster 或 Sentinel 节点发现，因此除了底层客户端能否连上，还需关注框架自身的行为。以下每个框架都给出经过测试验证的推荐接入方式：连接集群版实例连接地址并按 standalone 使用；对涉及跨 slot、事务或 Sentinel 交互的框架，给出对应的集群版配置指引，按指引配置即可顺畅使用。其中 Celery 的 result backend 场景较为特殊，我们会单独说明并给出更省心的选型建议。

2.1 Spring Boot + Spring Data Redis + Spring Session

已验证版本：Spring Boot 3.5.15 / Spring Data Redis 3.5.12 / Spring Session Data Redis 3.5.7（底层 Lettuce 6.8.1.RELEASE，JDK 17）。

最佳实践：连接实例连接地址，使用 standalone + Lettuce RESP2，并配置 ConfigureRedisAction.NO_OP。

1@Bean
2public ConfigureRedisAction configureRedisAction() {
3    return ConfigureRedisAction.NO_OP;
4}

发现与连接方式：

• Spring Data Redis 使用 standalone host/port 配置连接实例连接地址。
• 不使用 Redis Cluster 或 Sentinel 节点发现。
• Lettuce 显式固定为 RESP2。

额外配置：

• 应用必须配置 ConfigureRedisAction.NO_OP。
• 不在应用启动阶段通过 CONFIG SET 修改实例。

使用注意：

• NO_OP 会关闭 Spring Session 对 keyspace notification 的自动配置；依赖过期事件的业务需单独验证。
• Spring Cache、Session、RedisTemplate 的 key 命名需避免无规划的跨 slot 多 key 操作。
• 不启用未经验证的读从路由、动态拓扑刷新与 Sentinel failover。

推荐理由：

Spring Session 默认启动会执行 CONFIG GET notify-keyspace-events，配置 NO_OP 可跳过这一启动动作，让 Spring Context 顺利初始化。配置之后，集群版 standalone 下的 RedisTemplate、Cache、Session 与停启恢复路径已验证通过。

用标准版接入同样需要配置 NO_OP，但不涉及跨 slot 约束。

2.2 Celery

选型建议：Celery result backend 会在事务内使用 PUBLISH，这一用法与集群版的 slot 路由模型不契合，且难以通过配置调整。为获得开箱即用的顺畅体验，Celery 场景推荐使用云数据库 Redis 标准版。 已验证版本：Celery 5.6.3 / Kombu 5.6.2（底层 redis-py 7.0.1，Python 3.9）。

最佳实践：使用云数据库 Redis 标准版，broker 与 result backend 使用同类型的 standalone 模式固定地址。

1celery -A <app> worker

发现与连接方式：

• broker 与 result backend 均按 standalone URL 连接标准版实例。
• 不使用 Redis Sentinel 节点发现。

额外配置：

• 无需关闭 mingle、gossip、heartbeat。
• 无需将 Kombu Redis priority queue 收敛为单 priority。
• 使用已验证的 redis-py 7.0.1、Celery 5.6.3、Kombu 5.6.2 版本组合。

使用注意：

• 当前测试保留了默认 mingle、gossip、heartbeat 与 priority steps，但测试环境使用 solo pool、单 worker 与独立队列；其他并发池、多 worker 与多队列部署仍需按实际配置验证。
• 上线前必须验证普通任务、失败任务、重试、result backend、TTL、worker 重启与恢复。

推荐理由：

Celery 的 result backend 会在事务内触发 PUBLISH（PUBLISH 不绑定具体 key，无法归入某个 slot），这一用法与集群版的 slot 路由模型天然不契合：即便对 broker 与 result backend 都配置 global_keyprefix（如 broker_transport_options={"global_keyprefix": "{celery}."}）把 key 收敛到同一 slot，result backend 仍难以顺畅工作。标准版是单机 / 主从架构，没有跨 slot 与事务约束，测试也已验证通过，因此是 Celery 场景更省心的选择。

2.3 BullMQ

已验证版本：BullMQ 5.78.1（底层 ioredis 5.11.1，Node.js v26.3.0）。

最佳实践：连接集群版实例连接地址，通过 ioredis standalone 模式接入，并为队列配置 hash tag prefix，使同一队列的 key 落入同一 slot。

1import { Queue, Worker } from "bullmq";
2
3const connection = {
4  host: "<实例连接地址>",
5  port: <端口>,
6  username: "<用户名>",
7  password: "<密码>",
8};
9
10// 通过 hash tag prefix 约束同一队列的 key 落入同一 slot
11const opts = { connection, prefix: "{<queue-name>}" };
12const queue = new Queue("<queue-name>", opts);
13const worker = new Worker("<queue-name>", processor, opts);

发现与连接方式：

• BullMQ 通过 ioredis standalone 模式连接实例连接地址。
• 不使用 ioredis Cluster 或 Sentinel 节点发现。

额外配置：

• 集群版必须为队列配置 hash tag prefix（如 prefix: "{<queue-name>}"），并配置集群版侧的 hash_tag: "{}"，双端配置生效后同一队列的 key 才会落入同一 slot。
• 不能沿用 BullMQ 默认 prefix。

使用注意：

• 上线前验证 delayed job、retry/backoff、failed job、QueueEvents、pause/resume、script reload 与 worker 恢复。

推荐理由：

BullMQ 的核心 job 状态、事件与脚本路径涉及多 key 操作，需要让同一队列的 key 落入同一 slot。为队列配置 hash tag prefix 并配合集群版侧 hash_tag: "{}" 后，同一队列的 key 会落入同一 slot，已验证业务路径可顺畅运行。

标准版为单机 / 主从架构，没有跨 slot 约束，使用 BullMQ 默认 prefix 即可，无需 hash tag 配置。

2.4 Redisson

已验证版本：Redisson 3.52.0（JDK 17）。

最佳实践：连接实例连接地址，使用 singleServerConfig。

1Config config = new Config();
2config.useSingleServer()
3    .setAddress("redis://<实例连接地址>:<端口>")
4    .setUsername("<用户名>")
5    .setPassword("<密码>");

发现与连接方式：

• Redisson 把实例连接地址当作单个 Redis endpoint。
• 不使用 Cluster 节点发现。
• 不使用 Sentinel 节点发现。

额外配置：

• 无需 checkSentinelsList=false，因为不进入 Sentinel 模式。

使用注意：

• 对 RLock、RMapCache、RTopic、Lua、TTL 与恢复语义按实际版本做回归测试。
• 多 key 对象或用户自定义 Lua 需保证 key 同 slot。
• singleServerConfig 表示客户端不消费集群拓扑信息；高可用由实例连接地址（VIP）承担。

推荐理由：

Redisson 集群版 standalone 的高层对象与恢复语义已验证通过。集群版的高可用由实例连接地址（VIP）承担，客户端无需消费拓扑信息，因此使用 singleServerConfig 直接把实例连接地址当作单节点接入即可，既最简洁也最稳定，无需引入 Sentinel 初始化检查或 Cluster 读从路由等额外环节。

2.5 Ray（external Redis / GCS）

已验证版本：Ray 2.51.2。

最佳实践：连接集群版实例连接地址作为 external Redis，并确保接入地址不暴露 Sentinel 兼容语义。

发现与连接方式：

• Ray external Redis / GCS 直接配置实例连接地址的 host/port。
• 不使用 Sentinel 或 Cluster 节点发现。

额外配置：

• 确保提供给 Ray 的地址不暴露 Sentinel 兼容语义。
• 启动测试前清理历史 Ray 进程与残留状态，避免旧 raylet 干扰结果。

使用注意：

• 当前只验证 external Redis / GCS 固定地址，不代表 Ray 支持基于本产品的 Redis Cluster / Sentinel 节点发现。
• 上线前验证 Ray head 启动、worker join、metadata key、task retry、节点恢复与地址切换。

推荐理由：

Ray 的 external Redis / GCS 只需把实例连接地址当作固定的 standalone 地址接入即可，本轮测试已验证通过。将接入地址保持为普通 standalone 地址（不暴露 Sentinel 兼容语义），可以让 Ray 直接按固定地址连接，接入路径清晰稳定。

标准版为单机 / 主从架构，接入地址天然是普通 standalone 地址，Ray 可直接按固定地址连接，更加省心。

三、关于 Cluster / Sentinel 兼容

集群版对外通过实例连接地址（VIP）提供服务。为便于原本运行在自建 Cluster / Sentinel 上的业务平滑迁移，集群代理层额外模拟（mock）了 Redis Cluster / Sentinel 协议的部分交互，使这类客户端能够连上并完成初始化。需要强调的是，这只是代理层的协议兼容模拟，后端并非真正的 Redis Cluster / Sentinel 部署，代理返回的拓扑也是模拟拓扑；因此该兼容模式仅用于迁移过渡，并非集群版的推荐接入方式。

• 新接入业务：建议直接把实例连接地址当作 standalone 模式的固定地址连接（见各客户端章节），不要启用 Cluster / Sentinel 节点发现。集群版的高可用已由实例连接地址（VIP）承担——后端分片的主从切换与故障转移由 VIP 层屏蔽，对客户端透明，因此不依赖节点发现也不会丢失高可用能力。
• 已使用 Cluster / Sentinel 接入的业务：可在迁移窗口内继续沿用，并按各客户端 / 框架对应章节的说明确认接入细节，逐步切换为 standalone 接入即可平滑过渡。