Um contentor Tailscale permanente deve continuar a representar a mesma máquina na consola de administração do Tailscale após um reinício do ZimaOS ou uma edição da aplicação. No tópico da fonte, de setembro de 2025, isso não estava a acontecer: cada reinício ou nova implementação criava outro nó Tailscale, apesar de o ficheiro Compose já montar /var/lib/tailscale para a AppData persistente do ZimaOS.
O resultado final da fonte é importante porque restringe a causa. O autor original afirmou que o armazenamento persistente já estava correto; eliminar a variável de ambiente da chave de autenticação fornecida continuamente foi a única alteração necessária. Depois disso, a identidade do nó Tailscale passou a persistir.
O Tailscale necessita de um estado persistente da máquina
O Tailscale armazena a identidade do nó, as chaves e o estado da ligação no respetivo diretório de estado. No Docker, o caminho é normalmente configurado com:
TS_STATE_DIR=/var/lib/tailscaleSe esse diretório existir apenas no sistema de ficheiros descartável do contentor, recriar o contentor cria uma identidade Tailscale nova.
A fonte já montava o diretório de estado
O ficheiro Compose original incluía:
/DATA/AppData/tailscale:/var/lib/tailscalejuntamente com TS_STATE_DIR=/var/lib/tailscale, rede do anfitrião, NET_ADMIN, NET_RAW, e acesso a /dev/net/tun. Em teoria, isso deveria preservar o estado.
Uma chave de autenticação serve para o registo inicial, não necessariamente para todos os reinícios
O ficheiro Compose também fornecia TS_AUTHKEY em cada arranque do contentor. Um membro da comunidade explicou que a reautenticação pode criar uma máquina nova quando o estado do nó existente não está a ser reutilizado conforme esperado.
O autor da resposta sugeriu utilizar uma chave de autenticação reutilizável e não efémera no primeiro arranque, aguardar que o nó aparecesse na consola de administração, remover depois a linha da chave de autenticação e voltar a implementar, para que o estado guardado da máquina passasse a ser a fonte da identidade.
O autor original confirmou que remover a chave de autenticação resolveu o problema
A resposta final da fonte indica que os outros elementos de persistência já estavam configurados e que apenas era necessário eliminar a variável de ambiente da chave de autenticação. O nome da máquina passou então a persistir entre reinícios.
Essa confirmação é mais sólida do que uma suposição genérica sobre permissões. Nesta instalação específica, a autenticação repetida foi o fator prático que desencadeou o problema.
A versão atual do Tailscale fornece TS_AUTH_ONCE
As implementações modernas do Tailscale em Docker podem utilizar TS_AUTH_ONCE=true. Quando já existe um estado persistente, isto indica ao contentor que não deve forçar outro início de sessão sempre que arranca.
Consulte os parâmetros atuais de estado e autenticação da Tailscale no Docker antes de reutilizar inalteradamente um ficheiro Compose de 2025.
Utilize uma pasta dedicada do anfitrião para o estado
Um diretório dedicado no anfitrião, como uma pasta AppData/estado da Tailscale, facilita a verificação de que as chaves da máquina sobrevivem à reimplementação. O respondente da fonte também recomendou garantir que a pasta tem permissões de escrita para o processo que armazena o estado da Tailscale.
As permissões são importantes porque um volume pode estar montado corretamente e, ainda assim, o processo não conseguir atualizar os respetivos ficheiros. Nessa situação, a Tailscale pode comportar-se como se a máquina não tivesse estado reutilizável.
Evite chaves de autenticação efémeras para um servidor permanente
A Tailscale suporta nós efémeros, intencionalmente temporários. Isso é útil para tarefas de CI de curta duração ou contentores descartáveis, mas é o oposto do que um servidor ZimaOS permanente necessita.
Ao criar uma credencial, verifique se corresponde ao ciclo de vida pretendido. Um servidor doméstico persistente deve normalmente manter a mesma identidade até que a revogue ou substitua deliberadamente.
TS_HOSTNAME não define a identidade da máquina
O contentor da fonte utilizava TS_HOSTNAME=zimaos. Essa definição controla o nome amigável apresentado à tailnet, mas preservar a mesma cadeia de nome do anfitrião não preserva a identidade criptográfica da máquina. Duas máquinas autenticadas recentemente podem tentar utilizar nomes semelhantes e, ainda assim, ser nós separados.
Teste o reinício e a reimplementação da aplicação
O problema original ocorreu após reinícios completos do sistema operativo e edições da aplicação ZimaOS. Uma correção correta deve, portanto, resistir a ambos:
- reinicie o contentor Tailscale;
- edite e implemente novamente a aplicação sem alterar o volume de estado;
- reinicie o ZimaOS;
- verifique se a mesma máquina continua online na consola de administração da Tailscale.
Se surgir um duplicado após apenas um desses eventos, compare o que acontece ao diretório de estado durante essa operação específica do ciclo de vida.
FAQ da Tailscale persistente
Porque foi criada uma nova máquina Tailscale após cada reinício?
No caso da fonte, o volume de estado já existia e a utilização repetida da chave de autenticação era o problema prático que restava.
Que caminho tem de persistir?
O caminho configurado por TS_STATE_DIRnormalmente /var/lib/tailscale dentro do contentor.
A TS_AUTHKEY deve permanecer no ambiente para sempre?
Não necessariamente. O utilizador da fonte corrigiu os nós duplicados removendo-o após o registo, e a Tailscale atual também disponibiliza TS_AUTH_ONCE.
TS_HOSTNAME preserva a identidade do nó?
Não. O estado da máquina Tailscale armazenado é o que preserva a identidade.
