Guia de correção do Docker para o Matrix Synapse com estado não saudável no CasaOS

Se o Matrix Synapse no CasaOS apresentar a mensagem «container is unhealthy», comece pelos registos do contentor e pelo homeserver.yaml gerado, em vez de reinstalar sem analisar. O Synapse tem uma imagem Docker oficial, mas um homeserver de produção também precisa de configuração e dados persistentes, de um nome de servidor adequado, do PostgreSQL e de um planeamento para HTTPS/federação.

O SQLite é aceitável para testes, mas a documentação atual do Synapse recomenda o PostgreSQL para quase todas as instalações reais. Um contentor pode iniciar e, ainda assim, continuar não saudável quando a configuração, a base de dados, as permissões ou a migração inicial falham.

Utilizar a imagem oficial do Synapse

O guia de instalação do Synapse atual documenta ghcr.io/element-hq/synapse como uma imagem de contentor oficial.

Gerar a configuração inicial

Crie um diretório persistente e gere a configuração uma vez antes do arranque normal:

mkdir -p /DATA/AppData/synapse
docker run --rm -it   -v /DATA/AppData/synapse:/data   -e SYNAPSE_SERVER_NAME=matrix.example.com   -e SYNAPSE_REPORT_STATS=no   ghcr.io/element-hq/synapse:latest generate

Substitua o domínio de exemplo pelo nome do servidor Matrix que pretende manter.

Verificar por que motivo o contentor está não saudável

docker ps -a | grep synapse
docker inspect synapse --format '{{json .State.Health}}'
docker logs --tail 200 synapse

Procure erros de YAML, ficheiros em falta, falhas de permissões, erros de ligação à base de dados ou migrações que nunca terminam.

Utilizar PostgreSQL em produção

O guia do PostgreSQL para o Synapse atual explica a configuração de base de dados suportada. Mantenha os dados do PostgreSQL persistentes e faça cópias de segurança juntamente com o estado do Synapse.

Não altere o server_name posteriormente sem planeamento

Os seus IDs Matrix são derivados do nome do servidor, por exemplo @user:example.com. Escolha o domínio definitivo antes de convidar utilizadores.

HTTPS é necessário para uma utilização prática

Normalmente, o Synapse escuta internamente em HTTP (habitualmente na porta 8008). Utilize um proxy inverso com HTTPS para os clientes e a federação, em vez de expor publicamente a porta direta do contentor.

A federação acrescenta mais requisitos de DNS e proxy

Se quiser comunicar com outros servidores Matrix, configure corretamente o nome público do servidor, o HTTPS e a deteção da federação. Um teste apenas local pode ser muito mais simples.

Faça cópias de segurança de mais do que apenas o contentor

Preserve o homeserver.yaml, as chaves de assinatura, os ficheiros multimédia carregados e a base de dados PostgreSQL. Transferir novamente a imagem não repõe a identidade de um homeserver.

O guia de resolução de problemas do Docker apresenta o modelo geral de depuração de contentores.

Verificar o proprietário dos ficheiros na pasta de dados persistentes

Se o registo do contentor indicar «permission denied» ao ler o homeserver.yaml, as chaves de assinatura ou os ficheiros multimédia, corrija o proprietário do diretório de dados Synapse associado ao UID/GID esperado pela imagem. Evite tornar toda a árvore de dados do CasaOS gravável por todos.

Aguardar a conclusão das migrações da base de dados antes de avaliar o estado

Após uma atualização ou a primeira ligação ao PostgreSQL, o Synapse pode precisar de algum tempo para executar as migrações do esquema. Acompanhe os registos em vez de reiniciar repetidamente o contentor, pois as migrações interrompidas podem dificultar o diagnóstico.

Testar a API local antes do proxy inverso

Confirme que o endpoint HTTP interno do Synapse responde a partir do anfitrião CasaOS antes de adicionar HTTPS, DNS ou federação. Se a API local não estiver saudável, um proxy inverso não a poderá corrigir.

Perguntas frequentes

Porque é que o Synapse está não saudável?

Verifique os registos e o estado de saúde para encontrar erros de configuração, permissões, base de dados ou migração; o tópico de origem não indicou uma causa única verificada.

Posso utilizar SQLite?

Para testes, sim. A documentação atual do Synapse recomenda o PostgreSQL para quase todas as instalações de produção.

Que porta utiliza o Synapse internamente?

As configurações Docker comuns disponibilizam a API de cliente/servidor na porta 8008, atrás de um proxy inverso.

Preciso do Element?

Não. O Synapse é o homeserver; o Element é um possível cliente/interface web.