إصلاح أخطاء استيراد Docker Compose في ZimaOS للتطبيقات المخصّصة

إذا رفض ZimaOS ملف Docker Compose أثناء تثبيت تطبيق مخصص → استيراد، فلا تفترض أن تثبيت ZimaOS تالف. ففي حالة مجتمعية في سبتمبر 2025، لم تُحدث إعادة تثبيت ZimaOS وإعادة المحاولة في متصفح خفي أي فرق. كانت المشكلة الفعلية في ملف Compose YAML المحفوظ: فقد تضرر تنسيقه أثناء نسخه إلى تطبيق الملاحظات، كما أن التعريف المُصدَّر احتوى على تعقيد أكبر مما يحتاجه التطبيق.

أصلح المستخدم ملف YAML، وبسّط خدمة Syncthing، وأكد حل مشكلة الاستيراد. كما يسلّط النقاش الضوء على حالة استخدام مهمة لـ ZimaOS: قد لا تتضمن خيارات مثل tmpfs قد لا يتضمن حقلًا مخصصًا في المحرر المرئي، ولذلك يظل استيراد Compose ضروريًا لإعدادات الحاويات المتقدمة.

كيف بدا فشل الاستيراد

كان المستخدم الأصلي يشغّل ZimaOS 1.4.3 على جهاز Beelink Mini، ووجد أن تطبيقًا مخصصًا مُصدَّرًا سابقًا لم يعد يُستورد بعد إعادة تثبيت نظيفة.

تحقق من YAML قبل استكشاف أخطاء ZimaOS وإصلاحها

تُعد YAML حساسة لمسافات البادئة. ويمكن لمستوى واحد أزيحته عن موضعه بواسطة تطبيق تدوين الملاحظات أن يحوّل Compose صالحًا إلى بنية مختلفة تمامًا.

لاحظ المؤلف الأصلي في النهاية أن التصدير المحفوظ كان منسقًا بصورة سيئة. فقد غيّرت آلية تدوين الملاحظات بنية الملف بعد نسخ ملف Compose من تثبيت ZimaOS القديم.

قبل تغيير مضيف ZimaOS:

1. الصق ملف Compose في أداة للتحقق من YAML/Compose؛
2. استخدم المسافات، وليس علامات التبويب؛
3. تحقق من مسافات بادئة كل عنصر في القائمة وكل خاصية فرعية؛
4. تأكد من أن كل تحميل bind يتضمن هدفًا على جانب الحاوية؛
5. أزل المفاتيح المكررة؛
6. قارن النتيجة بمواصفات Docker Compose الحالية.

يحتاج تحميل Bind كامل إلى كلٍّ من المصدر والهدف

يبدو تحميل bind بصيغة طويلة صالحًا كما يلي:

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

يدعم Docker Compose الحالي أيضًا إعدادات bind اختيارية مثل:

bind:
  create_host_path: true

المتطلب الأساسي هو أن تكون بنية YAML صالحة وأن المصدر و الهدف متداخلة ضمن إدخال التحميل نفسه.

تشير خدمات Docker Compose إلى

صيغة المنافذ الطويلة صالحة، لكن أبقِها بسيطة

احتوى التصدير القديم على إدخالات منافذ مطولة مثل:

المنافذ:
  - target: 8384
    published: "8384"
    protocol: tcp
    mode: ingress

يعرّف Docker Compose الحالي بالفعل الوضع بصيغة المنافذ الطويلة، ولا سيما لسلوك النشر في Swarm. وهذا يعني أن المفتاح نفسه ليس غير صالح عالميًا في Compose.

ومع ذلك، لم يستطع مستورد ZimaOS لعام 2025 وملف YAML المُصدَّر التالف التعامل مع البنية المحفوظة بشكل سليم. وبالنسبة إلى خدمة ZimaOS عادية على مضيف واحد، غالبًا ما تكون الصيغة الأبسط أسهل في التحقق:

المنافذ:
  - "8384:8384"
  - "22000:22000/tcp"
  - "22000:22000/udp"
  - "21027:21027/udp"

استخدم الصيغة الطويلة الأكثر تقدمًا فقط عندما تحتاج فعلًا إلى خياراتها.

استخدم شبكة المضيف بشكل صحيح

إذا كان التطبيق يحتاج إلى استخدام شبكة مضيف Docker، فإن Compose يوفر:

network_mode: host

لا تجمع بين network_mode مع الشبكات للنفس الخدمة؛ إذ يرفض Docker Compose الحالي هذا الجمع.

يختلف هذا عن تعريف شبكة عادية ينشئها المستخدم باسم المضيف.

ميزة tmpfs صالحة في Docker Compose

