Falha do CasaOS ao carregar aplicações: correção da versão da API do Docker

Se o próprio CasaOS carregar, mas a secção Aplicações apresentar apenas “Falha ao carregar as aplicações, tente atualizar mais tarde” após uma atualização do Docker, verifique os registos do CasaOS App Management antes de alterar as permissões do sistema de ficheiros. No caso da IceWhale Community de novembro de 2025, o erro decisivo não estava no próprio painel: o CasaOS App Management estava a tentar utilizar a API Docker 1.43, enquanto o Docker Engine 29.0.1 exigia pelo menos a API 1.44.

O mesmo registo também continha erros de permissões em /var/run/casaos, /var/log/casaos, e /var/lib/casaos, mas a rejeição da API do Docker era uma falha de compatibilidade separada que impedia o CasaOS de listar informações sobre contentores/aplicações. Posteriormente, os responsáveis pelo CasaOS atualizaram o script de instalação para funcionar com versões mais recentes do Docker e aplicar o tratamento de compatibilidade da API, pelo que os utilizadores atuais devem começar pelo instalador atualizado do CasaOS em vez de fazerem um downgrade permanente do Docker.

O erro que identificou o verdadeiro problema de compatibilidade

O autor original informou:

Resposta de erro do daemon:
a versão do cliente 1.43 é demasiado antiga.
A versão mínima da API suportada é a 1.44,
atualize o seu cliente para uma versão mais recente

O ambiente era:

Ubuntu Server;
Docker Engine 29.0.1;
API do Docker 1.52;
CasaOS App Management criado em outubro de 2024.

Isto explica por que motivo o painel do CasaOS podia continuar a abrir enquanto a secção Aplicações falhava: a interface Web e o serviço de gestão de aplicações baseado no Docker são camadas diferentes.

Porque é que uma atualização do Docker pode interromper a listagem de aplicações do CasaOS

O Docker Engine disponibiliza uma API com versões. Normalmente, os clientes de gestão mais antigos conseguem negociar com daemons mais recentes, mas o Docker tem aumentado progressivamente a versão mínima da API que aceita.

A documentação atual do Docker explica a negociação de versões da API e indica que as versões mais antigas são gradualmente descontinuadas ou removidas. Consulte a documentação da API do Docker Engine.

Neste caso de origem, o CasaOS App Management comunicava através da API 1.43, enquanto o daemon Docker 29 recusava qualquer versão inferior à 1.44. Isso fazia com que a enumeração das aplicações falhasse antes de a interface poder apresentar a lista de aplicações.

Os erros de permissões eram reais, mas não correspondiam à mesma falha

Os registos também continham mensagens como:

open /var/run/casaos/app-management.url: permissão negada
mkdir /var/lib/casaos/appstore/...tmp: permissão negada
não é possível mudar o nome do ficheiro de registo ... permissão negada

O autor já tinha criado os diretórios CasaOS relevantes e ajustado as respetivas permissões, mas a App Store continuava a falhar. Esse resultado é importante: alterações abrangentes de permissões não conseguiram corrigir uma incompatibilidade com a API do Docker.

Não recursivamente chmod 777 ou alterar a propriedade nos diretórios do sistema CasaOS só porque a interface indica que as aplicações não foram carregadas. Leia primeiro os registos exatos.

O que a comunidade recomendava na altura

A MjTech respondeu que este era um problema conhecido relacionado com o Docker e indicou ao autor uma correção da comunidade BigBear para erros da API do Docker no CasaOS.

Na altura, as soluções alternativas temporárias comuns incluíam:

reduzir a versão mínima da API do Docker aceite pelo daemon através de uma substituição do systemd;
ou utilizar temporariamente uma versão mais antiga do Docker que ainda aceitasse a API do cliente do CasaOS.

Essas soluções alternativas foram úteis em novembro de 2025, mas não devem tornar-se automaticamente o procedimento permanente de 2026, porque o instalador do CasaOS foi posteriormente atualizado.

O CasaOS atualizou posteriormente o instalador

Em dezembro de 2025, um responsável pela manutenção do CasaOS comunicou no GitHub que o script de instalação tinha sido corrigido para:

instalar a versão mais recente disponível do Docker Engine, em vez da versão antiga 24.0.7 prevista;
aplicar mecanismos de compatibilidade da API do Docker para versões mais recentes do Docker;
permitir que os serviços e as aplicações integradas do CasaOS funcionem com versões modernas do Docker.

O responsável pela manutenção afirmou especificamente que uma instalação limpa ou o script de instalação atual poderia ser utilizado para reparar o problema anterior de aplicações do Docker que não carregavam.

Para consultar o código-fonte atual, veja o script de instalação do CasaOS.

Correção inicial atual: utilizar o instalador atualizado do CasaOS

Atualmente, o CasaOS documenta:

curl -fsSL https://get.casaos.io | sudo bash

ou:

wget -qO- https://get.casaos.io | sudo bash

Antes de executar um instalador num servidor existente, faça uma cópia de segurança das bases de dados e configurações importantes das aplicações. A reparação foi concebida para preservar o estado do CasaOS, mas um servidor doméstico nunca deve depender de um script de reparação como único plano de recuperação.

