Tutorial: mover Traefik para novo servidor sem perder rotas

15 min de leitura  ·  Guia técnico

Mover o Traefik para um novo servidor significa transferir toda a configuração do proxy reverso — arquivos estáticos, certificados ACME e definições de rota — sem interromper os serviços em produção. Para migrar o Traefik sem perder rotas, siga estes passos:

1. Faça backup dos arquivos traefik.yml, acme.json e docker-compose.yml no servidor de origem.
2. Instale o Docker e o Docker Compose no servidor de destino.
3. Transfira os arquivos via rsync ou scp e ajuste permissões do acme.json.
4. Crie a rede Docker externa no novo servidor antes de subir os containers.
5. Valide rotas e certificados no novo servidor apontando o DNS temporariamente.
6. Atualize o DNS definitivo e desligue o ambiente antigo após confirmar o funcionamento.

Pré-requisitos para migrar o Traefik

• Acesso SSH com privilégios de root ou sudo nos dois servidores (origem e destino).
• Docker Engine 24.x ou superior instalado no servidor de destino (Debian 12 ou Ubuntu 24.04 LTS recomendados).
• Docker Compose v2 (plugin integrado ao Docker CLI, comando docker compose).
• Traefik v2.x ou v3.x em execução no servidor de origem com configuração baseada em arquivos (traefik.yml ou traefik.toml).
• Acesso ao painel de controle de DNS do domínio para alterar registros A.
• TTL do DNS configurado para um valor baixo (300 segundos ou menos) com antecedência de pelo menos 24 horas antes da migração.
• Porta 80 e 443 liberadas no firewall do novo servidor.

Etapa 1 — Inventário e backup dos arquivos do Traefik no servidor de origem

Antes de qualquer transferência, mapeie exatamente quais arquivos compõem a instalação do Traefik. Em ambientes Docker, a configuração costuma estar concentrada em um diretório dedicado. Identifique o caminho com:

find / -name "traefik.yml" -o -name "traefik.toml" -o -name "acme.json" 2>/dev/null

Saída esperada (exemplo):

/opt/traefik/traefik.yml
/opt/traefik/acme.json
/opt/traefik/docker-compose.yml

Com os caminhos identificados, crie um arquivo compactado de backup:

tar -czvf traefik-backup-$(date +%Y%m%d).tar.gz /opt/traefik/

Verifique o conteúdo do arquivo gerado antes de prosseguir:

tar -tzvf traefik-backup-20250101.tar.gz

Você verá a listagem de todos os arquivos incluídos. Guarde também o conteúdo do docker-compose.yml de cada serviço que usa labels do Traefik — esses arquivos definem as rotas e middlewares e precisam ser copiados junto com a configuração central.

Etapa 2 — Preparar o servidor de destino com Docker e rede externa

No servidor de destino (neste exemplo, Debian 12), instale o Docker Engine seguindo o repositório oficial. Evite instalar via apt install docker.io, pois essa versão costuma estar desatualizada nos repositórios padrão do Debian.

apt update && apt install -y ca-certificates curl gnupg
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/debian bookworm stable" \
  > /etc/apt/sources.list.d/docker.list
apt update && apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Confirme a instalação:

docker --version && docker compose version

Docker version 26.1.4, build 5650f9b
Docker Compose version v2.27.1

Agora crie a rede Docker externa que o Traefik usará para se comunicar com os outros containers. Essa rede não é exportada pelo docker-compose.yml e precisa ser criada manualmente no novo servidor:

docker network create traefik-net

a3f8c2d1e4b7...

Se o nome da rede no seu ambiente for diferente (por exemplo, web ou proxy), substitua nos comandos acima e no docker-compose.yml. Todos os containers que precisam ser roteados pelo Traefik devem estar conectados a essa mesma rede externa.

Etapa 3 — Transferir arquivos de configuração e certificados ACME

A transferência segura dos arquivos de configuração do Traefik é feita com rsync via SSH. Execute o comando a partir do servidor de origem (ou de uma máquina local com acesso a ambos):

rsync -avz --progress /opt/traefik/ root@IP_NOVO_SERVIDOR:/opt/traefik/

Saída esperada durante a transferência:

sending incremental file list
traefik.yml
acme.json
docker-compose.yml
sent 48,320 bytes  received 92 bytes  96,824.00 bytes/sec
total size is 48,100  speedup is 1.00

Atenção: O arquivo acme.json contém chaves privadas dos certificados TLS. Após a transferência, ajuste as permissões no servidor de destino — o Traefik recusa iniciar se as permissões estiverem incorretas:

chmod 600 /opt/traefik/acme.json
chown root:root /opt/traefik/acme.json

Verifique também se o traefik.yml referencia caminhos de arquivo corretos para o novo servidor. Abra o arquivo e confirme as entradas de certificatesResolvers e providers.file:

cat /opt/traefik/traefik.yml

