إصلاح مشكلة فشل CasaOS في تحميل التطبيقات بعد تحديث Docker

إذا كان CasaOS نفسه يُحمَّل، لكن قسم التطبيقات يعرض فقط «فشل تحميل التطبيقات، يُرجى التحديث لاحقًا» بعد تحديث Docker، فتحقّق من سجلات إدارة تطبيقات CasaOS قبل تغيير أذونات نظام الملفات. في حالة مجتمع IceWhale في نوفمبر 2025، لم يكن الخطأ الحاسم في لوحة التحكم نفسها: إذ كانت إدارة تطبيقات CasaOS تحاول استخدام واجهة Docker البرمجية 1.43، بينما كان محرك Docker 29.0.1 يتطلب الإصدار 1.44 على الأقل.

كما احتوى السجل نفسه على أخطاء أذونات ضمن /var/run/casaos, /var/log/casaos، و /var/lib/casaos، لكن رفض واجهة Docker البرمجية كان مشكلة توافق منفصلة منعت CasaOS من إدراج معلومات الحاويات والتطبيقات. حدّث مشرفو CasaOS لاحقًا برنامج التثبيت ليعمل مع إصدارات Docker الأحدث ويطبّق معالجة توافق الواجهة البرمجية، لذا ينبغي للمستخدمين الحاليين البدء ببرنامج تثبيت CasaOS المحدّث بدلًا من خفض إصدار Docker بشكل دائم.

الخطأ الذي حدّد مشكلة التوافق الحقيقية

أفاد المؤلف الأصلي بما يلي:

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

كانت البيئة كما يلي:

• خادم Ubuntu؛
• محرك Docker 29.0.1؛
• واجهة Docker البرمجية 1.52؛
• إدارة تطبيقات CasaOS التي بُنيت في أكتوبر 2024.

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

لماذا قد يؤدي تحديث Docker إلى تعطيل قائمة تطبيقات CasaOS

يتيح محرك Docker واجهة برمجية ذات إصدارات. عادةً ما يمكن لعملاء الإدارة الأقدم التفاوض مع البرامج الخفية الأحدث، لكن Docker رفع تدريجيًا الحد الأدنى لإصدار الواجهة الذي يقبله.

تشرح وثائق Docker الحالية التفاوض على إصدار الواجهة البرمجية، وتشير إلى أن الإصدارات الأقدم من الواجهة تُهمَل تدريجيًا أو تُزال. راجع وثائق واجهة محرك Docker البرمجية.

في هذه الحالة المصدرية، كانت إدارة تطبيقات CasaOS تتحدث باستخدام واجهة Docker البرمجية 1.43، بينما رفض البرنامج الخفي Docker 29 أي إصدار أقدم من 1.44. أدى ذلك إلى فشل تعداد التطبيقات قبل أن تتمكن الواجهة من عرض قائمة التطبيقات.

كانت أخطاء الأذونات حقيقية، لكنها لم تكن سبب العطل نفسه

كما احتوت السجلات على رسائل مثل:

open /var/run/casaos/app-management.url: تم رفض الإذن
mkdir /var/lib/casaos/appstore/...tmp: تم رفض الإذن
تعذّر إعادة تسمية ملف السجل ... تم رفض الإذن

كان المؤلف قد أنشأ الأذونات وعدّلها مسبقًا على أدلة CasaOS ذات الصلة، ومع ذلك ظل متجر التطبيقات يفشل. هذه النتيجة مهمة: لم تستطع تغييرات الأذونات الشاملة إصلاح عدم توافق واجهة Docker البرمجية.

لا تستخدمه بشكل تكراري chmod 777 أو تغيير ملكية أدلة نظام CasaOS لمجرد أن واجهة المستخدم تقول إن التطبيقات فشلت في التحميل. اقرأ السجلات الدقيقة أولًا.

ما أوصى به المجتمع في ذلك الوقت

أفاد MjTech بأن هذه مشكلة معروفة مرتبطة بـ Docker، ووجّه صاحب الموضوع إلى إصلاح من مجتمع BigBear لأخطاء واجهة برمجة تطبيقات Docker في CasaOS.

