Falha na Instalação da App CasaOS: Registos, DNS e Portas

Uma falha na instalação de uma aplicação CasaOS geralmente parece um erro simples na interface: a loja de aplicações não carrega, o botão de instalação da aplicação falha, ou o contentor aparece mas nunca abre. A causa real é geralmente mais profunda do que a interface CasaOS. O CasaOS é concebido para instalação de aplicações com um clique e implantação de aplicações Docker, por isso uma falha na instalação pode vir da camada de serviço CasaOS, transferência da imagem Docker, resolução DNS, hora do sistema, arquitetura da CPU ou conflitos de porta do anfitrião.

A forma mais segura de resolver problemas não é reinstalar o CasaOS primeiro. Comece por ler o erro real, depois teste uma camada de cada vez: registos, rede e DNS, sincronização de hora, arquitetura da CPU, portas e compatibilidade Docker.

Resumo rápido: A mensagem de erro do CasaOS é apenas o primeiro sintoma

Uma mensagem genérica de “falha na instalação” indica que o CasaOS não conseguiu completar a implantação, mas não indica qual camada falhou. O catálogo de aplicações pode não ter carregado, o Docker pode não ter transferido a imagem, a imagem pode não corresponder à arquitetura da sua CPU, uma porta do anfitrião pode já estar ocupada, ou o contentor pode ter iniciado e depois falhado.

A instalação da aplicação CasaOS depende tanto da camada de serviço CasaOS como do ambiente Docker subjacente. As transferências de imagens Docker também podem ser afetadas pelo acesso ao registo, definições de proxy, ligações de baixa largura de banda e tempos limite de transferência de camadas.

Use esta ordem:

# 1. Ler registos do serviço CasaOS
journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

# 2. Verificar contentores Docker
docker ps -a

# 3. Ler os registos do contentor falhado
docker logs --tail 100 <nome_ou_id_do_contentor>

# 4. Testar acesso a DNS e registo
getent hosts github.com
getent hosts registry-1.docker.io

# 5. Verificar hora do sistema
timedatectl

# 6. Verificar arquitetura da CPU
uname -m

# 7. Verificar portas em escuta
sudo ss -tulpn | grep LISTEN

Comece pelos registos antes de alterar as definições

Os registos são a forma mais rápida de separar um problema do CasaOS de um problema do Docker, rede, imagem ou aplicação. O Linux journalctl comando imprime entradas do jornal systemd, e o seu -u opção filtra registos para uma unidade de serviço específica.

Para CasaOS, comece pelos registos ao nível do serviço:

journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

Depois verifique o Docker. O Docker docker logs comando recupera registos de um contentor, e o --follow opção pode transmitir nova saída enquanto o contentor está a correr.

docker ps -a
docker logs --tail 100 <nome_ou_id_do_contentor>
docker logs -f <nome_ou_id_do_contentor>

O que está a procurar:

Pista do registo	Direção provável
host inexistente / falha na pesquisa DNS	DNS ou resolução de rede
tempo de ligação esgotado	Rede, proxy, firewall, acesso ao registo ou largura de banda baixa
certificado / TLS / erro x509	Hora do sistema, certificados CA ou interceptação HTTPS
erro de formato exec	Arquitetura de CPU errada para a imagem
porta já está alocada / ligação: endereço já em uso	Conflito de porta do anfitrião
versão mínima da API suportada	Incompatibilidade entre o cliente Docker e a API do daemon
O contentor sai imediatamente	Configuração da aplicação, permissão do volume, variável de ambiente em falta ou problema na imagem

A regra é simples: não corrija cinco coisas ao mesmo tempo. Copie a primeira linha de erro clara e depois teste a camada a que ela aponta.

Verifique o DNS e o acesso à rede

Se a loja de aplicações não carregar ou a instalação falhar ao descarregar uma imagem, verifique o DNS e o acesso à rede de saída antes de alterar as definições do CasaOS. O Docker puxa imagens de registos como o Docker Hub. Se o anfitrião CasaOS não conseguir resolver domínios do registo, as transferências de imagens podem falhar antes mesmo de o contentor ser criado.

Use testes de resolução de nomes em vez de usar apenas ping:

getent hosts github.com
getent hosts registry-1.docker.io
getent hosts hub.docker.com

