Ir para o conteúdo
Promovaweb

Tailscale em Docker e no WSL 2

Revisado em

Docker e WSL 2 acrescentam um segundo ambiente de rede ao lado do host. O cliente Tailscale pode viver dentro desse ambiente ou fora dele, e essa escolha define qual identidade aparece na tailnet, qual endereço responde e onde cada consulta precisa ser feita.

Nos dois casos desta página existe um host e um ambiente dentro dele. No Docker, o container oficial do Tailscale registra uma identidade própria na tailnet, separada da máquina que executa o Docker. No WSL 2, a distribuição Linux roda ao lado do Windows. A documentação do Tailscale recomenda que o cliente fique no Windows.

A consequência prática é a mesma: uma consulta feita no lugar errado descreve outro cliente. tailscale status no host não consulta o container. O aplicativo conectado no Windows não comprova que uma aplicação dentro da distribuição aceita conexões. Por isso, cada seção abaixo mostra onde a consulta precisa ser feita.

Container Docker com estado persistente

O container oficial executa o cliente Tailscale e registra uma identidade na tailnet. O registro e a persistência do estado são as primeiras partes a observar, porque a aplicação que você pretende conectar recebe uma configuração de rede própria, separada desse registro.

Auth key fora do Git

O registro sem navegador usa uma auth key. Para um exemplo persistente, a opção de dispositivo efêmero fica desativada. A chave vai para um arquivo local chamado tailscale.env, fora do Git:

TS_AUTHKEY=SUBSTITUA_PELA_SUA_AUTH_KEY

No Linux, chmod 600 tailscale.env limita a leitura do arquivo. O valor continua acessível à administração do Docker, então o arquivo, a saída de inspeção do container e a chave não podem aparecer em comentários e capturas.

Volume de estado e modo userspace

O exemplo usa o modo userspace, sem interface TUN. A imagem latest acompanha atualizações. Num ambiente mantido por você vale fixar a versão ou o digest depois da sua validação.

Terminal
docker volume create tailscale-state
docker run -d \
--name tailscale-guia \
--env-file ./tailscale.env \
-e TS_HOSTNAME=docker-guia \
-e TS_STATE_DIR=/var/lib/tailscale \
-e TS_AUTH_ONCE=true \
-e TS_USERSPACE=true \
-v tailscale-state:/var/lib/tailscale \
--restart unless-stopped \
tailscale/tailscale:latest

O volume mantém a identidade do dispositivo. A opção TS_AUTH_ONCE evita autenticar novamente uma identidade já válida a cada inicialização. Depois do primeiro registro, a chave pode sair da configuração quando o container é recriado com o mesmo volume e o estado autenticado.

Registro e reinício pelo docker exec

A máquina docker-guia aparece em Machines no painel administrativo. No host, as consultas passam pelo docker exec, porque o cliente está dentro do container:

Terminal
docker exec tailscale-guia tailscale status
docker exec tailscale-guia tailscale ip -4
docker restart tailscale-guia
docker exec tailscale-guia tailscale status

Depois do reinício, o registro original continua presente e o endereço permanece associado a ele. Uma nova máquina no painel indica um problema no volume ou no caminho do estado.

Quando a inicialização falha, os registros recentes e os volumes montados mostram a causa:

Terminal
docker logs --tail 50 tailscale-guia
docker inspect --format '{{json .Mounts}}' tailscale-guia

O segundo comando restringe a inspeção aos volumes. O destino /var/lib/tailscale precisa apontar para o volume esperado. Uma inspeção completa expõe as variáveis de ambiente, que podem conter a auth key. Os logs também precisam de revisão antes de qualquer compartilhamento.

Um volume vazio, um caminho alterado ou uma autenticação ainda pendente explicam comportamentos diferentes. A causa identificada se corrige antes de recriar o container. O estado persistido contém material de autenticação do dispositivo, então o backup dele precisa de acesso restrito. Excluir esse estado muda as condições para retomar a identidade, mesmo com o mesmo nome de container.

A aplicação ao lado do cliente

Este container registra o cliente e não publica automaticamente as portas de outros containers. A integração de uma aplicação usa o compartilhamento do namespace de rede, descrito no exemplo oficial de Docker Compose. O modo kernel exige TUN e permissões adicionais. docker stop tailscale-guia encerra o exemplo. O volume preservado permite retomar a mesma identidade.

WSL 2 e o cliente do Windows

A documentação do Tailscale recomenda executar o cliente no Windows quando você usa WSL 2. Outro túnel dentro da distribuição pode causar problemas de tamanho de pacote quando o tráfego passa pelos dois clientes. O host Windows, portanto, é o primeiro lugar a conectar e a conferir.

Distribuição e cliente do host

No PowerShell, wsl -l -v mostra a versão do WSL usada por cada distribuição. A coluna VERSION precisa indicar 2. A instalação do WSL segue a documentação da Microsoft listada nas fontes.

Com o aplicativo autenticado conforme a instalação no Windows, o PowerShell confere o estado e testa outro dispositivo:

Terminal
tailscale status
tailscale ping nome-do-destino

O ping confirma o caminho do Tailscale. A aplicação ainda depende da porta, da autenticação e das permissões. O teste do serviço real vem depois.

O processo que precisa responder

Um serviço dentro do WSL possui endereço de escuta e configuração próprios. O cliente conectado no Windows não confirma que uma aplicação Linux está disponível para outras máquinas. Um servidor aberto no terminal da distribuição pertence ao Linux. Dentro dela, as portas em escuta aparecem com:

Terminal
ss -lnt

O endereço de escuta importa. Um processo limitado a 127.0.0.1 recebe conexões pelo loopback daquele ambiente. O acesso a partir do Windows e de outra máquina depende também do modo de rede do WSL e das permissões do host. A escuta em todas as interfaces só faz sentido depois de definido o alcance desejado.

A investigação segue por partes: primeiro o serviço abre no ambiente que o executa, depois pelo Windows e por último a partir de outro dispositivo da tailnet. Quando só o último teste falha, o encaminhamento e o firewall do host são os pontos a conferir. Quando o acesso funciona pelo IP e falha pelo nome, o DNS do ambiente Linux vem antes de qualquer outro cliente. O caso de nome que não resolve detalha a comparação. Um segundo cliente Linux não corrige uma aplicação parada.

Uma identidade Linux separada

A instalação dentro do WSL 2 é uma alternativa avançada documentada pelo fabricante. Ela faz sentido depois de revisar o caminho de rede e a limitação dos túneis sobrepostos. O pacote Linux vem do procedimento oficial da distribuição. A autenticação usa sudo tailscale up.

No painel, um nome que identifique a máquina como WSL a diferencia do host. Durante os testes, vale registrar qual cliente está ativo. Para voltar ao uso somente no Windows, sudo tailscale down desconecta o cliente Linux. A conferência se repete no host.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.