تطلب تطبيق المؤلف المصدر:

tmpfs:
  - /run

يدعم Docker Compose الحالي صراحةً tmpfs نقاط التحميل. ويمكنه أيضًا قبول خيارات:

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

في إصدار ZimaOS المصدر، لم يكن نموذج التطبيق المخصص المرئي يوفر حقلًا لهذا الخيار، ولذلك احتاج المستخدم إلى الاستيراد عبر Compose بدلًا من إدخال كل إعداد يدويًا.

لا يزال ZimaOS الحالي يدعم استيراد Docker Compose

يصف توثيق ZimaOS الحالي سير العمل هذا:

1. افتح لوحة المعلومات؛
2. اختر تثبيت تطبيق مخصص؛
3. انقر على استيراد؛
4. افتح علامة تبويب Docker Compose؛
5. ألصق YAML؛
6. أرسل الإعدادات المُنشأة وراجعها قبل التثبيت.

توثيق التطبيقات المخصصة في ZimaOS

كيف بدا تعريف Compose المعطوب والمصحح

بنية Syncthing أبسط

يمكن أن يبدو تخطيط نظيف لمضيف واحد من الناحية المفاهيمية كما يلي:

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

استخدم قيم PUID/PGID والمسارات وإعدادات الشبكة ووسم الصورة المناسبة لنشرك الخاص. استخدم نقاش المصدر معرّفات الجذر أثناء استكشاف المشكلة، لكن ذلك ليس سببًا لتشغيل كل حاوية Syncthing بصلاحيات الجذر.

ملف ZimaOS Compose مُصدَّر ليس تنسيقًا احتياطيًا لا يجوز المساس به

ذكر مؤلف المصدر أن الملف الإشكالي نتج عن تصدير الحاويات قبل إعادة تثبيت ZimaOS. وهذه نسخة احتياطية مفيدة، لكن تعريفات التطبيقات المُصدَّرة قد تحتوي على بيانات وصفية أنشأها ZimaOS أو صياغة أكثر إسهابًا من حزمة Compose مكتوبة يدويًا.

قبل الاعتماد على الملفات المُصدَّرة للتعافي من الكوارث:

• وخزّنها بصيغة نصية عادية أو بصيغة ملائمة للتعامل مع الشيفرة؛
• ضعها تحت إدارة الإصدارات عند الاقتضاء؛
• تحقق من صلاحيتها ما دام النظام الأصلي يعمل؛
• انسخ مجلدات AppData الدائمة احتياطيًا بشكل منفصل.

قائمة التحقق من استيراد Compose في ZimaOS

1. تحقق من صحة YAML قبل الاستيراد.
2. استبدل علامات الجدولة بمسافات.
3. تحقق من صحة المسافات البادئة في YAML ضمن ports و volumes و environment و networks.
4. تأكد من أن كل عملية ربط للمجلدات تتضمن مصدرًا وهدفًا.
5. استخدم network_mode: host إذا كان المقصود استخدام شبكة المضيف.
6. لا تجمع بين network_mode وخدمة الشبكات.
7. احتفظ بـ tmpfs في Compose إذا كانت واجهة المستخدم المرئية لا تتيح ذلك.
8. أزل الخيارات المُنشأة أو المتقدمة التي لا يحتاج إليها التطبيق.
9. احتفظ بنسخة احتياطية منفصلة من بيانات التطبيق؛ فملف Compose وحده لا يحتوي على البيانات.

الأسئلة الشائعة حول استيراد Docker Compose في ZimaOS

هل كانت المشكلة الأصلية ناتجة عن ذاكرة التخزين المؤقت للمتصفح؟

لا. أعاد المؤلف إنتاج المشكلة بعد إعادة تثبيت ZimaOS تثبيتًا نظيفًا وفي متصفح خفي، ثم أكد أن مشكلات التنسيق في Compose المحفوظ كانت السبب الحقيقي.

هل يدعم ZimaOS استخدام tmpfs في نموذج التطبيق المخصص المرئي؟

ذكر نقاش عام 2025 أن واجهة المستخدم الرسومية لم تكن تتيح ذلك الخيار. يدعم Docker Compose نفسه tmpfsلذلك يكون الاستيراد هو المسار المتقدم المناسب.

هل تُعدّ mode: ingress و protocol: tcp غير صالحتين في Docker Compose؟

ليس بشكل عام. يدعم Compose الحالي صيغة المنافذ المطوّلة، بما في ذلك الوضع. الدرس العملي المستخلص من الحالة المصدرية هو التحقق من ملف YAML بالكامل وإزالة التعقيد غير الضروري عندما يتعذر على مستورد ZimaOS استخدام الصيغة المُصدَّرة بشكل موثوق.