Migração e multisite, Gestão avançada de WordPress

Dois tópicos que assustam administradores iniciantes: “Como movo um site sem estragar nada?” e “O que é este Multisite e preciso dele?”. Vamos abordá-los.

Migração e Multisite são duas decisões diferentes que muitas vezes se confundem. Uma migração move ficheiros, base de dados e DNS. O Multisite muda a forma como vários sites partilham uma única instalação de WordPress. A referência oficial para a parte da rede é o manual do WordPress Multisite.

#Como migrar um site WordPress sem perder dados

Mover um site (ex: de servidor local para produção ou mudar de alojamento) é um processo de 3 passos:

1. Ficheiros: Copie tudo de public_html (de preferência por SSH, como se explica abaixo).
2. Base de Dados: Exporte o ficheiro .sql (ex: através do phpMyAdmin ou com wp db export).
3. Mudança de Domínio (momento chave): O WordPress guarda o endereço do site em muitos lugares na base de dados (em wp_options, mas também no conteúdo dos posts como links de imagens).

Erro de amador: Editar manualmente o ficheiro SQL no bloco de notas. Isto estraga “dados serializados” (serialized arrays) de plugins e widgets. Método profissional: Use WP-CLI (wp search-replace 'antigo.pt' 'novo.pt') ou o plugin Better Search Replace. Ambos mantêm a integridade dos dados.

#Porque é que uma substituição SQL estraga dados serializados do PHP

O WordPress guarda grande parte das opções do tema, da configuração de widgets e dos dados de plugins (por exemplo Advanced Custom Fields ou layouts de construtores de páginas) como strings PHP serializadas. Uma definição na tabela wp_options pode ter este aspeto:

a:2:{s:4:"host";s:9:"antigo.pt";s:4:"port";i:3306;}

Aqui, s:9 declara que a string antigo.pt tem exatamente 9 caracteres. Se trocar o domínio com localizar e substituir num editor de texto, ou com um UPDATE wp_options SET option_value = REPLACE(...), por loja-nova.pt (12 caracteres), a declaração continua a dizer s:9.

Da próxima vez que o WordPress chamar unserialize(), o PHP encontra 12 caracteres onde esperava 9, mostra o aviso unserialize(): Error at offset, desiste e descarta o array inteiro. Resultado: os widgets desaparecem, as opções de layout voltam aos valores de origem e as chaves de API perdem-se.

#Como o WP-CLI search-replace trata dados serializados

O WP-CLI trata a serialização por si. O comando carrega cada valor em memória, desserializa-o, substitui a string, recalcula os comprimentos e volta a serializar antes de gravar no MySQL. A referência do search-replace indica também que os valores das chaves primárias nunca são alterados. Mantenha o dry-run idêntico à execução real, para que a pré-visualização mostre exatamente o que vai mudar:

# 1. Dry-run: mesmas tabelas e opções da execução real, nada é gravado
wp search-replace 'https://antigo.pt' 'https://loja-nova.pt' \
  --all-tables --skip-columns=guid --dry-run

# 2. Executar a substituição
wp search-replace 'https://antigo.pt' 'https://loja-nova.pt' \
  --all-tables --skip-columns=guid

# 3. Limpar a cache de objetos e regenerar as regras de reescrita
wp cache flush
wp rewrite flush --hard

Duas opções copiadas de tutoriais antigos precisam de correção. --recurse-objects já vem ativa por defeito, por isso acrescentá-la não muda nada. --precise não é o que protege os dados serializados: por defeito, o comando usa consultas SQL rápidas e muda sozinho para PHP nas colunas com dados serializados, enquanto --precise força o PHP em todas as colunas. É mais lento e só compensa em estruturas invulgarmente complexas. Mais importante é --skip-columns=guid, pelo motivo explicado mais abaixo na secção sobre o URL do site.

#Como migrar o WordPress sem tempo de inatividade

Para lojas online e sites de angariação de contactos, onde cada transação conta, funciona uma sequência em quatro fases.

#Fase 1: baixar o TTL do DNS 48 horas antes

Baixe o TTL dos registos A do domínio para 300 segundos (5 minutos). Assim, as caches de DNS atualizam-se depressa quando o novo IP for publicado.

#Fase 2: sincronização incremental de ficheiros com rsync

O FTP clássico é lento, não é cifrado e falha em silêncio com bibliotecas de média grandes. Use rsync por SSH para espelhar os ficheiros diretamente entre servidores, excluindo as pastas de cache temporária:

rsync -avzP --delete \
  --exclude 'wp-content/cache/*' \
  --exclude 'wp-content/uploads/cache/*' \
  --exclude '*.log' \
  [email protected]:/var/www/vhosts/site.pt/public/ /var/www/html/

