فشل تثبيت تطبيق CasaOS: السجلات، نظام أسماء النطاقات والمنافذ

عادةً ما يبدو فشل تثبيت تطبيق CasaOS كخطأ بسيط في واجهة المستخدم: متجر التطبيقات لن يتم تحميله، زر تثبيت التطبيق يفشل، أو تظهر الحاوية لكنها لا تفتح أبدًا. السبب الحقيقي عادةً ما يكون أعمق من واجهة CasaOS. تم تصميم CasaOS حول تثبيت التطبيقات بنقرة واحدة ونشر تطبيقات Docker، لذا قد يأتي الفشل من طبقة خدمة CasaOS، سحب صورة Docker، حل DNS، وقت النظام، معمارية وحدة المعالجة المركزية، أو تعارضات منفذ المضيف.

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

ملخص سريع: رسالة خطأ CasaOS هي فقط العَرَض الأول

رسالة "فشل التثبيت" العامة تخبرك بأن CasaOS لم يتمكن من إكمال النشر، لكنها لا تخبرك أي طبقة فشلت. قد لا يكون كتالوج التطبيقات قد تم تحميله، قد لا يكون Docker قد سحب الصورة، قد لا تتطابق الصورة مع معمارية وحدة المعالجة المركزية الخاصة بك، قد يكون منفذ المضيف مشغولًا بالفعل، أو قد تكون الحاوية قد بدأت ثم تعطلت.

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

استخدم هذا الترتيب:

# 1. قراءة سجلات خدمة CasaOS
journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

# 2. تحقق من حاويات Docker
docker ps -a

# 3. قراءة سجلات الحاوية الفاشلة
docker logs --tail 100 <container_name_or_id>

# 4. اختبار الوصول إلى DNS والسجل
getent hosts github.com
getent hosts registry-1.docker.io

# 5. تحقق من وقت النظام
timedatectl

# 6. تحقق من معمارية وحدة المعالجة المركزية
uname -m

# 7. تحقق من المنافذ المستمعة
sudo ss -tulpn | grep LISTEN

ابدأ بالسجلات قبل تغيير الإعدادات

السجلات هي أسرع طريقة لفصل مشكلة CasaOS عن مشكلة Docker أو الشبكة أو الصورة أو التطبيق. نظام Linux journalctl الأمر يطبع الإدخالات من سجل systemd، و -u الخيار يفلتر السجلات لوحدة خدمة محددة.

بالنسبة لـ CasaOS، ابدأ بسجلات مستوى الخدمة:

journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

ثم تحقق من Docker. Docker’s docker logs الأمر يسترجع السجلات من حاوية، و --follow الخيار يمكنه بث مخرجات جديدة أثناء تشغيل الحاوية.

docker ps -a
docker logs --tail 100 <container_name_or_id>
docker logs -f <container_name_or_id>

ما تبحث عنه:

دليل السجل	الاتجاه المحتمل
لا يوجد مثل هذا المضيف / فشل في البحث عن DNS	DNS أو حل الشبكة
انتهت مهلة الاتصال	الشبكة، الوكيل، جدار الحماية، الوصول إلى السجل، أو عرض النطاق الترددي المنخفض
شهادة / TLS / خطأ x509	وقت النظام، شهادات CA، أو اعتراض HTTPS
خطأ في تنسيق التنفيذ	معمارية وحدة المعالجة المركزية خاطئة للصورة
المنفذ مخصص بالفعل / bind: العنوان مستخدم بالفعل	تعارض منفذ المضيف
أدنى إصدار API مدعوم	عدم تطابق واجهة برمجة تطبيقات عميل / خادم Docker
الخادم الحاوي يخرج فورًا	تكوين التطبيق، إذن المجلد، متغير بيئة مفقود، أو مشكلة في الصورة

القاعدة بسيطة: لا تصلح خمسة أشياء دفعة واحدة. انسخ أول سطر خطأ واضح، ثم اختبر الطبقة التي يشير إليها.

تحقق من DNS والوصول إلى الشبكة

إذا لم يتم تحميل متجر التطبيقات أو فشل التثبيت أثناء تنزيل صورة، فتحقق من DNS والوصول إلى الشبكة الصادرة قبل تغيير إعدادات CasaOS. يقوم Docker بسحب الصور من سجلات مثل Docker Hub. إذا لم يتمكن مضيف CasaOS الخاص بك من حل أسماء النطاقات للسجل، فقد تفشل عمليات السحب قبل حتى إنشاء الحاوية.