O getent o comando consulta bases de dados configuradas através do Name Service Switch, incluindo a base de dados hosts usada para pesquisas de nomes de host. Se estes comandos não retornarem nada, o CasaOS pode não conseguir aceder ao GitHub, Docker Hub ou a um catálogo de aplicações personalizado mesmo que o painel local ainda abra.

Depois verifique a configuração do resolvedor:

cat /etc/resolv.conf

No Linux, /etc/resolv.conf é o ficheiro de configuração do resolvedor usado para DNS, e o nameserver as entradas definem quais servidores DNS o resolvedor deve consultar. Se o DNS estiver avariado, mudar temporariamente para resolvedores públicos estáveis pode confirmar se este é o problema:

sudo nano /etc/resolv.conf

Exemplo de teste temporário:

nameserver 1.1.1.1
nameserver 8.8.8.8

Não se fique pelo “a internet funciona no meu portátil.” O CasaOS corre no servidor, por isso o caminho DNS do servidor é o que importa.

Verifique a hora do sistema antes de culpar a loja de aplicações

A hora incorreta do sistema pode quebrar o HTTPS e a validação de certificados de formas que parecem falhas na loja de aplicações ou no registo. Antes de alterar a configuração do Docker ou do CasaOS, verifique se o relógio do servidor está correto e se a sincronização do tempo está ativa.

timedatectl

Na saída, procure linhas como:

Relógio do sistema sincronizado: sim
Serviço NTP: ativo

Se a sincronização estiver desligada, ative-a:

sudo timedatectl set-ntp true

Depois de a ativar, aguarde um momento e execute novamente timedatectl antes de tentar novamente a instalação da aplicação CasaOS.

Confirme que a arquitetura da sua CPU corresponde à imagem da aplicação

O CasaOS pode funcionar em várias plataformas de hardware, incluindo dispositivos x86-64 e ARM. Isso não significa que todas as aplicações Docker em todos os catálogos suportem todas as arquiteturas. Um Raspberry Pi, Orange Pi, placa ARM mini ou uma box Android reutilizada pode não conseguir executar uma imagem que foi construída apenas para linux/amd64.

Verifique a arquitetura do seu anfitrião:

uname -m

uname -m resultado	Significado habitual
x86_64	AMD64 / x86-64
aarch64	ARM64
armv7l	ARM de 32 bits
i386 / i686	x86 de 32 bits

O código do contentor deve ser compatível com a arquitetura do anfitrião porque os contentores partilham o kernel do anfitrião. Sem emulação, não pode executar um linux/amd64 contentor num arm64 host. Imagens multi-plataforma resolvem isto fornecendo variantes como linux/amd64 e linux/arm64 sob uma imagem.

Se os logs mostrarem erro de formato exec, verifique a página da imagem ou o manifesto do registo para suporte ARM. Se a imagem não fornecer a sua plataforma, alterar as definições do CasaOS não resolve. Precisa de uma imagem multi-arquitetura, uma tag diferente ou uma app diferente.

Verifique Conflitos de Porta Antes de Reinstalar

Algumas instalações de apps do CasaOS terminam, mas a app ainda não abre. Em muitos casos, o container iniciou mas a porta do host já estava ocupada ou mapeada incorretamente.

Verifique as portas ativas em escuta:

sudo ss -tulpn | grep LISTEN

Depois compare o resultado com as definições de porta da app. O Docker Compose define portas como mapeamentos entre a máquina host e os containers, e estes mapeamentos permitem o acesso externo aos serviços que correm dentro dos containers.

Um mapeamento típico é assim:

portas:
  - "8080:80"

Parte	Significado
8080	Porta do host: onde o seu navegador acede
80	Porta do container: onde a app escuta dentro do container

Se outro serviço já usa a porta do host 80, não altere primeiro a porta do container. Altere a porta do host para um valor não usado:

portas:
  - "8080:80"

Isto é especialmente importante para apps como proxies reversos, bloqueadores de anúncios, painéis e servidores web, porque costumam usar por padrão as portas 80, 443, 8080, ou 3000.

Lista de Verificação Prática para Falhas de Apps no CasaOS

Use esta lista de verificação antes de reinstalar o CasaOS ou eliminar containers.