Um exemplo de configuração estática válida para Traefik v3 com Let's Encrypt:

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

certificatesResolvers:
  letsencrypt:
    acme:
      email: [email protected]
      storage: /etc/traefik/acme.json
      httpChallenge:
        entryPoint: web

providers:
  docker:
    exposedByDefault: false
  file:
    directory: /etc/traefik/dynamic/
    watch: true

api:
  dashboard: true
  insecure: true

Etapa 4 — Subir o Traefik no novo servidor e validar rotas

Com os arquivos transferidos e a rede criada, suba o Traefik no servidor de destino. Antes de alterar o DNS, use o arquivo /etc/hosts da sua máquina local para apontar o domínio temporariamente para o novo IP e validar o roteamento sem afetar usuários em produção.

No servidor de destino, acesse o diretório e suba os containers:

cd /opt/traefik
docker compose up -d

[+] Running 2/2
 ✔ Network traefik-net  Created
 ✔ Container traefik    Started

Verifique se o container está em execução e sem erros:

docker ps
docker logs traefik --tail 50

Acesse o dashboard do Traefik na porta 8080 para confirmar que os routers e services foram carregados:

curl -s http://IP_NOVO_SERVIDOR:8080/api/rawdata | python3 -m json.tool | grep '"status"'

Na sua máquina local, adicione uma entrada temporária no /etc/hosts (Linux/macOS) ou C:\Windows\System32\drivers\etc\hosts (Windows):

IP_NOVO_SERVIDOR  seudominio.com www.seudominio.com

Teste o certificado TLS e a resposta HTTP:

curl -I https://seudominio.com

HTTP/2 200
server: traefik
content-type: text/html; charset=utf-8

Se a resposta retornar HTTP/2 200 com o cabeçalho server: traefik, o roteamento está funcionando corretamente no novo servidor. Remova a entrada do /etc/hosts após a validação.

Etapa 5 — Migrar os serviços de aplicação e atualizar o DNS

Com o Traefik validado, transfira os demais serviços (aplicações, bancos de dados, etc.) para o novo servidor seguindo o mesmo processo de cópia de docker-compose.yml e dados persistentes. Para cada serviço, certifique-se de que a rede traefik-net está declarada como externa no docker-compose.yml:

networks:
  traefik-net:
    external: true

E que o container da aplicação está conectado a ela:

services:
  minha-app:
    image: minha-imagem:latest
    networks:
      - traefik-net
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.minha-app.rule=Host(`seudominio.com`)"
      - "traefik.http.routers.minha-app.entrypoints=websecure"
      - "traefik.http.routers.minha-app.tls.certresolver=letsencrypt"

Após validar todos os serviços, atualize o registro A do domínio no painel de DNS para apontar para o IP do novo servidor. Com o TTL já reduzido para 300 segundos, a propagação ocorre em poucos minutos. Você pode acompanhar a propagação com:

watch -n 10 "dig +short seudominio.com @8.8.8.8"

Quando o IP retornado for o do novo servidor, a migração está concluída. Para referência sobre como gerenciar registros DNS do seu domínio, consulte o artigo Como gerenciar um domínio na base de conhecimento da AviraHost.

Atenção: Só desligue o servidor antigo após confirmar que o DNS propagou completamente e que os serviços estão respondendo normalmente pelo novo IP. Mantenha o servidor antigo ativo por pelo menos 24 horas como precaução.

Problemas comuns e como resolver

Sintoma: Traefik não inicia e exibe erro "acme.json: permission denied"

Causa: O arquivo acme.json foi transferido com permissões incorretas. O Traefik exige que esse arquivo tenha permissão 600 e pertença ao usuário que executa o processo (geralmente root em containers).
Solução: Execute chmod 600 /opt/traefik/acme.json && chown root:root /opt/traefik/acme.json no servidor de destino e reinicie o container com docker compose restart traefik. Verifique os logs novamente com docker logs traefik --tail 30.

Sintoma: Rotas aparecem no dashboard mas retornam erro 502 Bad Gateway

Causa: Os containers de aplicação não estão conectados à rede Docker externa traefik-net, ou a rede não foi criada antes de subir os serviços.
Solução: Confirme que a rede existe com docker network ls | grep traefik-net. Se não existir, crie com docker network create traefik-net. Em seguida, verifique se o docker-compose.yml de cada serviço declara a rede como externa e recrie os containers com docker compose down && docker compose up -d.

Sintoma: Certificado TLS inválido ou "certificate signed by unknown authority" após migração

Causa: O Traefik tentou renovar o certificado antes do DNS apontar para o novo servidor, resultando em falha no desafio HTTP-01 do Let's Encrypt. O acme.json pode ter sido sobrescrito com dados inválidos.
Solução: Restaure o acme.json original do backup, certifique-se de que o DNS já aponta para o novo IP e reinicie o Traefik. Se o certificado ainda estiver inválido, remova o conteúdo do acme.json (deixe o arquivo vazio com echo "{}" > acme.json) e deixe o Traefik reemitir automaticamente — isso só funciona se o DNS já estiver propagado.

