编程 Redis 换 Valkey 迁移指南：Docker 部署 + ACL 多账号实践

背景：Redis 许可证变更与 Valkey 替代方案

Redis 7.4+ 开始，开源许可证从 BSD 3-Clause 变更为 RSALv2 + SSPLv1，对云厂商和商业嵌入场景产生直接影响：

Redis Inc. 官方理由是云厂商（AWS、GCP、阿里云等）将 Redis 作为托管服务售卖，与自身商业产品形成竞争且无法从中获益。对商业产品嵌入，可选低版本 Redis 或用替代方案，当下最合适的是 Valkey。

许可证变更后一周内，Linux 基金会宣布成立 Valkey 项目，AWS、Google Cloud、Oracle、Ericsson 及 Redis 原核心维护者共同支持，基于 Redis 7.2.4 fork，保持 BSD 3-Clause 许可证。

• GitHub：https://github.com/valkey-io/valkey
• 官网：https://valkey.io/

Valkey 与 Redis 协议完全兼容，迁移可无缝替换。

一、部署

• 官方文档：https://valkey.io/topics/installation/
• 当前最新版：9.1.1（https://valkey.io/download/ ）
• 镜像地址：https://hub.docker.com/r/valkey/valkey/

1. docker-compose.yaml

services:
valkey:
image: docker.io/valkey/valkey:9.1.1-alpine3.24
container_name: valkey
restart: unless-stopped
ports:
- "6379:6379"
volumes:
# 数据持久化
- $PWD/valkey_data:/data
# 配置文件挂载（可选，不用则删掉这行和下方 config 子配置）
- ./valkey.conf:/usr/local/etc/valkey/valkey.conf:ro
command: >
valkey-server /usr/local/etc/valkey/valkey.conf
--appendonly yes
--appendfsync everysec
--save 900 1
--save 300 10
--save 60 10000
--maxmemory 2gb
--maxmemory-policy allkeys-lru
--timeout 300
--tcp-keepalive 60
--loglevel notice
healthcheck:
test: ["CMD", "valkey-cli", "--no-auth-warning", "-a", "$${VALKEY_PASSWORD}", "ping"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
deploy:
resources:
limits:
memory: 2560M
reservations:
memory: 512M
sysctls:
# 关闭透明大页，避免性能警告
- net.core.somaxconn=1024
ulimits:
nproc: 65535
nofile:
soft: 65535
hard: 65535

2. valkey.conf（按需修改）

# ====================== 网络 ======================
bind 0.0.0.0
port 6379
protected-mode yes
tcp-backlog 511
timeout 300
tcp-keepalive 60

# ====================== 通用 ======================
daemonize no
supervised no
pidfile /var/run/valkey_6379.pid
loglevel notice
logfile ""
databases 16
always-show-logo no
set-proc-title yes
proc-title-template "{title} {listen-addr} {server-mode}"

# ====================== 快照 ======================
save 900 1
save 300 10
save 60 10000
stop-writes-on-bgsave-error yes
rdbcompression yes
rdbchecksum yes
dbfilename dump.rdb
rdb-del-sync-files no
dir /data

# ====================== 复制 ======================
replica-serve-stale-data yes
replica-read-only yes
repl-diskless-sync yes
repl-diskless-sync-delay 5
repl-diskless-sync-max-replicas 0
repl-diskless-load disabled
repl-disable-tcp-nodelay no
replica-priority 100
acllog-max-len 128

# ====================== 安全 ======================
# 密码通过环境变量注入，这里不硬编码
# requirepass your_strong_password_here

rename-command FLUSHDB ""
rename-command FLUSHALL ""
rename-command DEBUG ""
rename-command CONFIG ""

# ====================== 客户端 ======================
maxclients 10000

# ====================== 内存管理 ======================
maxmemory 2gb
maxmemory-policy allkeys-lru
maxmemory-samples 5
replica-ignore-maxmemory yes
active-expire-effort 1

# ====================== AOF 持久化 ======================
appendonly yes
appendfilename "appendonly.aof"
appendfsync everysec
no-appendfsync-on-rewrite no
auto-aof-rewrite-percentage 100
auto-aof-rewrite-min-size 64mb
aof-load-truncated yes
aof-use-rdb-preamble yes
aof-timestamp-enabled no

# ====================== 慢查询 ======================
slowlog-log-slower-than 10000
slowlog-max-len 128

# ====================== 延迟监控 ======================
latency-monitor-threshold 0

# ====================== 事件通知 ======================
notify-keyspace-events ""

# ====================== 高级配置 ======================
hash-max-listpack-entries 512
hash-max-listpack-value 64
list-max-listpack-size -2
list-compress-depth 0
set-max-intset-entries 512
zset-max-listpack-entries 128
zset-max-listpack-value 64
hll-sparse-max-bytes 3000
stream-node-max-bytes 4096
stream-node-max-entries 100
activerehashing yes
client-output-buffer-limit normal 0 0 0
client-output-buffer-limit replica 256mb 64mb 60
client-output-buffer-limit pubsub 32mb 8mb 60
hz 10
dynamic-hz yes
aof-rewrite-incremental-fsync yes
rdb-save-incremental-fsync yes
jemalloc-bg-thread yes

3. 启动与验证

# 启动
docker compose up -d

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f valkey

# 连接测试
docker exec -it valkey valkey-cli -a your_strong_password_here ping
# 返回 PONG 即正常

二、使用

2.1 命令行文档

https://valkey.io/commands/

2.2 用户名密码设置

Valkey 完全兼容 Redis 6+ ACL 语法。

1. default 默认用户：客户端连接未执行 AUTH 时默认使用该用户。生产环境强烈建议 default off 禁用，所有业务显式 AUTH 登录业务账号。

2. 认证两种方式：

# 双参数：指定用户名+密码（ACL标准）
AUTH username password
# 单参数：只传密码，等价登录 default 用户
AUTH password

1. 权限生效条件：命令权限和 key 权限两个条件同时满足才能执行；缺任一返回 NOPERM。

2. 两套持久化方式：

• 写在 valkey.conf 里（user xxx ...）
• 外部 aclfile（推荐）：aclfile /etc/valkey/users.acl，独立文件管理用户，支持 ACL SAVE 写入、ACL LOAD 重载

2.3 ACL 最佳实践

首次初始化

用独立的 aclfile（如 users.acl），先用明文密码设置管理员用户，保证启动后有账号可登录。

docker-compose.yaml:

services:
valkey:
image: valkey:9.1.1-alpine3.24
container_name: valkey
ports:
- "6379:6379"
volumes:
# 数据持久化
- ./data:/data
# valkey 配置文件
- ./conf:/etc/valkey
command: valkey-server /etc/valkey/valkey.conf
restart: always

conf/valkey.conf:

bind 0.0.0.0
port 6379
protected-mode yes

# 指定 acl 文件容器内路径，挂载映射宿主机文件
aclfile /etc/valkey/users.acl

# 关闭 requirepass，全部交给 acl 管理
# requirepass xxx

# 持久化 RDB/AOF 按需开启
dbfilename dump.rdb
dir /data

conf/users.acl（注意：不要放中文注释，否则启动报 ACL 解析错误）：

# 关闭 default 用户，禁止匿名登录
user default off reset

# 读写账号 app-rw，密码自行替换，>代表明文，启动 valkey 会自动转 hash 存储
user app-rw on >AppRw@2026 ~app:* -@all +@read +@write -KEYS -FLUSHALL -FLUSHDB

# 只读账号 app-ro
user app-ro on >AppRo@2026 ~app:* -@all +@read

# 管理员账号，运维使用，尽量业务程序不要用
user valkey-admin on >Admin@2026 ~* &* +@all

转为哈希密码

启动容器后，用管理员登录执行 acl list 查看 sha256 哈希：

127.0.0.1:6379> acl list
1) "user app-ro on sanitize-payload #34af85bc909f3d211abcd44cfd8d8ac4b4ab6a2f061e8b7358a81deb5fc24a4b ~app:* resetchannels -@all +@read"
2) "user app-rw on sanitize-payload #22d71145828b716282c45fb591468ed9a217bf3caf29ef876bdaa0ea60a82a79 ~app:* resetchannels -@all +@read +@write -keys -flushall -flushdb"
3) "user default off sanitize-payload resetchannels -@all"
4) "user valkey-admin on sanitize-payload #a36aef5a11c4073fbe60314fc9df530a9d5f986533594d1f5190742ff9e0e408 ~* &* +@all"

