تخطَّ إلى المحتوى
حاوية التطوير

استكشاف الأخطاء وإصلاحها

الحاوية لا تبدأ

Section titled “الحاوية لا تبدأ”

”Conflict. The container name is already in use”

Section titled “”Conflict. The container name is already in use””
Terminal window
docker rm -f devcontainer
docker compose up -d

أدوات الذكاء الاصطناعي لا تعمل

Section titled “أدوات الذكاء الاصطناعي لا تعمل”

”claude: command not found”

Section titled “”claude: command not found””

قد تكون الصورة قديمة. اسحب أحدث إصدار وأعد التشغيل:

Terminal window
docker compose pull
docker compose up -d

Claude يظهر “Not logged in”

Section titled “Claude يظهر “Not logged in””

نقطة الدخول تُنشئ ملف ~/.claude.json مع إشارات الإعداد الأولي. إذا كان مفقوداً:

Terminal window
echo '{"hasCompletedOnboarding": true}' > ~/.claude.json

Claude يظهر “Invalid API key”

Section titled “Claude يظهر “Invalid API key””

تحقق من القيمة المُعيَّنة فعلياً:

Terminal window
echo "$ANTHROPIC_API_KEY"

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

  • مفتاح وكيل LiteLLM مفقود أو غير صالح — إذا كنت تستخدم وضع الوكيل، تأكد من أن LITELLM_API_KEY في .env يحتوي على بيانات اعتماد الوكيل الصحيحة، ثم أعد تشغيل الحاوية حتى تتمكن نقطة الدخول من اشتقاق ANTHROPIC_API_KEY.
  • عدم تطابق رمز OAuth أو وضع الوكيل — استخدم وضع مصادقة واحد فقط. إذا تم تعيين CLAUDE_CODE_OAUTH_TOKEN، فإنه يأخذ الأولوية على وضع وكيل LiteLLM.

طلبات API تفشل مع خطأ 401

Section titled “طلبات API تفشل مع خطأ 401”

تحقق من أن مفتاح API مُعيَّن بشكل صحيح:

Terminal window
echo "$ANTHROPIC_API_KEY"

تحقق من عمله عن طريق إجراء استدعاء مباشر لمزود الخدمة الخاص بك.

Claude يقول “model not found”

Section titled “Claude يقول “model not found””

يتم تحديد النموذج بواسطة مزود الخدمة ومفتاح API الخاص بك. راجع وثائق مزود الخدمة للاطلاع على النماذج المتاحة.

واجهة سطر أوامر GitHub

Section titled “واجهة سطر أوامر GitHub”

”gh: not authenticated”

Section titled “”gh: not authenticated””

واجهة سطر أوامر gh تتطلب متغير بيئة GH_TOKEN. أضفه إلى ملف .env الخاص بك:

GH_TOKEN=ghp_your-token-here

أنشئ رمزاً في github.com/settings/tokens. الرموز الدقيقة (موصى بها) أو الرموز الكلاسيكية مع نطاق repo كلاهما يعمل. أعد تشغيل الحاوية بعد تحديث .env.

استنساخ HTTPS عبر git يفشل مع خطأ 401

Section titled “استنساخ HTTPS عبر git يفشل مع خطأ 401”

عند تعيين GH_TOKEN، تقوم نقطة الدخول بتشغيل gh auth setup-git لتكوين مساعد بيانات اعتماد git لـ HTTPS. إذا فشلت عمليات HTTPS:

  1. تحقق من صلاحية الرمز: gh auth status
  2. تحقق من تكوين مساعد بيانات الاعتماد: git config --global credential.helper
  3. أعد تشغيل الحاوية لإعادة تشغيل نقطة الدخول

SSH مقابل HTTPS

Section titled “SSH مقابل HTTPS”

يمكن لكلتا طريقتي المصادقة التعايش في الحاوية:

  • SSH (SSH_PRIVATE_KEY في .env) — يستخدم عناوين git@github.com:. مطلوب إذا كانت مؤسستك تفرض SSH.
  • HTTPS (GH_TOKEN في .env) — يستخدم عناوين https://github.com/. إعداد أبسط، بدون إدارة مفاتيح.

إذا تم تكوين كليهما، يستخدم git البروتوكول الذي يتطابق مع عنوان URL البعيد. للتبديل في استنساخ موجود:

Terminal window
# SSH to HTTPS
git remote set-url origin https://github.com/owner/repo.git


# HTTPS to SSH
git remote set-url origin git@github.com:owner/repo.git

مشكلات الصلاحيات

Section titled “مشكلات الصلاحيات”

”Permission denied” على /workspace أو /home

Section titled “”Permission denied” على /workspace أو /home”
Terminal window
sudo chown -R $(id -u):$(id -g) /workspace ~

فشل npm install مع خطأ EACCES

Section titled “فشل npm install مع خطأ EACCES”

تقوم نقطة الدخول تلقائياً بتكوين بادئة npm عامة قابلة للكتابة بواسطة المستخدم في ~/.npm-global، لذا يجب أن تعمل أوامر npm install -g أثناء التشغيل بدون sudo. إذا كنت لا تزال ترى أخطاء EACCES، أعد تطبيق الإصلاح يدوياً:

Terminal window
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

مشكلات البناء

Section titled “مشكلات البناء”

البناء يستغرق وقتاً طويلاً جداً

Section titled “البناء يستغرق وقتاً طويلاً جداً”

أول عملية بناء تقوم بتنزيل الصورة الأساسية (~1 جيجابايت). عمليات البناء اللاحقة تستخدم ذاكرة التخزين المؤقت. إذا كان بطيئاً في كل مرة:

Terminal window
docker builder prune

“No space left on device”

Section titled ““No space left on device””
Terminal window
docker system prune -a --volumes

تحذير: هذا يزيل جميع الحاويات والصور ووحدات التخزين غير المستخدمة — وليس فقط الخاصة بهذا المشروع.

الشبكات

Section titled “الشبكات”

لا يمكن الوصول إلى الإنترنت من داخل الحاوية

Section titled “لا يمكن الوصول إلى الإنترنت من داخل الحاوية”
Terminal window
ping -c 1 8.8.8.8
nslookup google.com
curl -I https://github.com

إذا فشل DNS، أضف إلى /etc/docker/daemon.json على المضيف:

{
  "dns": ["8.8.8.8", "8.8.4.4"]
}

ثم أعد تشغيل Docker.

العرض عن بُعد (noVNC)

Section titled “العرض عن بُعد (noVNC)”

شاشة سوداء في noVNC

Section titled “شاشة سوداء في noVNC”

قد لا يكون Xvfb قد بدأ. تحقق داخل الحاوية:

Terminal window
ps aux | grep Xvfb

إذا لم يكن قيد التشغيل، تحقق من أن ENABLE_VNC غير مُعيَّن على false وأعد تشغيل الحاوية.

خطأ “Cannot open display” أو “No display”

Section titled “خطأ “Cannot open display” أو “No display””

قد لا يكون متغير البيئة DISPLAY مُعيَّناً. تحقق:

Terminal window
echo "$DISPLAY"

يجب أن يكون :99. إذا كان فارغاً، أضف DISPLAY=:99 إلى .env أو devcontainer.json وأعد التشغيل.

رفض الاتصال على المنفذ 6080

Section titled “رفض الاتصال على المنفذ 6080”

قد لا يكون noVNC قيد التشغيل. تحقق داخل الحاوية:

Terminal window
ps aux | grep -E 'novnc|websockify'

إذا لم يكن قيد التشغيل، تحقق من أن ENABLE_VNC مُعيَّن على true (الافتراضي) وراجع سجلات الحاوية:

Terminal window
docker compose logs dev | grep -i vnc

المنفذ 6080 قيد الاستخدام بالفعل

Section titled “المنفذ 6080 قيد الاستخدام بالفعل”

غيّر منفذ المضيف في docker-compose.yml:

ports:
  - "127.0.0.1:16080:6080"

أدوات مطوري Chrome عبر MCP

Section titled “أدوات مطوري Chrome عبر MCP”

تصحيح أخطاء Chrome عن بُعد لا يستجيب

Section titled “تصحيح أخطاء Chrome عن بُعد لا يستجيب”

يجب أن يكون مثيل Chrome المشترك قيد التشغيل على المنفذ 9222. تحقق داخل الحاوية:

Terminal window
# Is Chrome running?
curl http://localhost:9222/json/version


# Check Chrome logs
cat ~/.local/share/chrome-browser/chrome.log


# Verify the symlink
ls -la /opt/google/chrome/chrome


# Restart Chrome manually
. /usr/local/lib/chrome-browser.sh
start_chrome_browser

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

خطأ قفل ملف تعريف المتصفح

Section titled “خطأ قفل ملف تعريف المتصفح”

مع بنية المتصفح المشترك، لا ينبغي أن تحدث أخطاء قفل الملف الشخصي. إذا رأيت واحداً، فقد تكون عملية Chrome قديمة تحتفظ بالقفل:

Terminal window
# Kill any stale Chrome processes
pkill -f 'chrome.*remote-debugging-port' || true


# Remove the lock file
rm -f ~/.cache/chrome-devtools-mcp/chrome-profile/SingletonLock


# Restart Chrome
. /usr/local/lib/chrome-browser.sh
start_chrome_browser

أدوات chrome-devtools-mcp مكررة

Section titled “أدوات chrome-devtools-mcp مكررة”

خادم chrome-devtools-mcp مسجل الآن عالمياً في ~/.claude/settings.json. إذا كان لديك ملف .mcp.json خاص بالمستودع يسجله أيضاً، فسترى أدوات مكررة. أزل إدخال chrome-devtools-mcp من ملفات .mcp.json الخاصة بالمستودع:

Terminal window
# Check for per-repo config
cat .mcp.json

أزل مفتاح chrome-devtools-mcp من أي ملف .mcp.json خاص بالمستودع لاستخدام التسجيل العالمي.

إعادة تعيين كل شيء

Section titled “إعادة تعيين كل شيء”
Terminal window
docker compose down -v
docker rm -f devcontainer 2>/dev/null
docker compose pull
docker compose up -d

هذا يدمر جميع البيانات في وحدات التخزين. ستحتاج إلى إعادة استنساخ المستودعات وإعادة تكوين الأدوات.