Verificar	Comando	Sinal positivo	Sinal negativo
Logs do serviço CasaOS	journalctl -xeu casaos-app-management --no-pager	Fluxo de instalação claro ou erro específico	Falha repetida do serviço ou erro da API Docker
Logs ao vivo do CasaOS	journalctl -u casaos -f	Ações da interface aparecem nos logs	Ação da app falha silenciosamente ou em loop
Lista de containers Docker	docker ps -a	Container criado e estado visível	Container em falta ou a reiniciar repetidamente
Logs do container	docker logs --tail 100 <container>	App inicia normalmente	Erro de saída, permissão, configuração ou arquitetura
Pesquisa DNS	getent hosts registry-1.docker.io	Endereços IP retornados	Sem resultado ou erro de pesquisa
Pull da imagem	docker pull <imagem>:<tag>	Transferências de imagem	Timeout, TLS, autenticação ou manifesto não correspondente
Hora do sistema	timedatectl	Relógio sincronizado, NTP ativo	Desvio de tempo ou NTP inativo
Arquitetura	uname -m	Plataforma da imagem corresponde	Host ARM com imagem apenas amd64
Portas	sudo ss -tulpn | grep LISTEN	Porta do host não usada	Porta já ocupada

Padrões Comuns de Falha e o Que Geralmente Significam

Loja de Apps Não Carrega

Se a própria Loja de Apps não carregar, comece pelo DNS e acesso à rede. O CasaOS depende de catálogos externos e fontes de imagens durante os fluxos normais de apps, por isso o servidor deve conseguir resolver e alcançar essas fontes.

Verifique:

getent hosts github.com
getent hosts registry-1.docker.io
timedatectl
journalctl -u casaos -f

Se o DNS falhar, corrija o resolvedor do servidor. Se o DNS funcionar mas os pulls do Docker falharem, teste o acesso ao registo e as condições de proxy ou firewall.

Falha na Instalação da App Durante o Pull da Imagem

Se a instalação falhar ao puxar a imagem, copie o erro exato do Docker. Teste manualmente:

docker pull <imagem>:<tag>

Se o pull manual falhar com erros de DNS ou timeout, o problema não é a interface CasaOS. Se falhar com erro de arquitetura ou sem manifesto correspondente, verifique a plataforma da imagem.

Aplicação Instalada mas Não Abre

Se a aplicação parecer instalada mas o navegador não conseguir abri-la, verifique primeiro as portas. Uma porta do anfitrião incorreta ou em conflito pode fazer um contêiner funcional parecer avariado.

Verifique:

docker ps
sudo ss -tulpn | grep LISTEN

Depois verifique se a aplicação está ligada à porta do anfitrião que está a visitar.

Aplicação Inicia e Para Imediatamente

Se o contêiner existir mas sair, leia os registos do contêiner:

docker logs --tail 100 <container>

Procure variáveis de ambiente em falta, caminhos de volume inválidos, erros de base de dados, erros de permissão ou erro de formato exec.

Registos Mostram Erros de Versão da API Docker

Se os registos mencionarem incompatibilidade da versão da API Docker, não adivinhe. Execute primeiro:

docker version

Problemas de versão da API Docker devem ser tratados como casos avançados de resolução de problemas. Considere uma substituição da API apenas se os registos mostrarem claramente uma incompatibilidade. Não adicione uma substituição systemd só porque uma aplicação falhou uma vez.

Problemas de Docker e Permissões em Aplicações CasaOS

Algumas aplicações falham porque o contêiner foi criado mas não tem o acesso esperado a um volume, dispositivo ou caminho de rede. Isto é comum quando os utilizadores instalam modelos personalizados, movem dados da aplicação, montam discos externos ou alteram pastas do anfitrião manualmente.

Verifique os caminhos mapeados da aplicação e os registos:

docker inspect <nome_ou_id_do_conteiner>
docker logs --tail 100 <nome_ou_id_do_contentor>

Procure por:

• pasta do anfitrião em falta;
• permissão negada;
• sistema de ficheiros só de leitura;
• base de dados não consegue inicializar;
• ficheiro de configuração não encontrado;
• caminho do dispositivo em falta;
• o utilizador do contêiner não consegue escrever no volume montado.

Quando o erro aponta para um volume ou problema de permissões, corrija primeiro o caminho ou a permissão. Reinstalar a aplicação sem alterar o caminho errado normalmente recria a mesma falha.

