文档中心

缓存数据库 Redis 版

开发参考（数据面）

参数支持

缓存数据库 Redis 版支持自定义部分参数的值，本文介绍 Redis 实例中支持自定义的参数的相关信息。

参数支持表

说明

为最大程度地保障实例的稳定运行，目前缓存数据库 Redis 版仅开放了部分参数，下表中仅列出了支持自定义的参数。暂不支持自定义未出现在表中的参数。

参数	说明
active-defrag-cycle-max	设置触发内存碎片整理时，CPU 占用比例的最大值。单位：%，取值范围：[1,40]，默认值：25。
active-defrag-cycle-min	设置触发内存碎片整理时，CPU 占用比例的最小值。单位：%，取值范围：[1,20]，默认值：1。
active-defrag-ignore-bytes	设置触发内存碎片整理时，碎片空间占用量的最小值。单位：MB，取值范围：[100,1024]，默认值：100。
active-defrag-max-scan-fields	设置在主哈希表扫描中，进行处理的 set/hash/zset/list 域数量的最大值。取值范围：[500,50000]，默认值：1000。
active-defrag-threshold-lower	设置触发内存碎片整理时，碎片空间占用比例的最小值。单位：%，取值范围：[5,50]，默认值：10。
active-defrag-threshold-upper	设置触发内存碎片整理时，碎片空间占用比例的最大值。当内存碎片超过该百分比时，尽最大努力整理。单位：%，取值范围：[50,150]，默认值：100。
activedefrag	开启或关闭自动内存碎片整理。取值范围如下： yes：开启。 no（默认值）：关闭。
client-output-buffer-pubsub-hard-limit	发布订阅客户端输出缓冲区的硬限制。当客户端的输出缓冲区内存占用量达到或超过该限制时，客户端连接会断开。单位：MB，取值范围：[1,64]，默认值：32。
client-output-buffer-pubsub-soft-limit	发布订阅客户端输出缓冲区的软限制。当输出缓冲区内存占用量在 client-output-buffer-pubsub-soft-seconds 参数指定的时间内，持续超过软限制设置的值时，客户端将断开连接。单位：MB，取值范围：[1,64]，默认值：8。
client-output-buffer-pubsub-soft-seconds	在发布订阅客户端断开连接之前，输出缓冲区大小持续超过 client-output-buffer-pubsub-soft-limit 参数值的时间。单位：秒（s），取值范围：[1,900]，默认值：60。
disabled-commands	设置禁用命令。默认禁用了 flushall、flushdb 和 keys 命令。您也可根据业务需求禁用某些执行时长较长、复杂度较高或对业务风险较大的命令。Redis 实例类型不同，支持的命令也不同。不同实例类型支持的命令详情，请参见命令支持。说明您可以在 disabled-commands 参数值中输入任意命令，但需注意如下几点：单个实例最多支持禁用 16 个命令，多个命令间用英文逗号（,）分隔。关于禁用命令的数量限制详情，请参见功能特性限制。不支持禁用 AUTH 命令。输入的命令不区分大小写，但不允许在参数值中传入空格。若输入了主命令，那么该主命令下的所有子命令都会被禁用。例如，您在 disabled-commands 参数中输入了 OBJECT 主命令，那么 OBJECT 主命令下的所有子命令（包括 OBJECT ENCODING、OBJECT FREQ、OBJECT HELP、OBJECT IDLETIME、OBJECT REFCOUNT）都会被禁用。不支持单独禁用任何子命令。例如，无论您将 OBJECT ENCODING 这一子命令以任意形式（包括但不限于 OBJECTENCODING、object\|encoding、object-encoding 等）输入到 disabled-commands 参数值中，该子命令也不会被禁用。如需禁用该子命令，您需要在 disabled-commands 参数值中输入其对应的主命令 OBJECT。当您在执行缓存数据库 Redis 版不支持的命令（如 RESET）时，通常会出现 unknown command 的报错；但若您将不支持的参数加入了禁用命令 disabled-commands 参数值中，在您执行该命令时，会出现 no permission to execute the command 的报错。
hash-max-ziplist-entries	当哈希对象同时满足如下条件时使用 ziplist 编码：哈希对象保存的所有键值对的键和值的字符串长度的字节数都小于 hash-max-ziplist-value 的值。哈希对象保存的键值对数量小于 hash-max-ziplist-entries 的值。取值范围：[1,10000]，默认值：512。
hash-max-ziplist-value	哈希对象同时满足以下两个条件时，使用 ziplist 编码：哈希对象保存的所有键值对的键和值的字符串长度的字节数都小于 hash-max-ziplist-value 的值。哈希对象保存的键值对数量小于 hash-max-ziplist-entries 的值。取值范围：[1,10000]，默认值：64。
hz	设置 Redis 后台任务的每秒执行次数，例如清除过期键任务。取值范围：[1,500]，默认值：10。说明该值越大，CPU 资源消耗越多，但在过期键较多的情况下清理频率也更高，同时 Redis 能够更精确地处理超时。建议取值不超过 100。
lazyfree-lazy-eviction	是否开启基于 lazyfree 的驱逐功能。取值范围如下： yes（默认值）：开启。 no：不开启。
lazyfree-lazy-expire	是否开启基于 lazyfree 的过期键删除功能。取值范围如下： yes（默认值）：开启。 no：不开启。
lazyfree-lazy-server-del	是否开启基于 lazyfree 的 DEL 命令功能（即是否开启异步删除数据功能）。取值范围如下： yes（默认值）：开启。 no：不开启。
lazyfree-lazy-user-del	是否开启用户发起删除操作异步释放内存。取值范围如下： yes（默认值）：开启。 no：不开启。说明该参数仅在 Redis 7.0 版本和 Redis 6.0 版本的实例中提供。
list-compress-depth	列表中两端不被压缩的节点个数。取值范围如下： 0（默认值）：列表中两端都不压缩。 1~65535：表示 list 两端各有 1~65535 个节点不压缩，中间的节点压缩。
list-max-ziplist-size	每个 quicklist 节点中 ziplist 长度的设置策略，取值范围：[-5,100000]，其中：取正值表示按照数据项个数来限定每个 quicklist 节点上的 ziplist 长度。例如，当该参数配置为 5 时，每个 quicklist 节点的 ziplist 最多包含 5 个数据项。取负值表示按照占用字节数来限定每个 quicklist 节点上的 ziplist 长度，其中： -5：每个 quicklist 节点上的 ziplist 大小不超过 64 KB。 -4：每个 quicklist 节点上的 ziplist 大小不超过 32 KB。 -3：每个 quicklist 节点上的 ziplist 大小不超过 16 KB。 -2（默认值）：每个quicklist 节点上的 ziplist 大小不超过 8 KB。 -1：每个 quicklist 节点上的 ziplist 大小不超过 4 KB。说明 Redis 7.0 版本中使用 list-max-listpack-size 替代了 list-max-ziplist-size 参数。您在使用火山引擎缓存数据库 Redis 版 7.0 实例时，仅需设置 list-max-ziplist-size 参数，该参数可完全兼容 list-max-listpack-size 参数（包括参数取值范围和实现效果）。更多关于 list-max-listpack-size 的信息，请参见 Configuration file。
lua-time-limit	一个 Lua 脚本阻塞执行的最长时间。当 Lua 运行超过该参数限制后，Redis 将开始接受其他命令但不会执行，而是返回 Busy 报错。单位：毫秒（ms），取值范围：[0,5000]（0 表示无限执行时间），默认值：5000。
maxmemory-policy	设置缓存满后 Redis 删除内容的策略，取值范围如下： volatile-lru（默认值）：只从已设置失效（expire）的键中选择最近最少使用的键进行删除。 volatile-lfu：只从已设置失效（expire）的键中选择最不常用的键进行删除。 volatile-random：只从已设置失效（expire）的键中，随机选择一些键进行删除。 volatile-ttl：只从已设置失效（expire）的键中，选出存活时间 TTL（Time To Live）最短的键进行删除。 allkeys-lru ：优先删除最近最少使用的键。 allkeys-lfu：优先删除最不常用的键。 allkeys-random：随机选择一些键进行删除。 noeviction：不删除任何键，只是在写操作时返回错误。
proxy-slowlog-slower-than	Proxy 节点上请求被记录为慢日志的执行时间阈值，执行时间高于该阈值的请求会被记录到 Proxy 节点的慢日志中。单位：微秒（us），取值范围：[50000,2000000]，默认值：500000。
read_request_distribution_strategy	设置 Redis 实例分片的读写分离策略。取值范围如下： read_primary_node_only（默认值）：读请求仅发送到主节点。 read_secondary_nodes_only：读请求随机发送到所有从节点，均匀分布。 read_primary_node_and_secondary_nodes：读请求随机发送到主节点和所有从节点，均匀分布。注意修改读写分离策略（read_request_distribution_strategy）的参数值后，客户端可能会短暂出现请求失败相关报错，建议在业务低峰期执行参数修改操作，并确保客户端配置了正确的重试机制。 Redis 单节点实例不支持读写分离功能，不支持设置该参数。关于单节点实例类型的更多说明，请参见产品架构。
repl-backlog-size	设置主从复制 Backlog 容量大小。Backlog 是一个用来存放主从同步数据的 Buffer。当一个从节点想要重新连接时，通常不希望全部数据重新同步，只是传递在从节点断开连接时丢失的这部分数据。这个值越大，从节点可以断开连接的时间就越长。单位：MB，取值范围：[64,256]，默认值：128。
set-max-intset-entries	当集合中的元素全是整数，且长度不超过 set-max-intset-entries 的值（默认为 512）时，Redis 会选用 Intset 作为内部编码，大于 512 时，选择 set 作为内部编码。取值范围：[1,10000]，默认值：512。
slowlog-log-slower-than	Server 节点上请求被记录为慢日志的执行时间阈值，执行时间高于该阈值的请求会被记录到 Server 节点的慢日志中。单位：微秒（us）。取值范围：[10000,10000000]，默认值：20000。
slowlog-max-len	Server 节点上最多保存的慢日志数量，慢日志是一个 FIFO 队列，当队列大小超过 slowlog-max-len 时，最旧的日志将被删除，最新的日志会加入到 Server 节点的慢日志中。取值范围：[1,1000]，默认值：128。
proxy-client-idle-timeout	在客户端连接空闲时长达到指定值时关闭连接。单位：秒（s），取值范围：[0,4000000]，默认值：0。
zset-max-ziplist-entries	当有序集合的元素同时满足以下两个条件时，使用 ziplist 编码，ziplist 可以有效的减少内存的使用。有序集合的元素小于 zset-max-ziplist-entries 配置。每个元素的值都小于 zset-max-ziplist-value。取值范围：[1,10000]，默认值：128。
zset-max-ziplist-value	当有序集合的元素同时满足以下两个条件时，使用 ziplist 编码，ziplist 可以有效的减少内存的使用。有序集合的元素个数小于 zset-max-ziplist-entries 配置。每个元素的长度都小于 zset-max-ziplist-value。取值范围：[1,10000]，默认值：64。
notify-keyspace-events	设置键空间或键事件通知。参数值可以是如下字符的任意组合： K：键空间，以 __keyspace@<db>__ 为前缀发布事件。 E：键事件，以 __keyevent@<db>__ 为前缀发布事件。 g：DEL、EXPIRE、RENAME 等类型无关的通用命令。 $：字符串命令。 l：列表命令。 s：集合命令。 h：哈希命令。 z：有序集合命令。 x：过期事件，当过期键被删除时，会发送事件。 e：驱逐事件，当键因为符合 maxmemory 策略而被驱逐时，会发送事件。 A：参数组合 g$lshzxe 别名。例如需要订阅过期事件的通知，您可以先在参数设置中将 notify-keyspace-events 参数值设置为 Ex。配置参数后，在客户端执行 PSUBSCRIBE __keyevent@0__* 命令，表示订阅 DB0 的键事件通知。说明实例架构类型不同，对该参数的支持情况不同，其中：未启用分片集群 Redis 实例支持该参数，您可以根据业务需要直接设置。针对分片集群的 Redis 实例，2024 年 05 月 09 日及之后创建的实例支持直接设置该参数；2024 年 05 月 09 日之前创建的实例如需使用该参数，请提交工单联系技术支持升级实例版本。空字符串表示关闭事件通知，默认值是空字符串。开启事件通知后，会占用一定的 CPU。更多信息，请参见 Redis keyspace notifications。自定义配置参数值时，参数值中需要同时满足如下规范，否则不会产生事件：至少需要指定 K 或 E 中的一个。至少需要指定 A、g、$、l、s、h、z、x 或 e 中的一个。 notify-keyspace-events 参数暂不对个人认证账号开放。如需使用，请先将个人认证升级为企业认证后再重新创建实例，通过企业认证账号创建的新实例默认支持使用该参数。
read_local_node_only	开启或关闭多可用区实例的就近访问功能。取值范围如下： yes（默认值）：开启。 no：关闭。注意修改就近访问功能（read_local_node_only）的参数值后，客户端可能会短暂出现请求失败相关报错，建议在业务低峰期执行参数修改操作，并确保客户端配置了正确的重试机制。仅部署了多可用区的实例支持设置该参数，单节点实例仅有一个节点，不支持部署多可用区。因此 Redis 单节点实例不支持设置该参数。关于多可用区部署方案的详情，请参见部署多可用区。若实例未开启读写分离功能（即 read_request_distribution_strategy 取值为 read_primary_node_only），即使开启了就近访问功能，也不会生效。关于就近访问功能的更多信息，请参见就近访问。
appendonly-switch	开启或关闭实例的 AOF 持久化功能。取值范围如下： on（默认值）:开启。 off: 关闭。说明 2024 年 07 月 10 日之前创建的实例如需使用该参数，请提交工单联系技术支持升级实例版本。仅主备实例支持该参数。单节点实例不支持持久化能力，无法设置该参数。关于实例类型的更多详情，请参见产品架构。 AOF 持久化功能和读写分离功能存在约束关系，其中：当参数 read_request_distribution_strategy 取值为 read_secondary_nodes_only 或 read_primary_node_and_secondary_nodes时，不支持将参数appendonly-switch 设置为 off。当参数 appendonly-switch 取值为 off 时，不支持将参数 read_request_distribution_strategy 设置为 read_secondary_nodes_only 或 read_primary_node_and_secondary_nodes。 AOF 持久化功能和数据闪回功能存在约束关系，其中：当参数 appendonly-switch 取值为 off 时，不允许开启数据闪回功能。当数据闪回功能开启时，不允许将 appendonly-switch 取值调整为 off 。
TransactionSplit	在使用代理模式（即使用公私网地址）连接实例执行事务命令时，是否支持将事务命令所要操作的 key 拆分到不同 slot。取值范围如下： false（默认值）：不支持拆分，即事务命令所要操作的 key 必须在同一 slot 中。 true：支持拆分，即事务命令所要操作的 key 可以在不同 slot 中。说明仅启用分片集群的实例支持设置该参数，未启用分片集群的实例仅支持一个 slot 无法拆分。关于实例架构的详情，请参见产品架构。该参数仅对 Proxy 版本小于或等于 proxy_version_1.506.0 的 Redis 分片集群实例生效。Proxy 版本大于 proxy_version_1.506.0 的 Redis 分片集群实例，无论该参数设置为何值，都默认支持事务命令所要操作的 key 可以在不同 slot 中。关于 Redis 分片集群在代理模式的事务命令限制详情，请参见事务命令限制。您可以通过 hash tag 来构造相同 slot 的 key。hash tag 的使用方法，请参见 Keys hash tags。
sentinel-passwordless-auth	参数支持
extra-passwordless-auth-command	设置哨兵模式下，额外允许免密执行的命令列表。命令需以小写字母的格式填写，多个命令间使用英文逗号（,）分隔。说明仅当设置了 sentinel-passwordless-auth 参数为 yes 且参数值生效的情况下，extra-passwordless-auth-command 参数中添加的命令才允许免密执行。设置后，可以在任意连接上免密执行已添加的命令，请谨慎操作。关于 Sentinel 兼容模式下的命令免密执行的操作步骤详情，请参见设置 Sentinel 命令免密执行。

最近更新时间：2026.10.21 17:48:53

这个页面对您有帮助吗？

有用

无用