لماذا Traefik v3 بدلًا من nginx لبيئة Docker الخاصة بك
nginx خادم HTTP ممتاز، لكن إعداده ثابت: كل خدمة جديدة تستلزم ملف vhost جديدًا وإعادة تحميل للعملية. Traefik مصمم للبيئات المعتمدة على الحاويات حيث تتغير الطبولوجيا باستمرار. في الإصدار 3، يدعم HTTP/3 (QUIC) بشكل أصيل، وبنية middlewares مبسطة، ووقت تشغيل أكثر صرامة يرفض الإعدادات الغامضة.
- اكتشاف تلقائي للحاويات عبر علامات Docker — لا إعادة تحميل يدوية عند إضافة خدمة.
- HTTPS تلقائي مع Let's Encrypt: شهادات تُحصل وتُخزن وتُجدد دون تدخل.
- Middlewares أصيلة قابلة للتعريف بالعلامات: BasicAuth، rate-limit، رؤوس الأمان، إعادة التوجيه.
- لوحة تحكم مدمجة للمراقبة الفورية: تتبع جميع المسارات والشهادات من المتصفح.
- دعم HTTP/3 (QUIC) بسطر إعداد واحد: يحسن الأداء على الاتصالات عالية الكمون.
- التوجيه بقواعد Host وPathPrefix والترويسات أو أي تركيبة — بصيغة Go Template معبرة.
- API REST داخلية: استعلم عن حالة الموجه وافحص الخلفيات النشطة.
- متوافق مع Docker Swarm وKubernetes وNomad — انتقل دون تغيير علاماتك.
المتطلبات التقنية قبل البدء
يتطلب هذا التثبيت خادم VPS يعمل بنظام Debian 12 أو Ubuntu 22.04/24.04، وDocker Engine 25+، وDocker Compose v2.24+. تأكد من أن المنفذين 80 و443 مفتوحان من الإنترنت في جدار الحماية. ستحتاج إلى اسم نطاق تتحكم في سجلات DNS الخاصة به: وجّه سجل A إلى عنوان IP الخادم قبل البدء، وإلا لن تتمكن Let's Encrypt من إصدار الشهادة. عنوان بريد إلكتروني صالح مطلوب لإشعارات انتهاء صلاحية ACME.
التثبيت الكامل لـ Traefik v3 خطوة بخطوة
إنشاء شبكة Docker المشتركة. يجب أن يكون Traefik على نفس شبكة الخدمات التي يوجّهها. أنشئها مرة واحدة:
docker network create traefik-public. ستُشار إلى هذه الشبكة في كل ملفdocker-compose.yml للخدمات.إنشاء ملف
acme.json للشهادات. ستكتب Let's Encrypt شهاداتها في هذا الملف. يجب أن يكون مملوكًا لـ root بصلاحيات 600 بالضبط:touch /opt/traefik/acme.json && chmod 600 /opt/traefik/acme.json. إذا كانت الصلاحيات خاطئة، سيرفض Traefik الإقلاع.إنشاء ملف
docker-compose.yml الخاص بـ Traefik. ضع الملف في/opt/traefik/docker-compose.yml مع الإعداد الكامل: نقاط الدخول TLS، ومحلل ACME لـ Let's Encrypt، وعلامات لوحة التحكم المحمية.توليد هاش BasicAuth للوحة التحكم. استبدل السلسلة المضمنة بهاش bcrypt حقيقي:
echo $(htpasswd -nB admin) | sed -e 's/\$/\$\$/g'. أمرhtpasswd موجود في حزمةapache2-utils. يجب مضاعفة علامات$ في قيم علامات Docker Compose.تشغيل Traefik. من
/opt/traefik/:docker compose up -d. تحقق من السجلات:docker compose logs -f traefik. يجب أن ترى"Starting provider" providerType=Docker ثم"Attaching router" routerName=dashboard.إضافة خدمة خلف Traefik. في ملف
docker-compose.yml الخاص بتطبيقك، انضم إلى شبكةtraefik-public (كشبكة خارجية) وأضف أربع علامات أساسية:traefik.enable=true، وقاعدةHost()، ونقطة الدخولwebsecure، ومحلل الشهادة، ومنفذ الخلفية.التحقق من شهادات Let's Encrypt. افحص
acme.json:cat /opt/traefik/acme.json | python3 -m json.tool | grep -A3 'domain'. يجب أن ترى نطاقاتك مع تاريخ انتهاء صلاحية بعد 90 يومًا.التحقق من إعادة توجيه HTTP إلى HTTPS. اختبر بـ curl:
curl -v http://app.dominio.com. يجب أن تحصل على301 Moved Permanently إلىhttps://. إذا حصلت على رفض للاتصال على المنفذ 80، تحقق من قواعد جدار الحماية.تفعيل HTTP/3 من جهة المتصفح. أضف ترويسة
Alt-Svc عبر middleware عام في علامات Traefik. الترويسةAlt-Svc: h3=":443"; ma=86400 تخبر المتصفح بدعم QUIC. تحقق بـcurl --http3 https://app.dominio.com -v.
Middlewares الأساسية: BasicAuth ومحدود المعدل ورؤوس الأمان
تُطبَّق middlewares Traefik عبر علامات Docker مباشرةً على موجّه الخدمة. إليك أهم ثلاث middlewares في الإنتاج، تُعلَن على الخدمة ذاتها دون لمس الإعداد المركزي لـ Traefik.
- BasicAuth على مسار خاص — لحماية أداة إدارة (Adminer، Flower...): أضف علامات
traefik.http.middlewares.adminauth.basicauth.users وtraefik.http.routers.myadmin.middlewares=adminauth. - Rate-limit ضد الإساءة — يحمي API أو نموذج تواصل: اضبط
ratelimit.average=100 (100 طلب/ثانية بالمتوسط) وratelimit.burst=50 (تحمّل 50 طلبًا متفجرًا). - رؤوس أمان HTTP —
X-Frame-Options،X-Content-Type-Options،Strict-Transport-Security: تقبل middlewareheaders في Traefik جميع هذه القيم مباشرةً كعلامات دون ملف nginx منفصل. - Redirect Regex — لإعادة توجيه
www.dominio.com إلىdominio.com: استخدم middlewareredirectregex معpermanent=true وتعبير منتظم مناسب. - Compress — فعّل ضغط gzip/brotli على جميع الاستجابات النصية بعلامة واحدة:
traefik.http.middlewares.compress.compress=true.
HTTP/3 (QUIC) في سطرين. في قسم command من ملف docker-compose.yml الخاص بـ Traefik، أضف --entrypoints.websecure.http3=true واكشف منفذ UDP 443. يُنشئ QUIC الاتصالات بسرعة أكبر بنسبة تصل إلى 30% على الشبكات المعرضة للخسارة ويُلغي مشكلة head-of-line blocking. المتصفحات الحديثة تفعّله تلقائيًا عبر ترويسة Alt-Svc. لا تعديلات مطلوبة على مستوى التطبيق.
الترحيل من Traefik v2: التغييرات الكاسرة
يُدخل Traefik v3 قطائع متعمدة مع v2 لإزالة الغموض المتراكم. البشرى الجيدة: الترحيل تدريجي — يمكن للإعدادات الإصدارين التعايش أثناء الانتقال. إليك أكثر النقاط كسرًا.
docker.swarmMode أصبحdocker.swarmmode (بأحرف صغيرة كاملة). إذا استخدمت الإعداد القديم، يتجاهله Traefik v3 بصمت وتوقف اكتشاف Swarm.- قاعدة
PathPrefix بدون شرطة مائلة لاحقة: في v3،PathPrefix('/api') مكافئ لـPathPrefix('/api/') — يتم توحيد الشرطة المائلة اللاحقة. tls.certificates في الإعداد الديناميكي: في v3، يجب أن يكون هذا القسم في الإعداد الثابت (traefik.yml) أو عبر مزود مخصص.- middleware
errors: المعاملquery أصبحurl. يجب تحديث أي إعداد يستخدمerrors.query. - إزالة دعم بروتوكول
spiffe: إذا كنت تستخدم مصادقة SPIFFE في بنية Consul، انتقل إلى حل mTLS قياسي قبل الترقية إلى v3. - إعداد
constraints في Docker: تغيّرت صياغة القيود لتتوافق مع تنسيق علامات Docker القياسي.
Traefik v3 مقابل nginx مقابل Caddy: أي ريفرس بروكسي لـ Docker؟
مرّر الجدول أفقيًا
| المعيار | Traefik v3 | nginx | Caddy v2 |
|---|---|---|---|
| الإعداد | علامات Docker أو TOML أو YAML — إعادة تحميل تلقائية فورية | ملفات vhost ثابتة — إعادة تحميل يدوية (`nginx -s reload`) | Caddyfile تصريحي — إعادة تحميل تلقائية فورية |
| HTTPS التلقائي | مدمج أصليًا (ACME v2، تحدي TLS-ALPN أو HTTP-01) | يتطلب certbot و cron وسكريبت إعادة تحميل | مدمج أصليًا، الأبسط في الإعداد (سطر واحد) |
| توجيه Docker الديناميكي | أصيل: اكتشاف فوري للحاويات عبر Docker socket | غير أصيل: يتطلب nginx-proxy أو تعديلًا يدويًا | أصيل عبر إضافة caddy-docker-proxy (غير رسمية) |
| HTTP/3 (QUIC) | مدعوم أصليًا منذ v3 (2024)، تفعيل بسطر واحد | مدعوم منذ nginx 1.25 (2023)، إعداد إضافي مطلوب | مدعوم أصليًا منذ Caddy 2.6 (2022) |
| الأداء الخام | أقل قليلًا من nginx عند الإنتاجية العالية جدًا (أكثر من 50k طلب/ثانية) | المرجع الصناعي للإنتاجية العالية والتزامن | مقارب لـ nginx في معظم أحمال الويب القياسية |
| منحنى التعلم | معتدل — مفاهيم الموجّه والخدمة والـ middleware يجب استيعابها | مرتفع لـ HTTPS مع Docker — توثيق مجزأ | منخفض — الإعداد الأكثر إيجازًا للحالات البسيطة |
استكشاف الأخطاء: الأخطاء الخمسة الأكثر شيوعًا
معظم مشكلات Traefik في الإنتاج تنشأ من ثلاثة مصادر: صلاحيات ملف acme.json، شبكة Docker المفقودة، وعلامات مُهرَّبة بشكل خاطئ في Compose. إليك الأخطاء مع رسائلها الفعلية.
level=error msg="Unable to obtain ACME certificate" error="acme: error 403" — Let's Encrypt لا تستطيع التحقق من نطاقك. تحقق من أن المنفذ 80 مفتوح من الإنترنت وأن DNS نطاقك يشير إلى عنوان IP الخادم.level=error msg="The acme.json file has bad file permissions" ثم رفض Traefik للإقلاع — صلاحيات الملف ليست 600. صحّح:chmod 600 /opt/traefik/acme.json.- الخدمة مرئية في لوحة Traefik لكن خطأ 502 Bad Gateway — حاوية الخدمة ليست على شبكة
traefik-public. تحقق بـdocker inspect <container> | grep -A20 Networks. - علامات مُتجاهَلة بصمت، المسار غائب عن لوحة التحكم — نسيت
traefik.enable=true على الخدمة، أو--providers.docker.exposedbydefault=false نشط والعلامة غائبة. invalid character '$' in label value — علامات$ في هاشات BasicAuth غير مضاعفة في ملف Compose. الصيغة الصحيحة:$$2y$$10$$... فيdocker-compose.yml.
الخطوة التالية: تعزيز بيئة Docker للإنتاج
يتولى Traefik v3 التوجيه وTLS، لكن بيئة Docker جاهزة للإنتاج تتطلب المزيد: healthchecks على الحاويات، وسياسة إعادة التشغيل، وسجلات مركزية، وتدوير الأسرار، ونسخ احتياطية للأحجام. راجع دليل docker-compose-production-checklist للحصول على قائمة مرجعية كاملة تطبّقها قبل نشر أي خدمة في حاوية على خادمك الافتراضي.
