Valkey 部署方式、Redis 兼容边界与提效工具手册

高谷深陵大约 18 分钟约 5389 字

Valkey 部署、兼容边界与迁移验证参考图Valkey 从 9.1 官方镜像、valkey-cli、ACL、持久化、Redis OSS 7.2 兼容基线、Redis CE 7.4+ 数据文件边界、Sentinel、Cluster 到团队治理的工具落地链路。高清原图

从一次“换镜像就能迁”的失败开始

一个常见现场是：本地把 Redis 镜像名改成 Valkey，PING 返回 PONG，团队便认为迁移完成；到了共享环境，应用却因 ACL、脚本、Cluster 路由或数据文件格式失败。另一个更危险的现场是为了联调把 6379 发布到局域网，容器镜像默认关闭 protected mode，又没有 ACL，任何能到达端口的人都可以读写缓存。

Valkey 延续了 Redis OSS 的大量协议、配置和命令心智，但不能被理解成“任意 Redis 换个镜像”。它与 Redis OSS 7.2 及更早开源版本保持兼容；Redis Community Edition 7.4 及之后产生的数据文件不能直接交给 Valkey 读取。客户端连通、命令兼容、持久化恢复和架构迁移是四个不同的验收层次，PONG 只完成了第一层。

下面的实验使用 Docker Engine 或 Docker Desktop、Docker Compose 和一个仅存放测试数据的目录。valkey-cli 可以来自本机，也可以直接在容器内运行。先确认 6379 没有被其他 Redis 或 Valkey 占用；若已占用，就在 .env 中改宿主机端口，绝不能临时借用共享或生产地址。生产 endpoint、真实密码、客户 key、RDB 和 AOF 文件也不要进入仓库或截图。

先确认本机状态：

docker version
docker compose version
docker ps --format "table {{.Names}}\t{{.Ports}}"

Windows 查端口：

netstat -ano | findstr 6379

Linux / macOS 查端口：

lsof -i :6379

如果端口已经被占用，不要为了省事把应用临时连到共享 Redis 或生产 Redis。先换本机端口，或者确认旧容器可以停掉。

这组命令只读本机容器状态。Windows 原生环境可用 netstat，Linux、macOS 或 WSL 可用 lsof；Windows 开发机的服务端采用 Docker 或 WSL。

把 Valkey 跑起来

示例使用 valkey/valkey:9.1.0，固定补丁版本可以避免 latest 漂移。Valkey 采用 BSD-3-Clause 许可；镜像及其基础层还可能包含其他许可，交付时应按组织的软件准入流程核对。

Valkey 的开发入口可以分四类：

方式	适合场景	注意点
本机包管理器	需要本机 `valkey-cli`、学习命令、调试单进程	不同发行版版本不同，要看 `valkey-server --version`
Docker 单容器	临时验证命令、客户端、迁移脚本	不适合作为团队长期模板
Docker Compose	项目级联调、新人一键启动、CI smoke	推荐作为团队默认开发入口
共享开发实例	多服务联调、低配置开发机、稳定测试数据	必须有 owner、ACL、prefix、清理窗口和误连生产防护

本机安装

macOS：

brew install valkey
brew services start valkey
brew services info valkey

Debian / Ubuntu 系：

sudo apt update
sudo apt install valkey

如果只是为了 CLI，不一定要启动本机服务。先验证：

valkey-cli --version
valkey-cli -h 127.0.0.1 -p 6379 PING

Windows 开发机建议走 WSL 或 Docker，不把 Windows 原生安装写成团队默认。

Docker 单容器

个人快速验证：

docker run --rm --name valkey-smoke -p 127.0.0.1:6379:6379 valkey/valkey:9.1.0

另开终端验证：

docker exec -it valkey-smoke valkey-cli PING
docker exec -it valkey-smoke valkey-cli INFO server

这只能说明进程可用。它没有 ACL、固定配置、volume、key prefix、清理脚本和团队验收，不要把它复制成项目模板。

主流部署方式