Erros Que Tornam a Resolução de Problemas do CasaOS Mais Difícil

Erro 1: Reinstalar a Aplicação Antes de Ler os Registos

Reinstalar pode ocultar o erro original e criar contêineres duplicados, volumes órfãos ou repetições de pull de imagens. Leia primeiro os registos do serviço CasaOS e dos contêineres Docker.

Erro 2: Corrigir o DNS Sem Testar a Resolução de Nomes

Alterar o DNS aleatoriamente pode dificultar a resolução de problemas. Teste a resolução primeiro com getent hostsSe o servidor não conseguir resolver domínios de registo ou catálogo, ajuste a configuração do resolvedor.

Erro 3: Ignorar a Compatibilidade de Imagens ARM vs AMD64

O CasaOS pode funcionar em dispositivos ARM, mas nem todas as imagens de aplicações suportam ARM. Se o seu anfitrião for aarch64 ou armv7l e a imagem for apenas amd64, a instalação pode falhar ou o contentor pode sair com erro de formato exec.

Erro 4: Alterar Portas do Contentor em Vez das Portas do Host

Se a documentação da aplicação indicar que o contentor escuta na porta 80, não altere a porta interna do contentor a menos que saiba que a aplicação a suporta. Altere antes a porta do host. Isto mantém o comportamento interno do serviço da aplicação intacto enquanto evita um conflito a nível do host.

Como Tentar a Instalação com Segurança

Depois de encontrar a causa provável, tente novamente de forma controlada:

1. Guarde a mensagem de erro exata.
2. Corrija apenas uma camada.
3. Reinicie o serviço relacionado apenas se necessário.
4. Tente novamente a instalação da aplicação.
5. Observe os registos enquanto tenta novamente.
6. Verifique se o contentor existe.
7. Verifique se a porta da aplicação está a escutar.
8. Abra a aplicação a partir do IP do host correto e da porta do host correta.

Uma tentativa segura pode ser assim:

journalctl -u casaos -f

Noutro terminal:

docker ps -a
docker logs -f <nome_ou_id_do_contentor>

Depois tente novamente a aplicação no CasaOS. Isto dá-lhe a ação da interface, o comportamento do serviço CasaOS e a saída do contentor Docker numa só passagem.

FAQ

Por que razão o CasaOS diz que a instalação da aplicação falhou?

Porque uma camada na cadeia de instalação falhou. A causa pode estar nos registos do serviço CasaOS, na transferência da imagem Docker, DNS, hora do sistema, arquitetura da CPU, conflitos de portas, permissões ou compatibilidade da API Docker. Comece pelos registos, depois teste a camada indicada pelo primeiro erro real.

Como verifico os registos de instalação da aplicação CasaOS?

Comece por:

journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

Depois verifique o Docker:

docker ps -a
docker logs --tail 100 <nome_ou_id_do_contentor>

Por que razão o CasaOS não consegue carregar a Loja de Aplicações?

As verificações mais comuns são DNS, acesso à rede externa, hora do sistema e registos do serviço CasaOS. Teste o DNS a partir do próprio servidor com getent hosts github.com e getent hosts registry-1.docker.io, depois verifique timedatectl e journalctl -u casaos -f.

O que significa erro de formato exec significa em CasaOS?

Normalmente significa que a imagem Docker não corresponde à arquitetura da sua CPU. Por exemplo, um host ARM pode estar a tentar executar uma imagem apenas amd64. Verifique uname -m e confirme se a imagem suporta a sua plataforma.

Como sei se uma aplicação CasaOS falhou devido a um conflito de portas?

Verifique quais portas já estão a escutar:

sudo ss -tulpn | grep LISTEN

Depois compare isso com a porta do host da aplicação. Se outro serviço já usar a mesma porta do host, altere a porta do host da aplicação para um valor não utilizado, mantendo a porta do contentor conforme a aplicação espera.

Uma falha na instalação de uma aplicação CasaOS torna-se muito mais fácil de resolver quando trata a mensagem da interface como um sintoma, não a causa raiz. Leia os registos primeiro, depois verifique o DNS, hora, arquitetura, portas e compatibilidade do Docker antes de reinstalar a aplicação ou alterar definições do sistema.