تخطي إلى المحتوى الرئيسي

وكيل Caddy للنطاقات المخصصة

تنتهي النطاقات المخصصة للكنائس (mychurch.org ← موقع B1 الخاص بالكنيسة) عند جهاز واحد من نوع Windows EC2 يعمل بخدمة Caddy. يتولى الجهاز شهادات TLS، ويحوّل كل نطاق إلى موقع {sub}.b1.church الخاص به، ويعيد توجيه الطلبات عبر reverse proxy مع تعديل ترويسة Host. يتكوّن إعداده بالكامل من ملفين فقط: ملف Caddyfile ثابت وملف hosts.map يُحدَّث من واجهة برمجة تطبيقات العضوية (Membership API)، لذلك يستمر عمله بعد إعادة التشغيل دون أي حالة تشغيل مخزّنة. تشرح هذه الصفحة كيفية بناء الجهاز من الصفر، وكيفية تشغيله، والمشكلات الشائعة التي تم اختبارها ميدانياً والتي قد يواجهها كل من يعيد بناءه.

لمعرفة كيفية توجيه الطلب إلى الكنيسة أو الموقع بعد وصوله إلى B1App، راجع توجيه المواقع وتعدد المواقع.

المكوّنات​

المكوّنالوصف
مثيل EC2خادم Windows Server؛ عنوان IP مرن 3.23.251.61 (مُدرج في سجلات DNS للكنائس حول العالم، فالعنوان دائم والمثيلات قابلة للاستبدال)
C:\caddy\caddy.exeنسخة Caddy مخصصة مع وحدة التخزين techknowlogick/certmagic-s3 — نسخة Caddy القياسية لا تستطيع قراءة مخزن الشهادات
C:\caddy\Caddyfileملف الإعداد الكامل للوكيل: TLS عند الطلب، وخريطة map من المضيف إلى المصدر، وإعادة التوجيه من www إلى النطاق الأساسي، وتحويل :80 إلى https
C:\caddy\hosts.mapسطر واحد لكل نطاق قابل للتوجيه بالصيغة {domain} {sub}.b1.church، ويُضمَّن في كتلة map داخل Caddyfile
sync-hostmap.ps1 + المهمة CaddyHostmapSyncمهمة مجدولة (كل 5 دقائق وعند الإقلاع، بصلاحيات SYSTEM) تحدّث hosts.map من الواجهة البرمجية، وتعيد تحميل Caddy بسلاسة عند حدوث تغيير فقط
خدمة Windows caddy (غلاف WinSW)تشغّل caddy.exe run --config C:\caddy\Caddyfile --adapter caddyfile، مع إعادة تشغيل تلقائية عند الفشل. لا يدعم Caddy مدير خدمات Windows (SCM)، لذلك يلزم وجود غلاف
دلو S3 churchapps-caddy-certsمخزن شهادات مشترك (region us-east-2، والبادئة certs) — تبقى الشهادات سليمة عند إعادة بناء المثيلات
دور IAM باسم CaddyRoleيمنح المثيل صلاحية الوصول إلى S3؛ يستخدم Caddy سلسلة بيانات الاعتماد الافتراضية لـ AWS (دون مفاتيح في الإعداد)

نقطتا الاتصال بالواجهة البرمجية اللتان يعتمد عليهما الجهاز​

كلتاهما في واجهة برمجة تطبيقات العضوية (Membership API). نقطة authorize مفتوحة دون مصادقة، أما hostmap فتتطلب ترويسة x-internal-key: <INTERNAL_API_KEY> منذ Api PR #67 (2026-08-16)، ويقرأ sync-hostmap.ps1 هذا المفتاح من C:\caddy\internal-key.txt:

نقطة الاتصالالدور
GET /membership/domains/authorize?domain={host}بوابة ask الخاصة بـ TLS عند الطلب في Caddy: تُرجع 200 {"authorized":true} إذا كان المضيف (أو النطاق الأساسي له، في حالة مضيف www.) موجوداً كصف في جدول domains، وتُرجع 404 في غير ذلك. هذه هي آلية الحماية من إساءة الاستخدام: لن يصدر Caddy شهادة لمضيف ترفضه هذه النقطة
GET /membership/domains/hostmapتتطلب x-internal-key (أو رمز JWT لمسؤول الخادم). تُرجع نص text/plain بأسطر {domain} {sub}.b1.church مرتبة ومنزوعة التكرار (تراعي المواقع: النطاق المخصص لموقع ثانوي يتّصل بنطاق ذلك الموقع الفرعي). وهي مصدر خريطة map