方式	架构组成	适用场景	核心风险
单机单实例	一个 Valkey 进程，一个数据目录	本地开发、CI、低价值缓存	单点故障、内存上限、持久化未演练
单机多实例	一台机器多个 Valkey 进程和端口	测试环境、多项目轻量隔离	共享硬件故障域，端口和目录容易混乱
主从复制	一个 primary 加多个 replica	读扩展、热备、备份卸载	默认异步复制，副本可能读旧值
Sentinel	主从加多个 Sentinel	非分片高可用、自动发现主库	不做分片，客户端必须支持 Sentinel
Cluster	多个 primary 分 slot，配 replica	水平扩容、数据量超过单机	多 key、脚本、事务、数据库数量、客户端路由和热点 slot 都会暴露设计问题
云托管	云厂商 Valkey / Redis 兼容服务	中小团队、少运维	命令禁用、版本、备份、TLS、费用和兼容性要逐项复核

做架构选择时可以沿责任拆分：单机提供低延迟，复制提供副本，Sentinel 提供非分片高可用，Cluster 提供分片扩容，云托管降低日常运维负担。进入生产后，还要为选定形态单独建立部署、监控、故障切换和容量扩容 runbook。

推荐项目目录：

your-project/
  compose.yaml
  .env.example
  cache/
    valkey/
      valkey.conf
      users.acl
      verify/
        verify.valkey
  docs/
    dependency-setup.md
  scripts/
    valkey-scan.sh
    valkey-reset.sh

`.env.example`

VALKEY_IMAGE=valkey/valkey:9.1.0
VALKEY_HOST_PORT=6379
VALKEY_KEY_PREFIX=dev:your-project:
VALKEY_DATABASE=0
VALKEY_MAXMEMORY=256mb
VALKEY_MAXMEMORY_POLICY=noeviction

VALKEY_APP_USER=app_dev
VALKEY_APP_PASSWORD=YOUR_STRONG_VALKEY_APP_PASSWORD
VALKEY_READONLY_USER=cache_readonly
VALKEY_READONLY_PASSWORD=YOUR_STRONG_VALKEY_READONLY_PASSWORD
VALKEY_OPS_USER=cache_ops
VALKEY_OPS_PASSWORD=YOUR_STRONG_VALKEY_OPS_PASSWORD

真实 .env 不提交。VALKEY_KEY_PREFIX 至少包含环境和项目，例如 dev:your-project:，共享实例再加模块或团队标识。

`compose.yaml`

services:
  valkey:
    image: ${VALKEY_IMAGE:-valkey/valkey:9.1.0}
    container_name: your-project-valkey
    ports:
      - "127.0.0.1:${VALKEY_HOST_PORT:-6379}:6379"
    environment:
      VALKEY_APP_USER: ${VALKEY_APP_USER:-app_dev}
      VALKEY_APP_PASSWORD: ${VALKEY_APP_PASSWORD}
      VALKEY_READONLY_USER: ${VALKEY_READONLY_USER:-cache_readonly}
      VALKEY_READONLY_PASSWORD: ${VALKEY_READONLY_PASSWORD}
      VALKEY_OPS_USER: ${VALKEY_OPS_USER:-cache_ops}
      VALKEY_OPS_PASSWORD: ${VALKEY_OPS_PASSWORD}
      VALKEY_KEY_PREFIX: ${VALKEY_KEY_PREFIX:-dev:your-project:}
      VALKEY_MAXMEMORY: ${VALKEY_MAXMEMORY:-256mb}
      VALKEY_MAXMEMORY_POLICY: ${VALKEY_MAXMEMORY_POLICY:-noeviction}
    command:
      - sh
      - -lc
      - |
        set -eu
        : "$${VALKEY_APP_PASSWORD:?VALKEY_APP_PASSWORD is required}"
        : "$${VALKEY_READONLY_PASSWORD:?VALKEY_READONLY_PASSWORD is required}"
        : "$${VALKEY_OPS_PASSWORD:?VALKEY_OPS_PASSWORD is required}"
        : "$${VALKEY_MAXMEMORY:?VALKEY_MAXMEMORY is required}"
        : "$${VALKEY_MAXMEMORY_POLICY:?VALKEY_MAXMEMORY_POLICY is required}"
        cat > /tmp/users.acl <<EOF
        user default off
        user $${VALKEY_APP_USER} on >$${VALKEY_APP_PASSWORD} ~$${VALKEY_KEY_PREFIX}* +@read +@write +@connection +ping -@dangerous +acl|whoami
        user $${VALKEY_READONLY_USER} on >$${VALKEY_READONLY_PASSWORD} ~$${VALKEY_KEY_PREFIX}* +@read +@connection +ping -@dangerous +acl|whoami
        user $${VALKEY_OPS_USER} on >$${VALKEY_OPS_PASSWORD} ~$${VALKEY_KEY_PREFIX}* +@read +@connection +ping -@dangerous +acl|whoami +acl|list +config|get +info +slowlog|get +client|list
        EOF
        exec valkey-server /usr/local/etc/valkey/valkey.conf \
          --aclfile /tmp/users.acl \
          --maxmemory "$${VALKEY_MAXMEMORY}" \
          --maxmemory-policy "$${VALKEY_MAXMEMORY_POLICY}"
    volumes:
      - valkey-data:/data
      - ./cache/valkey/valkey.conf:/usr/local/etc/valkey/valkey.conf:ro
      - ./cache/valkey/verify:/verify:ro
    healthcheck:
      test: ["CMD-SHELL", "VALKEYCLI_AUTH=\"$${VALKEY_APP_PASSWORD}\" valkey-cli --user \"$${VALKEY_APP_USER}\" PING | grep PONG"]
      interval: 10s
      timeout: 5s
      retries: 12
    restart: unless-stopped

