Como hospedar o Trilium Notes por conta própria em 2026: diretório de dados, WebSockets e backups

Um contêiner do Trilium Notes pode estar verde enquanto a tarefa que realmente importa para os usuários está quebrada. No Trilium Notes, essa falha oculta geralmente significa que o diretório de dados foi montado no caminho errado ou não tem permissão de escrita. Este guia trata “criar notas vinculadas, adicionar um anexo e uma relação, pesquisar por eles e verificar o histórico de revisões após uma reinicialização” como o teste de aceitação e estrutura a implantação de trás para frente a partir desse resultado.

O Trilium Notes tem uma função específica na stack: uma base de conhecimento pessoal em formato de árvore. Portanto, a pergunta para produção não é se a porta 8080 responde uma vez, mas se o estado, as dependências e o endereço público continuam de acordo após uma reinicialização, atualização e restauração.

Mapeie o Trilium Notes antes de tocar no Docker

O processo HTTP do Trilium Notes escuta na porta 8080; mantenha essa porta na rede da aplicação e publique apenas a rota da plataforma. O requisito de runtime local é um diretório de dados durável e memória suficiente para a indexação. Valide isso com a carga de trabalho de aceitação; um health check ocioso não consegue provar que o recurso é suficiente.

Registre o limite em um contrato curto: quem é responsável pelo requisito, qual credencial é usada, qual timeout é aceitável e como a falha se manifesta. Em seguida, execute esta transação: crie notas vinculadas, adicione um anexo e uma relação, pesquise por eles e verifique o histórico de revisões após uma reinicialização. Observe a indexação de notas, o tamanho dos anexos, os scripts e o crescimento de document.db durante a execução, pois essa carga de trabalho fornece um tamanho inicial mais útil do que um contêiner ocioso.

Teste o Trilium Notes de fora do servidor

Exponha um único hostname HTTPS para o Trilium Notes; mantenha a porta 8080 bruta privada. Publique a interface web por HTTPS com WebSockets preservados. Isso impede que navegadores e clientes de API conheçam dois endereços concorrentes.

A partir de um cliente limpo, execute a transação conhecida como válida e inspecione a primeira requisição que falhar. Use o guia de domínio personalizado quando houver problemas de DNS ou TLS. Trate “o diretório de dados foi montado no caminho errado ou não tem permissão de escrita” como um diagnóstico separado da aplicação depois que a rota estiver comprovada.

Inicie o Trilium Notes com padrões observáveis

Uma inicialização com formato de produção é intencionalmente simples: estado nomeado, porta explícita e nenhum segredo dentro da imagem.

docker run -d \
  --name trilium-notes \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v trilium-notes-data:/home/node/trilium-data \
  -e TRILIUM_DATA_DIR=/home/node/trilium-data \
  triliumnext/notes:latest

O exemplo é uma base, não uma stack de suporte completa. Confirme o requisito local antes da exposição: um diretório de dados durável e memória suficiente para a indexação. Verifique os mounts efetivos e o listener, depois tente criar notas vinculadas, adicionar um anexo e uma relação, pesquisar por eles e verificar o histórico de revisões após uma reinicialização. Fixe a imagem que está funcionando antes da próxima reinicialização.

Monitore a carga de trabalho, não apenas o contêiner

Observe o trabalho realizado pelo Trilium Notes: indexação de notas, tamanho dos anexos, scripts e crescimento de document.db. Defina limites com margem para esse trabalho e evite um liveness probe que concorra com ele. A verificação operacional ainda deve tentar criar notas vinculadas, adicionar um anexo e uma relação, pesquisar por eles e verificar o histórico de revisões após uma reinicialização em uma programação definida.

Para atualizações, lembre-se de que as migrações, os scripts e as extensões de tema do TriliumNext devem ser testados em um diretório de dados duplicado. Implante o candidato sobre uma cópia recuperada e repita o teste conhecido. Se o diretório de dados tiver sido montado no caminho errado ou não tiver permissão de escrita, use os logs de runtime e a requisição de rede real para descobrir qual suposição mudou.

O que deve passar antes que os dados reais do Trilium Notes cheguem

O registro de release do Trilium Notes precisa de fatos, não de um “parece bom”. Armazene o digest da imagem selecionada, o checksum da configuração, o hostname público e um resultado com timestamp para: criar notas vinculadas, adicionar um anexo e uma relação, pesquisar por eles e verificar o histórico de revisões após uma reinicialização. Use dados de exemplo que não sejam de produção para que a verificação possa ser executada após cada implantação.

