Como usar Redis como cache de objetos no WordPress

O que um cache de objetos Redis faz pelo WordPress

Um cache de objetos Redis para WordPress armazena em memória os resultados das consultas à base de dados. Assim, o pedido seguinte lê esses resultados do Redis em vez de consultar novamente o MySQL. O WordPress já inclui um cache de objetos no core, WP_Object_Cache, mas este fica na memória do PHP e é eliminado quando o pedido termina. Um ficheiro drop-in substitui-o por um cache que comunica com o Redis. Assim, o cache mantém-se entre pedidos.

O cache de objetos não é cache de páginas. Essa diferença determina se vale a pena seguir este guia. Um cache de páginas armazena o HTML final de um URL e volta a servi-lo sem executar o PHP. É mais rápido do que qualquer operação que o Redis possa fazer e funciona para visitantes que não iniciaram sessão. Quando alguém inicia sessão, adiciona um artigo ao carrinho ou abre o painel de administração, o cache de páginas deixa de ser utilizado e o WordPress executa o pedido completo: bootstrap, plugins e consultas. Um cache de objetos torna esse pedido mais barato. É a ferramenta para o tráfego que um cache de páginas não consegue tratar: sessões autenticadas, carrinhos, checkout e wp-admin. Numa loja WooCommerce, esse é o maior volume de tráfego dispendioso.

Os dois caches funcionam em conjunto e, num site movimentado, ambos são necessários. Identifique claramente o problema que pretende resolver. Um site institucional com leitores anónimos obtém quase todo o seu desempenho de um cache de páginas. Adicionar Redis a esse site altera muito pouco.

Há uma limitação importante antes de começar. Um cache de objetos não torna rápida uma consulta lenta. Remove a repetição de uma consulta que já foi executada. O primeiro pedido depois de uma falha de cache paga o custo total. Por isso, um plugin que execute uma consulta sem índice continuará a executá-la uma vez durante cada período de vida do cache.

O que precisa primeiro

• Uma VPS Linux com shell e sudo. Não é necessário um painel de controlo.
• WordPress servido por PHP-FPM, por exemplo, numa stack LAMP no Ubuntu 24.04.
• WP-CLI no servidor. Cada passo também tem uma alternativa no painel de administração, mas a versão para shell é mais rápida.
• Redis na mesma máquina que o PHP. A latência é o objetivo principal, e um salto de rede anula essa vantagem.

Os comandos abaixo destinam-se ao Ubuntu 24.04 com PHP 8.3 e o utilizador web www-data. Ajuste a versão do PHP e o utilizador ao seu servidor. Execute os comandos wp a partir do diretório do WordPress, que contém wp-config.php.

Instalar o Redis e a extensão PHP

sudo apt update
sudo apt install -y redis-server php-redis
sudo systemctl enable --now redis-server
redis-cli ping

redis-cli ping deve devolver PONG. Se apresentar Could not connect to Redis at 127.0.0.1:6379: Connection refused, o servidor não está em execução. Leia systemctl status redis-server antes de prosseguir.

php-redis é o PhpRedis, a extensão C do PECL. É mais rápida do que o Predis, que é escrito apenas em PHP, e o plugin utiliza-a automaticamente quando está disponível. O PHP-FPM carrega as extensões no arranque. Por isso, uma extensão nova só fica disponível depois de reiniciar o pool.

sudo systemctl restart php8.3-fpm
php -m | grep redis

Tenha cuidado com essa última verificação: php -m apresenta os módulos do PHP da linha de comandos, e o FPM pode carregar um conjunto diferente. A verificação relevante é a dos diagnósticos do próprio plugin, mais abaixo.

Em agosto de 2026, o Ubuntu 24.04 disponibiliza o Redis 7.0.15, que é adequado para uma cache de objetos. Se preferir uma versão atual, o Redis disponibiliza o seu próprio repositório APT.

sudo apt install -y lsb-release curl gpg
curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
sudo chmod 644 /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list
sudo apt update
sudo apt install -y redis

Se a sua distribuição disponibilizar o Valkey, o fork iniciado depois da alteração da licença em 2024, este utiliza o mesmo protocolo e tudo o que se segue aplica-se sem alterações.