volumes:
  valkey-data:
    name: your-project-valkey-data

要点：

宿主机只绑定 127.0.0.1。default 用户关闭。app、readonly、ops 三类账号分开。

日常账号禁用 @dangerous。.env 中的内存上限和淘汰策略通过启动参数覆盖配置文件，改值后重建容器才会生效。使用固定镜像 tag。

配置文件和验证脚本进仓库，真实密码不进仓库。

`cache/valkey/valkey.conf`

bind 0.0.0.0
protected-mode no
port 6379
dir /data

appendonly yes
appendfilename "appendonly.aof"
save 60 1

databases 16
maxmemory 256mb
maxmemory-policy noeviction

loglevel notice

为什么容器内 protected-mode no？

Compose 网络里的应用容器需要访问 Valkey。宿主机端口只绑定到 127.0.0.1。ACL 已经关闭默认用户并要求认证。

共享开发实例不要直接复制这份本地配置。共享环境需要防火墙、内网范围、TLS、审计、清理窗口和 owner。

启动：

docker compose up -d valkey
docker compose ps valkey
docker compose logs --tail=80 valkey

验证版本和身份：

docker compose exec valkey sh -lc '
  export VALKEYCLI_AUTH="$VALKEY_APP_PASSWORD"
  valkey-cli --user "$VALKEY_APP_USER" PING
  valkey-cli --user "$VALKEY_APP_USER" ACL WHOAMI
  valkey-cli --user "$VALKEY_APP_USER" INFO server | sed -n "1,20p"
'

最小写读清理：

docker compose exec valkey sh -lc '
  export VALKEYCLI_AUTH="$VALKEY_APP_PASSWORD"
  valkey-cli --user "$VALKEY_APP_USER" SET "${VALKEY_KEY_PREFIX}smoke" ok EX 60
  valkey-cli --user "$VALKEY_APP_USER" GET "${VALKEY_KEY_PREFIX}smoke"
  valkey-cli --user "$VALKEY_APP_USER" TTL "${VALKEY_KEY_PREFIX}smoke"
  valkey-cli --user "$VALKEY_APP_USER" DEL "${VALKEY_KEY_PREFIX}smoke"
'

反向验证危险命令被拒绝：

docker compose exec valkey sh -lc '
  export VALKEYCLI_AUTH="$VALKEY_APP_PASSWORD"
  valkey-cli --user "$VALKEY_APP_USER" FLUSHALL
'

预期是 NOPERM。如果能执行，说明 ACL 失效，不能进入共享环境。

验证持久化入口：

docker compose exec valkey sh -lc '
  export VALKEYCLI_AUTH="$VALKEY_OPS_PASSWORD"
  valkey-cli --user "$VALKEY_OPS_USER" CONFIG GET dir
  valkey-cli --user "$VALKEY_OPS_USER" CONFIG GET appendonly
  valkey-cli --user "$VALKEY_OPS_USER" INFO persistence | sed -n "1,40p"
  ls -lah /data
