دليل تشغيل تفعيل Pages

يقود دليل التشغيل هذا apothem.ahmedgad.com من تهيئة GitHub Pages جديدة إلى صفحة وصول HTTPS بحالة 200 OK. كُتب الإجراء للمشغِّل الذي يستخدم gh وحدة تحكم مزوِّد DNS؛ ويتبعه مساهم جديد كفء دون سياق مسبق.

يُبنى دليل التشغيل بوصفه نواة مستقلة عن المزوِّد (خطوات جانب GitHub وخطوات سجل DNS التي يتشاركها كل مزوِّد) يتبعها ملاحق خاصة بالمزوِّد لـNamecheap وCloudflare وRoute53، وبديل احتياطي عام لـDNS. شغِّل النواة بالترتيب؛ وانتقل إلى الملحق المطابق لمُسجِّل نطاق القمة / مضيف DNS؛ ثم عُد إلى النواة للتحقق.

يُستضاف الموقع من المستودع العام ahmed-g-gad/apothem عبر GitHub Pages مع توجيه CNAME الخاص بالنطاق المخصص إلى ahmed-g-gad.github.io. يُخرج بناء الموقع الثابت إلى site/dist/؛ ويرفع سير عمل Pages أداة البناء تلك إلى الموقع المباشر عند كل دفع إلى main.

1. المتطلبات المسبقة

يؤكد المشغِّل ما يلي قبل المتابعة:

• حالة المستودع. ahmed-g-gad/apothem عام، ومُفعَّل عليه Pages (Settings > Pages > Source: GitHub Actions)، ويوجد سير العمل publish-static-site.yml في .github/workflows/publish-static-site.yml.
• سلطة DNS. يتحكم المشغِّل في DNS لـahmedgad.com عند المُسجِّل أو عند مضيف DNS مُفوَّض (Cloudflare، Route53، إلخ). يُحدَّد مضيف DNS عبر dig NS ahmedgad.com +short.
• الأدوات. gh (GitHub CLI) الإصدار 2.40 أو أحدث، مُصادَقًا عليه مقابل حساب ahmed-g-gad؛ وdig (BIND dig أو drill) للتحقق من DNS؛ ومتصفح لفحص HTTPS.
• موقف القمة. يُهيِّئ دليل التشغيل هذا النطاق الفرعي apothem.ahmedgad.com فقط. ولا تُمسّ القمة ahmedgad.com. يتطلب CNAME عند القمة تسطيح CNAME (Cloudflare) أو سجلات ALIAS (Route53)؛ ومسار النطاق الفرعي يتجنب كلا صنفي التعقيد.

2. النواة المستقلة عن المزوِّد

2.1 أضف النطاق المخصص إلى Pages

gh api -X PUT \
  /repos/ahmed-g-gad/apothem/pages \
  -F cname=apothem.ahmedgad.com \
  -F https_enforced=true

تحقَّق من أن الاستدعاء أعاد سجل CNAME الجديد:

gh api /repos/ahmed-g-gad/apothem/pages \
  --jq '.cname, .https_enforced, .status'

المخرجات المتوقعة:

apothem.ahmedgad.com
true
built

تؤكد الحالة built أن أحدث بناء لـPages نجح. أما الحالة null فتعني أن Pages لم يُشغَّل منذ تطبيق CNAME — ادفع إيداعًا بلا تغيير إلى main لتشغيل البناء.

2.2 أكِّد ملف CNAME

يستقبل GitHub Pages ملف site/public/CNAME عبر أداة بناء الموقع الثابت عند كل نشر. يحتوي الملف على النطاق المخصص في سطر واحد، دون مخطط، ودون شرطة مائلة في النهاية:

apothem.ahmedgad.com

يوجد الملف في site/public/CNAME. تحقَّق:

cat site/public/CNAME

إذا كان الملف مفقودًا، أعد إنشاءه في site/public/CNAME وأودِعه تحت chore: restore Pages CNAME.

2.3 أضف سجل DNS

يخدم Pages النطاق المخصص عندما يعيد مزوِّد DNS للقمة أحد عناوين IP الأربعة لـGitHub (لنطاقات القمة) أو CNAME يشير إلى <owner>.github.io (للنطاقات الفرعية). بالنسبة إلى apothem.ahmedgad.com يكون صنف السجل هو CNAME:

يختلف تدفق الواجهة الدقيق لإضافة السجل بين المزوِّدين؛ انتقل إلى الملحق المطابق أدناه، وعُد إلى هنا عند حفظ السجل.

2.4 انتظر انتشار DNS

يكتمل الانتشار خلال خمس دقائق للسجلات ذات TTL المنخفض وخلال ساعة لـTTL الافتراضي البالغ 3600 ثانية — وقد تُمدِّد حواف المزوِّد هذه النافذة أثناء نقل منطقة DNS. تابِع التقدم:

dig apothem.ahmedgad.com CNAME +short

المخرجات المتوقعة:

ahmed-g-gad.github.io.

