ZimaOS Docker Compose インポートエラー：YAMLの修正

ZimaOSがカスタムアプリをインストール → インポート中にDocker Composeファイルを拒否した場合、ZimaOSのインストールが破損していると決めつけないでください。2025年9月のコミュニティ事例では、ZimaOSを再インストールし、シークレットブラウジングで再試行しても状況は変わりませんでした。実際の問題は保存したCompose YAMLにありました。メモにコピーする際に形式が壊れており、エクスポートされた定義にはアプリケーションが必要とする以上の複雑さが含まれていました。

ユーザーはYAMLを修正し、Syncthingサービスを簡素化して、インポートの問題が解決したことを確認しました。このスレッドは、ZimaOSの重要なユースケースも示しています。次のようなオプション tmpfs ビジュアルエディターに専用フィールドがない場合があるため、高度なコンテナ設定にはComposeのインポートが必要です。

インポート失敗の状況

元のユーザーはBeelink MiniでZimaOS 1.4.3を実行しており、以前エクスポートしたカスタムアプリケーションが、クリーンインストール後にインポートできなくなったことに気づきました。

Docker Composeカスタムアプリの送信後にエラーを表示するZimaOSのブラウザーコンソール — 保存したDocker ComposeテキストをZimaOSのカスタムアプリインポーターに送信した際、最初の症状が現れました。

ZimaOSカスタムアプリインポーターのトラブルシューティング中に取得されたブラウザー開発者コンソールの出力 — OSの再インストールやブラウザーセッションの変更を行っても、根本的なComposeの問題は解消されませんでした。

ZimaOSのトラブルシューティング前にYAMLを検証する

YAMLではインデントが重要です。メモアプリによって1つのレベルがずれるだけで、有効なComposeがまったく異なる構造に変わることがあります。

保存したエクスポートの形式が大きく崩れていたことに、作成者は最終的に気づきました。Composeファイルを以前のZimaOSインストールからコピーした後、メモの作成手順によって構造が変わっていました。

ZimaOSホストを変更する前に：

ComposeファイルをYAML/Composeバリデーターに貼り付ける。
タブではなくスペースを使用する。
すべてのリスト項目と子プロパティのインデントを確認する。
すべてのbindマウントにコンテナ側のtargetがあることを確認する。
重複するキーを削除する。
結果を現在のDocker Compose仕様と比較してください。

完全なBindマウントにはSourceとTargetの両方が必要

有効な長形式のbindマウントは次のようになります。

- PGID=1000
  - type: bind
    source: /DATA/AppData/syncthing/data
    target: /var/syncthing

現在のDocker Composeでは、次のようなオプションのbind設定もサポートされています。

bind:
  create_host_path: true

YAML構造が有効であること、そして source および target 同じマウントエントリの下にネストされています。

Docker Compose services reference

Docker Composeサービスでは、次を参照します。

ロング形式のポート構文は有効ですが、シンプルに保ちましょう

ただし、ZimaOSの2025年版インポーターと破損したエクスポート済みYAMLでは、保存された構造を正しく処理できませんでした。通常の単一ホスト上のZimaOSサービスでは、より単純な構文のほうが検証しやすいことがよくあります。
  古いエクスポートには、次のような冗長なポートエントリが含まれていました。
    - target: 8384
    published: "8384"
    protocol: tcp

mode: ingress mode 現在のDocker Composeには、次の定義があります。

主にSwarmでの公開動作のためのロング形式のポート構文で使用されます。つまり、このキー自体がComposeで常に無効というわけではありません。

ただし、ZimaOSの2025年版インポーターと破損したエクスポート済みYAMLでは、保存された構造を正しく処理できませんでした。通常の単一ホスト上のZimaOSサービスでは、より単純な構文のほうが検証しやすいことがよくあります。
  - "8384:8384"
  ポート:
  - "22000:22000/tcp"
  - "22000:22000/udp"

- "21027:21027/udp"

実際にオプションが必要な場合にのみ、より高度なロング形式を使用します。

ホストネットワークを正しく使用する

使用

次の2つは組み合わせないでください network_mode アプリケーションでDockerホストネットワークが必要な場合、Composeでは次のように指定できます。 networks 同じサービスに

これは、同じサービスに通常のユーザー作成ネットワークを指定する場合とは異なります。現在のDocker Composeでは、この組み合わせは拒否されます。 ホスト.

tmpfsは有効なDocker Compose機能です

元の作成者のアプリケーションには、次の設定が必要でした。

- /media/SLOT4/Syncthing:/media/data/syncthing
  tmpfs:

現在のDocker Composeは、これを明示的にサポートしています。 tmpfs マウント。オプションも指定できます。