Sintoma: Dashboard do Traefik acessível mas nenhum router aparece listado

Causa: O provider Docker não está detectando os containers porque eles foram iniciados antes da rede traefik-net ser criada, ou o socket do Docker não está montado corretamente no container do Traefik.
Solução: Verifique se o docker-compose.yml do Traefik monta o socket: volumes: - /var/run/docker.sock:/var/run/docker.sock:ro. Reinicie todos os containers na ordem correta: primeiro o Traefik, depois as aplicações. Use docker compose down && docker compose up -d em cada diretório de serviço.

Sintoma: Redirecionamento HTTP para HTTPS não funciona após migração

Causa: O middleware de redirecionamento estava definido em um arquivo de configuração dinâmica (/etc/traefik/dynamic/) que não foi copiado para o novo servidor.
Solução: Verifique se todos os arquivos do diretório dynamic/ foram transferidos. Liste o conteúdo com ls -la /opt/traefik/dynamic/ e compare com o servidor de origem. Copie os arquivos faltantes e aguarde o Traefik recarregar automaticamente (o watch está ativo por padrão).

Perguntas frequentes sobre migração do Traefik

É possível migrar o Traefik sem derrubar os serviços em produção?

Sim. A estratégia mais segura é manter o servidor antigo ativo enquanto o novo é configurado e testado. Após validar rotas e certificados no novo servidor, você altera o DNS para apontar para o novo IP e só então desliga o ambiente anterior. O TTL baixo no DNS reduz o tempo de transição e minimiza o impacto para os usuários finais.

Os certificados Let's Encrypt do Traefik precisam ser reemitidos na migração?

Não necessariamente. O arquivo acme.json contém todos os certificados emitidos pelo Traefik via ACME. Se você copiar esse arquivo para o novo servidor com as permissões corretas (chmod 600), o Traefik reutilizará os certificados existentes sem precisar reemitir. Certifique-se de que o domínio já aponta para o novo IP antes de iniciar o Traefik — caso contrário, ele tentará renovar e poderá falhar no desafio HTTP-01.

O que acontece com os middlewares e rotas definidos no docker-compose.yml?

Middlewares e rotas definidos via labels no docker-compose.yml são portáteis: basta copiar o arquivo para o novo servidor e executar docker compose up -d. As configurações estáticas em traefik.yml ou traefik.toml também devem ser copiadas. Nenhuma configuração fica armazenada no estado interno do Traefik além do acme.json, o que torna a migração relativamente simples.

Como verificar se o Traefik está roteando corretamente após a migração?

Acesse o dashboard do Traefik (por padrão na porta 8080) e verifique se todos os routers e services aparecem com status verde. Você também pode usar curl -I https://seudominio.com para confirmar que o certificado TLS é válido e que a resposta vem do novo servidor. Cheque os logs com docker logs traefik para identificar erros de roteamento ou falhas de certificado.

Preciso recriar a rede Docker externa ao migrar o Traefik?

Sim. A rede Docker externa usada pelo Traefik (geralmente chamada de traefik-net ou web) não é exportada com o docker-compose.yml. No novo servidor, crie a rede manualmente com docker network create traefik-net antes de executar docker compose up -d. Todos os containers que precisam ser roteados pelo Traefik devem estar conectados a essa mesma rede externa.

Conclusão

Migrar o Traefik para um novo servidor sem perder rotas é um processo estruturado que depende de três pilares: backup correto dos arquivos de configuração, preparação adequada do ambiente de destino e validação antes de alterar o DNS. Seguindo as etapas deste tutorial, você garante continuidade dos serviços em produção. Para aprofundar o gerenciamento do seu ambiente Linux, consulte também o artigo Dicas de Otimização de Servidores Linux.

• Reduza o TTL do DNS para 300 segundos pelo menos 24 horas antes da migração para acelerar a propagação após a troca de IP.
• Valide rotas e certificados via /etc/hosts antes de alterar o DNS público, evitando expor usuários a erros durante a transição.
• Mantenha o servidor antigo ativo por 24 horas após a migração como contingência, desligando-o somente após confirmar que o tráfego está fluindo normalmente pelo novo ambiente.

Leia também

• Solucionar erro de Traefik ao rotear containers Docker no Debian 12
• Solucionar problemas de migração de hospedagem sem downtime: passo a passo
• O que é Servidor Proxy Reverso e Como Configurá-lo

Precisa de ajuda com migração de containers e Traefik?

Configurar e migrar ambientes Docker com Traefik exige atenção a detalhes de rede, permissões e DNS que podem ser desafiadores sem a infraestrutura certa. Um VPS com recursos adequados e suporte técnico especializado facilita esse processo e reduz o risco de downtime.

Conheça os planos de VPS da AviraHost e migre seu Traefik com segurança