Vincule o Redis para impedir qualquer acesso externo

O Redis não tem palavra-passe por predefinição. Qualquer processo que consiga abrir uma ligação à porta 6379 pode ler todos os valores em cache e executar FLUSHALL. As instâncias expostas à Internet são encontradas por scanners em poucas horas, por isso a configuração de rede vem antes do ajuste de desempenho.

Abra /etc/redis/redis.conf e confirme estas linhas:

bind 127.0.0.1 -::1
protected-mode yes

Depois, verifique o que está realmente a escutar, porque o ficheiro de configuração é apenas uma declaração e ss é a evidência.

sudo ss -lntp | grep 6379

127.0.0.1:6379 é o resultado pretendido. 0.0.0.0:6379 significa que o Redis está a responder na interface pública: corrija a linha bind e reinicie o serviço.

Quando o PHP e o Redis estão no mesmo servidor, um socket Unix é melhor do que TCP via loopback. Não existe uma pilha TCP no percurso, e o acesso é controlado pelas permissões do ficheiro, em vez de depender de uma regra de firewall que pode ser alterada mais tarde.

unixsocket /run/redis/redis-server.sock
unixsocketperm 770

O socket pertence ao utilizador e grupo redis, por isso o utilizador web tem de ser adicionado a esse grupo.

sudo systemctl restart redis-server
sudo usermod -aG redis www-data
sudo systemctl restart php8.3-fpm
redis-cli -s /run/redis/redis-server.sock ping

Esse comando também tem de apresentar PONG. Could not connect to Redis at /run/redis/redis-server.sock: Permission denied significa que o grupo não foi aplicado. Verifique id www-data e lembre-se de que um processo PHP-FPM em execução mantém os grupos que tinha no arranque, razão pela qual o reinício está incluído na lista. Mantenha o TCP ativado até confirmar que o socket funciona; caso contrário, um erro de escrita pode eliminar ambos os caminhos de acesso ao mesmo tempo.

Que quantidade de memória o Redis deve receber?

Calcule o valor com base no seu próprio servidor. O Redis sem maxmemory cresce até o kernel ficar sem memória e o OOM killer terminar um processo, normalmente o maior. Num servidor WordPress, esse processo costuma ser o MySQL. journalctl -k | grep -i "out of memory" mostra esse encerramento depois de ocorrer, mas nessa altura o site já está indisponível.

Comece pela RAM total e subtraia os consumos conhecidos. O MySQL ou MariaDB reserva innodb_buffer_pool_size, além dos buffers por ligação. O PHP-FPM consome pm.max_children multiplicado pelo tamanho residente real de um worker. Num site com muitos plugins, esse valor costuma ficar entre 64 MB e 128 MB. O kernel e o servidor Web precisam de algumas centenas de megabytes. O que sobra é o seu limite máximo, e o Redis recebe uma parte dele.

Agora faça medições em vez de adivinhar. Depois de um dia com tráfego real:

redis-cli info memory | grep -E 'used_memory_human|maxmemory_human|maxmemory_policy'
redis-cli dbsize

Se used_memory_human ficar muito abaixo do seu limite, reduza o limite e devolva a RAM ao MySQL, que a utilizará melhor. Se atingir o limite e evicted_keys aumentar durante todo o dia, aumente-o. Defina o valor em /etc/redis/redis.conf.

maxmemory 256mb
maxmemory-policy allkeys-lru

redis-cli config set maxmemory 256mb aplica-se imediatamente e é perdido no próximo reinício. É a mesma armadilha que um sysctl -w isolado. Edite o ficheiro, execute sudo systemctl restart redis-server e leia o valor novamente. Também é útil ter uma segunda barreira: um limite MemoryMax na unidade systemd impede que um Redis mal configurado derrube o servidor. Defina-o acima de maxmemory, nunca com o mesmo valor, porque um limite de cgroup termina o processo em vez de expulsar uma chave. Se o Redis for executado num contentor ao lado do WordPress, o mesmo valor deve estar nos limites de memória do seu ficheiro Compose, e o mesmo raciocínio orienta a escolha entre executar a base de dados no Docker ou no host.

Escolha a política de expulsão de forma deliberada

Uma instância Redis nova usa noeviction por predefinição. Verifique a sua:

redis-cli config get maxmemory-policy

Com noeviction, uma instância cheia deixa de aceitar escritas e responde com:

(error) OOM command not allowed when used memory > 'maxmemory'.

Essa única linha representa o pior modo de falha deste guia, porque o site não fica indisponível. Fica mais lento. Todas as escritas na cache falham. O WordPress volta à base de dados para obter o valor, tenta armazená-lo novamente no pedido seguinte e falha outra vez. O site passa a executar todo o trabalho original na base de dados mais uma ida ao Redis para cada chave. Nada no painel de administração do WordPress indica que isto está a acontecer. A cadeia aparece no log de erros do PHP. Por isso, procure OOM command not allowed com grep quando um site ficar mais lento depois de adicionar uma cache.

allkeys-lru é a predefinição correta neste caso. O Redis elimina a chave usada há mais tempo quando a memória fica limitada. Isto corresponde exatamente ao que uma cache de objetos precisa, porque cada valor é uma cópia de dados que continuam a existir no MySQL. Perder uma chave custa uma consulta. Recusar uma escrita custa todas as consultas, em todos os pedidos, até alguém detetar o problema.

Evite as políticas volatile-* para este fim. Elas consideram apenas chaves que têm uma expiração. O Redis documenta que se comportam como noeviction quando nenhuma chave tem expiração. O WordPress armazena a maioria das entradas da cache de objetos sem TTL. Por isso, volatile-lru numa cache de objetos pode ficar cheia e começar a recusar escritas. allkeys-lfu é uma alternativa razoável se o tráfego atingir frequentemente um conjunto pequeno de chaves, porque elimina chaves com base na frequência e não na recência. Escolha uma política de forma deliberada e registe o motivo.

Persistência: mantenha-a desativada, salvo se houver um motivo

O redis.conf fornecido pelo pacote ativa snapshots RDB com linhas como save 900 1 e mantém o ficheiro append-only desativado. Numa cache de objetos pura, os snapshots não trazem benefícios. Por definição, os dados podem ser regenerados, e uma cache restaurada a partir de um ficheiro com vinte minutos de idade contém valores obsoletos que o WordPress vai utilizar.

Os snapshots também têm custos. BGSAVE cria um fork do processo, e a cópia na escrita pode aumentar bastante o consumo de memória enquanto o processo filho escreve. Num VPS pequeno, isto aparece no log do Redis:

Can't save in background: fork: Cannot allocate memory

e frequentemente também aparece este aviso no arranque. O Redis está a indicar que o fork provavelmente vai falhar mais tarde:

WARNING overcommit_memory is set to 0! Background save may fail under low memory condition.

Para desativar os snapshots, defina uma agenda de save vazia em /etc/redis/redis.conf, reinicie o serviço e confirme que o valor voltou a ficar vazio.

save ""

sudo systemctl restart redis-server
redis-cli config get save

Mantenha a persistência apenas se a mesma instância armazenar algo que não possa reconstruir, como uma fila de tarefas ou contadores de limite de pedidos. Nesse caso, separe as duas funções. Uma cache precisa que as chaves sejam removidas quando necessário, enquanto os dados persistentes precisam que as chaves sejam mantidas. maxmemory e a remoção por limite de memória aplicam-se à instância inteira, não a um índice de base de dados específico. Duas instâncias em dois sockets são a solução mais simples.

Instale o plugin e entenda o drop-in

wp plugin install redis-cache --activate
wp redis enable
wp redis status

wp redis enable exibe Object cache enabled. quando é concluído com sucesso. Na prática, copia wp-content/plugins/redis-cache/includes/object-cache.php para wp-content/object-cache.php. Essa cópia é o drop-in, e é o drop-in que executa o trabalho. O WordPress carrega wp-content/object-cache.php muito cedo, antes de qualquer código de plugin ser executado. É assim que o cache fica disponível durante todo o pedido. Um plugin ativo sem um drop-in instalado não armazena nada em cache.