تدفق الطلب​

  1. يحلّ المتصفح mychurch.org إلى 3.23.251.61 (سجل A للنطاق الأساسي، أو CNAME proxy.b1.church).
  2. ينهي Caddy جلسة TLS. إذا كانت الشهادة متوفرة في S3 يقدّمها مباشرة؛ وإذا كان اسم SNI غير معروف يُسأل authorize؛ فإذا أعادت 200 يُصدَر الشهادة عند الطلب من Let's Encrypt؛ وإذا أعادت 404 يُرفض الاتصال (لا شهادة ولا رد، فالمضيف غير المعروف يُرفض على مستوى TLS، ولا يحصل على خطأ HTTP).
  3. تحوّل map المضيف إلى {sub}.b1.church؛ ويحصل www.{apex} على إعادة توجيه 302 إلى النطاق الأساسي؛ ويحصل المضيف المصرّح به وغير المدرج في الخريطة (نطاق جديد تماماً ضمن نافذة المزامنة التي لا تتجاوز 5 دقائق) على خطأ 404 نظيف.
  4. يتّصل reverse_proxy بـ {sub}.b1.church:443 مع SNI وHost مُعاد كتابتهما إلى المصدر، فتقدّم شبكة Vercel موقع B1App. كما يرسل Caddy النطاق الأصلي للزائر في الترويسة X-Church-Host (لأن Vercel يستبدل X-Forwarded-Host بالمضيف المُعاد كتابته). يقبلها وسيط B1App فقط إذا كانت /domains/public/lookup/{host} تربطها بالمعرّف الفرعي {sub} نفسه الخاص بمضيف الطلب، ثم يعرضها كترويسة x-public-host للاستخدام في ترويسة Link القانونية وفي robots.txt وsitemap.xml. وتُحذف دائماً أي ترويسة x-public-host يرسلها العميل. أما مخطط Schema.org ChurchJsonLd فيستمر في استخدام عنوان b1.church (لأن قراءة الترويسات هناك ستجعل الصفحات ديناميكية).
  5. يمرّر المنفذ 80 تحديات ACME من نوع HTTP-01، ويعيد توجيه كل ما عداها بالرمز 308 إلى https.

انتشار النطاقات الجديدة: النطاق المحفوظ في B1Admin يصبح قابلاً للتوجيه خلال حوالي 5 دقائق (مهمة المزامنة)، وتُصدَر شهادته عند أول طلب HTTPS.

بناء الجهاز من الصفر​

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

  1. IAM: أرفق الدور CaddyRole (صلاحية الوصول إلى S3 لدلو الشهادات) بالمثيل. تحقّق من ذلك عبر IMDSv2 من داخل الجهاز. انتبه إلى أن طلب IMDS بسيط يُرجع 401 يعني فقط أن IMDSv2 مفروض، ولا يعني أن الدور غير موجود.
  2. صحة الواجهة البرمجية: يجب أن تُرجع authorize الرمز 404 لنطاق وهمي، ويجب أن تُرجع hostmap (مع ترويسة x-internal-key) الرمز 200 قبل أي خطوة أخرى.

ثم:

  1. الملف الثنائي: نزّل نسخة مخصصة من خدمة البناء الخاصة بـ Caddy: https://caddyserver.com/api/download?os=windows&arch=amd64&p=github.com/techknowlogick/certmagic-s3 (حجمها نحو 57 ميغابايت مقابل 45 ميغابايت للنسخة القياسية؛ الإصدار v2.11.4 وقت كتابة هذه الصفحة). اختيار الوحدة مهم: techknowlogick/certmagic-s3 تستخدم المفاتيح bucket وregion وprefix المتطابقة مع تخطيط الشهادات الحالي، بينما فرع ss098 يستخدم host وendpoint ولن يجد الشهادات الموجودة.
  2. الملفات: ضع Caddyfile وsync-hostmap.ps1 وinternal-key.txt (مفتاح INTERNAL_API_KEY للإنتاج، في سطر واحد) داخل C:\caddy\؛ ثم املأ الخريطة مرة واحدة باستخدام sync-hostmap.ps1 -NoReload.
  3. بوابات التحقق قبل أول تشغيل: يجب أن يُظهر caddy list-modules وحدة تخزين s3؛ ويجب أن يُنتج caddy adapt في كتلة التخزين القيمة "module":"s3","bucket":"churchapps-caddy-certs","region":"us-east-2","prefix":"certs"؛ ويجب أن ينجح caddy validate.
  4. الخدمة: ثبّتها عبر WinSW (معرّف الخدمة caddy، مع إعادة تشغيل تلقائية عند الفشل، وسجلات دوّارة). تعمل بصلاحيات LocalSystem، وهي قادرة على الوصول إلى IMDS للحصول على بيانات اعتماد الدور.
  5. مهمة المزامنة: سجّل المهمة CaddyHostmapSync (بصلاحيات SYSTEM، كل 5 دقائق وعند بدء التشغيل، مع حد تنفيذ 4 دقائق).
  6. التحقق قبل التحويل: اختبر النطاقات بإجبار حلّها إلى 127.0.0.1 باستخدام curl --resolve (لا تصل حركة مرور حقيقية إلى الجهاز قبل نقل عنوان IP المرن). يجب أن يقدّم النطاق الموجود موقعه بشهادة سارية منقولة من التخزين القديم؛ ويجب أن يعيد www. التوجيه برمز 302؛ ويجب أن يُرفض الاتصال بالمضيف غير المعروف على مستوى TLS؛ ويجب أن يعود Restart-Service caddy إلى تقديم الخدمة دون الحاجة إلى إعادة تهيئة يدوية. اختبار إعادة التشغيل هذا هو جوهر التصميم الثابت كله.
  7. الإطلاق الفعلي: أعد ربط عنوان IP المرن 3.23.251.61 بالمثيل الجديد. لن تتغير سجلات DNS للكنائس أبداً.