'

验证 .env 中的容量配置确实进入了运行时，而不是只停留在模板里：

docker compose exec valkey sh -lc '
  export VALKEYCLI_AUTH="$VALKEY_OPS_PASSWORD"
  valkey-cli --user "$VALKEY_OPS_USER" CONFIG GET maxmemory maxmemory-policy
'

maxmemory 返回字节数，256mb 对应 268435456；策略应返回 noeviction。修改 .env 后要执行 docker compose up -d --force-recreate valkey 再检查。若输出仍是旧值，应检查 Compose 展开结果和容器启动命令，而不是根据 .env 猜测进程配置。

验证 Redis 兼容识别：

docker compose exec valkey sh -lc '
  export VALKEYCLI_AUTH="$VALKEY_OPS_PASSWORD"
  valkey-cli --user "$VALKEY_OPS_USER" INFO server | grep -E "server_name|valkey_version|redis_version"
'

Valkey 为兼容可能保留 redis_version 口径，实际识别应看 server_name 和 valkey_version。

从命令响应追到内存与磁盘

SET key value EX 60 成功后，value 进入内存 keyspace，过期时间作为独立元数据参与到期判断。读取碰到已过期 key 时会把它当成不存在；后台的主动过期周期也会持续抽样清理，因此“TTL 到零”和“内存字节立刻下降”不是同一个时刻。达到 maxmemory 后，maxmemory-policy 决定分支：当前配置为 noeviction，新写入会报错，而不是悄悄删除旧 key。

持久化走另一条链。RDB 保存某一时点的内存快照，AOF 记录能够重建状态的写操作；appendonly yes 并不等于每次响应前都已落到稳定介质，实际丢失窗口由 fsync 策略、操作系统和存储共同决定。复制同样默认是异步链路，primary 已返回成功不代表 replica 已经应用该写入。

用一个专用 key 验证当前 Compose 的重启恢复，不要只检查 /data 下“有文件”：

docker compose exec valkey sh -lc '
  export VALKEYCLI_AUTH="$VALKEY_APP_PASSWORD"
  valkey-cli --user "$VALKEY_APP_USER" SET "${VALKEY_KEY_PREFIX}restart-proof" before-restart
'

docker compose exec valkey sh -lc '
  export VALKEYCLI_AUTH="$VALKEY_OPS_PASSWORD"
  valkey-cli --user "$VALKEY_OPS_USER" INFO persistence | grep -E "aof_enabled|aof_pending_bio_fsync|aof_last_write_status"
'

docker compose restart valkey

docker compose exec valkey sh -lc '
  export VALKEYCLI_AUTH="$VALKEY_APP_PASSWORD"
  valkey-cli --user "$VALKEY_APP_USER" GET "${VALKEY_KEY_PREFIX}restart-proof"
  valkey-cli --user "$VALKEY_APP_USER" DEL "${VALKEY_KEY_PREFIX}restart-proof"
'

健康路径中，持久化状态显示 AOF 已启用且最近写入状态正常，重启后返回 before-restart。若文件存在但 key 消失，应先查挂载目录、启动参数、AOF 加载日志和最近写入状态；这类失败证明“开启 AOF”与“完成可恢复性验收”之间还有加载和校验两步。

Java / Spring Boot

大多数 Java 项目仍会通过 Redis 协议客户端连接 Valkey。示例：

spring.data.redis.host=localhost
spring.data.redis.port=6379
spring.data.redis.username=app_dev
spring.data.redis.password=YOUR_STRONG_VALKEY_APP_PASSWORD
spring.data.redis.database=0
spring.data.redis.timeout=2s
spring.data.redis.client-type=lettuce
spring.data.redis.lettuce.pool.max-active=16
spring.data.redis.lettuce.pool.max-idle=8

团队必须另外写清：

当前连接的是 Valkey，不是 Redis。客户端兼容基线按 Redis OSS 7.2 命令集验证。database 不是租户隔离方案。Valkey 9.0 起 Cluster 可通过 cluster-databases 启用多个 DB，但默认值仍是 1；使用非 0 DB 前要同时验证服务端配置、ACL 数据库权限和客户端重连后的 SELECT。

