Este tópico de janeiro de 2026 sobre Nextcloud/MariaDB é um dos exemplos mais claros de por que motivo a rede dos contentores deve ser diagnosticada camada a camada. O utilizador instalou aplicações separadas do Nextcloud e do MariaDB; o MariaDB atingiu um estado saudável de “pronto para aceitar ligações”, mas o Nextcloud falhou durante a configuração inicial com getaddrinfo for mariadb failedA reinstalação de ambas as aplicações e a eliminação das respetivas pastas não alterou o erro.
A descoberta decisiva ocorreu quando a comunidade testou o IP Docker real do contentor MariaDB. O Nextcloud começou imediatamente a instalação. Isso provou que o servidor da base de dados, as credenciais e o caminho TCP eram, em princípio, funcionais, enquanto o nome de anfitrião mariadb não estava a ser resolvido a partir do contentor do Nextcloud.
O utilizador queria uma base de dados MariaDB separada para o Nextcloud
As primeiras respostas discutiram alternativas, como uma imagem do Nextcloud tudo-em-um com o PostgreSQL incluído ou a criação manual de uma base de dados e de um utilizador MariaDB através do phpMyAdmin. Essas sugestões não correspondiam ao problema final. O utilizador já tinha o MariaDB a funcionar e precisava que o Nextcloud conseguisse aceder-lhe.
Os registos do MariaDB mostraram que a base de dados estava saudável
A comunidade recomendou corretamente não alterar repetidamente as palavras-passe do MariaDB e as variáveis de ambiente depois de a base de dados já ter sido inicializada. Muitas imagens de bases de dados aplicam as variáveis de inicialização apenas na primeira criação do diretório de dados.
O anfitrião da base de dados tem de estar acessível a partir do interior do Nextcloud
Durante a configuração inicial do Nextcloud, o campo do anfitrião da base de dados pode conter um nome de anfitrião e uma porta, como:
mariadb:3306Isto só funciona quando a rede do Docker fornece resolução de nomes para mariadb a partir do contentor do Nextcloud.
getaddrinfo for mariadb failed — é um erro de contentor relacionado com DNS?
O erro principal foi:
php_network_getaddresses: getaddrinfo for mariadb failedIsto acontece antes de o MariaDB poder aceitar ou rejeitar um nome de utilizador e uma palavra-passe. Se o nome não puder ser resolvido para um endereço IP, as credenciais da base de dados ainda não estão a ser avaliadas.
O facto de ambas as aplicações indicarem “Bridge” não resolveu a resolução de nomes
O utilizador confirmou que ambas as aplicações apresentavam a rede Bridge no ZimaOS, mas mariadb continuava sem ser resolvido. Esta é uma nuance importante do Docker: os contentores ligados de forma independente à bridge predefinida do Docker não obtêm automaticamente o mesmo comportamento de DNS baseado no nome do serviço que os serviços ligados a uma rede bridge definida pelo utilizador.
Por isso, “ambos indicam bridge” não é prova suficiente de que um contentor consegue resolver o nome do outro contentor.
Uma reinstalação limpa não corrigiu o comportamento da rede
O utilizador desinstalou o Nextcloud e o MariaDB, eliminou as respetivas pastas e voltou a instalá-los de raiz. O mesmo erro de nome de anfitrião voltou a ocorrer. Este teste negativo é útil porque mostra que o problema não era simplesmente constituído por dados antigos do MariaDB ou por uma palavra-passe incorreta ocasional.
Um aviso de acesso local do Nextcloud era um problema separado
O utilizador encontrou uma sugestão online para ativar allow_local_remote_servers. Aplicar essa definição durante a configuração inicial fez com que o Nextcloud deixasse de iniciar corretamente. A comunidade explicou que esta opção tratava de uma regra de segurança diferente do Nextcloud e não corrigia a resolução de nomes Docker.
A comunidade passou então para testes diretos da rede Docker
O autor da resposta solicitou verificações sobre:
- se ambos os contentores estavam em execução;
- o modo de rede efetivamente indicado pelo Docker;
- se o Nextcloud conseguia resolver ou fazer ping a
mariadb; - o IP Docker atual do contentor MariaDB.
Esta é a escalada correta quando as capturas de ecrã da configuração deixam de explicar o comportamento: testar a ligação a partir do mesmo espaço de nomes de rede onde o Nextcloud está a ser executado.
Usar o IP do contentor MariaDB permitiu instalar o Nextcloud
O teste decisivo consistiu em substituir mariadb:3306 temporariamente com o IP e a porta Docker do contentor MariaDB. O utilizador de origem respondeu que, nesse caso, o Nextcloud foi instalado.
O autor da resposta resumiu claramente o resultado:
-
mariadb:3306falhou; - o IP Docker direto na porta 3306 funcionou imediatamente.
Isso é uma forte indicação de um problema na resolução do nome do contentor.
Um IP direto do contentor é uma solução alternativa de diagnóstico válida
Usar o IP prova que é possível aceder à base de dados e permite prosseguir com a instalação. No caso de origem, foi uma solução alternativa eficaz.
No entanto, os endereços IP atribuídos automaticamente aos contentores podem mudar quando um contentor é recriado, removido ou ligado a uma rede diferente. Uma configuração que dependa permanentemente de 172.17.x.x pode falhar mais tarde sem qualquer alteração na configuração do Nextcloud ou do MariaDB.
Uma rede Docker definida pelo utilizador é um design melhor a longo prazo
A arquitetura mais robusta consiste em ligar o Nextcloud e a MariaDB à mesma rede Docker definida pelo utilizador e utilizar um nome estável de serviço ou de contentor como anfitrião da base de dados. O Docker disponibiliza DNS incorporado nas redes definidas pelo utilizador especificamente para este fim.
A edição nativa de YAML do ZimaOS permite atualmente definir este tipo de rede com mais facilidade do que quando o tópico de origem foi criado. Utilize o modelo de configuração Compose atual do ZimaOS ao criar uma rede partilhada para o Nextcloud e a MariaDB.
Preserve deliberadamente os dados da MariaDB
Se a MariaDB já contiver uma base de dados Nextcloud funcional, não elimine o respetivo diretório de dados persistentes apenas para alterar a rede Docker. A participação na rede pode ser alterada sem recriar o conteúdo da base de dados.
Antes de qualquer migração, faça uma cópia de segurança da base de dados e registe o utilizador atual, o nome da base de dados e o mapeamento do volume.
Não desative os controlos de segurança do Nextcloud para reparar o DNS do Docker
Definições como domínios fidedignos, acesso remoto local ao servidor e configuração de proxy inverso protegem o Nextcloud na camada HTTP/aplicacional. Só devem ser alteradas quando o erro correspondente do Nextcloud o exigir.
A getaddrinfo O erro relativo ao nome do anfitrião da base de dados pertence à camada de rede Docker.
Uma árvore de diagnóstico melhor
- Confirme que a MariaDB está em execução e a escutar na porta 3306.
- Confirme que a base de dados pretendida existe e que as credenciais são conhecidas.
- Teste se o Nextcloud consegue resolver o nome do anfitrião da base de dados.
- Se a resolução do nome do anfitrião falhar, teste o IP do contentor da base de dados.
- Se o IP funcionar, corrija a rede Docker em vez de alterar as palavras-passe da base de dados.
- Mova ambos os contentores para uma rede estável definida pelo utilizador, para obter um nome de anfitrião duradouro.
Perguntas frequentes sobre o Nextcloud e a MariaDB
A própria MariaDB estava avariada?
Não. O respetivo registo mostrava que estava pronto para aceitar ligações.
O que significava «getaddrinfo for mariadb failed»?
O Nextcloud não conseguiu resolver o nome do anfitrião da base de dados antes de chegar sequer à fase de autenticação.
O que confirmou o diagnóstico?
Usar o IP Docker direto do contentor MariaDB permitiu que o Nextcloud começasse a ser instalado.
O IP direto do contentor deve ser o anfitrião permanente da base de dados?
Pode funcionar, mas uma rede Docker partilhada, definida pelo utilizador, com resolução estável de nomes é mais robusta.
A reinstalação de ambas as aplicações resolveu o problema?
Não. O utilizador de origem efetuou uma reinstalação limpa e o mesmo erro de resolução do nome do anfitrião voltou a ocorrer.