A opção -a preserva permissões e datas dos ficheiros, -z comprime os dados durante a transferência e -P permite retomar uma transferência interrompida.

#Fase 3: janela de mudança

1. Ative o modo de manutenção no servidor de origem: wp maintenance-mode activate.
2. Gere um dump limpo da base de dados: wp db export mudanca.sql --add-drop-table.
3. Transfira e importe o dump no novo servidor: wp db import mudanca.sql.
4. Execute wp search-replace para atualizar URLs, HTTPS ou caminhos diferentes.
5. Teste localmente apontando o domínio para o novo IP no seu ficheiro hosts.

#Fase 4: mudança de DNS e verificação

Aponte o registo A para o IP do novo servidor. Como o TTL foi reduzido na fase 1, o tráfego passa para o novo alojamento em poucos minutos. Quando o DNS estiver propagado em todo o lado, reponha o TTL habitual (86400 segundos).

#Regra 3-2-1 para backups do WordPress

A regra 3-2-1:

• 3 cópias dos dados.
• 2 meios diferentes (ex: servidor + cloud).
• 1 cópia fora do escritório (off-site).

Não dependa apenas do alojamento. Instale UpdraftPlus ou Duplicator e envie cópias para Google Drive/Dropbox. É a sua apólice de seguro contra ataques ou contra incidentes como o incêndio no centro de dados da OVH em Estrasburgo, em março de 2021.

#O que é o WordPress multisite e quando usar

Multisite (MU) é uma funcionalidade que permite correr 100, 1000 ou um milhão de sites numa única instalação WordPress.

• Um conjunto de ficheiros (core, temas, plugins).
• Uma base de dados (com tabelas separadas para cada site).
• Um super-administrador.

Quando usar?

• Tem uma rede de sites de franchising (ex: lisboa.empresa.pt, porto.empresa.pt).
• É uma universidade a dar um blog a cada estudante/professor.
• Precisa de criar sites de demonstração ou de staging interno com a mesma configuração, por script.

Um serviço multilingue, por si só, raramente justifica o Multisite: WPML ou Polylang numa única instalação funcionam frequentemente melhor. O manual vai no mesmo sentido: se os sites precisam de partilhar muitos dados ou utilizadores, ou apenas de temas diferentes por secção, uma única instalação com um plugin pode servir melhor do que uma rede.

Quando NÃO usar?

• Quando tem 5 sites para clientes completamente diferentes. Se um site “morre” (erro PHP), caem todos. Base de dados de utilizadores partilhada também pode ser problemática.
• Quando os sites precisam de versões de PHP, planos de alojamento ou zonas de segurança diferentes.
• Quando prevê separar mais tarde um site da rede: a extração exige exportar tabelas filtradas, mudar prefixos e reassociar utilizadores.

Multisite é uma ferramenta poderosa, mas requer um servidor sólido e conhecimento de administração. Não o ative “por diversão”.

#Tabelas da base de dados no WordPress multisite

Uma instalação normal de WordPress tem 12 tabelas principais. No Multisite, o WordPress separa os dados globais dos dados de cada site:

• Tabelas globais da rede: wp_users e wp_usermeta (cada conta existe uma vez em toda a rede, com funções diferentes por site), e wp_blogs, wp_site e wp_sitemeta, que guardam as definições da rede, as regras de registo e a lista de sites.
• Tabelas de cada site: cada novo site recebe o seu próprio conjunto identificado pelo ID; o site 2 usa wp_2_posts, wp_2_options e wp_2_comments.

+-----------------------------------------------------+
|             Esquema do WordPress Multisite          |
+-----------------------------------------------------+
| Tabelas globais:                                    |
| - wp_users / wp_usermeta                            |
| - wp_blogs / wp_site / wp_sitemeta                  |
+-----------------------------------------------------+
| Site principal (ID 1):                              |
| - wp_posts, wp_options, wp_terms...                 |
+-----------------------------------------------------+
| Subsite (ID 2, ex. porto.empresa.pt):               |
| - wp_2_posts, wp_2_options, wp_2_terms...           |
+-----------------------------------------------------+

#Requisitos antes de criar uma rede WordPress multisite

O capítulo Before you create a network enumera restrições que o ecrã Configuração da rede aplica, e a maioria das conversões falhadas esbarra numa delas.