RedisTemplate 序列化格式、key prefix、TTL 默认值和错误回退策略。连接池、超时、重试和熔断，不让缓存慢故障拖垮主链路。

Node / Python / Go

不要凭名称指定唯一客户端。接入评审看这些问题：

维度	检查点
协议	是否支持 RESP2 / RESP3，是否按 Redis OSS 7.2 兼容基线测试
Cluster	是否处理 `MOVED` / `ASK` 和拓扑刷新
Sentinel	是否支持 Sentinel master name，而不是写死主库地址
TLS	是否支持证书、SNI、校验和连接池
ACL	是否支持 username / password
超时	连接、读写、命令和重试策略是否可控
序列化	跨语言 value 是否可读，版本升级是否兼容

迁移验证

从 Redis OSS 7.2 及更早版本迁到 Valkey，至少要做：

记录源 Redis 版本、许可口径、INFO server、INFO keyspace。确认不是 Redis CE 7.4+ 数据文件。只在测试实例上演练 RDB / AOF 迁移。

恢复到 Valkey 后比对 key 数量、样本 key、TTL、数据类型和业务自检。用应用连接 Valkey 跑 smoke test。回滚路径写清：源实例是否保留，DNS / 配置如何切回，写入窗口如何控制。

迁移不是“换镜像重启”。只要涉及真实数据，就要把迁移当成变更。

启动和停止：

docker compose up -d valkey
docker compose logs -f valkey
docker compose stop valkey
docker compose down

查看 key：

docker compose exec valkey sh -lc '
  export VALKEYCLI_AUTH="$VALKEY_OPS_PASSWORD"
  valkey-cli --user "$VALKEY_OPS_USER" --scan --pattern "${VALKEY_KEY_PREFIX}*" | head -50
'

不要用 KEYS * 做共享环境排查。

查看内存、持久化和慢命令：

docker compose exec valkey sh -lc '
  export VALKEYCLI_AUTH="$VALKEY_OPS_PASSWORD"
  valkey-cli --user "$VALKEY_OPS_USER" INFO memory | sed -n "1,40p"
  valkey-cli --user "$VALKEY_OPS_USER" INFO persistence | sed -n "1,40p"
  valkey-cli --user "$VALKEY_OPS_USER" SLOWLOG GET 10
'

本地重置：

docker compose down
docker volume rm your-project-valkey-data
docker compose up -d valkey

共享环境禁止这样重置。共享环境只允许按 prefix dry run 后清理。

`NOAUTH`、`WRONGPASS` 或 `NOPERM`

现象：

NOAUTH Authentication required.
WRONGPASS invalid username-password pair
NOPERM this user has no permissions

判断：

docker compose exec valkey sh -lc '
  export VALKEYCLI_AUTH="$VALKEY_APP_PASSWORD"
  valkey-cli --user "$VALKEY_APP_USER" ACL WHOAMI
'

处理：

确认 username、password 和 .env 没混 Redis / Valkey。确认 ACL 文件被加载。确认 key 是否落在 VALKEY_KEY_PREFIX 下。

不要为了省事打开 default 用户。

protected mode 和端口暴露

现象：本机能连，其他容器能连，但局域网也能连，或者相反，应用容器连不上。

判断：

docker port your-project-valkey
docker compose exec valkey sh -lc '
  export VALKEYCLI_AUTH="$VALKEY_OPS_PASSWORD"
  valkey-cli --user "$VALKEY_OPS_USER" CONFIG GET bind protected-mode port
'

处理：

本机开发端口绑定 127.0.0.1。Compose 内应用用 service name valkey，不要用 localhost。共享环境用防火墙、TLS、ACL 和只读账号。

Redis 客户端兼容假设过大

现象：本地 PING 通过，应用启动后 metadata、脚本、Cluster、异常码或监控指标不一致。

判断：

客户端版本是否只按 Redis 8 能力测试。是否使用 Redis Stack / Redis 8 新命令或模块。是否依赖 INFO 中的 redis_version 判断服务端。

处理：

以 Redis OSS 7.2 兼容基线写 smoke test。用 INFO server 识别 server_name 和 valkey_version。对脚本、pipeline、多 key、事务和 Cluster 单独补测试。