As instruções de instalação atuais estão disponíveis no repositório do CasaOS no GitHub.

Verifique o erro da API antes de aplicar qualquer substituição de compatibilidade

Verifique o Docker:

docker version

Em seguida, inspecione a Gestão de Aplicações do CasaOS:

sudo systemctl status casaos-app-management
sudo journalctl -u casaos-app-management --no-pager -n 100

Se o registo contiver explicitamente:

a versão 1.43 do cliente é demasiado antiga
A versão mínima da API suportada é a 1.44

então está perante a mesma categoria de falha da API do Docker que a discussão de origem.

Se o registo apresentar, em vez disso, erros de disco cheio, falhas de DNS, um daemon do Docker parado, um catálogo da loja de aplicações corrompido ou ficheiros em falta, não aplique uma solução alternativa da API apenas porque a mensagem da interface é idêntica.

Sobre a substituição histórica de compatibilidade da API do Docker

As soluções alternativas da comunidade e do GitHub durante o incidente de 2025 adicionaram uma definição de ambiente systemd do Docker que permitia novamente versões mais antigas da API do cliente. Isso podia restaurar a listagem de aplicações enquanto o CasaOS continuava a utilizar a API 1.43.

Isto altera o limite de compatibilidade do daemon do Docker. Trate-o como um mecanismo temporário de compatibilidade para uma incompatibilidade confirmada entre um cliente antigo e um daemon novo, não como uma definição genérica de ajuste do CasaOS.

A documentação atual do Docker explica que o suporte para APIs legadas muda ao longo do tempo e recomenda manter os clientes atualizados em vez de depender permanentemente de versões antigas da API.

Não defina cegamente DOCKER_API_VERSION no CasaOS

Do Docker DOCKER_API_VERSION variável força um cliente a utilizar uma versão específica da API e desativa a negociação normal da API. A documentação do Docker indica que é utilizada principalmente nos casos em que é necessária uma versão exata da API ou para depuração.

Isto é diferente de fazer com que um daemon do Docker mais recente aceite a API mais antiga de um cliente do CasaOS. Definir um valor arbitrário da API do lado do cliente pode agravar a incompatibilidade.

Confirme também que o Docker está operacional

sudo systemctl status docker
docker ps

Se o próprio Docker estiver parado, o CasaOS não poderá listar os contentores em execução, independentemente da versão da API.

Verifique o espaço em disco antes de reinstalar qualquer coisa

A mesma mensagem da interface “Falha ao carregar as aplicações” surgiu em casos não relacionados do CasaOS em que o disco do sistema estava quase cheio. Verifique:

df -h

Um sistema de ficheiros raiz cheio pode interromper os registos, os ficheiros temporários, as atualizações da App Store e o estado do Docker. Não presuma que todas as faixas idênticas da interface têm a mesma causa.

Ordem segura de resolução de problemas

Confirme que o próprio painel do CasaOS abre.
Verificar systemctl status docker e docker ps.
Verificar df -h.
Ler gestão de aplicações do casaos registos.
Se o registo mostrar a incompatibilidade da API 1.43/1.44, use primeiro o procedimento atual de instalação/reparação do CasaOS.
Utilize uma substituição de compatibilidade da API apenas quando a incompatibilidade estiver confirmada e o procedimento de reparação atual não estiver disponível.
Não alargue indiscriminadamente as permissões nas pastas do CasaOS sem provas.
Faça uma cópia de segurança dos dados das aplicações antes de reinstalar ou efetuar alterações ao Docker a nível do sistema.

FAQ: Falha ao carregar as aplicações no CasaOS

Porque é que o painel do CasaOS funciona enquanto as Aplicações não?

A interface, os serviços do CasaOS, o daemon do Docker e a Gestão de Aplicações do CasaOS são componentes separados. No caso de origem, a falha ocorreu especificamente quando a Gestão de Aplicações tentou consultar o Docker.

O Docker 29 foi a causa no tópico de origem?

Os registos de origem mostravam que o Docker 29.0.1 exigia a API 1.44, enquanto o cliente de Gestão de Aplicações do CasaOS instalado usava a API 1.43. Essa incompatibilidade impedia diretamente a listagem das aplicações.

Devo usar chmod nas pastas do CasaOS para corrigir a página?

Não sem provas. O autor original já tinha alterado as permissões e continuava a ter a falha da API do Docker. Leia primeiro os registos exatos do serviço.

Devo fazer downgrade do Docker?

Essa foi uma solução temporária usada no passado. Mais tarde, o CasaOS atualizou o instalador para suportar a compatibilidade com versões modernas do Docker, por isso use o procedimento atual de reparação/instalação antes de forçar uma versão mais antiga do Docker.

“Falha ao carregar as aplicações” significa sempre uma incompatibilidade da API do Docker?

Não. A mesma mensagem da interface pode resultar de um daemon do Docker parado, de um disco cheio, de permissões, de falhas na gestão de aplicações ou de outros problemas de serviços. O diagnóstico é determinado pelo registo.