مشكلات ميدانية مُختبرة (تعلمناها بالطريقة الصعبة، لا تتراجع عنها)​

المشكلةالعَرَضالحل
tls_server_name {vars.upstream} في ناقل reverse_proxyتُرجع كل النطاقات الموجّهة الخطأ 502، لأن متغيرات الخريطة تُحلّ فارغةً وقت الاتصال بـ TLS ("either ServerName or InsecureSkipVerify must be specified")استخدم المتغير الأصلي للناقل: tls_server_name {http.reverse_proxy.upstream.host}
مفاتيح مكررة أو أسطر تالفة في hosts.mapيتوقف معالج map في Caddy بخطأ فادح عند تكرار مفتاح الإدخال، فسطر تالف واحد قد يُسقط الإعداد كلهيقوم سكربت المزامنة بتطبيع المسافات، ويُسقط الأسطر المشوهة (ويرفض الملف كله فقط إذا تجاوزت الأسطر التالفة 20%)، ويزيل التكرار مع الإبقاء على الأول، ويكتب الملف بترميز UTF-8 دون BOM (لأن BOM يُفسد أول مفتاح في الخريطة). كما تُصفّي الواجهة البرمجية صفوف النطاقات الفارغة أو التي تحتوي مسافات من المصدر
Register-ScheduledTask -RepetitionDuration ([TimeSpan]::MaxValue)يفشل تسجيل المهمة بصمت (XML خارج النطاق، وخطأ غير قاتل)ابنِ فترة التكرار ككائن CIM من النوع MSFT_TaskRepetitionPattern مع Interval = "PT5M" ودون مدة؛ وأضف ExecutionTimeLimit مدته 4 دقائق (لأن أول تشغيل بصلاحيات SYSTEM قد يتعلق عند البحث البارد في TLS/CRL)
تحذير

يرتبط واجهة الإدارة (admin API) بالعنوان localhost:2019 فقط. كان وضع التشغيل القديم يعرّضها عن بُعد حتى تتمكن واجهة برمجة تطبيقات العضوية من دفع إعدادات المسارات، لكن التصميم الثابت لا يحتاج إلى أي دفع عن بُعد، وتقليص سطح الهجوم متعمّد. يُعد الأمر caddy reload (الذي يشغّله سكربت المزامنة محلياً) المستهلك الوحيد لواجهة الإدارة.

الدفع إلى وضع التشغيل القديم

لا تزال CaddyHelper في الواجهة البرمجية (ونقطتا /membership/domains/caddy و/caddy/init) موجودة كمسار للعودة إلى وضع التشغيل القديم المُعدّ عبر الواجهة البرمجية. ومن المقرر حذفها بعد أن يثبت الجهاز الثابت استقراره لأسبوعين تقريباً، وبعد ذلك تصبح authorize وhostmap نقطتي التكامل الوحيدتين.

العمليات​

  • السجلات: سجلات WinSW الدوّارة في C:\caddy\ (مخرجات الخدمة وأخطاؤها؛ تظهر أخطاء reverse-proxy في caddy-service.err.log)، وسجل المزامنة في C:\caddy\sync-hostmap.log.
  • فرض تحديث الخريطة: Start-ScheduledTask -TaskName CaddyHostmapSync.
  • تغيير الإعداد: عدّل C:\caddy\Caddyfile ثم نفّذ caddy validate وcaddy reload (أو Restart-Service caddy، فإعادة التشغيل آمنة بحكم التصميم).
  • حذف عدد كبير من النطاقات يُفعّل حارس الانكماش في سكربت المزامنة عن قصد؛ انقل hosts.map القديم جانباً ثم أعد تشغيل المهمة لقبول انكماش كبير مقصود.
  • تعليمات DNS للكنائس لا تتغير أبداً: سجل A للنطاق الأساسي 3.23.251.61، أو CNAME proxy.b1.church.

صفحات ذات صلة​