في ذلك الوقت، شملت الحلول البديلة المؤقتة الشائعة ما يلي:

• خفض الحد الأدنى لإصدار واجهة برمجة التطبيقات الذي يقبله البرنامج الخفي عبر تجاوز في systemd؛
• أو استخدام إصدار أقدم من Docker مؤقتًا، كان لا يزال يقبل واجهة برمجة تطبيقات CasaOS لدى العميل.

كانت تلك الحلول البديلة مفيدة في نوفمبر 2025، لكنها لا ينبغي أن تتحول تلقائيًا إلى الإجراء الدائم لعام 2026، لأن مُثبّت CasaOS حُدّث لاحقًا.

حدّث CasaOS المُثبّت لاحقًا

في ديسمبر 2025، أفاد أحد مشرفي CasaOS على GitHub بأن نص التثبيت قد أُصلح بحيث:

• تثبيت أحدث إصدار متاح من Docker Engine بدلًا من الإصدار القديم المستهدف Docker 24.0.7؛
• تطبيق معالجة توافق واجهة برمجة تطبيقات Docker لإصدارات Docker الأحدث؛
• السماح لخدمات CasaOS وتطبيقاته المضمنة بالعمل مع Docker الحديث.

ذكر المشرف تحديدًا أنه يمكن استخدام تثبيت نظيف أو نص التثبيت الحالي لإصلاح مشكلة عدم تحميل تطبيقات Docker السابقة.

للاطلاع على المصدر الحالي، راجع نص مُثبّت CasaOS.

الإصلاح الأول الحالي: استخدم مُثبّت CasaOS المحدّث

يوثّق CasaOS حاليًا ما يلي:

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

أو:

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

قبل تشغيل مُثبّت على خادم موجود، احتفظ بنسخة احتياطية من قواعد بيانات التطبيقات المهمة وتهيئتها. صُمم الإصلاح للحفاظ على حالة CasaOS، لكن لا ينبغي لخادم منزلي أن يعتمد على برنامج إصلاح نصي بوصفه خطة الاسترداد الوحيدة.

تتوفر تعليمات التثبيت الحالية في مستودع CasaOS على GitHub.

تحقق من خطأ واجهة برمجة التطبيقات قبل تطبيق أي تجاوز للتوافق

تحقق من Docker:

docker version

فعندئذٍ افحص إدارة تطبيقات CasaOS:

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

إذا كان السجل يتضمن صراحةً:

إصدار العميل 1.43 قديم جدًا
الحد الأدنى لإصدار واجهة برمجة التطبيقات المدعوم هو 1.44

فعندئذٍ تكون أمام الفئة نفسها من أعطال واجهة برمجة تطبيقات Docker المذكورة في سلسلة النقاش الأصلية.

إذا أظهر السجل بدلًا من ذلك أخطاء امتلاء القرص، أو فشل DNS، أو توقف Docker daemon، أو تلف كتالوج متجر التطبيقات، أو فقدان ملفات، فلا تطبّق حلًا بديلًا لواجهة برمجة التطبيقات لمجرد أن رسالة واجهة المستخدم مطابقة.

حول تجاوز توافق واجهة برمجة تطبيقات Docker التاريخي

أتاحت الحلول البديلة التي قدمها المجتمع على GitHub أثناء حادثة عام 2025 إضافة إعداد لبيئة systemd الخاصة بـ Docker، ما سمح مجددًا بإصدارات أقدم من واجهة برمجة التطبيقات لدى العميل. وقد يؤدي ذلك إلى استعادة عرض قائمة التطبيقات بينما كان CasaOS لا يزال يستخدم واجهة برمجة التطبيقات 1.43.

يغيّر ذلك حدّ التوافق في برنامج Docker الخفي. تعامل معه كآلية توافق مؤقتة لحالة عدم تطابق مؤكدة بين عميل قديم وبرنامج خفي أحدث، وليس كإعداد عام لضبط CasaOS.

توضح وثائق Docker الحالية أن تغييرات دعم API القديم تحدث بمرور الوقت، وتوصي بإبقاء العملاء محدثين بدلًا من الاعتماد الدائم على إصدارات API القديمة.

لا تعيّن DOCKER_API_VERSION في CasaOS بشكل أعمى

