xtulnx/redis

By xtulnx

•Updated 27 days ago

Image

375

Overview Tags

xtulnx/redis repository overview

⁠Redis

基于 Redis 官方 Alpine 镜像，可通过同一个镜像启动单点 Redis，或在单个容器内启动由多个 Redis 进程组成的 Cluster。

集群模式主要用于开发、联调和功能测试。所有节点仍位于同一个容器和宿主机内，不具备生产环境所需的故障隔离能力。

⁠镜像

Tag	Redis 版本	说明
`xtulnx/redis:latest`、`:8`、`:8.10`、`:8.10.1`	8.10.1	默认变体，固定精确版本
`xtulnx/redis:7.4`	7.4 最新补丁版	跟随官方 `redis:7.4-alpine` 次版本别名
`xtulnx/redis:7.2`	7.2 最新补丁版	遗留兼容变体，跟随官方 `redis:7.2-alpine` 次版本别名

以上 tag 均发布 linux/amd64 和 linux/arm64 多架构镜像。

Redis 7.2、7.4 和 8 的授权协议不同，使用和再分发时应分别遵守对应上游版本的许可证。Redis 7.2、7.4 和 8 也必须使用不同的数据卷：允许先备份再向前升级，但不要让旧版本直接打开新版本运行过的数据卷进行降级。

镜像默认使用单点模式，默认端口为 6379，数据目录为 /data，AOF 持久化默认开启。

未设置 REDIS_MODE 时会启动单点模式。唯一的兼容例外是设置了旧变量 REDIS_PORT1 时会自动使用集群模式。

⁠单点模式

无密码启动：

docker run -d \
  --name redis \
  -p 6379:6379 \
  -v redis-data:/data \
  xtulnx/redis:latest

设置密码和端口：

docker run -d \
  --name redis \
  -e REDIS_MODE=standalone \
  -e REDIS_PASSWORD=change-me \
  -e REDIS_PORT=6380 \
  -p 6380:6380 \
  -v redis-data:/data \
  xtulnx/redis:latest

连接测试：

redis-cli -h 127.0.0.1 -p 6380 -a change-me ping

⁠集群模式

下面的示例在一个容器中启动 7000 到 7005 共 6 个节点，组成 3 主 3 从集群：

docker run -d \
  --name redis-cluster \
  --stop-timeout 60 \
  -e REDIS_MODE=cluster \
  -e REDIS_PASSWORD=change-me \
  -e REDIS_CLUSTER_ANNOUNCE_IP=192.168.1.10 \
  -e REDIS_CLUSTER_PORT_START=7000 \
  -e REDIS_CLUSTER_PORT_END=7005 \
  -e REDIS_CLUSTER_REPLICAS=1 \
  -p 7000-7005:7000-7005 \
  -p 17000-17005:17000-17005 \
  -v redis-cluster-data:/data \
  xtulnx/redis:latest

REDIS_CLUSTER_ANNOUNCE_IP 是 Cluster 返回给客户端以及节点间通信使用的地址：

客户端从宿主机或局域网访问时，设置为 Docker 宿主机可达的 IP，不能设置为 127.0.0.1。
仅供同一 Docker 网络内的容器访问时可以不设置，入口脚本会使用当前容器 IP。
使用端口映射时，宿主机端口必须与容器端口保持一致。

每个节点还会使用“服务端口 + 10000”的 Cluster Bus 端口，因此示例除 7000-7005 外还必须开放 17000-17005。

⁠节点和端口数量

Redis Cluster 至少需要 3 个主节点。REDIS_CLUSTER_REPLICAS 表示每个主节点分配几个副本：

拓扑	配置	Redis 节点端口	Cluster Bus 端口	说明
最小集群	3 主 0 从，`REDIS_CLUSTER_REPLICAS=0`	3 个	3 个	可以形成集群，但没有副本和故障接管能力
默认集群	3 主 3 从，`REDIS_CLUSTER_REPLICAS=1`	6 个	6 个	默认配置，允许每个主节点有一个副本

节点总数必须能被“每个主节点 + 它的副本数”整除，并且最终至少得到 3 个主节点。例如配置 1 个副本时，最低需要 7000-7005 共 6 个 Redis 节点端口，同时还需要 17000-17005 共 6 个 Bus 端口。

连接测试：

redis-cli -c -h 192.168.1.10 -p 7000 -a change-me cluster info

