Migrar do Redis para o Valkey no Magento 2 sem derrubar a loja

Descubra em um comando se você já está fora

Comece pela versão exata, não pela que você acha que é:

php bin/magento --version

Compare com a régua da Adobe. Quem está no 2.4.9 já nasceu sem Redis. Nas linhas anteriores, o corte foi por patch: 2.4.5-p16, 2.4.6-p14, 2.4.7-p9 e 2.4.8-p4 são os últimos que ainda listam Redis. Qualquer patch depois desses já exige Valkey.

A tabela de requisitos do sistema lista o Valkey 8.1 para o 2.4.8-p5 e o Valkey 9 para o 2.4.9. Vale conferir a versão que a sua distro instala antes de sair rodando apt install, porque repositório de sistema costuma atrasar.

valkey-server --version
valkey-cli ping

Um detalhe que muda o roteiro: até o 2.4.8, o CLI do Magento ainda usa os flags de Redis. A partir do 2.4.9 é que os flags valkey entram no lugar. Antes de escolher qual usar, pergunte ao próprio binário:

php bin/magento setup:config:set --help | grep valkey

Se não voltar nada, a sua instalação ainda quer os flags --cache-backend-redis-*. Aponte eles para o servidor Valkey e funciona igual — é o mesmo protocolo.

Os três comandos que trocam o backend

Da 2.4.9 para cima, é isto aqui, com a loja em manutenção porque o env.php muda no meio:

php bin/magento setup:config:set --cache-backend=valkey \
  --cache-backend-valkey-server=127.0.0.1 \
  --cache-backend-valkey-port=6379 \
  --cache-backend-valkey-db=0

php bin/magento setup:config:set --page-cache=valkey \
  --page-cache-valkey-server=127.0.0.1 \
  --page-cache-valkey-port=6379 \
  --page-cache-valkey-db=1

php bin/magento setup:config:set --session-save=valkey \
  --session-save-valkey-host=127.0.0.1 \
  --session-save-valkey-port=6379 \
  --session-save-valkey-db=2

A mesma implicância de nome do Redis continua de pé: cache e page cache usam --...-valkey-server, e a sessão usa --session-save-valkey-host. E os números de banco precisam ser diferentes entre si, pela mesma razão de sempre: um cache:flush limpa o banco inteiro.

A senha, quando existe, sai do /etc/valkey/valkey.conf e entra em cada bloco com o seu próprio flag: --cache-backend-valkey-password, --page-cache-valkey-password e --session-save-valkey-password.

O env.php muda de forma no 2.4.9

Essa é a parte que passa batido em migração feita às pressas. Até o 2.4.8, o backend no app/etc/env.php é o caminho completo da classe:

'backend' => 'Magento\Framework\Cache\Backend\Valkey',

No 2.4.9 o Magento passou a usar o Symfony Cache, e o valor virou um apelido curto:

'backend' => 'valkey',

Não é cosmético. A Adobe documenta que o nome simplificado é o que liga o adapter novo, com pipelining automático, invalidação por tag em PSR-6 e serialização com igbinary — a documentação fala em entradas 45% menores e 5 a 10% mais rápidas. Se você copiou o env.php de um servidor 2.4.8 para um 2.4.9, herdou o caminho de classe antigo e perdeu tudo isso sem receber nenhum erro na tela.

Repare também no bloco de sessão: o save vira valkey, mas a chave de dentro continua se chamando redis, por compatibilidade. É feio e é assim mesmo — não tente "corrigir" na mão.

Como conferir que migrou de verdade

Cache é dado descartável, então não existe migração de conteúdo: você sobe o Valkey vazio e o Magento repopula. Sessão é outra história — trocar o destino desloga todo mundo. Faça em horário de movimento baixo e avise o atendimento.

Depois do último comando, três checagens:

• php bin/magento cache:flush e, em seguida, valkey-cli INFO keyspace. Os bancos 0, 1 e 2 têm que aparecer com chave dentro conforme a loja é navegada.
• valkey-cli -n 2 DBSIZE depois de você fazer login no admin: se continuar zerado, a sessão ainda está em outro lugar.
• grep -c backend app/etc/env.php e leia o arquivo. É onde mora o erro do parágrafo anterior.

Só depois disso desligue o serviço antigo. Manter o Redis rodando por uma semana não custa nada e evita aquela madrugada em que você descobre que um flag foi digitado errado. E se a loja estiver com o page cache no Varnish, o banco 1 vai ficar quase vazio: é esperado, o Magento continua usando o cache type page_cache mesmo assim. Para o resto da conta de tempo de resposta, o guia de performance e Core Web Vitals cobre o que vem depois do cache.