bitnami/valkey-cluster

Bitnami Valkey Cluster 镜像文档

镜像概述和主要用途

Valkey 是一款开源（BSD许可）的高性能键值数据存储系统，支持缓存、消息队列等多种工作负载，也可作为主数据库使用。Valkey Cluster 是 Valkey 的分布式集群模式，提供数据分片、高可用和水平扩展能力。

Bitnami Valkey Cluster 镜像旨在简化 Valkey 集群的部署和管理，基于 Bitnami 安全加固标准构建，适用于开发、测试及生产环境（推荐使用 Bitnami Secure Images 用于生产）。

核心功能和特性

Valkey Cluster 核心功能

• 分布式数据分片：自动将数据分布到多个节点，支持水平扩展
• 高可用架构：通过主从复制实现故障自动转移
• 兼容 Redis 协议：可无缝迁移现有 Redis 集群 workload
• 持久化机制：支持 AOF（Append-Only File）和 RDB（Redis Database）两种持久化方式
• 集群自动发现：支持动态节点加入和配置更新

Bitnami 镜像特性

• 安全加固：基于最小化 Photon Linux 操作系统，减少***面
• 供应链安全：提供 SBOM（软件物料清单）、VEX/KEV 漏洞透明度报告
• 配置灵活性：支持环境变量、配置文件覆盖、自定义参数
• 持久化支持：数据目录可挂载外部卷，确保数据持久化
• TLS 加密：内置 TLS 支持，保护集群通信安全
• 一致性部署：与 Bitnami Helm Chart、虚拟机镜像配置一致，便于跨环境迁移

使用场景和适用范围

适用场景

• 分布式缓存系统：减轻数据库负载，提升应用响应速度
• 分布式锁服务：基于 Redlock 协议实现跨节点锁机制
• 消息队列：通过 Pub/Sub 或 List 数据结构实现简单消息传递
• 会话存储：存储分布式应用的用户会话数据
• 实时分析：高频读写场景下的实时数据存储

适用范围

• 开发/测试环境：快速部署 Valkey 集群，验证分布式功能
• 小规模生产环境：使用 "latest" 标签镜像，需自行维护更新
• 企业生产环境：推荐采用 Bitnami Secure Images，获取长期支持、安全加固和企业级服务

快速启动

通过以下命令快速启动 Valkey Cluster 容器（允许空密码访问）：

console
docker run --name valkey-cluster -e ALLOW_EMPTY_PASSWORD=yes bitnami/valkey-cluster:latest

重要通知：Bitnami 镜像目录即将变更

自 2025 年 8 月 28 日起，Bitnami 将升级其公共镜像目录，推出 Bitnami Secure Images 计划，主要变更如下：

• 首次向社区用户开放安全优化版容器镜像
• 逐步弃用免费 tier 中的非加固 Debian 基础镜像，仅保留 "latest" 标签用于开发
• 现有镜像（含历史版本标签，如 2.50.0、10.6）将迁移至 "Bitnami Legacy" 仓库（docker.io/bitnamilegacy），不再更新
• 生产环境建议使用 Bitnami Secure Images，包含加固容器、CVE 透明度报告、SBOM 和企业支持

详细说明见 https://github.com/bitnami/containers/issues/83267%E3%80%82

获取镜像

推荐方式：拉取预构建镜像

从 Docker Hub 拉取最新版镜像：

console
docker pull bitnami/valkey-cluster:latest

拉取特定版本（查看 https://hub.docker.com/r/bitnami/valkey-cluster/tags/%EF%BC%89%EF%BC%9A

console
docker pull bitnami/valkey-cluster:[TAG]  # 例如：bitnami/valkey-cluster:7.2.4

手动构建镜像

克隆仓库并构建（替换 APP、VERSION、OPERATING-SYSTEM 占位符）：

console
git clone https://github.com/bitnami/containers.git
cd bitnami/APP/VERSION/OPERATING-SYSTEM
docker build -t bitnami/APP:latest .