A rede não pode ser criada quando o endereço do WordPress usa uma porta diferente de 80 ou 443. A instalação com subdomínios fica bloqueada quando o URL do WordPress contém um caminho (o WordPress não está na raiz do documento), quando o endereço é localhost ou quando é um IP como 127.0.0.1. Para testes locais, o manual sugere associar um nome de anfitrião próprio a 127.0.0.1 no ficheiro hosts. A instalação com subdiretórios fica bloqueada quando a instalação existente tem mais de um mês, porque os artigos do site principal entrariam em conflito com os caminhos dos subsites. Numa rede por caminhos, os URLs dos artigos do site principal recebem ainda o prefixo /blog/.

Do lado do servidor, o Apache precisa de mod_rewrite com suporte para .htaccess, FollowSymLinks não desativado e AllowOverride em All ou Options All para o vhost. As ligações permanentes amigáveis já têm de funcionar no site único. Decida o domínio, incluindo a questão do www, antes da ativação. Se o WordPress tiver de correr a partir de um diretório próprio, essa mudança também vem antes. O DNS wildcard só é necessário quando os utilizadores criam sites em subdomínios a pedido; os sites adicionados à mão podem usar registos DNS próprios ou anfitriões virtuais.

#Como criar uma rede WordPress multisite passo a passo

O procedimento Create a Network tem uma ordem que importa. Faça backup da base de dados e dos ficheiros. Desative todos os plugins; podem ser reativados quando a rede existir. Depois acrescente o interruptor ao wp-config.php, acima da linha /* That's all, stop editing! Happy publishing. */:

// Passo 1: mostrar o menu de configuração da rede no painel
define('WP_ALLOW_MULTISITE', true);

Vá a Ferramentas > Configuração da rede, escolha subdomínios (site.dominio.pt) ou subdiretórios (dominio.pt/site/) e cole as constantes geradas no wp-config.php, logo abaixo da linha com WP_ALLOW_MULTISITE:

// Passo 2: ativar a rede (variante com subdomínios)
define('MULTISITE', true);
define('SUBDOMAIN_INSTALL', true);
define('DOMAIN_CURRENT_SITE', 'dominio.pt');
define('PATH_CURRENT_SITE', '/');
define('SITE_ID_CURRENT_SITE', 1);
define('BLOG_ID_CURRENT_SITE', 1);

O mesmo ecrã mostra regras de reescrita. Substituem o bloco do WordPress no .htaccess (no Nginx passam a ser regras do bloco server). Faça cópia dos dois ficheiros antes de os editar. Depois, volte a iniciar sessão pela ligação que o WordPress mostra; por vezes é preciso limpar os cookies do navegador. “Os meus sites” passa a incluir o menu Administração da rede. Mudar mais tarde entre subdomínios e subdiretórios é possível, mas o manual avisa que pode não ser fácil, por isso decida antes de existir o primeiro subsite.

#Mapeamento de domínios em multisite sem plugin

Desde o WordPress 4.5, o mapeamento de domínios é uma funcionalidade nativa, segundo o capítulo de mapeamento de domínios. A ordem de trabalho é esta: primeiro, cada domínio tem de apontar para o servidor no DNS. Depois, TLS para o domínio principal e certificados SNI para os restantes, para que todo o início de sessão no painel seja cifrado. Só então se escreve o URL completo, por exemplo https://cliente.pt, no campo Endereço do site (URL) do subsite, em Sites > Editar site. Baixe o TTL um dia antes e mude o endereço só quando o servidor já responder ao novo nome de anfitrião. Se o início de sessão num site mapeado falhar com um erro de cookies bloqueados, ou sem mensagem nenhuma, o manual indica acrescentar esta linha depois das constantes da rede:

define( 'COOKIE_DOMAIN', $_SERVER['HTTP_HOST'] );

#Funções de utilizador entre sites no WordPress multisite

No Multisite, todos os utilizadores estão numa tabela partilhada. A associação e as funções atribuem-se por site.

O que isto significa na prática:

• Um administrador de porto.empresa.pt não consegue instalar plugins. Essa tarefa é do super-administrador.
• Apagar um utilizador na Administração da rede remove a conta em todo o lado, não apenas numa filial.
• Um início de sessão comum a várias marcas surge naturalmente com o Multisite; o isolamento entre clientes, não.

Documente quem é super-administrador e mantenha esse número baixo. Demasiados super-administradores é a causa habitual de “alguém ativou um plugin na Administração da rede e caíram três sites”.

#Como juntar sites WordPress numa rede multisite

Ativar a rede numa instalação existente, como descrito acima, não é o mesmo que fundir cinco instalações independentes. Cada site adicional tem de entrar por exportação e importação (WXR), WP-CLI ou uma ferramenta que entenda os prefixos de tabela do Multisite.

Ordem recomendada:

1. Backup completo de ficheiros e base de dados de todos os sites de origem (3-2-1: três cópias, dois meios, uma fora do escritório).
2. Montar a rede em staging com a mesma versão de PHP da produção.
3. Criar sites vazios na Administração da rede com os domínios ou subdomínios definitivos.
4. Importar o conteúdo site a site. Depois, correr o search-replace dos URLs antigos apenas dentro das tabelas desse site, com --url=<site> e sem --network.
5. Associar utilizadores: e-mails repetidos passam a ser uma só conta e as funções atribuem-se por site.
6. Verificar os ficheiros de média. Os uploads de um subsite ficam em wp-content/uploads/sites/{id}/.
7. Baixar o TTL do DNS, mudar e ter pronto o SQL para reverter.

#Como retirar um site do WordPress multisite

Por vezes a rede revela-se o modelo errado. Nesse caso exporta-se um site:

1. Identificar o blog_id e o prefixo das tabelas (wp_5_, etc.), por exemplo com wp site list --fields=blog_id,url.
2. Exportar o conteúdo (WXR) ou clonar as tabelas para uma nova base de dados com o prefixo normal wp_.
3. Copiar os ficheiros de média de uploads/sites/{id}/ para a pasta normal uploads/.
4. Atualizar siteurl e home e depois correr o search-replace.
5. Instalar apenas os plugins e temas que esse site usava de facto, não todo o diretório da rede às cegas.

Planeie redirecionamentos dos antigos URLs em subdomínio para o novo domínio. Caso contrário perde autoridade de ligações e o Search Console enche-se de erros 404.

#Como mudar o URL do site WordPress depois de uma migração

Em Definições > Geral há dois campos: Endereço do WordPress (URL), onde estão os ficheiros do núcleo, e Endereço do site (URL), o que os visitantes escrevem. Quando, depois de uma mudança, não se consegue entrar no painel, o capítulo de migração documenta quatro formas de os corrigir. Aplicam-se a instalações únicas; para o Multisite, o manual remete para a base de dados, tratada na secção seguinte.

1. wp-config.php: define( 'WP_HOME', 'https://example.pt' ); e define( 'WP_SITEURL', 'https://example.pt' );. Os valores ficam fixos no código e os campos das Definições gerais deixam de ser editáveis.
2. functions.php: duas chamadas a update_option() para siteurl e home no tema ativo, carregadas uma vez e depois removidas. O manual é explícito: o código não pode ficar no ficheiro.
3. RELOCATE: define('RELOCATE', true); no wp-config.php e depois abrir wp-login.php no novo endereço. Corrige apenas o URL do site e mais nada. Deixar a constante é inseguro, porque em algumas configurações permite a um atacante mudar o endereço do site. Remova-a logo a seguir.
4. Base de dados ou WP-CLI: editar siteurl e home em wp_options, ou correr wp option update home 'https://example.pt' e wp option update siteurl 'https://example.pt'.

O mesmo capítulo tem uma regra que vale a pena repetir: nunca se altera a coluna guid de wp_posts. Os leitores de feeds usam o GUID para reconhecer os artigos que já mostraram, por isso reescrevê-lo faz com que artigos antigos reapareçam como novos. É por isso que o exemplo de WP-CLI da documentação usa --skip-columns=guid. Os endereços antigos também podem ficar em transients; na cópia migrada podem ser apagados sem risco (wp transient delete --all), porque o WordPress volta a criá-los quando precisa.

Mover o WordPress para outro diretório no mesmo servidor tem a sua própria ordem: primeiro mudam-se os dois URLs nas Definições, depois movem-se os ficheiros. Se os ficheiros foram movidos antes, o manual propõe uma ligação simbólica temporária do caminho antigo para o novo (ln -s /path/to/new /path/to/old), depois da qual os passos normais funcionam.

#Como executar o wp search-replace numa rede multisite

No Multisite, o wp search-replace só toca, por defeito, nas tabelas do site atual. A referência do comando define os alcances:

• sem opção: as tabelas registadas em $wpdb para o site indicado com --url (o principal, por defeito),
• --network: todas as tabelas registadas em $wpdb em toda a rede,
• --all-tables-with-prefix: qualquer tabela com o prefixo do WordPress, registada ou não,
• --all-tables: todas as tabelas da base de dados, seja qual for o prefixo. Sobrepõe-se a --network, por isso numa base partilhada com outras aplicações chega também às tabelas delas.

As tabelas sem chave primária são ignoradas sem aviso; wp db query 'DESCRIBE <tabela>' mostra se existe PRI. A forma documentada de transformar uma rede de produção numa cópia local reescreve também as tabelas da rede de forma explícita:

wp search-replace --url=example.pt example.pt example.test \
  'wp_*options' wp_blogs wp_site --network --skip-columns=guid

--export=rede.sql grava os dados transformados num ficheiro em vez da base de dados em uso, o que dá jeito quando a importação acontece no novo servidor. Antes e depois da alteração, o wp site list lista todos os sites para comparar os endereços guardados:

for url in $(wp site list --field=url); do
  echo "$url $(wp option get siteurl --url="$url")"
done

As notas do manual sobre mover o Multisite definem o alcance. Mesmo domínio num servidor novo: copiam-se ficheiros e base de dados tal como numa instalação única. Domínio novo: movem-se os ficheiros, atualiza-se DOMAIN_CURRENT_SITE no wp-config.php e o .htaccess se a pasta mudou, e depois revêem-se wp_site e wp_blogs (domínio e caminho) e, em cada tabela wp_N_options, os valores home, siteurl e fileupload_url. Passar de subdomínios para subdiretórios, ou o contrário, exige ainda mudar SUBDOMAIN_INSTALL e as regras de reescrita.

#Como testar a migração WordPress em staging

A forma mais segura de mudar de alojamento é fazer a migração duas vezes: primeiro num subdomínio de staging, depois a sério.

Antes do ensaio, confirme que tem uma cópia completa segundo a regra 3-2-1, com ficheiros e base de dados guardados fora do servidor de origem. Se algo correr mal, é essa cópia que o salva.

No staging, verifique primeiro a versão de PHP do novo alojamento, porque uma diferença face ao servidor antigo é uma das falhas mais comuns. Depois corra o wp search-replace em modo dry-run e leia a lista de tabelas e o número de substituições antes de aplicar a alteração. Procure também URLs absolutos escritos à mão em plugins personalizados, que o search-replace na base de dados não apanha.

A terceira falha típica são as tarefas cron esquecidas. Faça a lista do que corre no servidor antigo e recrie cada tarefa no novo.

Só quando o staging funciona sem erros é que aponta o DNS. Se a migração incluir uma rede Multisite, teste pelo menos um site de cada tipo da rede, porque um erro de PHP num deles pode derrubar todos.

#Erros comuns de staging no WordPress multisite

O Multisite falha mais vezes em staging do que em produção.

URLs fixos na rede. Uma ferramenta de clonagem que só troca o domínio principal, mas deixa wp_blogs e wp_site a apontar para a produção, faz os editores iniciarem sessão no ambiente errado ou mistura cookies.

Search-replace sem excluir o GUID ou sem dry-run. Corra sempre o dry-run. Limite as tabelas quando move apenas um site.

Cron e e-mail. O cron da rede (wp-cron.php) e o e-mail de saída do staging não podem chegar a clientes reais. Bloqueie o SMTP de saída em staging ou encaminhe-o para uma caixa de testes.

Subdomínios de staging. staging.marca.pt precisa de DNS próprio e normalmente de um certificado TLS próprio. Um certificado wildcard para *.marca.pt não cobre staging.outramarca.pt. Teste o HTTPS antes de convidar os editores.

Ativação de plugins ao nível da rede. Um plugin de teste em staging não faz mal. A mesma ação em produção sem um site canário, sim. Mantenha pelo menos um site canário onde os plugins novos são ativados primeiro.

WooCommerce numa rede. Se a rede for uma cadeia de lojas, teste os callbacks do fornecedor de pagamentos para cada URL de site. Webhooks que continuam a apontar para staging depois do lançamento saem caros. Sem comércio eletrónico, a migração limita-se a conteúdo, média e funções.

#Multisite, migração simples ou instalação separada

#O que deve estar na lista de verificação de uma migração WordPress

1. Backup verificado com um teste de restauro, não apenas pelo tamanho do ficheiro.
2. Mesma versão de PHP e extensões em staging e produção.
3. wp search-replace --dry-run sem surpresas, com as mesmas opções da execução real.
4. Início de sessão testado como super-administrador e como administrador de um site.
5. Os URLs de média carregam por HTTPS em todos os domínios mapeados.
6. wp site list --field=url corresponde à lista de endereços esperada.
7. TTL do DNS reduzido e plano de reversão escrito (quem muda o registo A, onde está o dump SQL anterior).

A migração é mecânica. O Multisite é um modelo de operação. Quem os mistura acaba a corrigir DNS quando devia ter separado os clientes, ou o contrário.

Migrações e redes Multisite partilham o mesmo ponto crítico: dados serializados e URL internos que ninguém revê antes de o DNS mudar. Se preferir ter essa passagem acompanhada, veja o que cobre o nosso apoio de desenvolvimento WordPress.