集群初始化完成后，节点配置和数据分别保存在 /data/<端口>/。重启容器时会恢复已有集群，不会重复执行集群创建。修改端口范围或公告 IP 时应使用新的数据卷，避免旧的 nodes.conf 与新配置冲突。

⁠安全停服

容器收到 SIGTERM 或 SIGINT 时，入口脚本会并行向所有节点发送 Redis SHUTDOWN，等待节点完成 AOF 刷盘和正常退出，然后再结束容器。正常使用 docker stop 或 docker compose down 时会走这个流程。

为给较大数据集留出刷盘时间，建议使用 docker run --stop-timeout 60；本模块的 Compose 示例已经设置 stop_grace_period: 1m。如果直接发送 SIGKILL、宿主机异常断电，或者停止宽限期耗尽后 Docker 强制终止容器，则无法保证完整的优雅停服。默认 AOF 使用 Redis 的 everysec 策略，此类异常情况下理论上仍可能丢失最近约 1 秒的数据。

⁠环境变量

变量	默认值	说明
`REDIS_MODE`	`standalone`	启动模式：`standalone` 或 `cluster`
`REDIS_PASSWORD`	空	Redis 密码；空值表示不启用认证
`REDIS_DATA_DIR`	`/data`	数据目录
`REDIS_BIND`	`0.0.0.0`	Redis 监听地址
`REDIS_APPENDONLY`	`yes`	是否开启 AOF：`yes` 或 `no`
`REDIS_LOGLEVEL`	`notice`	Redis 日志级别
`REDIS_PROTECTED_MODE`	`no`	Redis protected mode：`yes` 或 `no`
`REDIS_CONFIG_FILE`	空	要合并的 Redis 原生配置文件路径
`REDIS_EXTRA_CONFIG`	空	要合并的多行 Redis 原生配置内容
`REDIS_PORT`	`6379`	单点模式端口
`REDIS_CLUSTER_PORT_START`	`7000`	集群节点起始端口
`REDIS_CLUSTER_PORT_END`	`7005`	集群节点结束端口
`REDIS_CLUSTER_REPLICAS`	`1`	每个主节点的副本数量
`REDIS_CLUSTER_ANNOUNCE_IP`	当前容器 IP	集群向客户端和其他节点公告的 IP
`REDIS_CLUSTER_NODE_TIMEOUT`	`5000`	集群节点超时，单位为毫秒

为兼容旧用法，镜像同时识别以下变量：

旧变量	对应变量
`REDIS_PWD`	`REDIS_PASSWORD`
`REDIS_PORT0`	单点端口或集群起始端口
`REDIS_PORT1`	集群结束端口；未设置 `REDIS_MODE` 时会自动启用集群模式
`REDIS_REPLICAS`	`REDIS_CLUSTER_REPLICAS`
`REDIS_HOST`	`REDIS_CLUSTER_ANNOUNCE_IP`

不要在没有密码和网络访问控制的情况下将 Redis 端口暴露到公网。

⁠合并 Redis 原生配置

不需要把大量 Redis 指令拆成一个个环境变量。镜像可以加载挂载的原生配置文件，并与入口脚本管理的启动配置合并：

docker run -d \
  -e REDIS_MODE=standalone \
  -e REDIS_CONFIG_FILE=/etc/redis/redis.conf \
  -v ./redis.conf:/etc/redis/redis.conf:ro \
  -v redis-data:/data \
  -p 6379:6379 \
  xtulnx/redis:latest

也可以使用 REDIS_EXTRA_CONFIG 一次传入多条原生 Redis 配置：

docker run -d \
  -e REDIS_PASSWORD=change-me \
  -e $'REDIS_EXTRA_CONFIG=maxmemory 256mb\nmaxmemory-policy allkeys-lru\ntcp-keepalive 120' \
  -p 6379:6379 \
  xtulnx/redis:latest

REDIS_CONFIG 是 REDIS_EXTRA_CONFIG 的兼容别名。两者同时设置时以 REDIS_EXTRA_CONFIG 为准。

合并配置的优先级从低到高为：

Redis 内置默认值
REDIS_CONFIG_FILE 指向的原生配置文件
REDIS_EXTRA_CONFIG 多行内容
入口脚本根据环境变量生成的模式、端口、目录、认证等托管配置
容器命令行追加的 Redis 参数

因此，普通的内存、淘汰、持久化、慢日志、客户端和复制配置都可以放进原始配置文件；托管模式下的 port、dir、daemonize、认证和 cluster-* 等关键项会由入口脚本覆盖，保证单点或多节点集群能够正确编排。

