CloudPirates Helm Chart for Valkey 技术文档

1. 镜像概述和主要用途

CloudPirates Helm Chart for Valkey 是由 CloudPirates 提供的 Helm 图表，用于在 Kubernetes 环境中简化 Valkey 数据库的部署、配置和生命周期管理。Valkey 是一款兼容 Redis 协议的高性能开源内存数据库，支持数据持久化、主从复制、哨兵等高可用特性，适用于缓存、会话存储、实时数据分析等场景。该 Helm Chart 旨在通过标准化配置和自动化流程，降低 Valkey 在 Kubernetes 集群中的部署门槛，提升管理效率。

2. 核心功能和特性

2.1 部署灵活性

• 支持自定义副本数、资源限制（CPU/内存）及节点亲和性配置，适配不同规模的业务需求。
• 提供多模式部署选项：单节点模式（开发测试）、主从复制模式（基础高可用）、哨兵模式（自动故障转移）。

2.2 数据可靠性

• 内置持久化存储支持，可配置 PersistentVolumeClaim（PVC）参数（存储大小、存储类、访问模式），确保数据持久化。
• 支持数据备份策略，可配置定时备份至外部存储（如 S3 兼容存储）。

2.3 安全性增强

• 支持密码认证（通过配置自动生成或自定义密码），默认启用访问控制。
• 可选 TLS 加密配置，保护客户端与 Valkey 节点间的通信安全。
• 支持 Kubernetes Secrets 管理敏感信息（如密码、TLS 证书）。

2.4 可观测性集成

• 内置 Prometheus 监控指标暴露（兼容 Redis Exporter 格式），支持对接 Grafana 可视化面板。
• 集成 Kubernetes Events 和日志输出，便于问题排查和状态监控。

2.5 运维便捷性

• 支持 Helm 标准生命周期管理（安装、升级、回滚、卸载），配置变更通过 values.yaml 或 --set 参数灵活调整。
• 提供健康检查（liveness/readiness probes）配置，确保服务可用性。
• 兼容 Kubernetes 自动扩缩容（HPA），可基于 CPU/内存使用率动态调整副本数。

3. 使用场景和适用范围

3.1 典型使用场景

• 缓存系统：作为应用层与数据库之间的缓存层，加速数据访问（如电商商品缓存、API 响应缓存）。
• 会话存储：存储分布式系统中的用户会话数据，支持高并发读写。
• 实时数据分析：处理实时产生的高频数据（如监控指标、用户行为日志），提供低延迟查询。
• 分布式锁：基于 Valkey 的原子操作实现分布式系统中的资源竞争控制。

3.2 适用范围

• 环境要求：Kubernetes 集群（版本 ≥ 1.21），Helm 3.x 及以上。
• 业务规模：适用于从开发测试环境到生产环境的全场景，支持单节点轻量部署（资源需求低）及大规模集群（多副本+哨兵高可用）。
• 用户群体：Kubernetes 运维人员、开发团队，需快速部署和管理 Valkey 的场景。

4. 使用方法和配置说明

4.1 前置条件

• Kubernetes 集群（版本 ≥ 1.21）
• Helm 3.x 客户端
• 集群内已配置默认存储类（如需持久化）

4.2 安装步骤

4.2.1 添加 Helm 仓库

bash
helm repo add cloudpirates-valkey [***]
helm repo update

4.2.2 安装 Helm Chart

默认配置（单节点模式，无持久化）：

bash
helm install valkey cloudpirates-valkey/valkey --namespace valkey --create-namespace

自定义配置（通过 --set 参数覆盖默认值）：

bash
helm install valkey cloudpirates-valkey/valkey \
  --namespace valkey --create-namespace \
  --set replicaCount=3 \
  --set persistence.enabled=true \
  --set persistence.size=10Gi \
  --set auth.enabled=true \
  --set auth.password=your-secure-password \
  --set resources.requests.cpu=1 \
  --set resources.requests.memory=2Gi

4.2.3 通过 values.yaml 自定义配置

下载默认配置文件并修改：

bash
helm show values cloudpirates-valkey/valkey > values.yaml
# 编辑 values.yaml 调整配置
helm install valkey cloudpirates-valkey/valkey -f values.yaml --namespace valkey

4.3 升级与卸载

4.3.1 升级 Chart

bash
helm upgrade valkey cloudpirates-valkey/valkey --namespace valkey -f values.yaml

4.3.2 卸载 Chart

bash
helm uninstall valkey --namespace valkey
# 如需删除命名空间（含 PVC 等资源）：
kubectl delete namespace valkey

4.4 部署方案示例

4.4.1 生产环境高可用配置（哨兵模式）

通过 values.yaml 配置哨兵模式（主从+哨兵）：

yaml
# values.yaml 片段
architecture: sentinel  # 启用哨兵模式（默认 single）
replicaCount: 3         # 主从副本总数（1主2从）
sentinel:
  replicaCount: 3       # 哨兵节点数
  quorum: 2             # 故障转移仲裁数
persistence:
  enabled: true
  size: 20Gi
  storageClass: "ssd-storage"  # 使用高性能存储类
resources:
  requests:
    cpu: 2
    memory: 4Gi
  limits:
    cpu: 4
    memory: 8Gi
auth:
  enabled: true
  password: "${VALKEY_PASSWORD}"  # 从环境变量读取密码（推荐生产环境）

安装命令：

bash
export VALKEY_PASSWORD=$(openssl rand -base64 16)  # 生成随机密码
helm install valkey cloudpirates-valkey/valkey -f values.yaml --namespace valkey

4.4.2 开发环境轻量配置（单节点+临时存储）

yaml
# values.yaml 片段
architecture: single
replicaCount: 1
persistence:
  enabled: false  # 禁用持久化（数据存储于内存，重启丢失）
resources:
  requests:
    cpu: 0.5
    memory: 1Gi
  limits:
    cpu: 1
    memory: 2Gi

5. 核心配置参数说明

6. 注意事项

• 生产环境建议启用持久化存储和密码认证，并配置资源限制避免节点资源耗尽。
• 哨兵模式下，哨兵节点数建议 ≥3（奇数），以确保高可用仲裁有效性。
• 升级前建议备份 values.yaml 和数据，避免配置冲突导致服务不可用。
• 监控集成需确保集群内已部署 Prometheus Operator，或手动配置 ServiceMonitor。