宿主机修改 users.acl，明文 >xxx 替换为 #hash：

user default off reset

user app-rw on #22d71145828b716282c45fb591468ed9a217bf3caf29ef876bdaa0ea60a82a79 ~app:* -@all +@read +@write -KEYS -FLUSHALL -FLUSHDB

user app-ro on #34af85bc909f3d211abcd44cfd8d8ac4b4ab6a2f061e8b7358a81deb5fc24a4b ~app:* -@all +@read

user valkey-admin on #a36aef5a11c4073fbe60314fc9df530a9d5f986533594d1f5190742ff9e0e408 ~* &* +@all

执行 ACL LOAD 热加载：

/data # valkey-cli
127.0.0.1:6379> auth valkey-admin Admin@2026
OK
127.0.0.1:6379> acl load
OK
# 确认生效
127.0.0.1:6379> ACL LIST

后续更新权限

增加用户并保存：

ACL SETUSER wuqy on >wuqy123456 ~easyops* +get +set
ACL LOAD
ACL LIST
ACL SAVE
auth wuqy wuqy123456

三、Valkey Admin

Valkey Admin 是 Valkey 项目推出的开源可观测性与管理工具，提供集群可视化、数据检查与故障排查的统一界面。支持 macOS/Linux 原生桌面应用，也支持 Docker/Kubernetes 容器化 Web 部署。

