Tailscale no Docker em loop? Como migrar para a instalação nativa no Linux sem perder o acesso remoto

Categoria: Linux, Docker, Redes e Acesso Remoto
Equipamento utilizado: Orange Pi OPI03
Sistema operacional: Debian Bookworm / Armbian
Software: Tailscale 1.104.2
Dificuldade: Intermediária

Introdução

O Tailscale é uma solução prática para conectar dispositivos Linux, Windows, servidores e equipamentos domésticos por meio de uma rede privada baseada no WireGuard.

Entretanto, quando executado em um container Docker, problemas de configuração, persistência do estado ou conectividade podem fazer com que o serviço entre em um ciclo de falhas, dificultando o diagnóstico e a manutenção.

Neste tutorial, mostro como migrar uma instalação do Tailscale em Docker para a instalação nativa no Linux, como resolver problemas de autenticação e como limpar registros duplicados no painel administrativo.

O procedimento foi baseado em um caso real ocorrido em um Orange Pi OPI03.

1. Entendendo a diferença entre Tailscale no Docker e no host

Antes de começar, é importante diferenciar três conceitos:

• IP da rede local: endereço atribuído ao equipamento na rede doméstica, como 192.168.31.31.
• IP interno do Docker: endereço privado utilizado pela rede de containers, frequentemente pertencente a faixas como 172.17.0.0/16.
• IP do Tailscale: endereço atribuído ao dispositivo na rede privada Tailscale, geralmente pertencente à faixa 100.64.0.0/10.

Ao executar o Tailscale em um container, a identidade e o endereço associados ao dispositivo dependem da configuração e da persistência do estado do cliente.

Na instalação nativa, o Tailscale passa a funcionar diretamente no sistema operacional. Se a identidade anterior não for preservada, o novo cliente poderá ser registrado como outro dispositivo e receber um IP diferente.

Importante: não confunda o IP interno do Docker com o IP do Tailscale. São endereços utilizados para finalidades diferentes.

2. Instalando o Tailscale nativamente no Debian

No Orange Pi OPI03, que utiliza Debian Bookworm, a instalação foi realizada pelo script oficial do Tailscale.

Execute:

curl -fsSL https://tailscale.com/install.sh | sh

O instalador configura o repositório oficial, atualiza a lista de pacotes e instala o cliente.

Após a instalação, o serviço tailscaled é habilitado pelo systemd.

Confira o estado do serviço:

systemctl status tailscaled --no-pager

Para verificar se o serviço está ativo e habilitado na inicialização:

systemctl is-active tailscaled
systemctl is-enabled tailscaled

Os resultados esperados são active e enabled, respectivamente.

3. Primeira autenticação

Inicie a conexão com o Tailscale:

tailscale up

Se o dispositivo ainda não estiver autenticado, o cliente normalmente exibirá um endereço para concluir o login pelo navegador.

Após autorizar o dispositivo, verifique a conexão:

tailscale status
tailscale ip -4

Se aparecer Logged out ou NeedsLogin, a autenticação ainda não foi concluída.

Não remova imediatamente o registro antigo do painel. Primeiro, confirme qual dispositivo está funcionando e qual identidade está sendo utilizada.

4. Quando o Tailscale apresenta erro de autenticação ou conexão

Durante a migração do OPI03, o cliente apresentou a seguinte mensagem:

You are logged out.
The last login error was:
register request: Post "https://controlplane.tailscale.com/machine/register":
read: connection reset by peer

Os logs também indicaram:

machineAuthorized=false
authURL=true

Isso significa que o cliente recebeu uma URL de autenticação, mas não conseguiu concluir o registro naquele momento.

O erro connection reset by peer indica que a conexão TCP foi encerrada inesperadamente. Ele não prova, isoladamente, que o problema está no Tailscale: firewall, roteador, proxy, filtragem de tráfego ou problemas temporários de rede também podem contribuir.

4.1. Testando a conectividade

Execute:

curl -sS -o /dev/null \
  --connect-timeout 8 --max-time 15 \
  -w 'HTTP %{http_code}\n' \
  https://controlplane.tailscale.com/key?v=148

Uma resposta HTTP indica que houve comunicação com o servidor. Erros de conexão ou timeout exigem investigação adicional.

Também é possível testar a porta HTTP:

curl -sS -o /dev/null \
  --connect-timeout 8 --max-time 15 \
  -w 'HTTP %{http_code}\n' \
  http://controlplane.tailscale.com/

Uma resposta HTTP, mesmo com código 301, 400 ou 404, é diferente de uma conexão que não consegue ser estabelecida.

Esses testes são indicativos: uma resposta HTTP não garante, por si só, que todas as etapas de registro do Tailscale funcionarão.

4.2. Solicitando uma nova autenticação

Se a conectividade estiver funcionando, mas o cliente continuar desconectado, tente:

tailscale up --force-reauth

Esse comando força uma nova autenticação. Se for apresentado um endereço de login, abra-o no navegador e conclua o processo.