As mensagens de erro indicam qual das duas partes falhou. Object cache could not be enabled. significa que a cópia falhou. Portanto, wp-content não pode ser escrito pelo utilizador que executa o WP-CLI. A foreign object cache drop-in was found. significa que outro plugin de cache já utiliza esse nome de ficheiro. A correção é wp redis update-dropin. Uma mensagem que termina em Redis server is unreachable:, seguida pelo erro do cliente, indica que as definições de ligação estão erradas. Volte a redis-cli ping.

Se a cópia falhar por causa das permissões, coloque o ficheiro manualmente e atribua-o ao utilizador do servidor Web.

cp wp-content/plugins/redis-cache/includes/object-cache.php wp-content/object-cache.php
sudo chown www-data:www-data wp-content/object-cache.php

Remover o plugin não remove o drop-in. Execute primeiro wp redis disable. O comando exibe Object cache disabled. e elimina o ficheiro. Se eliminar o diretório do plugin enquanto o drop-in permanece, o site continuará a executar o código antigo de cache, sem um plugin para o atualizar.

Configurações de ligação em wp-config.php

Adicione estas definições acima da linha que contém /* That's all, stop editing! */, porque as constantes definidas depois dela são processadas demasiado tarde.

define( 'WP_REDIS_HOST', '127.0.0.1' );
define( 'WP_REDIS_PORT', 6379 );
define( 'WP_REDIS_DATABASE', 0 );
define( 'WP_REDIS_PREFIX', 'shop_prod:' );

Para o socket Unix, defina o esquema e o caminho. O host e a porta são ignorados nesse caso.

define( 'WP_REDIS_SCHEME', 'unix' );
define( 'WP_REDIS_PATH', '/run/redis/redis-server.sock' );
define( 'WP_REDIS_PREFIX', 'shop_prod:' );

WP_REDIS_MAXTTL força uma expiração em todas as chaves, em segundos. Não precisa desta opção com allkeys-lru. É útil quando pretende impor um limite máximo para a antiguidade de um valor em cache.

Um Redis, vários sites: prefixos e bases de dados

O Redis disponibiliza dezasseis bases de dados numeradas por predefinição, com um espaço de chaves plano em cada uma. Duas instalações do WordPress apontadas para a base de dados 0 e sem prefixo escrevem os mesmos nomes de chaves no mesmo espaço. Assim, um site pode ler e servir as opções do outro. Atribua um prefixo próprio a cada site.

define( 'WP_REDIS_PREFIX', 'shopA_prod:' );
define( 'WP_REDIS_DATABASE', 1 );

O prefixo separa os nomes das chaves. O índice da base de dados separa os espaços de chaves, o que é importante ao limpar dados: esvaziar um índice deixa os restantes intactos. O plugin também documenta WP_REDIS_SELECTIVE_FLUSH, que elimina apenas as chaves correspondentes ao seu prefixo em vez de eliminar a base de dados inteira, mas precisa de as procurar.

Os prefixos e os índices não separam a memória. maxmemory e a política de eviction aplicam-se à instância inteira. Por isso, um site com muita atividade pode expulsar as chaves de um site com pouca atividade, sem que nenhum dos dois o assinale. Os sites que não podem afetar-se entre si precisam de instâncias Redis separadas, cada uma com o seu próprio socket e o seu próprio limite.

Mantenha o staging fora do cache de produção

Um site de staging normalmente é uma cópia dos ficheiros e da base de dados de produção. Isso significa que também é uma cópia de wp-config.php, com o mesmo prefixo e o mesmo índice de base de dados. Se o apontar para o mesmo Redis, ele grava as chaves de produção com valores de staging. Um preço de teste ou uma opção alterada passa então a aparecer no site ativo, sem deploy nem registo.

Separe cada ambiente manualmente. Em wp-config.php do staging:

define( 'WP_REDIS_PREFIX', 'shop_staging:' );
define( 'WP_REDIS_DATABASE', 5 );

Melhor ainda, atribua ao staging uma instância própria do Redis ou não use qualquer cache de objetos. define( 'WP_REDIS_DISABLED', true ); desativa o cache em runtime e mantém o drop-in instalado. Esta também é a forma mais rápida de confirmar se um problema é ou não causado pelo cache.

Tutoriais mais antigos definiam WP_CACHE_KEY_SALT para este fim. O readme do plugin marca essa constante como obsoleta e indica WP_REDIS_PREFIX como substituta. Use, portanto, o nome novo.

