企业官网建设流程全解析

Azure Cosmos DB Garnet Cache API 兼容性指南：受支持的 Redis 命令、数据类型与实现状态全览

【免费下载链接】garnetGarnet is a remote cache-store from Microsoft Research that offers strong performance (throughput and latency), scalability, storage, recovery, cluster sharding, key migration, and replication features. Garnet can work with existing Redis clients.项目地址: https://gitcode.com/GitHub_Trending/garnet4/garnet

本指南以 Azure Cosmos DB Garnet Cache（微软研究院 Garnet 远程缓存存储的 Azure 全托管服务形态）为对象，逐条梳理其在 15 个命令类别下对 Redis 命令的实现状态（已支持 ➕ / 未支持 ➖），并说明键值大小限制、数据类型覆盖范围与 Lua 脚本、Vector Set 等特殊能力的启用前提。读完本文，你将掌握该服务与 Redis 生态的兼容边界，能够据此评估现有 Redis 客户端代码的迁移成本，并为应用设计合理的键值规模。

兼容性总览

Azure Cosmos DB Garnet Cache 与自托管 Garnet 一样，基于 Redis 的 RESP 协议工作，因此可以无缝对接各主流编程语言中已有的 Redis 客户端（如 C# 的 StackExchange.Redis、Java 的 Jedis/Redisson、Python 的 redis-py、Node.js 的 node_redis、Go 的 go-redis 等）。它对 Redis 数据类型与命令的支持是"子集式"的：核心的 String、Hash、Set、Sorted Set，加上 Pub/Sub 发布订阅、Lua 脚本（默认关闭）以及预览阶段的 Vector Set 向量检索，都在支持范围内。

关于数据规模，官方给出了两个明确的量化约束：

• 单个键值对的最大大小为 32MB；
• 为获得最低延迟，建议将键值对大小控制在 1KB 左右。

这意味着该服务适合典型的分布式缓存与热数据加速场景，而不适合在单个 key 内塞入超大对象。如果你有单 key 超过 32MB 的需求，应先在应用层做分片或改用对象存储。

需要说明的是：Azure Cosmos DB Garnet Cache 支持的命令集合是开源 Garnet 命令集的子集，且仍在持续扩充中。判断某个命令是否可用，应以本文的完整清单为准，而不是直接照搬开源 Garnet 的支持列表——例如开源 Garnet 已实现的BITMAP、GEO、LIST、HYPERLOGLOG、STREAM、TRANSACTIONS、ACL、SLOWLOG、OBJECT、MEMORY、MODULE、JSON 模块等类别，在 Azure 托管形态下并未出现在受支持类别清单中。开源完整列表可对照 website/docs/commands/api-compatibility.md。

命令类别总览

Azure Cosmos DB Garnet Cache 实现的是开源 Garnet 命令的不断增长子集，以下列出至少包含一个已支持命令的类别：

1. CLIENT
2. CLUSTER
3. COMMAND
4. CONNECTION
5. GENERIC
6. HASH
7. KEYS
8. LATENCY
9. PUB/SUB
10. SCRIPTING
11. SERVER
12. SET
13. SORTED SET
14. STRING
15. VECTOR SET (Preview)

完整命令清单

下表沿用官方图例：➕ = 已实现，➖ = 未实现。各命令的详细语法与 RESP 返回值可点击链接进入对应的开源 Garnet 命令文档（命令语义与开源版一致，只是支持状态按本表为准）。

CLIENT

CLIENT 类别在托管服务中只实现了CLIENT ID与CLIENT INFO两条。从源码结构看，CLIENT 相关命令的处理逻辑位于 ClientCommands.cs，而 ClientSession 目录下的客户端会话实现对应的是开源版的自托管客户端能力。如果你依赖CLIENT SETNAME、CLIENT TRACKING（RESP3 客户端缓存）或CLIENT LIST来排查连接，在迁移到托管缓存时需要调整运维脚本。

CLUSTER

托管服务的集群拓扑由 Azure 平台负责管理（节点通过你创建集群时提供的虚拟网络内部 IP 暴露），因此大多数集群管理类命令（MEET、SETSLOT、ADDSLOTS等）被禁用以避免用户干预平台调度。保留实现的CLUSTER NODES、CLUSTER SLOTS、CLUSTER KEYSLOT主要用于让 Redis 客户端自动发现节点拓扑与计算槽位；READONLY/READWRITE则用于在副本上开启/关闭只读路由。集群命令的完整开源实现可参考 RespClusterBasicCommands.cs。

