وكيل 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 |
تدفق الطلب
- يحلّ المتصفح
mychurch.orgإلى3.23.251.61(سجلAللنطاق الأساسي، أوCNAME proxy.b1.church). - ينهي Caddy جلسة TLS. إذا كانت الشهادة متوفرة في S3 يقدّمها مباشرة؛ وإذا كان اسم SNI غير معروف يُسأل
authorize؛ فإذا أعادت 200 يُصدَر الشهادة عند الطلب من Let's Encrypt؛ وإذا أعادت 404 يُرفض الاتصال (لا شهادة ولا رد، فالمضيف غير المعروف يُرفض على مستوى TLS، ولا يحصل على خطأ HTTP). - تحوّل
mapالمضيف إلى{sub}.b1.church؛ ويحصلwww.{apex}على إعادة توجيه 302 إلى النطاق الأساسي؛ ويحصل المضيف المصرّح به وغير المدرج في الخريطة (نطاق جديد تماماً ضمن نافذة المزامنة التي لا تتجاوز 5 دقائق) على خطأ 404 نظيف. - يتّصل
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.orgChurchJsonLdفيستمر في استخدام عنوانb1.church(لأن قراءة الترويسات هناك ستجعل الصفحات ديناميكية). - يمرّر المنفذ 80 تحديات ACME من نوع HTTP-01، ويعيد توجيه كل ما عداها بالرمز 308 إلى https.
انتشار النطاقات الجديدة: النطاق المحفوظ في B1Admin يصبح قابلاً للتوجيه خلال حوالي 5 دقائق (مهمة المزامنة)، وتُصدَر شهادته عند أول طلب HTTPS.
بناء الجهاز من الصفر
ملخص مكثّف من الإجراء الذي تم اختباره ميدانياً (الخطوات الكاملة مع الأوامر الجاهزة للنسخ موجودة في مساحة العمليات، وليست في هذا المستودع). تحقّق من المتطلبات الأساسية أولاً، فالبناء يفشل بدونها:
- IAM: أرفق الدور
CaddyRole(صلاحية الوصول إلى S3 لدلو الشهادات) بالمثيل. تحقّق من ذلك عبر IMDSv2 من داخل الجهاز. انتبه إلى أن طلب IMDS بسيط يُرجع 401 يعني فقط أن IMDSv2 مفروض، ولا يعني أن الدور غير موجود. - صحة الواجهة البرمجية: يجب أن تُرجع
authorizeالرمز 404 لنطاق وهمي، ويجب أن تُرجعhostmap(مع ترويسةx-internal-key) الرمز 200 قبل أي خطوة أخرى.
ثم:
- الملف الثنائي: نزّل نسخة مخصصة من خدمة البناء الخاصة بـ 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ولن يجد الشهادات الموجودة. - الملفات: ضع
Caddyfileوsync-hostmap.ps1وinternal-key.txt(مفتاحINTERNAL_API_KEYللإنتاج، في سطر واحد) داخلC:\caddy\؛ ثم املأ الخريطة مرة واحدة باستخدامsync-hostmap.ps1 -NoReload. - بوابات التحقق قبل أول تشغيل: يجب أن يُظهر
caddy list-modulesوحدة تخزين s3؛ ويجب أن يُنتجcaddy adaptفي كتلة التخزين القيمة"module":"s3","bucket":"churchapps-caddy-certs","region":"us-east-2","prefix":"certs"؛ ويجب أن ينجحcaddy validate. - الخدمة: ثبّتها عبر WinSW (معرّف الخدمة
caddy، مع إعادة تشغيل تلقائية عند الفشل، وسجلات دوّارة). تعمل بصلاحيات LocalSystem، وهي قادرة على الوصول إلى IMDS للحصول على بيانات اعتماد الدور. - مهمة المزامنة: سجّل المهمة
CaddyHostmapSync(بصلاحيات SYSTEM، كل 5 دقائق وعند بدء التشغيل، مع حد تنفيذ 4 دقائق). - التحقق قبل التحويل: اختبر النطاقات بإجبار حلّها إلى
127.0.0.1باستخدامcurl --resolve(لا تصل حركة مرور حقيقية إلى الجهاز قبل نقل عنوان IP المرن). يجب أن يقدّم النطاق الموجود موقعه بشهادة سارية منقولة من التخزين القديم؛ ويجب أن يعيدwww.التوجيه برمز 302؛ ويجب أن يُرفض الاتصال بالمضيف غير المعروف على مستوى TLS؛ ويجب أن يعودRestart-Service caddyإلى تقديم الخدمة دون الحاجة إلى إعادة تهيئة يدوية. اختبار إعادة التشغيل هذا هو جوهر التصميم الثابت كله. - الإطلاق الفعلي: أعد ربط عنوان 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.
صفحات ذات صلة
- توجيه المواقع وتعدد المواقع: كيف يُحلّ الطلب الموجّه إلى كنيسة أو موقع داخل B1App
- نشر واجهة برمجة التطبيقات: نشر واجهة Membership API التي تقدّم
authorizeوhostmap