خاص بـ Docker DOCKER_API_VERSION يفرض المتغير على العميل استخدام إصدار محدد من API ويعطّل التفاوض العادي على API. وتوثّق Docker استخدامه أساسًا للحالات التي تتطلب إصدار API محددًا أو لأغراض تصحيح الأخطاء.

يختلف ذلك عن جعل برنامج Docker الخفي الأحدث يقبل API أقدم لعميل CasaOS. وقد يؤدي تعيين قيمة عشوائية لـ API على جانب العميل إلى تفاقم عدم التطابق.

تحقق أيضًا من سلامة Docker

sudo systemctl status docker
docker ps

إذا كان Docker نفسه متوقفًا، فلن تتمكن CasaOS من سرد الحاويات قيد التشغيل بغض النظر عن إصدار API.

تحقق من مساحة القرص قبل إعادة تثبيت أي شيء

ظهرت رسالة واجهة المستخدم نفسها «فشل تحميل التطبيقات» في حالات غير مرتبطة من CasaOS عندما كان قرص النظام ممتلئًا تقريبًا. تحقق من:

df -h

يمكن لنظام ملفات جذر ممتلئ أن يعطّل السجلات والملفات المؤقتة وتحديثات متجر التطبيقات وحالة Docker. لا تفترض أن كل شريط واجهة مستخدم متطابق له السبب نفسه.

ترتيب استكشاف الأخطاء وإصلاحها الآمن

1. تأكد من أن لوحة معلومات CasaOS نفسها تفتح.
2. تحقق systemctl status docker و docker ps.
3. تحقق df -h.
4. اقرأ casaos-app-management السجلات.
5. إذا أظهر السجل عدم تطابق API بين 1.43 و1.44، فاستخدم مسار التثبيت/الإصلاح الحالي لـ CasaOS أولًا.
6. استخدم تجاوز توافق API فقط عند التحقق من عدم التطابق وعدم توفر مسار الإصلاح الحالي.
7. لا تُرخِ الأذونات على مجلدات CasaOS بشكل واسع من دون دليل.
8. انسخ بيانات التطبيقات احتياطيًا قبل إعادة التثبيت أو إجراء تغييرات على Docker على مستوى النظام.

الأسئلة الشائعة حول فشل CasaOS في تحميل التطبيقات

لماذا تعمل لوحة معلومات CasaOS بينما لا تعمل التطبيقات؟

تُعد واجهة المستخدم وخدمات CasaOS وبرنامج Docker الخفي وإدارة تطبيقات CasaOS مكونات منفصلة. وقد حدث الفشل في الحالة المصدرية تحديدًا عندما حاولت إدارة التطبيقات الاستعلام من Docker.

هل كان Docker 29 هو السبب في الموضوع الأصلي؟

أظهرت السجلات المصدرية أن Docker 29.0.1 يتطلب API بالإصدار 1.44، بينما كان عميل إدارة تطبيقات CasaOS المثبّت يستخدم API بالإصدار 1.43. وقد منع عدم التطابق هذا عرض التطبيقات مباشرةً.

هل ينبغي تنفيذ chmod على مجلدات CasaOS لإصلاح الصفحة؟

ليس من دون دليل. فقد عدّل المؤلف الأصلي الأذونات بالفعل، ومع ذلك ظل فشل Docker API قائمًا. اقرأ سجلات الخدمة الدقيقة أولًا.

هل ينبغي خفض إصدار Docker؟

كان ذلك أحد الحلول المؤقتة السابقة. حدّثت CasaOS لاحقًا برنامج التثبيت لديها لدعم توافق Docker الحديث، لذا استخدم مسار الإصلاح/التثبيت الحالي قبل فرض إصدار أقدم من Docker.

هل تعني عبارة «فشل تحميل التطبيقات» دائمًا وجود عدم تطابق في Docker API؟

لا. قد تنتج رسالة واجهة المستخدم نفسها عن توقف برنامج Docker الخفي، أو امتلاء القرص، أو مشكلات الأذونات، أو فشل إدارة التطبيقات، أو مشكلات أخرى في الخدمات. وتحدد السجلات التشخيص.