COMMAND

COMMAND INFO已实现，可用于查询特定命令是否存在及其实参数信息，这是客户端在连接后做能力探测的常用手段。命令元数据（名称、参数、类别、ACL 权限位）在仓库中由 RespCommandsInfo.cs、RespCommandDocs.cs 等文件维护，并由 RespCommandAccessor.cs 提供查询入口。

CONNECTION

连接认证在托管服务中不由AUTH命令承担，而是改用 Azure RBAC + Microsoft Entra ID 的访问令牌方式：Redis 客户端通过--user <object-id> --pass <access-token>完成鉴权（详见 website/docs/azure/quickstart.md 的 Step 4）。因此AUTH、HELLO、SELECT均未实现——客户端在连接握手阶段应跳过这些命令。PING与ECHO用于连通性测试，在 BasicCommands.cs 中实现。

GENERIC

GENERIC 类别只有UNLINK（异步删除键）被标记为已实现。注意：TTL、EXPIRE等过期相关命令在开源 Garnet 中属于 KEYS 类别，需结合下方 KEYS 表一起判断。如果你的代码依赖SCAN做键遍历或RENAME做键重命名，在托管服务上需要改用其他方案。

HASH

HASH 是托管服务中覆盖最完整的复合数据结构之一，25 条命令全部实现，包括 Redis 7.4 引入的字段级过期能力（HEXPIRE/HEXPIREAT/HEXPIRETIME/HPEXPIRE/HPEXPIREAT/HPEXPIRETIME/HPTTL/HPERSIST）。底层哈希对象的实现位于 Objects/Hash，相应命令处理位于 HashObjectCommands.cs。用于会话/用户画像等"键内多字段"场景时，HASH 完全可以作为主力数据结构。

KEYS

KEYS 类别实现了DEL、EXISTS、EXPIRE三个最常用的键管理命令。注意EXPIREAT（绝对时间戳过期）与KEYS（全库模式匹配）未实现——KEYS命令在开源 Garnet 中也仅在单机模式可用，托管服务禁用它以避免全库扫描影响性能。键管理命令的核心实现位于 KeyAdminCommands.cs。

LATENCY

LATENCY HISTOGRAM与LATENCY RESET已实现，可查看/重置各命令的延迟直方图。在托管服务上更推荐通过 website/docs/azure/monitoring.md 描述的 Azure Monitor 指标做长期观测，LATENCY命令适合即时诊断。

PUB/SUB

发布订阅能力完整可用（9/11 条已实现），支持精确频道与模式匹配（PSUBSCRIBE），但没有分片频道（shard channel）能力。底层由 SubscribeBroker.cs 实现订阅分发表，命令入口在 PubSubCommands.cs。可用于应用内的消息广播、缓存失效通知等场景。

SCRIPTING

Lua 脚本（EVAL/EVALSHA及SCRIPT LOAD/EXISTS/FLUSH）已实现但默认关闭，这是托管服务为隔离脚本执行风险而做的安全设计——需要通过邮件申请后才启用。脚本执行引擎即开源 Garnet 的 LuaRunner.cs，其托管内存分配器 LuaManagedAllocator.cs 用于限制脚本对服务器内存的占用。注意EVAL_RO/EVALSHA_RO（只读脚本）与SCRIPT KILL未实现。

SERVER

SERVER 类别中绝大多数命令被禁用：持久化（BGSAVE/SAVE/LASTSAVE）、复制（REPLICAOF/PSYNC/REPLCONF/SYNC/ROLE）、ACL 与 CONFIG 修改、FLUSHALL等均不可用，因为这些能力由 Azure 平台托管（持久化模式在预配时固定，见 website/docs/azure/cluster-configuration.md）。唯一常用的是FLUSHDB（清空当前库）与CONFIG GET（读取配置）。认证与授权通过 GarnetAclWithAadAuthenticator.cs 一类的 AAD 认证器对接 Entra ID RBAC，而非 Redis 原生 ACL 命令。

SET