Verifique em vez de confiar

Comece pelos diagnósticos do próprio plugin.

wp redis status

A linha mais importante é Drop-in. Drop-in: Valid significa que o WordPress está a carregar o ficheiro deste plugin. Drop-in: Not installed significa que a cópia nunca foi feita e que o site não tem uma cache persistente, por muito verde que pareça o ecrã de administração. Status indica a ligação e Client identifica a extensão em uso. É aí que confirma PhpRedis em vez de Predis.

Depois, consulte diretamente o núcleo do WordPress, porque ele não depende daquilo que o plugin indica.

wp eval 'var_dump( wp_using_ext_object_cache() );'

bool(true) significa que o núcleo está a comunicar com uma cache de objetos externa.

Depois, confirme que as chaves estão a ser criadas, usando o prefixo que configurou.

redis-cli -n 0 dbsize
redis-cli -n 0 --scan --pattern 'shop_prod:*' | head

dbsize a aumentar enquanto navega pelo site é a prova. Zero chaves com um drop-in válido significa que a ligação está a falhar silenciosamente ou que o prefixo não é o que pensa.

Por fim, veja o que o Redis mede por si.

redis-cli info stats | grep -E 'keyspace_hits|keyspace_misses|evicted_keys|expired_keys'

A taxa de acertos é keyspace_hits / (keyspace_hits + keyspace_misses) e a documentação do Redis apresenta essa fórmula. Tenha em conta duas ressalvas. Os contadores abrangem toda a instância desde o último reinício. Por isso, misturam todos os sites e todas as aplicações que a partilham. Além disso, a taxa imediatamente depois de um flush ou reinício não tem significado, porque a cache ainda está a ser preenchida. Deixe-a funcionar durante um dia normal de tráfego.

Não compare o seu valor com uma taxa de acertos ou uma contagem de consultas publicada por uma empresa de alojamento. Esses valores descrevem os sites e o conjunto de plugins dessa empresa. O valor relevante é o seu, medido antes e depois numa página que uma cache de páginas não consegue servir.

curl -o /dev/null -s -w '%{time_starttransfer}\n' -b cookies.txt https://example.com/my-account/

Execute isso com um cookie jar autenticado, várias vezes, primeiro com a cache desativada (WP_REDIS_DISABLED) e depois ativada. Essa diferença é o seu resultado.

Quando o Redis torna o WordPress mais lento

Uma instância cheia com a política errada é o principal problema, já abordado acima: OOM command not allowed when used memory > 'maxmemory'. no log e um site que paga tanto pela base de dados como pela cache.

Usar o Redis noutro host é o segundo problema. O WordPress faz centenas de chamadas à cache de objetos durante um pedido. Se um pedido fizer 500 chamadas e cada ida e volta custar 1 ms, isso representa meio segundo de espera que um socket local não teria. Mantenha o Redis no mesmo servidor ou numa rede privada com latência inferior a 1 ms. A vantagem do mesmo servidor proporcionada pelo kernel é uma questão separada: o agendamento consciente da cache adicionado no Linux 7.2 tenta manter processos que comunicam frequentemente, como PHP-FPM e Redis, em cores que partilham uma cache. Um convidado VPS beneficia menos disso do que um servidor físico.

Uma tabela de opções com um volume enorme de dados carregados automaticamente é o terceiro problema e é comum em sites antigos. O WordPress coloca todas as opções carregadas automaticamente numa única chave de cache. Assim, um megabyte desses dados atravessa a ligação em cada pedido. Meça:

wp db query "SELECT ROUND(SUM(LENGTH(option_value))/1024) AS kb FROM wp_options WHERE autoload IN ('yes','on','auto','auto-on');"

O WordPress 6.6 adicionou novos valores de carregamento automático. Por isso, uma consulta antiga que corresponda apenas a 'yes' subestima os valores numa instalação moderna. Qualquer valor superior a 1 megabyte é um problema a corrigir na tabela de opções, não no Redis.

Um reinício esvazia tudo. Por isso, os minutos após systemctl restart redis-server são compostos apenas por falhas de cache e operações na base de dados. Reinicie quando o tráfego estiver baixo. Além disso, uma cache de objetos não impede que wp-cron.php seja executado durante o carregamento das páginas pelos visitantes, o que é outra fonte de pedidos lentos: mova o WP-Cron para uma tarefa real do cron do sistema enquanto trata deste problema.