Comprove dois eventos de ciclo de vida separadamente. A substituição de um contêiner deve preservar a operação normal; uma recuperação limpa deve mostrar que as notas, relações, anexos, atributos e revisões retornam e que a pesquisa conhecida encontra a mesma nota. Enquanto as verificações são executadas, meça a indexação de notas, o tamanho dos anexos, os scripts e o crescimento de document.db, e mantenha o resultado como o envelope esperado para essa versão.

Teste também uma condição negada ou inválida: envie uma entrada inofensiva próxima do limite de recurso ou formato associado a este limite: o diretório de dados foi montado no caminho errado ou não tem permissão de escrita. O Trilium Notes deve falhar de maneira diagnosticável e não deve sobrescrever um estado saudável. Restaure a condição válida, execute novamente o exemplo e anexe os logs relevantes com os dados confidenciais ocultados. Esses artefatos fornecem evidências concretas para uma futura decisão de rollback.

Faça backup do estado que o Trilium Notes não consegue recriar

Defina o recovery point e o recovery time do Trilium Notes em termos de document.db, anexos, revisões e configuração. Monte /home/node/trilium-data antes do bootstrap, grave dados de exemplo inofensivos e substitua o contêiner para comprovar que esse caminho é realmente persistente. Um volume nomeado resolve a persistência em redeploy; não resolve um comprometimento nem a perda do servidor.

Crie um ambiente de restauração limpo, use a mesma versão fixada da aplicação e comprove que as notas, relações, anexos, atributos e revisões retornam e que a pesquisa conhecida encontra a mesma nota. Registre os comandos, as correções de ownership e o tempo decorrido. O guia de backup é um padrão útil: um backup só é confiável depois da restauração, não depois do upload.

Escolha o limite de confiança do Trilium Notes

Feche a janela de bootstrap assim que existir o primeiro administrador confiável. A armadilha concreta do Trilium Notes é expor uma base de conhecimento pessoal sem um login forte; o limite mais seguro é tratar o notebook como dados privados, exigir um login forte e não expor um sistema de arquivos mais amplo do que o diretório de dados.

TRILIUM_DATA_DIR controla o comportamento, não a confidencialidade; valide seu tipo e valor e armazene as credenciais reais do Trilium Notes separadamente. A rede privada deve transportar as credenciais das dependências, e as roles dentro do Trilium Notes devem conceder a menor ação útil. Mantenha os corpos de requisições sensíveis e as respostas dos provedores fora dos logs rotineiros.

O que o Dockup deve automatizar para o Trilium Notes

Para o Trilium Notes, o Dockup pode criar a rota e o certificado TLS, preservar os mounts, entregar secrets e disponibilizar um diretório de dados durável e memória suficiente para a indexação em uma rede privada, durante a implantação no Dockup ou em servidores conectados.

O release gate ainda é a transação concreta do Trilium Notes: criar notas vinculadas, adicionar um anexo e uma relação, pesquisar por eles e verificar o histórico de revisões após uma reinicialização. Verifique também a condição de restauração — as notas, relações, anexos, atributos e revisões retornam e a pesquisa conhecida encontra a mesma nota. Essas duas verificações mostram se a implantação funciona e se pode ser recuperada.

Perguntas frequentes

O que o Trilium Notes precisa para uma implantação em produção?

Encaminhe o contêiner do Trilium Notes na porta 8080 por meio de uma única origem HTTPS. O requisito de runtime local é um diretório de dados durável e memória suficiente para a indexação. Não considere o Trilium Notes pronto até conseguir criar notas vinculadas, adicionar um anexo e uma relação, pesquisar por eles e verificar o histórico de revisões após uma reinicialização.

Quais dados do Trilium Notes devem fazer parte de um backup?

Persista /home/node/trilium-data e inclua document.db, anexos, revisões e configuração no mesmo manifesto de recuperação. Uma restauração limpa do Trilium Notes só passa quando as notas, relações, anexos, atributos e revisões retornam e a pesquisa conhecida encontra a mesma nota.

O Trilium Notes exige HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do Trilium Notes e mantenha a porta 8080 na rota interna. Aplique corretamente a configuração do Trilium Notes: publique a interface web por HTTPS com WebSockets preservados. No Trilium Notes, o HTTPS protege as credenciais ou o conteúdo dos usuários durante o trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como uma atualização do Trilium Notes deve ser testada?

Restaure o estado atual do Trilium Notes em uma implantação isolada, aplique a versão candidata e repita sua transação de aceitação. Tenha atenção especial, pois as migrações, os scripts e as extensões de tema do TriliumNext devem ser testados em um diretório de dados duplicado. Mantenha a imagem anterior do Trilium Notes até entender os limites de migração de dados e rollback.