如果希望完全使用原始配置文件、不进行任何合并或托管，可以直接把配置文件作为 redis-server 的位置参数传入：

docker run -d \
  -v ./redis.conf:/etc/redis/redis.conf:ro \
  -v redis-data:/data \
  -p 6379:6379 \
  xtulnx/redis:latest \
  redis-server /etc/redis/redis.conf

此时由原始配置文件完整决定端口、数据目录、认证、前台运行和集群行为，不再使用 REDIS_MODE 等托管变量。配置中的 daemonize 必须保持为 no，否则 Redis 转入后台后容器会退出。

⁠通过参数追加 Redis 配置

以 redis-server 或 -- 开头的参数会追加到入口脚本生成的 Redis 配置之后。单点和集群模式都支持这种方式；集群模式下参数会应用到每个节点。

例如，限制单点实例最大内存并启用 LRU 淘汰策略：

docker run -d \
  -p 6379:6379 \
  xtulnx/redis:latest \
  redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru

集群模式下不要通过参数覆盖 port、dir、cluster-config-file 或 cluster-announce-*，这些配置由入口脚本按节点生成。

传入其他命令时，镜像会直接执行该命令：

docker run --rm xtulnx/redis:latest redis-cli --version

⁠Docker Compose

模块附带的 docker-compose.yml 使用 profile 区分两种模式，完整内容如下：

services:
  standalone:
    profiles:
      - standalone
    image: xtulnx/redis:latest
    restart: unless-stopped
    stop_grace_period: 1m
    environment:
      REDIS_MODE: standalone
      REDIS_PASSWORD: ${REDIS_PASSWORD:-}
      REDIS_PORT: ${REDIS_PORT:-6379}
    ports:
      - "${REDIS_PORT:-6379}:${REDIS_PORT:-6379}"
    volumes:
      - redis-standalone:/data

  cluster:
    profiles:
      - cluster
    image: xtulnx/redis:latest
    restart: unless-stopped
    stop_grace_period: 1m
    environment:
      REDIS_MODE: cluster
      REDIS_PASSWORD: ${REDIS_PASSWORD:-}
      REDIS_CLUSTER_ANNOUNCE_IP: ${REDIS_CLUSTER_ANNOUNCE_IP:-}
      REDIS_CLUSTER_PORT_START: ${REDIS_CLUSTER_PORT_START:-7000}
      REDIS_CLUSTER_PORT_END: ${REDIS_CLUSTER_PORT_END:-7005}
      REDIS_CLUSTER_REPLICAS: ${REDIS_CLUSTER_REPLICAS:-1}
    ports:
      - "${REDIS_CLUSTER_PORT_START:-7000}-${REDIS_CLUSTER_PORT_END:-7005}:${REDIS_CLUSTER_PORT_START:-7000}-${REDIS_CLUSTER_PORT_END:-7005}"
      - "${REDIS_CLUSTER_BUS_PORT_START:-17000}-${REDIS_CLUSTER_BUS_PORT_END:-17005}:${REDIS_CLUSTER_BUS_PORT_START:-17000}-${REDIS_CLUSTER_BUS_PORT_END:-17005}"
    volumes:
      - redis-cluster:/data

volumes:
  redis-standalone:
  redis-cluster:

对应的 compose.env.example 内容：

REDIS_PASSWORD=change-me

REDIS_PORT=6379

# 外部客户端访问时改为 Docker 宿主机可达的 IP
REDIS_CLUSTER_ANNOUNCE_IP=192.168.1.10
REDIS_CLUSTER_PORT_START=7000
REDIS_CLUSTER_PORT_END=7005
REDIS_CLUSTER_BUS_PORT_START=17000
REDIS_CLUSTER_BUS_PORT_END=17005
REDIS_CLUSTER_REPLICAS=1

启动单点：

docker compose \
  --env-file compose.env.example \
  --profile standalone up -d

启动集群前，先在 compose.env.example 中把 REDIS_CLUSTER_ANNOUNCE_IP 调整为宿主机可达 IP，然后执行：

docker compose \
  --env-file compose.env.example \
  --profile cluster up -d

如果修改集群节点端口范围，还要同步把 REDIS_CLUSTER_BUS_PORT_START 和 REDIS_CLUSTER_BUS_PORT_END 设置为对应节点端口加 10000，Compose 才能映射正确的 Cluster Bus 端口。

Tag summary

Recent tags

Content type

Image

Digest

sha256:630f21a99…

Size

37.2 MB

Last updated

27 days ago

docker pull xtulnx/redis