استخدم اختبارات حل الأسماء بدلاً من استخدام ping:

getent hosts github.com
getent hosts registry-1.docker.io
getent hosts hub.docker.com

الأمر getent الأمر يستعلم قواعد البيانات المكونة من خلال Name Service Switch، بما في ذلك قاعدة بيانات المضيفين المستخدمة للبحث عن أسماء المضيفين. إذا لم تُرجع هذه الأوامر شيئًا، فقد لا يتمكن CasaOS من الوصول إلى GitHub أو Docker Hub أو كتالوج التطبيقات المخصص حتى لو كان لوحة التحكم المحلية لا تزال تفتح.

ثم تحقق من تكوين المحلل:

cat /etc/resolv.conf

على لينكس، /etc/resolv.conf هو ملف تكوين المحلل المستخدم لـ DNS، و nameserver تحدد الإدخالات خوادم DNS التي يجب على المحلل الاستعلام منها. إذا كان DNS معطلاً، يمكن للتبديل المؤقت إلى محللات عامة مستقرة تأكيد ما إذا كانت هذه هي المشكلة:

sudo nano /etc/resolv.conf

مثال اختبار مؤقت:

nameserver 1.1.1.1
nameserver 8.8.8.8

لا تتوقف عند "الإنترنت يعمل على جهاز الكمبيوتر المحمول الخاص بي". يعمل CasaOS على الخادم، لذا فإن مسار DNS الخاص بالخادم هو المهم.

تحقق من وقت النظام قبل لوم متجر التطبيقات

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

timedatectl

في الإخراج، ابحث عن أسطر مثل:

ساعة النظام متزامنة: نعم
خدمة NTP: نشطة

إذا كان التزامن متوقفًا، فقم بتمكينه:

sudo timedatectl set-ntp true

بعد تمكينه، انتظر لحظة وأعد تشغيل timedatectl قبل إعادة محاولة تثبيت تطبيق CasaOS.

تأكد من تطابق بنية وحدة المعالجة المركزية مع صورة التطبيق

يمكن لـ CasaOS العمل على عدة منصات أجهزة، بما في ذلك أجهزة x86-64 وARM. هذا لا يعني أن كل تطبيق Docker في كل كتالوج يدعم كل بنية. قد يفشل Raspberry Pi أو Orange Pi أو لوحة ARM الصغيرة أو صندوق Android المعاد استخدامه في تشغيل صورة تم إنشاؤها فقط لـ linux/amd64.

تحقق من بنية المضيف الخاصة بك:

uname -m

uname -m النتيجة	المعنى المعتاد
x86_64	AMD64 / x86-64
aarch64	ARM64
armv7l	ARM 32-بت
i386 / i686	x86 32-بت

يجب أن يكون رمز الحاوية متوافقًا مع بنية المضيف لأن الحاويات تشترك في نواة المضيف. بدون المحاكاة، لا يمكنك تشغيل linux/amd64 حاوية على arm64 المضيف. تحل الصور متعددة المنصات هذه المشكلة من خلال توفير متغيرات مثل linux/amd64 و linux/arm64 تحت صورة واحدة.

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

تحقق من تعارضات المنافذ قبل إعادة التثبيت

تكتمل بعض تثبيتات تطبيق CasaOS، لكن التطبيق لا يفتح. في كثير من الحالات، بدأت الحاوية لكن منفذ المضيف كان مشغولًا بالفعل أو تم تعيينه بشكل غير صحيح.

تحقق من المنافذ النشطة التي تستمع:

sudo ss -tulpn | grep LISTEN

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

يبدو التعيين النموذجي هكذا:

المنافذ:
  - "8080:80"

الجزء	المعنى
8080	منفذ المضيف: ما يزوره متصفحك
80	منفذ الحاوية: ما يستمع إليه التطبيق داخل الحاوية

إذا كان منفذ المضيف مستخدمًا بالفعل من قبل خدمة أخرى 80، لا تغير منفذ الحاوية أولاً. غيّر منفذ المضيف إلى قيمة غير مستخدمة:

المنافذ:
  - "8080:80"

هذا مهم بشكل خاص للتطبيقات مثل البروكسي العكسي، مانعات الإعلانات، لوحات التحكم، وخوادم الويب، لأنها غالبًا ما تستخدم المنافذ الافتراضية 80, 443, 8080، أو 3000.

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

