Corrija os erros de importação do Docker Compose no ZimaOS para aplicações personalizadas

Se o ZimaOS rejeitar um ficheiro Docker Compose durante Install a Customized App → Import, não presuma que a instalação do ZimaOS está corrompida. No caso da comunidade em setembro de 2025, reinstalar o ZimaOS e tentar novamente num navegador em modo incógnito não fez qualquer diferença. O problema real estava no YAML do Compose guardado: a formatação tinha sido danificada ao copiá-lo para as notas, e a definição exportada continha mais complexidade do que a aplicação necessitava.

O utilizador corrigiu o YAML, simplificou o serviço Syncthing e confirmou que o problema de importação estava resolvido. O tópico também destaca um caso de utilização importante do ZimaOS: opções como tmpfs pode não ter um campo dedicado no editor visual, pelo que a importação do Compose continua a ser necessária para definições avançadas do contentor.

Aspeto da falha de importação

O utilizador original executava o ZimaOS 1.4.3 num Beelink Mini e descobriu que uma aplicação personalizada anteriormente exportada já não podia ser importada depois de uma reinstalação limpa.

Valide o YAML antes de resolver problemas no ZimaOS

O YAML é sensível à indentação. Um único nível deslocado por uma aplicação de notas pode transformar um Compose válido numa estrutura completamente diferente.

O autor original acabou por reparar que a exportação guardada estava mal formatada. O seu fluxo de trabalho para tomar notas tinha alterado a estrutura depois de o ficheiro Compose ter sido copiado da antiga instalação do ZimaOS.

Antes de alterar o anfitrião ZimaOS:

1. cole o ficheiro Compose num validador de YAML/Compose;
2. use espaços, não tabulações;
3. verifique a indentação de cada item da lista e propriedade subordinada;
4. confirme que todas as montagens bind têm um destino no contentor;
5. remova chaves duplicadas;
6. compare o resultado com a especificação atual do Docker Compose.

Uma montagem bind completa precisa de origem e destino

Um bind mount válido em formato longo é semelhante a:

volumes:
  - type: bind
    source: /DATA/AppData/syncthing/data
    target: /var/syncthing

O Docker Compose atual também suporta definições de bind opcionais, como:

bind:
  create_host_path: true

O requisito principal é que a estrutura YAML seja válida e que origem e destino estão aninhados na mesma entrada de montagem.

Os serviços Docker Compose referenciam

A sintaxe longa das portas é válida, mas mantenha-a simples

A exportação antiga continha entradas de portas extensas, como:

portas:
  - target: 8384
    published: "8384"
    protocol: tcp
    mode: ingress

O Docker Compose atual define modo na sintaxe longa das portas, principalmente para o comportamento de publicação do Swarm. Isto significa que a própria chave não é universalmente inválida no Compose.

No entanto, o importador do ZimaOS de 2025 e o YAML exportado danificado não processavam corretamente a estrutura guardada. Para um serviço normal do ZimaOS num único anfitrião, uma sintaxe mais simples é frequentemente mais fácil de validar:

portas:
  - "8384:8384"
  - "22000:22000/tcp"
  - "22000:22000/udp"
  - "21027:21027/udp"

Utilize a forma longa mais avançada apenas quando realmente precisar das respetivas opções.

Utilizar corretamente a rede do anfitrião

Se a aplicação precisar da rede do anfitrião do Docker, o Compose disponibiliza:

network_mode: host

Não combine network_mode com uma redes lista para o mesmo serviço; o Docker Compose atual rejeita essa combinação.

Isto é diferente de definir uma rede normal, criada pelo utilizador, com o nome anfitrião.

tmpfs é uma funcionalidade válida do Docker Compose

A aplicação do autor da fonte precisava de:

tmpfs:
  - /run

O Docker Compose atual suporta explicitamente tmpfs montagens. Também pode aceitar opções:

tmpfs:
  - /run
  - /data:mode=755,uid=1000,gid=1000

Na versão de origem do ZimaOS, o formulário visual de aplicações personalizadas não disponibilizava um campo para esta opção, razão pela qual o utilizador precisava de importar o Compose em vez de introduzir manualmente todas as definições.

O ZimaOS atual continua a suportar a importação de Docker Compose

A documentação atual do ZimaOS descreve este fluxo de trabalho:

1. abra o painel;
2. selecione Instalar uma aplicação personalizada;
3. clique em Importar;
4. abra o separador Docker Compose;
5. cole o YAML;
6. submeta e reveja as definições geradas antes da instalação.

Documentação de aplicações personalizadas do ZimaOS

Como era o Compose danificado e corrigido

Uma estrutura Syncthing mais simples

Uma estrutura simples para um único anfitrião pode ser conceptualmente semelhante a:

services:
  syncthing:
    image: syncthing/syncthing:2.0
    container_name: syncthing
    restart: unless-stopped
    network_mode: host
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - /DATA/AppData/syncthing/data:/var/syncthing
      - /media/SLOT4/Syncthing:/media/data/syncthing
    tmpfs:
      - /run

Utilize o PUID/PGID, os caminhos, a rede e a etiqueta de imagem adequados à sua própria implementação. O tópico de origem utilizava IDs de root durante a resolução do problema, mas isso não é motivo para executar todos os contentores Syncthing como root.

Um ficheiro Compose do ZimaOS exportado não é um formato de cópia de segurança intocável

O autor da fonte afirmou que o ficheiro problemático resultou da exportação de contentores antes de reinstalar o ZimaOS. Trata-se de uma cópia de segurança útil, mas as definições de aplicações exportadas podem conter metadados gerados pelo ZimaOS ou uma sintaxe mais prolixa do que uma stack Compose escrita manualmente.

Antes de confiar nos ficheiros exportados para a recuperação após um desastre:

• guarde-as num formato de texto simples ou compatível com código;
• coloque-as sob controlo de versões, se adequado;
• valide-as enquanto o sistema original ainda funciona;
• faça cópias de segurança separadas das pastas AppData persistentes.

Lista de verificação para a importação do Compose no ZimaOS

1. Valide o YAML antes de o importar.
2. Substitua tabulações por espaços.
3. Verifique a indentação das listas em ports, volumes, environment e networks.
4. Certifique-se de que cada montagem bind inclui uma origem e um destino.
5. Utilize network_mode: host se for pretendida uma rede do anfitrião.
6. Não combine network_mode e o serviço redes.
7. Mantenha tmpfs no Compose se a interface visual não o disponibilizar.
8. Remova as opções geradas/avançadas de que a aplicação não necessita.
9. Mantenha uma cópia de segurança separada dos dados da aplicação; o Compose, por si só, não contém os dados.

Perguntas frequentes sobre a importação do Docker Compose no ZimaOS

O problema original foi causado pela cache do navegador?

Não. O autor reproduziu o problema após uma reinstalação limpa do ZimaOS e num navegador anónimo, tendo depois confirmado que os problemas de formatação no Compose guardado eram a verdadeira causa.

O ZimaOS suporta tmpfs no formulário visual de aplicações personalizadas?

O tópico de 2025 referia que a interface gráfica não apresentava essa opção. O próprio Docker Compose suporta tmpfs, pelo que a importação é o caminho avançado adequado.

Are mode: ingress and protocol: tcp invalid Docker Compose?

Não universalmente. O Compose atual suporta a sintaxe longa de portas, incluindo modoA lição prática do caso de origem é validar todo o YAML e remover complexidade desnecessária quando o importador do ZimaOS não consegue utilizar de forma fiável o formato exportado.