المخرجات الفارغة تعني أن السجل لم ينتشر بعد. أعد التشغيل كل 30 ثانية. إذا لم يظهر السجل أبدًا بعد 30 دقيقة، عُد إلى الملحق المطابق لمضيف DNS وتحقَّق من أن السجل مُودَع عند المزوِّد، لا معلَّقًا في حالة مسوَّدة.

2.5 تحقَّق من HTTPS

curl -sSI https://apothem.ahmedgad.com/ | head -5

المخرجات المتوقعة:

HTTP/2 200
server: GitHub.com
content-type: text/html; charset=utf-8
strict-transport-security: max-age=31536000

يؤكد السطران HTTP/2 200 وserver: GitHub.com معًا أن Pages يخدم الموقع بشهادة TLS صالحة. كما يُحقق التحويل 301 إلى عنوان HTTPS عند طلب HTTP عادي البوابة أيضًا؛ ففرض HTTPS مُفعَّل.

إذا أعاد curl الرمز 526 (رمز شهادة غير صالحة خاص بـCloudflare) أو 502 (بوابة سيئة)، فالشهادة لم تُصدَر بعد. يُوفِّر Pages شهادات Let's Encrypt تلقائيًا بمجرد تحلُّل CNAME؛ فامنح حتى 24 ساعة للإصدار الأول. للتشخيص:

gh api /repos/ahmed-g-gad/apothem/pages \
  --jq '.https_certificate.state, .https_certificate.description'

تعني state: approved أن الإصدار اكتمل. وتعني state: requesting أن الإصدار جارٍ؛ انتظر. وأي حالة أخرى تتطلب إعادة تشغيل Pages (أوقِف النطاق المخصص وأعِد تشغيله عبر الـAPI).

2.6 تحقَّق من الروابط العميقة

curl -sSI https://apothem.ahmedgad.com/architecture/ | head -3

المخرجات المتوقعة:

HTTP/2 200
server: GitHub.com
content-type: text/html; charset=utf-8

يعني رمز 404 على رابط عميق أن بناء الموقع الثابت لم يلتقط الصفحة أو أن النشر لم يكتمل. شغِّل إعادة بناء عبر gh workflow run publish-static-site.yml.

2.7 سجِّل التحقق

أضِف صفًا إلى سجل حالة موقع المشغِّل (أو إلى سجل التحقق في دليل التشغيل هذا إن كان يُحفَظ مضمَّنًا) مع التاريخ، وهوية المشغِّل، ومخرجات حالة Pages من gh api. سجل التحقق هو أثر التدقيق — فكل تغيير في تهيئة Pages يترك صفًا.

3. ملحق المزوِّد — Namecheap

يكشف Namecheap عن DNS عبر علامة التبويب "Advanced DNS" لدى المُسجِّل. يملك المشغِّل ahmedgad.com هنا عندما تتطابق سجلات NS للمُسجِّل مع dns1.registrar-servers.com و dns2.registrar-servers.com (الافتراضي لـNamecheap). تحقَّق بـdig NS ahmedgad.com +short.

الخطوات:

1. سجِّل الدخول إلى Namecheap؛ وافتح لوحة التحكم.
2. انقر Domain List في التنقل الأيسر؛ وحدِّد موقع ahmedgad.com؛ وانقر Manage.
3. انقر علامة التبويب Advanced DNS.
4. انقر Add New Record. واختَر:
   • Type: CNAME Record
   • Host: apothem (دون قمة، دون نقطة في النهاية)
   • Value: ahmed-g-gad.github.io. (مع نقطة في النهاية)
   • TTL: Automatic (افتراضي Namecheap؛ يحترم 1800 ثانية)
5. انقر علامة الاختيار الخضراء للحفظ.
6. انتظر من 5 إلى 10 دقائق لانتشار حافة Namecheap؛ ثم عُد إلى النواة المستقلة عن المزوِّد §2.4 للتحقق بـdig.

عُطل شائع: ترفض واجهة Namecheap سجلات CNAME بصمت عندما يشغل سجل A المضيف نفسه بالفعل. احذف سجل A المتعارض أولًا؛ فـCNAME وA على المضيف نفسه يتنافيان بحسب RFC 1034.

4. ملحق المزوِّد — Cloudflare

يستضيف Cloudflare DNS القمة عندما تشير سجلات NS للمُسجِّل إلى *.ns.cloudflare.com (افتراضي Cloudflare بعد التفويض). تحقَّق بـ dig NS ahmedgad.com +short.

الخطوات:

1. سجِّل الدخول إلى Cloudflare؛ واختَر منطقة ahmedgad.com.
2. انقر DNS -> Records في التنقل الأيسر.
3. انقر Add record. واختَر:
   • Type: CNAME
   • Name: apothem (يُضيف Cloudflare القمة تلقائيًا)
   • Target: ahmed-g-gad.github.io (دون نقطة في النهاية في واجهة Cloudflare)
   • TTL: Auto (افتراضي Cloudflare؛ يوجِّه عبر حافته)
   • Proxy status: DNS only (سحابة رمادية، لا برتقالية)
4. انقر Save.