استخدم هذه القائمة قبل إعادة تثبيت CasaOS أو حذف الحاويات.

التحقق	الأمر	علامة جيدة	علامة سيئة
سجلات خدمة CasaOS	journalctl -xeu casaos-app-management --no-pager	تدفق تثبيت واضح أو خطأ محدد	فشل خدمة متكرر أو خطأ في واجهة برمجة تطبيقات Docker
سجلات CasaOS الحية	journalctl -u casaos -f	تظهر إجراءات واجهة المستخدم في السجلات	فشل إجراء التطبيق بصمت أو تكرار
قائمة حاويات Docker	docker ps -a	تم إنشاء الحاوية والحالة مرئية	الحاوية مفقودة أو تعيد التشغيل بشكل متكرر
سجلات الحاوية	docker logs --tail 100 <container>	يبدأ التطبيق بشكل طبيعي	خروج، إذن، تكوين، أو خطأ في البنية
بحث DNS	getent hosts registry-1.docker.io	عناوين IP المعادة	لا توجد نتيجة أو خطأ في البحث
سحب الصورة	docker pull <image>:<tag>	تنزيلات الصورة	انتهاء المهلة، TLS، المصادقة، أو عدم وجود بيان مطابق
وقت النظام	timedatectl	الساعة متزامنة، NTP نشط	انحراف الوقت أو عدم نشاط NTP
البنية	uname -m	تطابق منصة الصورة	مضيف ARM مع صورة amd64 فقط
المنافذ	sudo ss -tulpn | grep LISTEN	منفذ المضيف غير مستخدم	المنفذ مشغول بالفعل

أنماط الفشل الشائعة وما تعنيه عادةً

متجر التطبيقات لا يتم تحميله

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

تحقق من:

getent hosts github.com
getent hosts registry-1.docker.io
timedatectl
journalctl -u casaos -f

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

فشل تثبيت التطبيق أثناء سحب الصورة

إذا فشل التثبيت أثناء سحب الصورة، انسخ رسالة الخطأ الدقيقة من Docker. اختبر يدويًا:

docker pull <image>:<tag>

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

التطبيق مثبت لكنه لا يفتح

إذا ظهر التطبيق كأنه مثبت لكن المتصفح لا يفتحه، تحقق من المنافذ أولاً. منفذ مضيف غير صحيح أو متضارب يمكن أن يجعل الحاوية العاملة تبدو معطلة.

تحقق من:

docker ps
sudo ss -tulpn | grep LISTEN

ثم تحقق مما إذا كان التطبيق مرتبطاً بمنفذ المضيف الذي تزوره.

التطبيق يبدأ ويتوقف فوراً

إذا كانت الحاوية موجودة لكنها تخرج، اقرأ سجلات الحاوية:

docker logs --tail 100 <container>

ابحث عن متغيرات بيئة مفقودة، مسارات وحدات تخزين غير صالحة، أخطاء قاعدة بيانات، أخطاء أذونات، أو خطأ في تنسيق التنفيذ.

السجلات تظهر أخطاء إصدار Docker API

إذا ذكرت السجلات عدم توافق إصدار Docker API، لا تخمن. نفذ أولاً:

docker version

يجب التعامل مع مشاكل إصدار Docker API كحالة استكشاف أخطاء متقدمة. لا تفكر في تجاوز API إلا إذا أظهرت السجلات بوضوح عدم تطابق API. لا تضف تجاوز systemd لمجرد فشل التطبيق مرة واحدة.

مشاكل Docker والأذونات في تطبيقات CasaOS

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

تحقق من المسارات المعينة للتطبيق والسجلات:

docker inspect <container_name_or_id>
docker logs --tail 100 <container_name_or_id>

ابحث عن:

• مجلد المضيف مفقود؛
• تم رفض الإذن؛
• نظام الملفات للقراءة فقط؛
• قاعدة البيانات لا يمكن تهيئتها؛
• ملف التكوين غير موجود؛
• مسار الجهاز مفقود؛
• مستخدم الحاوية لا يمكنه الكتابة إلى وحدة التخزين المركبة.

عندما يشير الخطأ إلى مشكلة في وحدة تخزين أو أذونات، أصلح المسار أو الأذونات أولاً. إعادة تثبيت التطبيق دون تغيير المسار الخاطئ عادةً ما يعيد نفس الفشل.

الأخطاء التي تجعل استكشاف أخطاء CasaOS أصعب