持久化数据

默认情况下，容器删除后数据会丢失。需挂载外部卷至 /bitnami 目录实现持久化：

Docker 命令方式

console
docker run \
  --name valkey-cluster \
  -e ALLOW_EMPTY_PASSWORD=yes \
  -v /path/to/valkey-cluster-persistence:/bitnami \
  bitnami/valkey-cluster:latest

Docker Compose 方式

修改 docker-compose.yml 文件：

yaml
services:
  valkey-cluster:
    ...
    volumes:
      - /path/to/valkey-cluster-persistence:/bitnami  # 挂载持久化目录
    ...

容器网络连接

容器需加入同一网络才能相互通信，可通过容器名作为主机名访问。

步骤 1：创建网络

console
docker network create valkey-cluster-network --driver bridge

步骤 2：启动 Valkey Cluster 节点

console
docker run \
  -e ALLOW_EMPTY_PASSWORD=yes \
  --name valkey-cluster-node1 \
  --network valkey-cluster-network \
  bitnami/valkey-cluster:latest

步骤 3：连接其他容器

其他容器加入同一网络后，可通过 valkey-cluster-node1:6379 访问 Valkey 服务。

配置说明

配置文件覆盖

镜像默认从 /opt/bitnami/valkey/mounted-etc/valkey.conf 加载配置，可挂载自定义配置文件覆盖：

console
docker run --name valkey-cluster \
  -e ALLOW_EMPTY_PASSWORD=yes \
  -v /path/to/your_valkey.conf:/opt/bitnami/valkey/mounted-etc/valkey.conf \  # 自定义配置文件
  -v /path/to/valkey-data:/bitnami/valkey/data \  # 数据持久化
  bitnami/valkey-cluster:latest

配置参数覆盖

无需替换完整配置文件时，可通过 overrides.conf 仅覆盖特定参数（优先级低于自定义 valkey.conf）：

console
docker run --name valkey-cluster \
  -e ALLOW_EMPTY_PASSWORD=yes \
  -v /path/to/overrides.conf:/opt/bitnami/valkey/mounted-etc/overrides.conf \  # 参数覆盖文件
  bitnami/valkey-cluster:latest

环境变量配置

可自定义环境变量

只读环境变量（运行时不可修改）

集群初始化与管理

手动初始化集群

所有节点启动后，通过 valkey-cli 初始化集群（替换 node1:port 为实际节点地址）：

console
valkey-cli --cluster create node1:port node2:port ... \
  --cluster-replicas 1 \  # 每个主节点的副本数
  --cluster-yes  # 自动确认所有配置

集群初始化故障排除

DNS 查找延迟可能导致初始化失败，可调整以下参数：

• VALKEY_CLUSTER_SLEEP_BEFORE_DNS_LOOKUP：DNS 查找前等待时间（默认 0，建议 Kubernetes 环境设为 30）
• VALKEY_CLUSTER_DNS_LOOKUP_RETRIES：DNS 查找重试次数（默认 1）
• VALKEY_CLUSTER_DNS_LOOKUP_SLEEP：重试间隔秒数（默认 1）

安全配置

启用 TLS 加密

通过环境变量配置 TLS（需挂载证书文件）：

console
docker run --name valkey-cluster \
  -v /path/to/certs:/opt/bitnami/valkey/certs \  # 挂载证书目录
  -e ALLOW_EMPTY_PASSWORD=yes \
  -e VALKEY_TLS_ENABLED=yes \
  -e VALKEY_TLS_CERT_FILE=/opt/bitnami/valkey/certs/valkey.crt \  # 证书文件
  -e VALKEY_TLS_KEY_FILE=/opt/bitnami/valkey/certs/valkey.key \    # 私钥文件
  -e VALKEY_TLS_CA_FILE=/opt/bitnami/valkey/certs/valkeyCA.crt \   # CA 证书
  bitnami/valkey-cluster:latest