Redis CE 7.4+ 数据文件不能直接迁

现象：把 RDB / AOF 拷进 Valkey 后无法加载，或者 key 数量不一致。

判断：

redis-cli INFO server
redis-cli CONFIG GET dir dbfilename appendonly appenddirname

处理：

先确认源 Redis 版本。Redis OSS 7.2 及更早版本按官方迁移文档做物理迁移或复制迁移。Redis CE 7.4+ 不能把数据文件直接当 Valkey 可读输入。

复杂迁移要进入受控变更，先在临时实例恢复并完成数据与业务校验。

Cluster 返回 `MOVED` 或非 0 DB 不可用

现象：

MOVED 12182 <node>:6379
ERR DB index is out of range

MOVED 说明客户端访问了不负责该 slot 的节点；非 0 DB 报错通常说明 Cluster 仍使用默认的 cluster-databases 1。Valkey 9.0 之前的 Cluster 只能使用 DB 0，Valkey 9.0 及之后可以显式增加数据库数量，但这会引入客户端支持、ACL 数据库权限和跨 DB 命令约束，不能把逻辑 DB 当成多租户隔离。

处理：

客户端启用 Cluster 模式。多 key 操作用 hash tag。需要非 0 DB 时，先检查 CONFIG GET cluster-databases，并在测试集群验证客户端连接、重连和故障切换。

新项目不要依赖 DB 1 / DB 2 做租户隔离；共享环境仍用 ACL 数据库权限、key pattern 和 prefix 建立边界。

Valkey 本身不是 HTTP 工具，代理主要影响镜像拉取、依赖下载和云控制台访问。

检查镜像拉取：

docker pull valkey/valkey:9.1.0

Java 依赖下载：

mvn -q dependency:get -Dartifact=org.springframework.boot:spring-boot-starter-data-redis

凭证规则：

.env 不提交，.env.example 只写占位符。CLI 优先用 VALKEYCLI_AUTH，避免把密码放到命令历史。GUI 截图隐藏 host、账号、key、value 和连接名。

Redis / Valkey 共享密码分开，不复用生产密码。CI Secret、共享开发实例密码和个人本机密码分开轮换。发现泄漏后轮换，而不是只删 Git 里的那一行。

权限规则：

账号	用途	权限边界
`default`	兼容旧客户端	开发模板关闭
`app_dev`	应用本地运行	只访问本项目 prefix，读写，禁危险命令
`cache_readonly`	排障查看	只读本项目 prefix
`cache_ops`	状态查看	`INFO`、`SLOWLOG GET`、`CONFIG GET`、`CLIENT LIST`，不执行清空和删除

团队落地不是把 valkey/valkey 写进 Compose 就结束。至少固定这些资产：

compose.yaml
.env.example
cache/valkey/valkey.conf
cache/valkey/verify/verify.valkey
docs/dependency-setup.md
scripts/valkey-scan.sh
scripts/valkey-reset.sh

共享实例规则：

必须有 owner。必须记录版本、镜像 tag、镜像 digest 和许可审查结果。必须区分 Redis、Valkey、Memcached，不让连接名写成“cache-dev”这种模糊词。

app、readonly、ops 账号分开。FLUSHALL、FLUSHDB、KEYS 对日常账号禁用。清理脚本先 dry run，输出 host、port、user、prefix 和 key 数量。

迁移 Redis 时记录源版本、目标版本、数据文件路径、回滚路径和验收结果。生产连接不得进入本地 .env、截图、示例代码和 GUI 默认连接。

Valkey 不是 Redis 8 无风险替代

现象：团队把 Redis 8 模板改成 Valkey 镜像，应用启动后模块命令、监控字段或持久化文件出问题。

判断：

源 Redis 是否是 OSS 7.2 及更早版本。是否用了 Redis CE 7.4+ 数据文件。是否用了 Redis Stack / Redis 8 新能力。

客户端是否按 Valkey 目标版本跑过 smoke test。

结论：Valkey 兼容基线要写成 Redis OSS 7.2，不写成 Redis 全版本。

`redis_version` 会迷惑监控和自动识别