الخطأ 1: إعادة تثبيت التطبيق قبل قراءة السجلات

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

الخطأ 2: إصلاح DNS دون اختبار حل الأسماء

تغيير DNS عشوائياً يمكن أن يصعب عملية استكشاف الأخطاء وإصلاحها. اختبر الحل أولاً باستخدام getent hostsإذا لم يتمكن الخادم من حل أسماء نطاقات السجل أو الكتالوج، فقم بضبط تكوين المحلل.

الخطأ 3: تجاهل توافق صورة ARM مقابل AMD64

يمكن لـ CasaOS العمل على أجهزة ARM، لكن ليس كل صورة تطبيق تدعم ARM. إذا كان المضيف الخاص بك aarch64 أو armv7l وإذا كانت الصورة مخصصة فقط لـ amd64، فقد يفشل التثبيت أو قد تخرج الحاوية مع خطأ في تنسيق التنفيذ.

الخطأ 4: تغيير منافذ الحاوية بدلاً من منافذ المضيف

إذا قالت وثائق التطبيق إن الحاوية تستمع على المنفذ 80، لا تغير منفذ الحاوية الداخلي إلا إذا كنت تعرف أن التطبيق يدعمه. بدلاً من ذلك، غيّر منفذ المضيف. هذا يحافظ على سلوك الخدمة الداخلية للتطبيق سليمًا مع تجنب تعارض على مستوى المضيف.

كيفية إعادة محاولة التثبيت بأمان

بعد أن تجد السبب المحتمل، أعد المحاولة بطريقة محكمة:

1. احفظ رسالة الخطأ الدقيقة.
2. قم بإصلاح طبقة واحدة فقط.
3. أعد تشغيل الخدمة ذات الصلة فقط إذا لزم الأمر.
4. أعد محاولة تثبيت التطبيق.
5. راقب السجلات أثناء إعادة المحاولة.
6. تحقق مما إذا كانت الحاوية موجودة.
7. تحقق مما إذا كان منفذ التطبيق يستمع.
8. افتح التطبيق من عنوان IP المضيف الصحيح ومنفذ المضيف الصحيح.

قد تبدو إعادة المحاولة الآمنة هكذا:

journalctl -u casaos -f

في نافذة طرفية أخرى:

docker ps -a
docker logs -f <container_name_or_id>

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

الأسئلة الشائعة

لماذا يقول CasaOS إن تثبيت التطبيق فشل؟

لأن طبقة واحدة في سلسلة التثبيت فشلت. قد يكون السبب سجلات خدمة CasaOS، سحب صورة Docker، DNS، وقت النظام، معمارية وحدة المعالجة المركزية، تعارض المنافذ، الأذونات، أو توافق Docker API. ابدأ بالسجلات، ثم اختبر الطبقة التي يظهرها أول خطأ حقيقي.

كيف أتحقق من سجلات تثبيت تطبيق CasaOS؟

ابدأ بـ:

journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

ثم تحقق من Docker:

docker ps -a
docker logs --tail 100 <container_name_or_id>

لماذا لا يمكن لـ CasaOS تحميل متجر التطبيقات؟

أكثر الفحوصات شيوعًا هي DNS، الوصول إلى الشبكة الصادرة، وقت النظام، وسجلات خدمة CasaOS. اختبر DNS من الخادم نفسه باستخدام getent hosts github.com و getent hosts registry-1.docker.io، ثم تحقق من timedatectl و journalctl -u casaos -f.

ماذا يعني خطأ في تنسيق التنفيذ ماذا يعني في CasaOS؟

عادةً ما يعني ذلك أن صورة Docker لا تتطابق مع معمارية وحدة المعالجة المركزية الخاصة بك. على سبيل المثال، قد يحاول مضيف ARM تشغيل صورة مخصصة فقط لـ amd64. تحقق من uname -m وتأكد مما إذا كانت الصورة تدعم منصتك.

كيف أعرف إذا فشل تطبيق CasaOS بسبب تعارض في المنافذ؟

تحقق من المنافذ التي تستمع بالفعل:

sudo ss -tulpn | grep LISTEN

ثم قارن ذلك مع منفذ المضيف الخاص بالتطبيق. إذا كان هناك خدمة أخرى تستخدم نفس منفذ المضيف، قم بتغيير منفذ المضيف الخاص بالتطبيق إلى قيمة غير مستخدمة مع الحفاظ على منفذ الحاوية كما يتوقع التطبيق.

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