Docker Compose 配置：

yaml
services:
  valkey-cluster:
    ...
    environment:
      - VALKEY_TLS_ENABLED=yes
      - VALKEY_TLS_CERT_FILE=/opt/bitnami/valkey/certs/valkey.crt
      - VALKEY_TLS_KEY_FILE=/opt/bitnami/valkey/certs/valkey.key
      - VALKEY_TLS_CA_FILE=/opt/bitnami/valkey/certs/valkeyCA.crt
    volumes:
      - /path/to/certs:/opt/bitnami/valkey/certs  # 挂载证书目录
    ...

RDB 持久化配置

修改 RDB 持久化策略（格式：<秒数>#<修改次数>，多个策略空格分隔）：

console
docker run --name valkey-cluster \
  -e ALLOW_EMPTY_PASSWORD=yes \
  -e VALKEY_RDB_POLICY_DISABLED=no \  # 启用 RDB 策略
  -e VALKEY_RDB_POLICY="900#1 600#5 300#10" \  # 900秒内1次修改触发持久化，以此类推
  -v /path/to/persistence:/bitnami \
  bitnami/valkey-cluster:latest

FIPS 模式配置（Bitnami Secure Images）

企业版镜像支持 FIPS 模式，通过环境变量启用：

• OPENSSL_FIPS=yes：启用 FIPS 模式（默认值）
• OPENSSL_FIPS=no：禁用 FIPS 模式

日志管理

镜像将日志输出至 stdout，可通过 docker logs 查看：

console
docker logs valkey-cluster  # 查看容器日志

可通过 --log-driver 配置日志驱动（如 json-file、syslog 等）：

console
docker run --name valkey-cluster \
  --log-driver json-file \  # 指定日志驱动
  --log-opt max-size=10m \  # 日志文件最大尺寸
  --log-opt max-file=3 \    # 保留日志文件数
  bitnami/valkey-cluster:latest

镜像升级

步骤 1：拉取新版本镜像

console
docker pull bitnami/valkey-cluster:latest

步骤 2：停止并删除旧容器

console
docker stop valkey-cluster  # 停止容器
docker rm -v valkey-cluster  # 删除容器（-v 清理匿名卷）

步骤 3：启动新版本容器

使用原持久化卷启动新容器：

console
docker run --name valkey-cluster \
  -e ALLOW_EMPTY_PASSWORD=yes \
  -v /path/to/valkey-cluster-persistence:/bitnami \
  bitnami/valkey-cluster:latest

使用 Docker Compose

注意：docker-compose.yml 文件仅建议用于开发/测试，生产环境推荐使用 https://github.com/bitnami/charts/tree/main/bitnami/valkey-cluster%E3%80%82

示例 docker-compose.yml 片段：

yaml
version: '3'
services:
  valkey-node-0:
    image: bitnami/valkey-cluster:latest
    environment:
      - ALLOW_EMPTY_PASSWORD=yes
      - VALKEY_CLUSTER_CREATOR=yes  # 作为集群创建节点
      - VALKEY_NODES=valkey-node-0,valkey-node-1  # 集群节点列表
    volumes:
      - valkey-data-0:/bitnami
  valkey-node-1:
    image: bitnami/valkey-cluster:latest
    environment:
      - ALLOW_EMPTY_PASSWORD=yes
      - VALKEY_NODES=valkey-node-0,valkey-node-1
    volumes:
      - valkey-data-1:/bitnami
volumes:
  valkey-data-0:
  valkey-data-1:

重要变更记录

2024年10月20日起

• 所有引用已更新至 Valkey 品牌（原 Redis 分支）

贡献

欢迎通过 https://github.com/bitnami/containers/issues 报告问题或提交 https://github.com/bitnami/containers/pulls 贡献代码。

注：完整文档请参见 https://github.com/bitnami/containers/blob/main/bitnami/valkey-cluster/README.md%E3%80%82