Depois, execute:

tailscale status
tailscale ip -4

No meu caso, a autenticação foi concluída e o dispositivo voltou a funcionar.

Atenção: não utilize tailscale up --reset repetidamente sem necessidade. Esse comando redefine as preferências de execução do cliente e pode complicar o diagnóstico se você não souber quais opções estavam configuradas.

Se o problema persistir, consulte os logs:

journalctl -u tailscaled -n 50 --no-pager

Antes de reinstalar o software, verifique a conectividade e identifique o erro exato.

5. Como resolver dispositivos duplicados no painel

Após a migração, o painel administrativo apresentou registros associados ao OPI03 com nomes e IPs diferentes.

Isso pode acontecer quando uma nova instalação é autenticada sem reutilizar a identidade anterior do cliente.

No meu caso, foram observados estes endereços durante a migração:

Esses endereços são específicos do meu ambiente e servem apenas como exemplo.

Procedimento seguro

1. No Linux, execute tailscale status e tailscale ip -4.
2. Acesse o painel administrativo: https://login.tailscale.com/admin/machines
3. Compare os dispositivos listados com o IP retornado pelo cliente atual.
4. Identifique os registros antigos e verifique se algum outro equipamento ou serviço ainda depende deles.
5. Remova somente os registros que você confirmou serem obsoletos.

Não exclua um dispositivo apenas porque ele tem um nome parecido com outro. Confirme o IP, o estado de conexão e a identidade antes de removê-lo.

Remover um registro antigo não garante que seu endereço IP será atribuído novamente ao dispositivo novo.

6. Verificação final da instalação

Depois de concluir a autenticação e a limpeza do painel, execute:

systemctl is-enabled tailscaled
systemctl is-active tailscaled
tailscale status
tailscale ip -4

No meu OPI03, o resultado final foi:

• Instalação nativa no Debian Bookworm.
• Serviço tailscaled ativo e habilitado.
• Autenticação concluída.
• Nome do dispositivo restaurado para opi03.
• IP Tailscale final: 100.91.183.85.
• Registros conferidos no painel administrativo.

Com isso, a migração foi concluída.

7. Como evitar problemas em futuras reinstalações

Para reduzir a possibilidade de perder a identidade do dispositivo:

• Mantenha o estado do Tailscale persistente quando utilizar Docker.
• Antes de remover um container, identifique o volume ou diretório que armazena o estado do cliente.
• Não presuma que uma nova instalação no host reutilizará automaticamente a identidade do container.
• Utilize o MagicDNS, quando habilitado, para acessar dispositivos pelo nome em vez de depender diretamente do IP.
• Antes de excluir um registro antigo, verifique se há scripts, conexões SSH, integrações ou serviços que ainda utilizam o endereço anterior.

FAQ — Perguntas frequentes sobre Tailscale no Docker e Linux

Dica extra: como manter o IP antigo do Tailscale após a migração

Durante os testes, encontrei uma alternativa para manter o IP Tailscale utilizado antes de migrar do Docker para a instalação nativa no Linux.

No painel administrativo do Tailscale, acesse:

1. Machines — abra a lista de dispositivos.
2. Localize o dispositivo desejado e clique nos três pontinhos (...).
3. Selecione Edit machine IPv4.
4. Informe o endereço IPv4 que deseja utilizar e confirme em Update IP.

No meu caso, utilizei essa opção para voltar ao IP anterior do OPI03, 100.74.55.26, evitando precisar atualizar imediatamente os serviços e scripts que dependiam desse endereço.

Atenção: o painel alerta que essa alteração interrompe as conexões existentes com o dispositivo. Pode ser necessário reconectar os clientes ou limpar o cache DNS. Antes de aplicar a mudança, confirme que o endereço desejado está disponível e que a alteração é permitida na configuração do seu tailnet.

Após a alteração, verifique o endereço atribuído no próprio Linux:

tailscale ip -4
tailscale status

Por fim, teste a conectividade a partir de outro dispositivo da rede Tailscale.

Essa alternativa pode facilitar migrações em ambientes que dependem de IPs fixos, mas confirme sempre o resultado no cliente e no painel antes de considerar o procedimento concluído.

Conclusão

A migração do Tailscale do Docker para o Linux nativo resolveu o problema de execução que eu estava enfrentando no Orange Pi OPI03.

Durante o processo, foi necessário concluir uma nova autenticação, investigar uma falha de conexão com o plano de controle e remover os registros antigos que não eram mais necessários.

A principal lição é simples: antes de reinstalar ou excluir dispositivos, preserve as informações de estado, verifique a conectividade e confirme qual identidade está realmente ativa.

Espero que este relato ajude outros usuários que estejam enfrentando problemas semelhantes com Tailscale, Docker e Linux.

HobbyTestLab.com — testes, tutoriais e soluções práticas para tecnologia.

Montando ou otimizando um computador de placa única?

Descubra mais guias sobre computadores de placa única e dicas de desempenho →