参数列表

REDIS 模块的参数列表，共有 22 个参数，分为两个部分：

• REDIS：19 个参数，用于 Redis/Valkey 集群的部署与配置
• REDIS_REMOVE：3 个参数，控制 Redis 集群的移除

参数概览

REDIS 参数组用于 Redis 集群的部署与配置，包括身份标识、实例定义、工作模式、内存配置、持久化以及监控。

REDIS_REMOVE 参数组控制 Redis 集群的移除行为，包括防误删保险、数据清理以及软件包卸载。

默认参数

REDIS：19 个参数，定义于 roles/redis/defaults/main.yml

#-----------------------------------------------------------------
# REDIS
#-----------------------------------------------------------------
#redis_cluster:             <集群> # Redis数据库集群名称，必选身份参数
#redis_node: 1              <节点> # Redis节点编号，正整数，集群内唯一，必选身份参数
#redis_instances: {}        <节点> # Redis节点上的实例定义
redis_fs_main: /data/redis        # Redis主数据目录，默认为 `/data/redis`
redis_exporter_enabled: true      # Redis Exporter 是否启用？
redis_exporter_port: 9121         # Redis Exporter监听端口
redis_exporter_options: ''        # Redis Exporter命令参数
redis_type: redis                 # 服务端引擎：redis 或 valkey
redis_mode: standalone            # Redis集群模式：sentinel，cluster，standalone
redis_conf: redis.conf            # Redis配置文件模板，sentinel 除外
redis_bind_address: '0.0.0.0'     # Redis监听地址，默认 `0.0.0.0`，留空则会绑定主机IP
redis_max_memory: 1GB             # Redis可用的最大内存
redis_mem_policy: allkeys-lru     # Redis内存逐出策略
redis_password: ''                # Redis密码，默认留空则禁用密码
redis_rdb_save: ['1200 1']        # Redis RDB 保存指令，字符串列表，空数组则禁用RDB
redis_aof_enabled: false          # Redis AOF 是否启用？
redis_rename_commands: {}         # Redis危险命令重命名列表
redis_cluster_replicas: 1         # Redis原生集群中每个主库配几个从库？
redis_sentinel_monitor: []        # Redis哨兵监控的主库列表，仅用于哨兵集群

REDIS_REMOVE：3 个参数，定义于 roles/redis_remove/defaults/main.yml

#-----------------------------------------------------------------
# REDIS_REMOVE
#-----------------------------------------------------------------
redis_safeguard: false            # 为 true 时无条件拒绝移除操作
redis_rm_data: true               # 移除Redis实例时是否一并移除数据目录？
redis_rm_pkg: false               # 是否卸载所选引擎与 redis-exporter？

REDIS

本节包含 redis 角色的参数， 这些是 redis.yml 剧本使用的操作标志参数。

redis_cluster

参数名称： redis_cluster， 类型： string， 层次：C

身份参数，必选参数，必须显式在集群层面配置，将用作集群内资源的命名空间。

需要遵循特定命名规则：[a-z][a-z0-9-]*，以兼容不同约束对身份标识的要求，建议使用 redis- 作为集群名前缀。

redis_node

参数名称： redis_node， 类型： int， 层次：I

Redis 节点序列号，身份参数，必选参数，必须显式在节点（Host）层面配置。

自然数，在集群中应当是唯一的，用于区别与标识集群内的不同节点，从0或1开始分配。

redis_instances

参数名称： redis_instances， 类型： dict， 层次：I

当前 Redis 节点上的 Redis 实例定义，必选参数，必须显式在节点（Host）层面配置。

内容为 JSON KV 对象格式。Key 为数值类型端口号，Value 为该实例特定的 JSON 配置项。

redis-test: # redis native cluster: 3m x 3s
  hosts:
    10.10.10.12: { redis_node: 1 ,redis_instances: { 6379: { } ,6380: { } ,6381: { } } }
    10.10.10.13: { redis_node: 2 ,redis_instances: { 6379: { } ,6380: { } ,6381: { } } }
  vars: { redis_cluster: redis-test ,redis_password: 'redis.test' ,redis_mode: cluster, redis_max_memory: 32MB }

每一个 Redis 实例在对应节点上监听一个唯一端口，实例配置项中 replica_of 用于设置一个实例的上游主库地址，构建主从复制关系。

redis_instances:
    6379: {}
    6380: { replica_of: '10.10.10.13 6379' }
    6381: { replica_of: '10.10.10.13 6379' }

redis_fs_main

参数名称： redis_fs_main， 类型： path， 层次：C

Redis 使用的主数据目录，默认为 /data/redis。

部署阶段不允许使用旧值 /data（redis 角色的 identity assert 会直接报错）；移除阶段为兼容旧配置，redis-rm.yml 在 redis_fs_main=/data 时会按 /data/redis 执行删除。