- /media/SLOT4/Syncthing:/media/data/syncthing
  tmpfs:
  - /data:mode=755,uid=1000,gid=1000

元のZimaOSバージョンでは、ビジュアル形式のカスタムアプリフォームにこのオプションの入力欄がありませんでした。そのため、ユーザーはすべての設定を手動で入力する代わりにComposeのインポートを使う必要がありました。

現在のZimaOSは引き続きDocker Composeのインポートをサポートしています

現在のZimaOSドキュメントでは、このワークフローが説明されています。

ダッシュボードを開きます。
カスタマイズしたアプリをインストールを選択します。
インポートをクリックします。
Docker Composeタブを開きます。
YAMLを貼り付けます。
インストール前に、生成された設定を送信して確認します。

ZimaOSカスタムアプリのドキュメント

壊れたComposeと修正後のComposeの見た目

保存したエクスポートから不正なDocker Compose形式が表示されているZimaOSカスタムアプリのインポート画面 — 元の作成者は、保存されたComposeテキストから本来のYAML構造が失われていたことを発見しました。

一部修復したSyncthing Docker Composeをインポートした後に表示されたZimaOSのエラー — 正常に解析できることは最初の段階にすぎません。生成されたサービス定義は、DockerとZimaOSの両方で有効でなければなりません。

ZimaOS Docker Compose定義を検証・簡素化するCompose Toolbox — コミュニティでは、再度インポートする前にComposeファイルを検証して簡素化することが推奨されました。

不要な設定を削除した後のSyncthing Docker Compose定義 — より小さく標準準拠のCompose定義にすることで、設定の把握と復元が容易になりました。

A Simpler Syncthing Structure

よりシンプルなSyncthing構成

すっきりした単一ホスト構成は、概念的には次のようになります。
  services:
    syncthing:
    image: syncthing/syncthing:2.0
    container_name: syncthing
    使用
    restart: unless-stopped
      environment:
      - PUID=1000
    - PGID=1000
      volumes:
      - /DATA/AppData/syncthing/data:/var/syncthing
    - /media/SLOT4/Syncthing:/media/data/syncthing
      tmpfs:

- /run

自分の環境に適したPUID/PGID、パス、ネットワーク設定、イメージタグを使用してください。元のスレッドではトラブルシューティング中にroot IDを使用していましたが、すべてのSyncthingコンテナをrootとして実行する理由にはなりません。

エクスポートしたZimaOS Composeファイルは、変更できないバックアップ形式ではありません

元の投稿者は、問題のあるファイルがZimaOSを再インストールする前にコンテナをエクスポートして作成したものだと述べています。これは有用なバックアップですが、エクスポートされたアプリケーション定義には、ZimaOSが生成したメタデータや、手書きのComposeスタックより冗長な構文が含まれる場合があります。

災害復旧のためにエクスポートファイルを頼りにする前に：
プレーンテキスト形式またはコード対応形式で保存します。
必要に応じてバージョン管理に入れます。
元のシステムがまだ動作している間に、それらを検証します。

永続的なAppDataフォルダーを別途バックアップします。

ZimaOS Composeインポートチェックリスト
インポート前にYAMLを検証します。
タブをスペースに置き換えます。
ports、volumes、environment、networksの下のインデントを確認します。
すべてのバインドマウントにソースとターゲットの両方を含めます。 使用 ホストネットワークを使用する場合は、network_mode: host
次の2つは組み合わせないでください network_mode とサービスの networks.
Keep tmpfs ビジュアルUIに表示されない場合は、Compose内で
アプリケーションが必要としない生成済みオプションや高度なオプションを削除します。
アプリケーションデータは別途バックアップしてください。Composeだけではデータはバックアップされません。

ZimaOS Docker Composeインポートに関するFAQ

元の問題はブラウザーのキャッシュが原因でしたか？

いいえ。投稿者はZimaOSをクリーンインストールした後、シークレットブラウザーでも同じ問題を再現し、保存されたComposeにおけるフォーマットの問題が実際の原因だと確認しました。

ZimaOSのビジュアルなカスタムアプリフォームはtmpfsをサポートしていますか？

2025年のスレッドでは、GUIにそのオプションが表示されないとされていました。Docker Compose自体は以下をサポートしています tmpfsそのため、インポートが適切な高度な方法です。

mode: ingress と protocol: tcp は無効なDocker Compose設定ですか？

一般的にそうとは限りません。現在のComposeは、以下を含む長いポート構文をサポートしています mode元の事例から得られる実践的な教訓は、ZimaOSのインポーターがエクスポート形式を確実に処理できない場合、YAML全体を検証し、不要な複雑さを取り除くことです。