• 官网：https://valkey-admin.valkey.io/
• GitHub：https://github.com/valkey-io/valkey-admin

主要功能：

• Dashboard 实时监控大盘：WebSocket 实时推送指标（内存、CPU、客户端连接数、缓存命中率、QPS）；完整展示 INFO 全部分类指标；异常告警提示
• Cluster Topology 集群拓扑可视化：图形化展示分片、主节点、副本节点 host:port、角色及在线/离线状态；支持大集群节点搜索过滤
• Key Browser 键浏览器：支持 String / Hash / List / Set / ZSet / Stream / JSON 七种类型；按前缀/通配符搜索、按类型过滤；查看 key 值、TTL、内存占用；UI 直接增删改；key 类型分布饼图
• Send Command 网页命令行：执行任意命令并格式化输出；命令历史记录；自动补全
• Activity 故障排查（部分依赖高版本 Valkey）：Hot Keys 热 key 检测（需 Valkey 8.0+ slot 统计）；Command Logs 聚合命令日志（Valkey 8.1+，标记延迟来源）；Big-Keys 大 key 扫描
• 连接管理：保存多套连接配置（单机/集群），支持 ACL 与密码认证

重要差异：Docker/K8s 部署的 Web 版没有 Hot-Keys、Command-Logs，这两个功能仅桌面客户端拥有。

docker-compose 部署

services:
valkey-admin:
image: valkey/valkey-admin:latest
container_name: valkey-admin
restart: unless-stopped
ports:
- "8080:8080"
environment:
DEPLOYMENT_MODE: Web
# 默认连接地址，也可以不设置，进页面后手动填写
VALKEY_HOST: my-valkey-host.example.com
VALKEY_PORT: 6379
VALKEY_TLS: "true"
VALKEY_AUTH_TYPE: password
VALKEY_USERNAME: myuser
VALKEY_PASSWORD: mypassword
# 自定义配置文件
CONFIG_PATH: /app/custom-config.yml
volumes:
- ./my-config.yml:/app/custom-config.yml:ro

可用环境变量：

启动：

docker compose up -d

访问 http://:8080 添加连接即可使用。