SET 的 16 个常规命令全部实现，包括集合运算SINTER/SDIFF/SUNION及其带存储变体、基数估算SINTERCARD、批量成员检测SMISMEMBER。仅与分片发布订阅相关的SPUBLISH/SSUBSCRIBE/SUNSUBSCRIBE未实现。底层实现位于 Objects/Set 与 SetObjectCommands.cs。

SORTED SET

SORTED SET 是覆盖最全面的类别，35 条命令全部实现，涵盖阻塞弹出（BZPOPMIN/BZPOPMAX/BZMPOP）、区间查询、排名查询、集合运算与存储变体。Redis 7.x 的ZINTERCARD、ZMPOP、ZMSCORE、ZRANDMEMBER等新命令也在支持之列；带ZRANGEBY*/ZREVRANGE*字样的旧命令被标记为 Deprecated，建议迁移到统一的ZRANGE语法。底层基于 Objects/SortedSet 与 SortedSetObjectCommands.cs，排行榜、时间窗口、延迟队列等场景可以放心使用。

STRING

STRING 类别 22 条命令全部实现，是最完整的类别。除基础的GET/SET/MGET/MSET外，还包括原子计数（INCR/DECR/INCRBYFLOAT）、取后删（GETDEL）、取后设过期（GETEX）、最长公共子序列LCS等。带PSETEX/SETEX/SUBSTR字样的旧命令标记为 Deprecated。字符串命令主体在 BasicCommands.cs 中实现。由于单键上限为 32MB，字符串适合存 JSON 序列化对象、令牌、会话数据等，但请遵循 1KB 左右的低延迟建议。

VECTOR SET (Preview)

Vector Set 是托管服务中面向 AI 场景的预览功能：基于 DiskANN 图索引（微软的近似最近邻算法）与 Garnet 的 Tsavorite 存储引擎，可插入高维向量并在同一键上做相似度检索，支持可选的 JSON 属性过滤。7 条命令已实现（VADD/VSIM/VREM/VEMB/VDIM/VINFO/VGETATTR），其余 5 条尚未实现。所有V*命令属于预览特性，命令与磁盘布局可能变更；在自托管 Garnet 中需以--enable-vector-set-preview服务参数启用。完整的语法、量化方式（NOQUANT/XPREQ8）、距离度量（L2/COSINE/IP/XCOSINE_NORMALIZED）与过滤表达式说明见 website/docs/commands/vector-sets.md，底层实现位于 Resp/Vector。

兼容边界速查：迁移时的高频差异

综合上述清单，从 Redis（或开源 Garnet）迁移到 Azure Cosmos DB Garnet Cache 时，以下几个差异最值得提前确认：

• 键值大小：单键值对 ≤ 32MB，推荐 ≤ 1KB 以获取最低延迟；
• 连接鉴权：不使用AUTH/HELLO，改用 Entra ID 访问令牌 + TLS；
• 库选择：不支持SELECT，单实例即单库；
• 键遍历：不支持SCAN/KEYS全库遍历；集合/哈希内遍历可用HSCAN/SSCAN/ZSCAN；
• 脚本默认关闭：Lua 脚本需申请启用，且无EVAL_RO/SCRIPT KILL；
• 复制与持久化由平台托管：REPLICAOF、BGSAVE、SAVE等不可用；持久化模式在创建集群时选定（无持久化或 AOF + RDB），之后不可更改；
• 集群管理命令受控：客户端仅需CLUSTER NODES/SLOTS/KEYSLOT与READONLY/READWRITE即可正常工作，其余集群命令由平台接管。

延伸阅读

• 快速上手：创建第一个 Azure Cosmos DB Garnet Cache：包含 RBAC 配置、网络访问与 redis-cli 连接实测的完整步骤
• 集群配置：SKU 分层、分片与副本、区域可用性
• 开源 Garnet 完整命令兼容性清单：作为本文清单的"父集"参考，可对比查看开源版已实现而托管版未开放的类别

【免费下载链接】garnetGarnet is a remote cache-store from Microsoft Research that offers strong performance (throughput and latency), scalability, storage, recovery, cluster sharding, key migration, and replication features. Garnet can work with existing Redis clients.项目地址: https://gitcode.com/GitHub_Trending/garnet4/garnet