数据目录的属主为操作系统用户 redis，内部结构详情请参考 FHS：Redis

redis_exporter_enabled

参数名称： redis_exporter_enabled， 类型： bool， 层次：C

是否启用 Redis 监控组件 Redis Exporter？

默认启用，在每个 Redis 节点上部署一个，默认监听 redis_exporter_port 9121 端口。所有本节点上 Redis 实例的监控指标都由它负责抓取。

将此参数设为 false 时，roles/redis/tasks/exporter.yml 仍会渲染配置文件，但会跳过 redis_exporter systemd 服务的启动步骤（redis_exporter_launch 任务带有 when: redis_exporter_enabled|bool 判断），可用于在节点上保留手工配置的 exporter。 redis_register 仍会写入该节点的 VictoriaMetrics 文件发现目标；如果没有自行提供同端口的 Exporter，应同时处理该监控目标，避免持续抓取失败。

redis_exporter_port

参数名称： redis_exporter_port， 类型： port， 层次：C

Redis Exporter 监听端口，默认值为：9121

redis_exporter_options

参数名称： redis_exporter_options， 类型： string， 层次：C/I

传给 Redis Exporter 的额外命令行参数，会被渲染到 /etc/default/redis_exporter 中（参见 roles/redis/tasks/exporter.yml），默认为空字符串。REDIS_EXPORTER_OPTS 最终会附加到 systemd 服务的 ExecStart=/bin/redis_exporter $REDIS_EXPORTER_OPTS，可用于配置额外的抓取目标或过滤行为。

redis_type

参数名称：redis_type，类型：enum，层次：G/C

选择 REDIS 模块使用的服务端实现，允许值为 redis 与 valkey，默认 redis。

角色会安装与该值同名的软件包，并在实例 systemd 单元中调用 /bin/redis-server / /bin/redis-cli 或 /bin/valkey-server / /bin/valkey-cli。配置路径、数据目录、实例服务名、Exporter 与监控标签仍使用 redis 命名空间，以保持现有清单和运维入口兼容。

应在集群层为所有成员设置相同值。修改 redis_type 只会改变角色选择的软件包和二进制，不会自动验证 RDB/AOF、复制、Sentinel 或 Cluster 的跨版本兼容性；已有集群切换前应先演练并准备回滚。

redis_mode

参数名称： redis_mode， 类型： enum， 层次：C

Redis 集群的工作模式，有三种选项：standalone, cluster, sentinel，默认值为 standalone

• standalone：默认，独立的 Redis 主从模式
• cluster： Redis 原生集群模式
• sentinel：Redis 高可用组件：哨兵

当使用 standalone 模式时，Pigsty 会根据 replica_of 参数设置 Redis 主从复制关系。

当使用 cluster 模式时，Pigsty 会根据 redis_cluster_replicas 参数使用所有定义的实例创建原生 Redis 集群。

当 redis_mode=sentinel 时，redis.yml 会执行 redis-ha 阶段，将 redis_sentinel_monitor 中的目标批量下发到所有哨兵；当 redis_mode=cluster 时还会执行 redis-join 阶段，调用所选引擎的 redis-cli 或 valkey-cli 执行 --cluster create。这两个阶段均在普通 ./redis.yml -l <cluster> 中自动触发，也可以通过 -t redis-ha 或 -t redis-join 单独运行。

redis_conf

参数名称： redis_conf， 类型： string， 层次：C

Redis 配置模板路径，Sentinel 除外。

默认值：redis.conf，这是一个模板文件，位于 roles/redis/templates/redis.conf。

如果你想使用自己的 Redis 配置模板，你可以将它放在 templates/ 目录中，并设置此参数为模板文件名。

注意： Redis Sentinel 使用的是另一个不同的模板文件，即 roles/redis/templates/redis-sentinel.conf。

redis_bind_address

参数名称： redis_bind_address， 类型： ip， 层次：C

Redis 服务器绑定的 IP 地址，空字符串将使用配置清单中定义的主机名。

默认值：0.0.0.0，这将绑定到此主机上的所有可用 IPv4 地址。

在生产环境中出于安全性考虑，建议仅绑定内网 IP，即将此值设置为空字符串 ''

当该值为空字符串时，模板 roles/redis/templates/redis.conf 会使用 inventory_hostname 渲染 bind <ip>，从而绑定到清单中声明的管理地址。

redis_max_memory

参数名称： redis_max_memory， 类型： size， 层次：C/I

每个 Redis 实例使用的最大内存配置，默认值：1GB。

redis_mem_policy

参数名称： redis_mem_policy， 类型： enum， 层次：C

Redis 内存回收策略，默认值：allkeys-lru，