اختيار حالة الوكيل حاسم. فتفعيل وكيل Cloudflare (السحابة البرتقالية) يوجِّه حركة المرور عبر حافة Cloudflare قبل الوصول إلى GitHub Pages؛ وهذا يكسر إصدار Let's Encrypt في Pages لأن Cloudflare يقدِّم شهادته الخاصة. أبقِ الوكيل مُعطَّلًا للإعداد الأولي؛ وفعِّل الوكيل لاحقًا فقط بعد أن تقرر ما إذا كنت ستدير الشهادة عند حافة Cloudflare.

5. انتظر من 1 إلى 2 دقيقة لانتشار حافة Cloudflare؛ ثم عُد إلى النواة المستقلة عن المزوِّد §2.4.

عُطل شائع: يزيل Cloudflare النقطة النهائية من أهداف CNAME بصمت. يقبل حقل الهدف ahmed-g-gad.github.io دون النقطة النهائية؛ ويُضيف المُحلِّل النقطة النهائية وقت الاستعلام. لا تكتب النقطة النهائية في واجهة Cloudflare — فهي تُنتج سجلًا بنقطة مزدوجة يفشل في التحلُّل.

5. ملحق المزوِّد — Route53

يستضيف Route53 المنطقة عندما تشير سجلات NS للمُسجِّل إلى أربعة خوادم awsdns-*.com / awsdns-*.org / awsdns-*.co.uk / awsdns-*.net. تحقَّق بـ dig NS ahmedgad.com +short.

الخطوات:

1. افتح AWS Console؛ وانتقل إلى Route53؛ وانقر Hosted zones؛ واختَر منطقة ahmedgad.com.
2. انقر Create record.
3. هيِّئ:
   • Record name: apothem (يُضيف Route53 القمة تلقائيًا)
   • Record type: CNAME
   • Value: ahmed-g-gad.github.io (دون نقطة في النهاية)
   • TTL: 300 (5 دقائق؛ افتراضيات Route53 أعلى؛ خفِّض TTL لانتشار أسرع أثناء التبديل)
   • Routing policy: Simple routing
4. انقر Create records.
5. انتظر من 1 إلى 5 دقائق لانتشار Route53؛ وعُد إلى §2.4.

يدعم Route53 سجلات الاسم البديل التي تتحلَّل وقت الاستعلام دون توسيط CNAME. ولا تُستخدم سجلات الاسم البديل هنا لأن أهداف الاسم البديل مقصورة على موارد AWS (CloudFront، S3، ELB، إلخ) وahmed-g-gad.github.io ليس موردًا في AWS. فـCNAME هو الصحيح.

عُطل شائع: تقبل واجهة Route53 أسماء سجلات مكررة بسياسات توجيه مختلفة؛ ويظهر هذا كتوجيه تجاوز فشل بأسلوب فحص الصحة بدلًا من CNAME بسيط. أكِّد أن Routing policy تُظهر Simple routing قبل الحفظ.

6. ملحق المزوِّد — DNS العام

لمضيفي DNS غير المشمولين بالملاحق المُسمّاة (لوحات DNS الافتراضية لمعظم المُسجِّلين — GoDaddy، Hover، Gandi، OVH، Porkbun، Domains.google، Network Solutions)، طبِّق شكل CNAME المستقل عن المزوِّد:

صنفا العُطل اللذان يتكرران عبر اللوحات العامة:

• عدم اتساق النقطة النهائية. تطلب بعض اللوحات النقطة النهائية؛ ويرفضها غيرها؛ ويقبل بعضها أيًّا منهما. عندما يفشل السجل في الانتشار بعد 30 دقيقة، بدِّل النقطة النهائية وأعِد الحفظ.
• سجل A متعارض على المضيف نفسه. ينتهك CNAME وA على المضيف نفسه RFC 1034 (Domain Names — Concepts and Facilities) القسم الثالث حول تفضيلات أسماء النطاقات. احذف سجل A المتعارض قبل إضافة CNAME.

بعد حفظ السجل، عُد إلى §2.4 للتحقق بـdig.

7. التعافي من الفشل

لإجراء تفعيل Pages أربعة أنماط فشل موثَّقة:

إذا فشل التعافي بعد دورة واحدة من التشخيص المطابق، صعِّد إلى دليل تشغيل التعافي من الإصدار (قد يكون الدفع القسري لتاريخ جديد قد ترك تهيئة Pages في حالة غير متسقة).

8. الإحالات المرجعية

• مصدر المواصفات. تُدرج المواصفات §2.5 دليل التشغيل هذا ضمن مُخرجات توثيق Cluster 4.
• الموقع القانوني لـ CNAME. يوجد ملف CNAME في site/public/CNAME ومُودَع في المستودع؛ ويقرأه Pages عند كل بناء.
• تدفق التعافي. يعيد دليل تشغيل التعافي من الإصدار تطبيق تهيئة Pages من لقطة التعافي عندما يفشل تسلسل التبديل في منتصف الطريق.
• دورة الإصدار. يتضمن كل تشغيل إصدار مهمة بناء Pages تتحقق من أن الموقع يُعرَض على النطاق المخصص.