blog
Servidores

Mudar a versão do PHP no VPS sem painel em 4 etapas

Como achar o binário que o Apache ou o NGINX realmente usa, instalar a versão nova em paralelo e virar só o vhost daquele cliente, com rollback de um comando.

JR · · 8 min de leitura · 1 tabela · 13 blocos de código

Resposta curta: num VPS sem painel, a versão que vale é a do pool PHP-FPM que o host virtual chama, não a que o `php -v` mostra. O processo tem 4 etapas: descobrir o socket no vhost, instalar a nova versão lado a lado com as extensões, trocar uma linha e provar por página de teste no document root.

Neste artigo
  1. O `php -v` responde pelo seu shell, não pelo site do cliente
  2. Como descobrir qual PHP o vhost chama de verdade
  3. Instalar a versão nova lado a lado com o site no ar
  4. Trocar uma linha no vhost e recarregar sem derrubar conexão
  5. Provar a versão no document root do cliente e apagar o teste
  6. Checklist de inventário, rollback e o que olhar no 502
  7. A frase que explica a troca para o cliente final

O `php -v` responde pelo seu shell, não pelo site do cliente

Num VPS de imagem pronta (Ubuntu com LAMP, Debian com NGINX, imagem LiteSpeed, AlmaLinux com Apache) não existe MultiPHP Manager. E a primeira armadilha é sempre a mesma: você entra por SSH, roda php -v, lê PHP 8.3.x e informa ao cliente que está tudo certo. Está errado.

php -v mostra o binário CLI que está no seu PATH. Esse binário atende cron, WP-CLI e Composer. O site, em uma requisição HTTP, é servido por outra coisa: um pool do PHP-FPM, um módulo do Apache ou um processo lsphp. São instalações independentes, com php.ini independente e conjunto de extensões independente.

Na prática isso significa que um VPS pode ter o WP-CLI rodando em 8.3 enquanto o wp-admin do cliente roda em 7.4. E o 7.4 é o que quebra plugin, o que aparece no Site Health e o que o scanner de segurança do cliente aponta.

A regra para trabalhar: a versão que vale é a do processo que o servidor web chama. Todo o resto é curiosidade.

As quatro etapas da troca no VPSDescobrirLer o vhost do siteInstalarNova versão lado a ladoApontarTrocar socket e recarregarProvarTestar e apagar o arquivo
Sequência de trabalho para trocar a versão sem painel, com o site no ar.

Como descobrir qual PHP o vhost chama de verdade

Faça nesta ordem. Cada passo leva segundos e você só desce para o próximo se o anterior não deu resposta.

Pergunte ao próprio site pelo cabeçalho HTTP

curl -sI https://exemplo.com.br/ | grep -i -E 'x-powered-by|server'

Se o expose_php estiver ligado, X-Powered-By: PHP/8.1.2 já encerra a investigação. Muitos stacks removem esse cabeçalho, então a ausência não prova nada.

Liste as versões instaladas e os sockets que estão de pé