• noeviction：内存达限时不保存新值：当使用主从复制时仅适用于主库
• allkeys-lru：保持最近使用的键；删除最近最少使用的键（LRU）
• allkeys-lfu：保持频繁使用的键；删除最少频繁使用的键（LFU）
• volatile-lru：删除带有真实过期字段的最近最少使用的键
• volatile-lfu：删除带有真实过期字段的最少频繁使用的键
• allkeys-random：随机删除键以为新添加的数据腾出空间
• volatile-random：随机删除带有过期字段的键
• volatile-ttl：删除带有真实过期字段和最短剩余生存时间（TTL）值的键。

详情请参阅 Redis内存回收策略。

redis_password

参数名称： redis_password， 类型： password， 层次：C/N

Redis 密码，空字符串将禁用密码，这是默认行为。

注意，由于 redis_exporter 的实现限制，您每个节点只能设置一个 redis_password。这通常不是问题，因为 pigsty 不允许在同一节点上部署两个不同的 Redis 集群。

Pigsty 会自动将此密码写入 /etc/default/redis_exporter（REDIS_PASSWORD=...），并通过 REDISCLI_AUTH 传给 redis-ha 与 redis-join 所选的 redis-cli / valkey-cli，避免把密码直接放在命令行参数中。

请在生产环境中使用强密码

redis_rdb_save

参数名称： redis_rdb_save， 类型： string[]， 层次：C

Redis RDB 保存指令，使用空列表则禁用 RDB。

默认值是 ["1200 1"]：如果最近20分钟至少有1个键更改，则将数据集转储到磁盘。

详情请参考 Redis持久化。

redis_aof_enabled

参数名称： redis_aof_enabled， 类型： bool， 层次：C

启用 Redis AOF 吗？默认值是 false，即不使用 AOF。

redis_rename_commands

参数名称： redis_rename_commands， 类型： dict， 层次：C

重命名 Redis 危险命令，这是一个 k:v 字典：old: new，old 是待重命名的命令名称，new 是重命名后的名字。

默认值：{}，你可以通过设置此值来隐藏像 FLUSHDB 和 FLUSHALL 这样的危险命令，下面是一个例子：

{
  "keys": "op_keys",
  "flushdb": "op_flushdb",
  "flushall": "op_flushall",
  "config": "op_config"  
}

redis_cluster_replicas

参数名称： redis_cluster_replicas， 类型： int， 层次：C

在 Redis 原生集群中，应当为一个 Master/Primary 实例配置多少个从库？默认值为： 1，即每个主库配一个从库。

redis_sentinel_monitor

参数名称： redis_sentinel_monitor， 类型： master[]， 层次：C

Redis 哨兵监控的主库列表，只在哨兵集群上使用。每个待纳管的主库定义方式如下所示：

redis_sentinel_monitor:  # primary list for redis sentinel, use cls as name, primary ip:port
  - { name: redis-src, host: 10.10.10.45, port: 6379 ,password: redis.src, quorum: 1 }
  - { name: redis-dst, host: 10.10.10.48, port: 6379 ,password: redis.dst, quorum: 1 }

其中，name，host 是必选参数，port，password，quorum 是可选参数，quorum 用于设置判定主库失效所需的法定人数数，通常大于哨兵实例数的一半（默认为1）。

从 Pigsty 4.0 开始还可以为某个条目添加 remove: true，此时 redis-ha 阶段只会执行 SENTINEL REMOVE <name>，用于清理不再需要的目标。

REDIS_REMOVE

本节包含 redis_remove 角色的参数， 这些是 redis-rm.yml 剧本使用的操作标志参数。

redis_safeguard

参数名称： redis_safeguard， 类型： bool， 层次：G/C/A

Redis 的防误删安全保险开关，默认值为 false。设置为 true 时，redis-rm.yml 会在注销、停服和删除之前 直接中止；它是静态布尔开关，不会探测 Redis 实例是否正在运行。

可以通过命令行参数 -e redis_safeguard=false 强制覆盖此保护。

redis_rm_data

参数名称： redis_rm_data， 类型： bool， 层次：G/C/A

移除 Redis 实例时，是否一并移除 Redis 数据目录？默认为 true。

数据目录（默认 /data/redis/，即 redis_fs_main）包含了 Redis 的 RDB 与 AOF 文件，如果不移除它们，那么新部署的 Redis 实例将会从这些备份文件中加载数据。

设置为 false 可以保留数据目录用于后续恢复。

redis_rm_pkg

参数名称： redis_rm_pkg， 类型： bool， 层次：G/C/A

移除 Redis 节点时，是否一并卸载 redis_type 指定的引擎与 redis-exporter 软件包？默认为 false。指定 redis_port 只移除单个实例时不会卸载共享软件包。

通常情况下不需要卸载软件包，仅当需要彻底清理节点时才需要启用此选项。