A publicação de origem reúne os elementos essenciais para registar um cliente Tailscale Docker no ZimaOS num plano de controlo Headscale autoalojado: estado persistente, uma chave de utilização única/pré-autenticação, o URL personalizado do Headscale, acesso TUN e as capacidades necessárias do contentor.
A documentação atual da Tailscale e do Headscale fornece agora um contrato upstream mais claro. A Tailscale suporta oficialmente um URL de servidor de controlo personalizado, e o Headscale documenta tanto o registo interativo como o registo com uma chave de pré-autenticação. Utilize esses métodos upstream para validar o comando/URL atual, em vez de depender apenas de uma captura de ecrã de 2025.
O Headscale substitui o plano de controlo de coordenação da Tailscale
O Headscale é uma implementação autoalojada do protocolo do servidor de controlo da Tailscale. Os clientes Tailscale continuam a criar túneis ponto a ponto encriptados, mas o registo e a coordenação são tratados pela instância Headscale do utilizador, em vez do plano de controlo predefinido da Tailscale.
Manter o diretório de estado do Tailscale
A fonte criou /DATA/AppData/tailscale/state e mapeou-o para /var/lib/tailscale. Isto é importante porque a identidade/o estado do nó deve persistir após a recriação do contentor e o reinício do anfitrião.
A fonte também recomendava permissões restritivas no diretório de estado do anfitrião. Isso é sensato, porque o estado faz parte da identidade do nó e não deve estar acessível a todos.
Utilizar o URL do Headscale como servidor de controlo personalizado
A documentação atual da Tailscale permite utilizar servidores de controlo personalizados através de:
tailscale login --login-server=<URL>A documentação do próprio Headscale utiliza o mesmo modelo com tailscale up --login-server <YOUR_HEADSCALE_URL>.
Consulte as orientações atuais da Tailscale para servidores de controlo personalizados.
Utilizar uma chave de pré-autenticação para o registo não interativo
A fonte adicionou temporariamente TS_AUTHKEY, registou o nó e, em seguida, removeu a variável. Atualmente, o Headscale documenta a criação de uma chave de pré-autenticação e a sua utilização com --authkey para o registo não interativo.
Utilize os métodos de registo atuais do Headscale.
Não deixe uma chave de autenticação reutilizável na definição da aplicação
Se a chave for reutilizável ou tiver uma validade longa, deixá-la no ambiente da aplicação ZimaOS cria uma exposição desnecessária. Depois de a identidade do nó ser armazenada com êxito, remova o segredo de registo quando já não for necessário.
Se uma chave foi publicada num fórum público ou numa captura de ecrã, revogue-a e crie uma nova.
O TUN do kernel e as capacidades afetam o modo de rede
A origem mapeia /dev/net/tun e concede NET_ADMIN/NET_RAW, que corresponde ao estilo de rede do kernel, em vez de uma rede exclusivamente userspace.
Os contentores Tailscale atuais também podem operar no modo userspace, por isso escolha deliberadamente o modo com base na necessidade de encaminhamento de sub-redes, comportamento de exit node ou rede completa do kernel.
A rede do host é poderosa
A origem utiliza a rede do host do Docker. Isto elimina o isolamento normal das portas do contentor e faz com que o Tailscale opere diretamente no namespace de rede do host.
Não altere de host para bridge — ou vice-versa — sem compreender como a aplicação Tailscale atual armazena as rotas, os listeners e os serviços anunciados.
O URL do Headscale deve estar acessível de forma fiável e devidamente protegido
Um servidor de controlo autoalojado torna-se uma infraestrutura crítica. Utilize DNS estável, uma configuração TLS válida e cópias de segurança da base de dados/configuração do Headscale. Se o servidor de controlo desaparecer, os pares existentes poderão continuar a comunicar temporariamente, mas os novos registos e as alterações de coordenação deixarão de estar disponíveis.
A origem é uma configuração funcional, não um contrato de suporte da IceWhale
A publicação não tem confirmação da equipa da IceWhale. É uma configuração da comunidade que está bem alinhada com os conceitos do Tailscale/Headscale upstream, mas ainda deve ser testada com o pacote Tailscale atual do ZimaOS.
Perguntas frequentes sobre o Headscale no ZimaOS
Os clientes Tailscale podem utilizar um servidor de controlo Headscale personalizado?
Sim. A documentação atual do Tailscale suporta oficialmente URLs de servidores de controlo personalizados.
A TS_AUTHKEY deve permanecer na aplicação para sempre?
Não. A origem removeu-a após o registo, e os segredos de registo de longa duração não devem ficar desnecessariamente expostos.
Porquê persistir /var/lib/tailscale?
Mantém a identidade/estado do nó do Tailscale após a recriação do contentor e o reinício.