现象：监控或应用通过 redis_version 判断服务端，结果把 Valkey 当 Redis。

判断：

valkey-cli INFO server | grep -E "server_name|valkey_version|redis_version"

治理：

监控识别优先看 server_name 和 valkey_version。连接池、指标、告警名称显式写 Valkey。文档里不要把 Valkey 实例继续叫 Redis。

Redis CE 7.4+ 数据文件会卡住迁移

现象：迁移时才发现 RDB / AOF 不兼容，窗口被迫延长。

排查路径：

迁移前读取源 INFO server。读取 CONFIG GET dir dbfilename appendonly appenddirname。先在临时 Valkey 实例恢复。

比对 INFO keyspace、样本 key、TTL、数据类型和业务自检。

取舍：不能物理迁移时，改用应用级回填、双写、旁路复制或专用迁移工具，并重新评估停机窗口。

ACL 和 prefix 不是装饰

现象：共享实例里不同项目 key 混在一起，清理脚本删到别人数据。

判断：

valkey-cli ACL LIST
valkey-cli --scan --pattern 'dev:your-project:*' | head -50

治理：

每个项目独立 prefix。ACL key pattern 限定到 prefix。清理脚本只能按 prefix。

个人实验 key 带环境和 owner，不带真实邮箱。

Cluster 会提前暴露 key 与数据库设计问题

现象：单机能跑，上 Cluster 后多 key 命令、Lua、事务失败，或者非 0 DB 因 cluster-databases、ACL 或客户端能力不一致而不可用。

判断：

valkey-cli -c CLUSTER KEYSLOT '{order:1001}:base'
valkey-cli -c CLUSTER KEYSLOT '{order:1001}:items'

治理：

新项目 key 设计默认考虑 hash tag。CI 增加 Cluster 兼容性用例。使用非 0 DB 时显式验证 cluster-databases、ACL 数据库权限和客户端重连；不把 DB index 当环境隔离。

扩容前做 big key 和 hot key 巡检。

只开启持久化不等于具备恢复能力

现象：AOF / RDB 文件存在，但没人知道恢复到哪里、恢复多久、恢复后如何校验。

判断：

valkey-cli INFO persistence
valkey-cli CONFIG GET dir dbfilename appendonly appenddirname

治理：

备份恢复以恢复演练为准。临时实例恢复后跑业务 smoke。记录 RPO / RTO 和 owner。

恢复脚本默认不能连生产 endpoint。

GUI 和连接名会制造误连生产

现象：代码里没有生产密码，但 GUI 里保存了生产写账号。

治理：

生产连接只发只读账号给普通排障。连接名必须包含环境和权限。截图前脱敏 host、key、value 和账号。

批量删除走脚本，不走 GUI。

安装后：

镜像 tag 与 digest 已固定，不使用 latest。valkey-cli PING 返回 PONG。INFO server 可看到 Valkey 真实版本。

宿主机端口只绑定 127.0.0.1。volume 名称明确，知道个人本机如何重置。

接入前：

项目文档写明这是 Valkey，不是 Redis。Redis OSS 7.2 兼容基线已进入迁移与集成测试。VALKEY_KEY_PREFIX 包含环境和项目。

app、readonly、ops 账号分开。FLUSHALL、FLUSHDB、KEYS 对日常账号返回 NOPERM。客户端支持 username / password、超时、连接池和必要的 Sentinel / Cluster 模式。

准备上 Cluster 的项目没有依赖非 0 DB。

迁移前：

源 Redis 版本已确认，不是 Redis CE 7.4+ 数据文件直接迁。迁移在临时实例演练过。key 数量、样本 key、TTL、数据类型和业务 smoke 已比对。

回滚路径、写入窗口和 owner 已记录。

共享实例前：

owner 已明确。防火墙、TLS、ACL 和清理窗口已确认。GUI 生产连接默认只读。

清理脚本先 dry run，只按 prefix 清理。RDB / AOF / 云快照有恢复演练计划。

Valkey 的价值在于给团队一个开放、可验证、Redis OSS 兼容基线清晰的缓存和数据结构服务。把兼容边界、迁移路径和治理规则写实，它才是工具效率；把它写成“Redis 免费替代”，后面一定会在迁移和生产联调里补课。