Manutenção

Limpe o cache depois de uma implementação que altere opções ou código do tema com wp cache flush. Execute wp redis update-dropin depois de atualizar um plugin se o drop-in não tiver sido atualizado automaticamente, porque um drop-in de uma versão antiga do plugin usado com uma versão mais recente é uma fonte real de comportamentos anómalos. Monitorize um servidor em produção com redis-cli --stat, que imprime uma linha por segundo. redis-cli monitor imprime todos os comandos e consome CPU real numa instância ocupada. Use-o durante alguns segundos enquanto reproduz um problema e pare-o em seguida.

Há mais um número que convém conhecer: redis-cli info clients apresenta connected_clients. O PHP-FPM mantém uma ligação por worker, por isso esse valor deve acompanhar o seu pm.max_children, e não excedê-lo numa ordem de grandeza. Se isso acontecer, alguma coisa está a abrir ligações e não as está a fechar.

FAQ

Ainda preciso de um cache de páginas se executar um cache de objetos Redis?

Sim, para tráfego anónimo. Um cache de páginas entrega HTML armazenado sem executar PHP, o que é sempre mais económico do que executar o WordPress com um cache de objetos aquecido. O cache de objetos trata os pedidos que o cache de páginas tem de ignorar: utilizadores autenticados, carrinhos, checkout e wp-admin. Numa loja ou num site de membros, vale a pena executar ambos. Num site cujos visitantes nunca iniciam sessão, o cache de páginas faz quase todo o trabalho.

Quanta memória devo atribuir ao Redis para o WordPress?

Calcule o valor com base no seu próprio servidor, em vez de copiar um número. Pegue na RAM total, subtraia o buffer pool do MySQL e os buffers por ligação, subtraia pm.max_children multiplicado pelo tamanho residente de um worker PHP-FPM e subtraia algumas centenas de megabytes para o kernel e o servidor Web. Atribua ao Redis uma parte do que restar. Depois de um dia de tráfego, verifique used_memory_human em redis-cli info memory e ajuste o valor. Um único site WordPress normalmente estabiliza em dezenas de megabytes. Por isso, um maxmemory de 256 MB é um ponto de partida generoso num servidor com 4 GB.

Porque é que o meu site ficou mais lento depois de ativar o cache de objetos Redis?

A causa habitual é uma instância cheia a executar a política noeviction. O Redis recusa novas escritas e devolve OOM command not allowed when used memory > 'maxmemory'.. O WordPress recorre então à base de dados para cada valor e, além disso, perde tempo numa ida desnecessária ao Redis. Verifique redis-cli config get maxmemory-policy, defina allkeys-lru e confirme que maxmemory não é demasiado pequeno. Outras causas comuns são um servidor Redis num host remoto, onde centenas de idas e voltas por pedido se acumulam, e um valor de opções carregado automaticamente com vários megabytes, que atravessa a ligação em cada pedido.

Vários sites WordPress podem partilhar um servidor Redis?

Sim, com cuidado. Atribua a cada site um WP_REDIS_PREFIX único para impedir colisões nos nomes das chaves e um índice WP_REDIS_DATABASE separado para que a limpeza de um site não esvazie o outro. O que continuam a partilhar é a memória: maxmemory e a expulsão aplicam-se à instância inteira. Por isso, um site ocupado pode expulsar as chaves de um site pouco utilizado. Os sites que não podem afetar-se mutuamente precisam de instâncias Redis separadas, cada uma com os seus próprios limites.

É seguro eliminar wp-content/object-cache.php?

Sim. É um drop-in, não faz parte do núcleo do WordPress, e removê-lo faz o WordPress voltar ao seu cache incorporado por pedido. O site continua a funcionar, mas faz simplesmente mais consultas à base de dados. Prefira wp redis disable, que elimina o ficheiro de forma limpa e comunica Object cache disabled.. Eliminá-lo manualmente é a medida de emergência correta se o Redis estiver indisponível ou a comportar-se de forma incorreta e não conseguir aceder à área de administração.