ls /etc/php/            # Debian/Ubuntu: versões instaladas
systemctl list-units 'php*-fpm*' --no-pager
ls /run/php/*.sock

Em imagens LiteSpeed o equivalente são diretórios por versão, no padrão /usr/local/lsws/lsphpXX/bin/lsphp, conforme a documentação das imagens LiteSpeed.

Leia o vhost daquele site, não a configuração global

grep -R -n -E 'fastcgi_pass|SetHandler|lsphp|php[0-9]' /etc/nginx/sites-enabled/ /etc/apache2/sites-enabled/ 2>/dev/null

É aqui que a resposta aparece em texto puro: um fastcgi_pass unix:/run/php/php7.4-fpm.sock; ou um SetHandler "proxy:unix:/run/php/php7.4-fpm.sock|fcgi://localhost". Anote o caminho exato do socket. Ele é o endereço da versão antiga e será a única coisa que você vai trocar.

Stack do VPS Quem escolhe o PHP da requisição Onde se troca a versão
NGINX + PHP-FPM fastcgi_pass do location ~ \.php$ server block do site
Apache + PHP-FPM (proxy_fcgi) SetHandler ... proxy:unix: VirtualHost do site
Apache + mod_php módulo carregado no servidor inteiro a2dismod/a2enmod, afeta todos os sites
LiteSpeed/OpenLiteSpeed handler externo lsphp configuração do vhost
CLI, cron, WP-CLI PATH / alternatives independente do site

A linha do mod_php é a que mais dói em VPS de agência: ela não é por site. Se o VPS hospeda cinco clientes com mod_php, trocar a versão troca para os cinco ao mesmo tempo. Nesse caso o trabalho real é migrar aquele vhost para PHP-FPM primeiro, e só depois escolher a versão. É mais serviço do que parece no orçamento, cobre por isso.

Instalar a versão nova lado a lado com o site no ar

Nada de "atualizar o PHP". Você instala a nova versão ao lado da antiga, sem desligar nada. O site continua no ar na versão velha enquanto você prepara a nova.

Em Debian e Ubuntu o caminho padrão é o repositório mantido por Ondřej Surý; em RHEL, AlmaLinux e Rocky, o Remi. Ambos entregam pacotes versionados que convivem: php8.2-fpm não remove php7.4-fpm.

Depois de habilitar o repositório da sua distribuição:

# Debian/Ubuntu (exemplo com 8.2)
sudo apt install php8.2-fpm php8.2-mysql php8.2-curl php8.2-gd \
                 php8.2-mbstring php8.2-xml php8.2-zip php8.2-intl
sudo systemctl enable --now php8.2-fpm

O conjunto de extensões não se adivinha: copie o do que está rodando hoje.

php7.4 -m > /tmp/ext-74.txt
php8.2 -m > /tmp/ext-82.txt
diff /tmp/ext-74.txt /tmp/ext-82.txt

O diff é o seu checklist de instalação. Extensões que somem silenciosamente e quebram site de cliente: intl (WooCommerce e traduções), imagick, soap (integrações com ERP), zip (atualização de plugin), bcmath e gmp (gateways de pagamento). Se o site usa Redis ou Memcached como object cache, instale o pacote correspondente da nova versão antes da troca, senão o cache cai e o site fica lento no mesmo minuto em que você vira a chave.

Em imagens LiteSpeed, a lógica é a mesma: instalar o pacote lsphpXX da versão desejada e os módulos equivalentes, mantendo a versão anterior no disco, conforme a FAQ de PHP das imagens LiteSpeed.

Um pool por site em vez de jogar todo mundo no `www`

Em VPS com mais de um cliente, não jogue todo mundo no pool www da nova versão. Copie /etc/php/8.2/fpm/pool.d/www.conf para cliente.conf, troque o nome do pool, o user/group e o caminho do socket (por exemplo /run/php/cliente-8.2.sock). Ganha isolamento de permissão, log separado e a possibilidade de reverter um site sem tocar nos outros.

Trocar uma linha no vhost e recarregar sem derrubar conexão

A edição é de uma linha. Faça backup antes, sempre, porque é o arquivo que você vai restaurar às pressas se der errado.

sudo cp /etc/nginx/sites-available/exemplo.conf{,.bak-$(date +%F)}

NGINX, dentro do server do site:

location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/cliente-8.2.sock;
}

Apache, antes de qualquer coisa, garanta os módulos de proxy FastCGI. Sem proxy_fcgi o configtest pode passar e o site responder erro, bem no passo mais arriscado:

sudo a2enmod proxy proxy_fcgi setenvif

Se o vhost vinha de mod_php, desabilite o handler antigo para esse site (ou sudo a2dismod php7.4, lembrando que isso afeta todos os vhosts que ainda dependem dele). Feito isso, dentro do <VirtualHost>:

<FilesMatch \.php$>
    SetHandler "proxy:unix:/run/php/cliente-8.2.sock|fcgi://localhost"
</FilesMatch>

Valide a sintaxe antes de recarregar. Esse par de comandos evita derrubar todos os sites do VPS por causa de uma chave esquecida:

sudo nginx -t && sudo systemctl reload nginx
# ou
sudo apachectl configtest && sudo systemctl reload apache2

O reload não derruba conexão em andamento. Com o pool da versão nova já em execução desde o enable --now, virar o vhost é só reload do servidor web: a indisponibilidade tende a zero. Janela real só aparece se você precisar reiniciar o FPM, por exemplo depois de mexer no php.ini ou na configuração do pool.

Provar a versão no document root do cliente e apagar o teste

Teste no document root do cliente, não no /var/www/html padrão. É a diferença entre provar e supor.

sudo -u www-data tee /var/www/exemplo/public_html/zz-check-9f3a.php >/dev/null <<'PHP'
<?php
header('Content-Type: text/plain');
echo PHP_VERSION, PHP_EOL;
echo php_sapi_name(), PHP_EOL;
echo php_ini_loaded_file(), PHP_EOL;
foreach (['mysqli','curl','gd','intl','mbstring','zip','imagick'] as $e) {
    echo $e, ': ', extension_loaded($e) ? 'ok' : 'FALTA', PHP_EOL;
}
PHP

Abra https://exemplo.com.br/zz-check-9f3a.php, leia, e apague o arquivo no mesmo minuto:

sudo rm /var/www/exemplo/public_html/zz-check-9f3a.php

Nome aleatório e remoção imediata não são frescura: arquivo de diagnóstico esquecido em raiz pública é item de relatório de pentest e vetor de fingerprint. O php_ini_loaded_file() entrega de brinde qual php.ini está valendo, o que resolve em segundos a dúvida de "editei o upload_max_filesize e não mudou nada".

Depois disso, confirme pelo lado do WordPress: Ferramentas > Saúde do site > Informações > Servidor. Se a tela do WordPress continuar mostrando a versão antiga, o cache de página ou de object cache está servindo conteúdo velho; limpe antes de desconfiar da configuração.

Checklist de inventário, rollback e o que olhar no 502

O valor aqui não é fazer uma vez, é fazer em quinze VPS sem pensar. Padronize:

  1. Inventário: por VPS, uma linha com domínio, document root, socket atual, versão atual, versão alvo.
  2. Backup de arquivos e banco antes de tocar na configuração, com restauração testada.
  3. Instalar a nova versão e as extensões do diff, sem apontar nada ainda.
  4. Subir o pool por site e conferir que o socket existe em /run/php/.
  5. Clonar o vhost em staging ou subdomínio e apontar o clone primeiro.
  6. Virar o vhost de produção, configtest, reload.
  7. Página de teste, Site Health, carrinho/checkout/formulário, log de erro.
  8. Remover a página de teste e registrar no inventário a data da troca.
  9. Ajustar cron e WP-CLI para a mesma versão (php8.2 /usr/local/bin/wp ... ou update-alternatives), senão você fica com dois PHPs divergentes no mesmo site.

Rollback: restaurar o .bak do vhost, configtest, reload. Volta em menos tempo do que leva para explicar. Mantenha a versão antiga instalada por alguns dias; só remova o pacote quando o site estiver estável e você tiver acompanhado o log de erro.

Onde olhar quando quebrar:

sudo tail -f /var/log/php8.2-fpm.log /var/log/nginx/exemplo.error.log

Erro 502 logo após a troca quase sempre é socket errado ou permissão do socket, não incompatibilidade do código. Confirme que o caminho no vhost é idêntico ao listen do pool, incluindo o nome do arquivo.

Diagnóstico do 502 logo após virar a chaveErro 502 após a trocaSite responde, PHP nãoSocket existe em /run/php?Compare com o listen do poolCaminho igual no vhost?Inclusive o nome do arquivoPermissão do socket confere?user e group do poolNada disso: restaurar .bakconfigtest e reload
Ordem de verificação antes de culpar o código do site.

A frase que explica a troca para o cliente final

Use esta, adaptando a versão e o horário:

Funciona porque responde às três perguntas que o cliente faz: por que mexer, quanto tempo fica fora e o que acontece se der errado. Se o cliente pedir prova do fim de suporte, mostre o calendário oficial de versões suportadas da linguagem. É um argumento de terceiro, não seu, e isso encurta a conversa.

Uma observação contra o nosso próprio interesse comercial: se o site do cliente está lento e você espera que a troca de 7.4 para 8.2 resolva, meça antes. Versão nova melhora o tempo de CPU do PHP, mas não conserta consulta lenta no banco, plugin que faz requisição externa síncrona nem imagem de 4 MB na home. Troque a versão porque sem suporte não há correção de segurança. Ganho de desempenho, quando vier, é bônus, e você deve medi-lo no site em questão antes de prometer.

Referências

  1. Documentação oficial (litespeed) — LiteSpeed Cloud Images: PHP FAQ. Consultado em 2026-10-25.
Leia também