Valkey Docker镜像文档

镜像概述和主要用途

Valkey是一款高性能数据结构服务器，主要用于处理键值（key/value）工作负载。它支持多种原生数据结构，并提供可扩展的插件系统，用于添加新的数据结构和访问模式。

核心功能和特性

• 高性能键值存储：优化的内存数据处理，支持高并发读写操作
• 多数据结构支持：原生支持字符串、哈希、列表、集合、有序集合等多种数据结构
• 可扩展插件系统：允许通过插件扩展新的数据结构和访问模式
• 持久化机制：支持RDB（快照）和AOF（日志）两种持久化策略，保障数据可靠性
• 高可用架构：支持主从复制、哨兵模式和集群模式，提供故障转移和负载均衡能力

使用场景和适用范围

• 缓存系统：作为应用层与数据库之间的缓存，减轻数据库负载
• 会话存储：存储用户会话信息，支持分布式系统中的会话共享
• 实时数据分析：处理高频写入的时序数据或实时指标
• 消息队列：基于列表结构实现简单的生产者-消费者模型
• 排行榜/计数器：利用有序集合实现实时排名和计数功能

支持的标签及对应Dockerfile链接

官方发布版本

• 8.1.3, 8.1, 8, latest, 8.1.3-bookworm, 8.1-bookworm, 8-bookworm, bookworm
• 8.1.3-alpine, 8.1-alpine, 8-alpine, alpine, 8.1.3-alpine3.22, 8.1-alpine3.22, 8-alpine3.22, alpine3.22
• 8.0.5, 8.0, 8.0.5-trixie, 8.0-trixie
• 8.0.5-alpine, 8.0-alpine, 8.0.5-alpine3.22, 8.0-alpine3.22
• 7.2.10, 7.2, 7, 7.2.10-bookworm, 7.2-bookworm, 7-bookworm
• 7.2.10-alpine, 7.2-alpine, 7-alpine, 7.2.10-alpine3.22, 7.2-alpine3.22, 7-alpine3.22

候选发布版本

• 9.0.0-rc2, 9.0, 9.0.0-rc2-trixie, 9.0-trixie
• 9.0.0-rc2-alpine, 9.0-alpine, 9.0.0-rc2-alpine3.22, 9.0-alpine3.22

最新不稳定版本

• unstable, unstable-bookworm
• unstable-alpine, unstable-alpine3.21

安全注意事项

为便于通过Docker网络从其他容器访问Valkey，默认关闭了"保护模式"（Protected mode）。这意味着如果通过-p参数将端口暴露到主机外部，任何人都可无密码访问实例。强烈建议：若需将Valkey暴露到公网，必须通过配置文件设置密码。

相关安全文档：

• Valkey官方安全指南
• 保护模式说明

使用方法和配置说明

启动Valkey实例

docker run --name some-valkey -d valkey/valkey

带持久化存储启动

Valkey支持多种持久化策略，以下示例配置为每60秒且至少1次写入操作时保存快照，并降低日志级别：

docker run --name some-valkey -d valkey/valkey valkey-server --save 60 1 --loglevel warning

数据默认存储在VOLUME /data中，可通过以下方式持久化：

• 使用--volumes-from some-volume-container挂载数据卷
• 使用-v /host/dir:/data挂载主机目录（需确保目录权限正确）

通过valkey-cli连接实例

在同一网络中连接Valkey实例（假设实例名为some-valkey，网络名为some-network）：

docker run -it --network some-network --rm valkey/valkey valkey-cli -h some-valkey

通过环境变量传递启动参数

使用VALKEY_EXTRA_FLAGS环境变量传递valkey-server启动参数，无需覆盖默认CMD：

docker run --env VALKEY_EXTRA_FLAGS='--save 60 1 --loglevel warning' valkey/valkey

自定义配置文件

方法1：通过Dockerfile构建

创建包含自定义valkey.conf的镜像：

FROM valkey/valkey
COPY valkey.conf /usr/local/etc/valkey/valkey.conf
CMD ["valkey-server", "/usr/local/etc/valkey/valkey.conf"]

方法2：运行时挂载配置文件

直接挂载主机目录中的配置文件：

docker run -v /host/valkey/conf:/usr/local/etc/valkey --name myvalkey valkey/valkey valkey-server /usr/local/etc/valkey/valkey.conf

注意：挂载的目录需可写，Valkey可能需要创建或修改配置文件。

Systemd启动通知（Podman Quadlet）

Valkey支持通过Systemd通知机制，确保依赖服务在Valkey就绪后启动。在Quadlet服务文件中配置：

[Container]
Image=docker.io/valkey/valkey:latest
Exec=valkey-server --supervised systemd
Notify=true

Docker Compose部署示例

创建docker-compose.yml快速部署带持久化的Valkey服务：

version: '3.8'
services:
  valkey:
    image: valkey/valkey:latest
    container_name: valkey-service
    restart: always
    ports:
      - "6379:6379"  # 暴露默认端口
    environment:
      - VALKEY_EXTRA_FLAGS=--save 60 1 --loglevel warning  # 持久化和日志配置
    volumes:
      - valkey-data:/data  # 数据持久化卷
    networks:
      - valkey-network

volumes:
  valkey-data:  # 命名卷，数据持久化到宿主机

networks:
  valkey-network:  # 自定义网络，隔离服务
    driver: bridge

启动服务：

docker-compose up -d

镜像变体

Valkey镜像提供多种变体，适用于不同场景：

valkey/valkey:<version>（默认变体）

• 基于Debian系统（如bookworm、trixie等发行版）
• 包含完整的系统工具链，兼容性好，适合大多数生产环境
• 标签中包含发行版名称（如8.1.3-bookworm），建议显式指定以避免依赖变更

valkey/valkey:<version>-alpine（轻量级变体）

• 基于Alpine Linux，镜像体积极小（约5MB基础镜像）
• 使用musl libc替代glibc，适合对镜像大小有严格要求的场景
• 标签中包含Alpine版本（如8.1.3-alpine3.22），需注意部分依赖musl的兼容性

注意：Alpine变体可能缺少部分系统工具（如bash、git），需在Dockerfile中额外安装。

许可证信息

镜像中软件的许可证信息参见Valkey官方COPYING文件。

Docker镜像可能包含基础系统（如Debian/Alpine）及依赖软件，这些组件可能具有独立许可证。使用前请确保遵守所有包含软件的许可证要求。