DevOps والتشغيل الأدلة التقنية

Backstage: كتالوج الخدمات Service Catalog مع التوثيق الموحد

نبني بوابة Backstage بصورة إنتاج على PostgreSQL لمتجر من فريقين، فيجد المطور الجديد مالك كل خدمة وعقد واجهتها وتوثيقها في صفحة واحدة، ثم نرى ماذا يحدث عندما يخطئ أحد في ملف الكتالوج.

Backstage: كتالوج الخدمات Service Catalog مع التوثيق الموحد

في الشهر الأول لأي مطور جديد في فريق تجاوز عشر خدمات، تتكرر نفس الأسئلة في قناة الفريق: من يملك خدمة الدفع؟ هل هذه الخدمة ما زالت تعمل في الإنتاج أم أوقفناها؟ أين عقد ال API الذي تستدعيه؟ أين التوثيق، في الويكي أم في ملف README أم في رأس فلان؟ وماذا أفعل إذا تعطلت في الليل؟ والإجابات موجودة كلها، ولكنها موزعة بين عشرة أماكن، وبعضها قديم، وبعضها لا يعرفه إلا شخص واحد. وكل سؤال منها يأخذ من المطور الجديد ساعة، ومن الزميل الذي يجيب عشر دقائق، وكل مرة.

والحل الذي بنته Spotify لهذه المشكلة ثم نشرته مفتوح المصدر Open Source هو Backstage: بوابة واحدة للمطورين Developer Portal، قلبها كتالوج الخدمات Software Catalog الذي يقول لك عن كل خدمة من يملكها وعلى ماذا تعتمد وما ال APIs التي تقدمها، وبجانبه التوثيق الموحد TechDocs الذي يعرض توثيق كل خدمة من ملفات Markdown في مستودعها نفسه. وفي هذا المقال سوف نتابع متجراً إلكترونياً لشركة ناشئة وصل فريقه إلى فريقين وعدة خدمات، فنبني له بوابة Backstage حقيقية بصورة إنتاج Production Image على PostgreSQL، ونكتب كتالوج المتجر، ونعرض توثيق خدمة منه، ثم نخطئ في الكتالوج عمداً لنرى ماذا يفعل Backstage. أما قوالب إنشاء الخدمات Templates والطرق الممهدة Golden Paths فقد شرحناها في مقال هندسة المنصات، ولن نكررها هنا.

وسوف نناقش في هذا المقال ما يلي:

  • ما هو Backstage ومن أين جاء، ولماذا هو إطار تبني عليه وليس منتجاً تثبته.
  • نموذج الكتالوج System Model: الأنواع والعلاقات والمالك ودورة الحياة، وملف catalog-info.yaml سطراً سطراً.
  • من أين يقرأ الكتالوج بياناته، وكيف تتحدث، وكيف يعمل TechDocs من Markdown إلى صفحة في البوابة.
  • مختبر حقيقي: صورة إنتاج بال Dockerfile الرسمي، وثلاث مشكلات واجهتنا في الطريق، والكتالوج والتوثيق في البوابة.
  • تجارب «ماذا لو»: مالك بخطأ إملائي، وخدمة تحذف من الملف، وصفحات توثيق تختفي عند إعادة إنشاء ال Container.
  • كيف تبدأ في فريقك، ومتى لا تحتاج Backstage أصلاً، والأخطاء الشائعة وقائمة تحقق.

ما هو Backstage؟ What is Backstage

بدأ Backstage مشروعاً داخلياً في Spotify، وفي 16 مارس 2020 نشرته الشركة مفتوح المصدر، وشرحت في مقال الإعلان المشكلة التي بني لها: كلما كبرت الشركة يحتاج المهندس أن يتعلم أدوات أكثر، من أدوات البنية التحتية إلى أنظمة CI والمراقبة، وكل أداة لها واجهتها، فجاء Backstage ليجمع الأدوات والخدمات والتوثيق في واجهة واحدة متسقة. ثم قبلته مؤسسة CNCF في 8 سبتمبر 2020، وانتقل إلى مستوى الاحتضان Incubating في 15 مارس 2022 كما في صفحة المشروع في CNCF.

وأهم ما يجب أن تعرفه قبل أن تبدأ أن Backstage إطار Framework وليس منتجاً جاهزاً. فلا توجد صورة Docker رسمية تشغلها وتبدأ العمل، وإنما الأمر create-app ينشئ لك تطبيق TypeScript كاملاً، فيه واجهة React وخادم Node.js، وأنت تملكه وتبنيه وتحدثه وتضيف إليه الإضافات Plugins بتعديل الكود. وهذا يعطيك مرونة كبيرة، فتستطيع أن تضيف صفحة لأي أداة داخلية، ولكنه يعني أن البوابة نفسها مشروع برمجي يحتاج من يصونه، كما سنرى في المختبر عندما أوقفتنا مشكلة في ملف القفل yarn.lock قبل أن نكتب أي سطر.

وفي Backstage ثلاث قدرات أساسية: الكتالوج Software Catalog، والتوثيق TechDocs، وقوالب الإنشاء Software Templates، ومعها البحث Search الذي يبحث في الكتالوج والتوثيق معاً. والقوالب هي الأكثر إبهاراً في العروض، ولكن الكتالوج هو الأساس الذي يعتمد عليه كل شيء آخر، فالقالب الذي ينشئ خدمة جديدة يسجلها في الكتالوج، وصفحة التوثيق تعيش داخل صفحة الخدمة في الكتالوج، والإضافات التي تعرض حالة CI أو المراقبة لخدمة تعرف هذه الخدمة من الكتالوج. ولذلك فالترتيب الذي ننصح به أن تبدأ بالكتالوج والتوثيق، ثم تضيف القوالب عندما يكون لديك ما تستحق أن تجعله طريقاً ممهداً.

ماذا يحل الكتالوج؟ Tribal Knowledge

المعرفة التي لا يعرفها إلا أشخاص معينون، ويسميها البعض المعرفة القبلية Tribal Knowledge، هي ما يجعل الفريق يبطئ كلما كبر. فالفريق الصغير يعرف كل شيء لأن كل شخص كتب جزءاً منه، ولكن عند الخدمة العاشرة والمطور الخامس عشر يصبح السؤال «من يملك هذه؟» سؤالاً حقيقياً، وتصبح الإجابة «اسأل فلان» نقطة فشل واحدة Single Point of Failure. والصورة التالية تبين الأسئلة التي يسألها المطور الجديد، والحقل الذي يجيب عن كل منها في ملف الكتالوج:

ستة أسئلة وحقولها: من يملك الخدمة في spec.owner، وهل هي في الإنتاج في spec.lifecycle، وعلى ماذا تعتمد في dependsOn وconsumesApis، وأين عقد ال API في نوع API بتعريف openapi، وأين التوثيق في التعليق backstage.io/techdocs-ref، وماذا أفعل إذا تعطلت في روابط metadata.links
كل سؤال له حقل، والحقل بجانب الكود

والفكرة المهمة هنا أن هذه المعلومات لا تكتب في نظام مركزي يحدثه شخص واحد، وإنما في ملف YAML اسمه غالباً catalog-info.yaml يعيش في مستودع كل خدمة، ويتغير مع الكود في نفس طلب الدمج Pull Request. فإذا أضاف المطور اعتماداً على قاعدة بيانات جديدة، فهو يضيفه في نفس الطلب الذي يضيف فيه الكود، والمراجع يراه. وهذا هو الفرق بين الكتالوج والجدول الذي يكتبه الفريق في الويكي ثم ينساه بعد شهرين: الكتالوج يقرأ من نفس المكان الذي يتغير فيه النظام. ولكن لاحظ أن هذا يحل مشكلة واحدة فقط، وهي مكان المعلومة، أما صحتها فتبقى مسؤولية الفريق، كما سنرى في تجربة «ماذا لو».

نموذج الكتالوج System Model

يصف توثيق نموذج النظام الأنواع Kinds التي يتكون منها الكتالوج، والصورة التالية تبين الأنواع التي استخدمناها لمتجر المختبر والعلاقات بينها:

نموذج الكتالوج: Group وUser للفريقين والأشخاص الثلاثة، وSystem اسمه shop، وثلاثة Components هي storefront وcheckout-api وpayments، واثنان من نوع API هما checkout-api وpayments-api، وResource اسمه orders-db
ستة أنواع تكفي لوصف متجر كامل

ولنمر على الأنواع لأن الخلط بينها أكثر خطأ تراه في الكتالوجات الجديدة:

  • المكون Component: قطعة برمجية تبنى وتنشر، مثل خدمة أو موقع أو مكتبة، ولها نوع في spec.type مثل service أو website أو library.
  • الواجهة API: العقد بين المكونات، وهي كيان مستقل وليست جزءاً من المكون، والسبب أن الواجهة قد يقدمها مكون وتستهلكها عشرة، وتتغير بدورة مختلفة عن الكود. ويعرض Backstage تعريفها بصيغة OpenAPI أو AsyncAPI أو GraphQL أو gRPC في صفحتها.
  • المورد Resource: ما يحتاجه المكون ليعمل ولا تكتبه أنت، مثل قاعدة البيانات Database أو مخزن الملفات أو قائمة الرسائل.
  • النظام System: مجموعة مكونات وواجهات وموارد تعمل معاً لتقدم قدرة واحدة، مثل المتجر، ويساعدك أن ترى الصورة الكاملة دون أن تغرق في عشرات المكونات.
  • المجال Domain: مجموعة أنظمة في مجال عمل واحد، مثل المدفوعات أو الشحن، ولم نحتجه في متجر صغير.
  • الفريق Group والمستخدم User: المالكون. والقاعدة المهمة أن المالك يكون فريقاً وليس شخصاً، والسبب أن الشخص يغادر أو ينتقل، والفريق يبقى، وإذا كان المالك شخصاً فأول مغادرة تترك الخدمة بلا مالك.

ولكل مكون كذلك دورة حياة Lifecycle في spec.lifecycle، والقيم المعروفة experimental وproduction وdeprecated. وهذا الحقل الصغير يجيب عن سؤال يكلف كثيراً في الواقع: هل أستطيع أن أبني على هذه الخدمة؟ فالخدمة المعلمة deprecated تقول للمطور الجديد ألا يضيف إليها اعتماداً جديداً، دون أن يحتاج أن يسأل أحداً.

ملف الكتالوج catalog-info.yaml سطراً سطراً

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

# Teams and people. Owners in the other files point here (group:team-checkout, user:ops-lead).
apiVersion: backstage.io/v1alpha1
kind: Group
metadata: { name: team-checkout, title: Checkout team }
spec: { type: team, children: [], members: [dev-a, dev-b] }
---
apiVersion: backstage.io/v1alpha1
kind: Group
metadata: { name: team-platform, title: Platform team }
spec: { type: team, children: [], members: [ops-lead] }
---
apiVersion: backstage.io/v1alpha1
kind: User
metadata: { name: dev-a }
spec: { memberOf: [team-checkout] }
---
apiVersion: backstage.io/v1alpha1
kind: User
metadata: { name: dev-b }
spec: { memberOf: [team-checkout] }
---
apiVersion: backstage.io/v1alpha1
kind: User
metadata: { name: ops-lead }
spec: { memberOf: [team-platform] }

والملف الثاني للمتجر نفسه:

# The shop system: three components, one API between them, one database.
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: shop
  description: Online store, from the product page to the payment
spec: { owner: group:team-checkout }
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: storefront
  description: Web storefront (product pages, cart)
  tags: [web, nextjs]
spec:
  type: website
  lifecycle: production
  owner: group:team-checkout
  system: shop
  dependsOn: [component:checkout-api]
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: checkout-api
  description: Orders and checkout. Calls the payments API.
  tags: [python, flask]
  annotations:
    backstage.io/techdocs-ref: dir:./checkout-api
  links:
    - { url: https://runbooks.example.com/checkout, title: Runbook }
spec:
  type: service
  lifecycle: production
  owner: group:team-checkout
  system: shop
  providesApis: [checkout-api]
  consumesApis: [payments-api]
  dependsOn: [resource:orders-db]
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payments
  description: Card payments through the payment gateway
  tags: [python]
spec:
  type: service
  lifecycle: production
  owner: group:team-platform
  system: shop
  providesApis: [payments-api]
---
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata: { name: orders-db, description: PostgreSQL database of orders }
spec: { type: database, owner: group:team-platform, system: shop }
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata: { name: checkout-api, description: Public checkout API used by the storefront }
spec:
  type: openapi
  lifecycle: production
  owner: group:team-checkout
  system: shop
  definition: |
    openapi: 3.0.3
    info: { title: Checkout API, version: 1.4.0 }
    paths:
      /api/checkout:
        post:
          summary: Pay for the current cart
          responses:
            "200": { description: Paid }
            "502": { description: The payment gateway refused or timed out }
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata: { name: payments-api, description: Internal card charge API }
spec:
  type: openapi
  lifecycle: production
  owner: group:team-platform
  system: shop
  definition: |
    openapi: 3.0.3
    info: { title: Payments API, version: 2.0.0 }
    paths:
      /charge:
        post:
          summary: Charge a card
          responses:
            "200": { description: Charged }
            "503": { description: Declined by the issuer }

في الملف أعلاه لاحظ التالي:

  • كل كيان يبدأ بثلاثة حقول ثابتة: apiVersion وkind وmetadata.name، والاسم مع النوع ومساحة الأسماء Namespace هو هوية الكيان، فـ checkout-api المكون وcheckout-api الواجهة كيانان مختلفان رغم نفس الاسم، لأن النوع مختلف، والصيغة الكاملة لكل حقل في توثيق صيغة الملف.
  • المراجع Entity References تكتب بصيغة kind:name، مثل group:team-checkout وresource:orders-db، وإذا حذفت النوع فإن Backstage يفترض نوعاً بحسب الحقل، ولذلك اكتبه دائماً لكي لا تخمن.
  • العلاقات تكتب من جهة واحدة فقط، فنحن كتبنا في checkout-api أنه consumesApis: [payments-api]، والكتالوج يولد العلاقة العكسية apiConsumedBy على الواجهة تلقائياً. ولهذا ظهر في المختبر أن للنظام shop سبع علاقات رغم أننا لم نكتب فيه أي علاقة.
  • التعليق Annotation backstage.io/techdocs-ref: dir:./checkout-api يقول لـ TechDocs أين يجد ملف mkdocs.yml للخدمة، والمسار نسبي من مكان الملف نفسه. والتعليقات المعروفة الأخرى مثل رابط المستودع ومعرف المشروع في أدوات CI موجودة في قائمة التعليقات المعروفة.
  • تعريف ال API مكتوب داخل الملف في spec.definition، وفي الواقع الأفضل أن يشير إلى ملف OpenAPI في المستودع بالصيغة $text: ./openapi.yaml، لكي يبقى العقد في مكان واحد، وقد شرحنا كيف تصمم هذا العقد في مقال تصميم واجهات API.
  • الروابط في metadata.links مكان دليل التشغيل وصفحة المناوبة ولوحة المراقبة، وهي أكثر ما يحتاجه المناوب في الليل، فاجعل رابط دليل التشغيل Runbook أول رابط في كل خدمة.

من أين يقرأ الكتالوج؟ Locations and Processing

الكتالوج لا يستقبل الكيانات بالدفع Push، وإنما يقرأها بنفسه من مواقع Locations تحددها في الإعداد أو تسجلها من الواجهة. والموقع قد يكون ملفاً محلياً كما في المختبر، أو رابطاً إلى ملف في GitHub أو GitLab أو Gitea، أو مزود اكتشاف Discovery Provider يمر على كل مستودعات المؤسسة ويبحث فيها عن catalog-info.yaml، وهذا الأخير هو ما تريده في الإنتاج، لكي لا يحتاج أحد أن يسجل كل خدمة يدوياً.

وبعد القراءة تمر الكيانات بثلاث مراحل يشرحها توثيق دورة حياة الكيان: الاستقبال Ingestion من الموقع، ثم المعالجة Processing التي تتحقق من الصيغة وتستخرج العلاقات، ثم الدمج Stitching الذي يجمع العلاقات من الجهتين في الكيان النهائي الذي تراه الواجهة. وهذه الدورة تتكرر دورياً لكل كيان، ولذلك فالتغيير في الملف لا يظهر فوراً، وإنما بعد الدورة التالية، وقد قسنا هذا في المختبر فكان بين 77 و88 ثانية. وهذا مهم لتعرفه قبل أن تظن أن تعديلك لم يعمل. وإذا كنت تريد أن ترى التغيير فوراً، ففي بطاقة About في صفحة كل كيان زر تحديث يطلب من الكتالوج أن يعيد معالجة هذا الكيان الآن بدلاً من انتظار الدورة، كما ترى في صورة صفحة الخدمة لاحقاً. ولكن لاحظ أن هذا الزر يحدث الكيان من موقعه، أي أنه لا يفيد إذا كان التغيير في ملف آخر، مثل فريق أضفته في ملف الفرق، فهنا تنتظر دورة ذلك الملف. وفي الفرق الكبيرة يكون عدد الكيانات بالآلاف، والدورة نفسها عمل مستمر على قاعدة البيانات والخادم، ولذلك فالكتالوج يحتاج قاعدة PostgreSQL حقيقية في الإنتاج، وليس SQLite في الذاكرة كما في الإعداد الافتراضي للتطوير، والتي تفقد كل شيء عند كل إعادة تشغيل.

وفي نفس التوثيق قاعدة يجب أن تعرفها قبل أن يحدث لك ما حدث لنا في المختبر: إذا توقف الموقع الأب عن إخراج كيان، لأنك حذفته من الملف مثلاً، فإن الكيان يصبح يتيماً Orphan، والسلوك الافتراضي للكتالوج أن يحذف الكيانات اليتيمة تلقائياً، ما لم تضبط catalog.orphanStrategy: keep. أي أن حذف سطر من ملف في مستودع يحذف الخدمة من البوابة كلها، مع كل ما ربطه الناس بها.

التوثيق كالكود: TechDocs

الفكرة في TechDocs بسيطة: التوثيق ملفات Markdown في مستودع الخدمة نفسه، يراجع في طلب الدمج مثل الكود، ثم يبنى بـ MkDocs ويعرض داخل صفحة الخدمة في البوابة، فلا يحتاج المطور أن يتذكر رابط ويكي منفصل. والصورة التالية تبين المسار:

مسار TechDocs في أربع خطوات: المصدر mkdocs.yml وملفات docs في المستودع، ثم التوليد بـ MkDocs مع techdocs-core بإعداد runIn local، ثم النشر إلى مخزن بإعداد publisher local أو S3، ثم العرض في تبويب Docs للخدمة
من ملف Markdown إلى صفحة في البوابة

وفي هذا المسار قراران يجب أن تأخذهما. الأول أين يحدث التوليد: في الإعداد الافتراضي builder: local يبني ال Backend التوثيق عند أول زيارة للصفحة، وهو مناسب للبداية، أما البنية الموصى بها فهي أن يبنيه خط CI عند كل تغيير ويرفعه إلى مخزن، ويكتفي ال Backend بالقراءة مع builder: external. والثاني أين يعمل MkDocs: الإعداد الافتراضي runIn: docker يشغل Container خاصاً للتوليد، وهذا يحتاج أن يصل ال Backend إلى Docker، وهو غير مناسب إذا كان ال Backend نفسه في Container، ولذلك يقول توثيق الإعداد إن runIn: local هو الخيار عندما تشغل Backstage في إعداد Docker خاص وتريد أن تتجنب تشغيل Docker داخل Docker، بشرط أن تثبت MkDocs بنفسك، وهذا ما فعلناه. وملف mkdocs.yml للخدمة قصير:

site_name: checkout-api
nav:
  - Overview: index.md
  - On-call: on-call.md
plugins:
  - techdocs-core

المختبر Lab: بوابة المتجر بصورة إنتاج

الآن سوف نبني البوابة كما تبنى للإنتاج، وليس بوضع التطوير yarn start الذي استخدمناه في مقال هندسة المنصات. أي صورة Docker فيها الواجهة والخادم معاً، وقاعدة PostgreSQL 18 للكتالوج بدلاً من SQLite في الذاكرة، والكتالوج والتوثيق من ملفات المختبر.

إنشاء التطبيق create-app

أنشأنا التطبيق بالأمر create-app بالإصدار 0.9.3، داخل Container من Node.js 24، مع الخيار --skip-install لأننا سوف نثبت الحزم داخل بناء ال Image وليس على الجهاز:

docker run --rm -e BACKSTAGE_APP_NAME=portal -v "$PWD:/work" -w /work node:24.22.1-bookworm \
  bash -c 'corepack enable; npx -y @backstage/[email protected] --path /work/portal --skip-install'

واستغرق الأمر 19 ثانية، والملف backstage.json في التطبيق الناتج يقول إن إصدار Backstage هو 1.56.0. والمتغير BACKSTAGE_APP_NAME يجيب عن سؤال اسم التطبيق الذي يطرحه الأمر، فيصبح الأمر قابلاً للتشغيل في سكربت.

ماذا يوجد في التطبيق الناتج؟ App Anatomy

قبل أن نبني، من المفيد أن تعرف ما أنشأه الأمر، لأن هذا ما سوف تصونه. ففي المجلد حزمتان أساسيتان: packages/app وهي الواجهة، تطبيق React يبنى إلى ملفات ثابتة، وpackages/backend وهو الخادم بلغة Node.js، يحمل الإضافات ويخدم الواجهة المبنية نفسها، ولذلك تكفي صورة واحدة ومنفذ واحد. وبجانبهما مجلد plugins فارغ للإضافات التي تكتبها بنفسك، ومجلد examples فيه كيانات تجريبية، وثلاثة ملفات إعداد. والإضافات التي يحملها ال Backend الافتراضي ظهرت في أول سطر من سجل التشغيل:

"message":"Plugin initialization started: 'app', 'auth', 'catalog', 'kubernetes', 'mcp-actions', 'notifications', 'permission', 'proxy', 'scaffolder', 'search', 'signals', 'techdocs', …"

أي أن التطبيق الجديد يحمل إضافة Kubernetes حتى لو لم يكن عندك Kubernetes، وإضافة القوالب Scaffolder، وإضافة MCP التي تعرض أدوات البوابة لوكلاء الذكاء الاصطناعي. وكل إضافة تحمل تعني كوداً يعمل وذاكرة تستهلك ومساحة هجوم Attack Surface إضافية، ولذلك راجع ملف packages/backend/src/index.ts بعد الإنشاء، واحذف الأسطر backend.add(...) للإضافات التي لا تستخدمها، فهذا من أول ما تفعله عندما تملك إطاراً وليس منتجاً.

مشكلة واجهتنا: yarn.lock من ثلاثة أسطر

ثم أضفنا ال Dockerfile متعدد المراحل Multi-stage من توثيق النشر بـ Docker وشغلنا البناء، ففشل بعد 79 ثانية في مرحلة yarn install --immutable:

#17 53.59 ➤ YN0028: │ The lockfile would have been modified by this install, which is explicitly forbidden.
#17 53.59 ➤ YN0000: · Failed with errors in 52s 488ms
#17 ERROR: process "/bin/sh -c yarn install --immutable" did not complete successfully: exit code: 1

والخيار --immutable يعني أن Yarn يرفض أن يغير ملف القفل أثناء التثبيت، وهذا صحيح تماماً في بناء الإنتاج، لأن الهدف أن يثبت البناء نفس الإصدارات التي اختبرها المطور. ولكن عندما فتحنا الملف وجدنا أنه ثلاثة أسطر فقط، أي رأس الملف بلا أي حزمة:

# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
# yarn lockfile v1

والسبب أن create-app يكتب ملف قفل فارغاً، ثم يعتمد على yarn install الذي يشغله بعد ذلك ليملأه، فإذا تخطيت التثبيت بقي الملف فارغاً، ويفشل أي بناء يستخدم --immutable. والحل أن تولد ملف القفل مرة واحدة دون أن تثبت الحزم على الجهاز، بالخيار --mode=update-lockfile، وهو يحل الإصدارات ويكتب الملف فقط:

docker run --rm -v "$PWD/portal:/app" -w /app node:24.22.1-bookworm \
  bash -c 'corepack enable && yarn install --mode=update-lockfile'

واستغرق 98 ثانية، وأصبح الملف 30,920 سطراً. وهذا الملف هو أهم ملف في المستودع بعد الكود، لأنه يحدد الإصدار الدقيق لكل حزمة من آلاف الحزم التي يعتمد عليها Backstage، فاحفظه في Git وراجع تغييراته عند كل ترقية.

ال Dockerfile مع MkDocs

استخدمنا ال Dockerfile الرسمي كما هو، مع ثلاثة تعديلات: ثبتنا إصدار Node بالكامل، وأضفنا MkDocs مع mkdocs-techdocs-core في بيئة Python افتراضية لكي يعمل TechDocs بإعداد runIn: local، ونسخنا كتالوج المختبر. والملف كاملاً كما يلي:

# Official multi-stage Dockerfile from backstage.io/docs/deployment/docker (Backstage 1.56.3 docs),
# with Node pinned, MkDocs added for TechDocs, and the lab catalog copied in.
# Stage 1 - Create yarn install skeleton layer
FROM node:24.22.1-trixie-slim AS packages

WORKDIR /app
COPY backstage.json package.json yarn.lock ./
COPY .yarn ./.yarn
COPY .yarnrc.yml ./

COPY packages packages

# Comment this out if you don't have any internal plugins
COPY plugins plugins

RUN find packages \! -name "package.json" -mindepth 2 -maxdepth 2 -exec rm -rf {} \+

# Stage 2 - Install dependencies and build packages
FROM node:24.22.1-trixie-slim AS build

# Install sqlite3 dependencies. You can skip this if you don't use sqlite3 in the image,
# in which case you should also move better-sqlite3 to "devDependencies" in package.json.
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && \
    apt-get install -y --no-install-recommends libsqlite3-dev && \
    rm -rf /var/lib/apt/lists/*

USER node
WORKDIR /app

COPY --from=packages --chown=node:node /app .

RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000 \
    yarn install --immutable

COPY --chown=node:node . .

RUN yarn tsc
RUN yarn --cwd packages/backend build

RUN mkdir packages/backend/dist/skeleton packages/backend/dist/bundle \
    && tar xzf packages/backend/dist/skeleton.tar.gz -C packages/backend/dist/skeleton \
    && tar xzf packages/backend/dist/bundle.tar.gz -C packages/backend/dist/bundle

# Stage 3 - Build the actual backend image and install production dependencies
FROM node:24.22.1-trixie-slim

# Install sqlite3 dependencies. You can skip this if you don't use sqlite3 in the image,
# in which case you should also move better-sqlite3 to "devDependencies" in package.json.
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && \
    apt-get install -y --no-install-recommends libsqlite3-dev && \
    rm -rf /var/lib/apt/lists/*

# From here on we use the least-privileged `node` user to run the backend.
USER node

# This should create the app dir as `node`.
# If it is instead created as `root` then the `tar` command below will
# fail: `can't create directory 'packages/': Permission denied`.
# If this occurs, then ensure BuildKit is enabled (`DOCKER_BUILDKIT=1`)
# so the app dir is correctly created as `node`.
WORKDIR /app

# Copy the install dependencies from the build stage and context
COPY --from=build --chown=node:node /app/.yarn ./.yarn
COPY --from=build --chown=node:node /app/.yarnrc.yml  ./
COPY --from=build --chown=node:node /app/backstage.json ./
COPY --from=build --chown=node:node /app/yarn.lock /app/package.json /app/packages/backend/dist/skeleton/ ./

# Note: The skeleton bundle only includes package.json files -- if your app has
# plugins that define a `bin` export, the bin files need to be copied as well to
# be linked in node_modules/.bin during yarn install.

RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000 \
    yarn workspaces focus --all --production && rm -rf "$(yarn cache clean)"

# Copy the built packages from the build stage
COPY --from=build --chown=node:node /app/packages/backend/dist/bundle/ ./

# Copy any other files that we need at runtime
COPY --chown=node:node app-config*.yaml ./

# This will include the examples, if you don't need these simply remove this line
COPY --chown=node:node examples ./examples

# TechDocs builds docs inside the backend (techdocs.generator.runIn: local), so the image needs MkDocs.
USER root
RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-venv && rm -rf /var/lib/apt/lists/*  && python3 -m venv /opt/mkdocs && /opt/mkdocs/bin/pip install --no-cache-dir mkdocs-techdocs-core==1.7.1
ENV PATH="/opt/mkdocs/bin:$PATH"
USER node

# The shop catalog of the lab (in a real setup this lives in each service repository)
COPY --chown=node:node catalog ./catalog

# This switches many Node.js dependencies to production mode.
ENV NODE_ENV=production

CMD ["node", "packages/backend", "--config", "app-config.yaml", "--config", "app-config.production.yaml", "--config", "app-config.lab.yaml"]

في الملف أعلاه لاحظ التالي:

  • المرحلة الأولى تنسخ ملفات package.json فقط، والسبب أن Docker يعيد استخدام طبقة yarn install من الذاكرة المؤقتة Cache ما دامت هذه الملفات لم تتغير، فتغيير سطر في الكود لا يعيد تثبيت الحزم.
  • المرحلة الثانية تبني كل شيء: yarn tsc للتحقق من الأنواع، ثم بناء ال Backend الذي يضم الواجهة المبنية معه، والنتيجة ملفان مضغوطان، هيكل Skeleton فيه ملفات package.json وحزمة Bundle فيها الكود المبني.
  • المرحلة الأخيرة تثبت حزم الإنتاج فقط بالأمر yarn workspaces focus --all --production، وتعمل بالمستخدم node وليس root. ولاحظ أننا رجعنا إلى root مؤقتاً لتثبيت Python ثم عدنا إلى node.

وكان البناء الثاني ناجحاً في 424 ثانية، منها 180 ثانية في yarn install، و10 ثوان في yarn tsc، و21 ثانية في بناء ال Backend، و100 ثانية في تثبيت حزم الإنتاج في المرحلة الأخيرة، و45 ثانية في تثبيت MkDocs. وال Image الناتجة حجمها 1.43 جيجابايت. وهذا رقم يستحق أن تفكر فيه: كل تحديث للبوابة، ولو كان سطراً في الإعداد إذا كان الإعداد داخل ال Image، يعني بناء بهذا الحجم، ولذلك أخرجنا الإعداد والكتالوج من ال Image وركبناهما Mount من الجهاز.

الإعداد Config مع Compose

يحمل Backstage ملفات الإعداد بالترتيب، وكل ملف يغطي ما قبله، فالأمر في آخر ال Dockerfile يحمل app-config.yaml ثم app-config.production.yaml ثم ملفنا app-config.lab.yaml:

# Lab overrides, loaded after app-config.yaml and app-config.production.yaml.
app:
  title: Shop Developer Portal
  baseUrl: http://localhost:47007
organization:
  name: Shop
backend:
  baseUrl: http://localhost:47007
auth:
  providers:
    guest:
      # Lab only: production builds refuse the guest provider without this flag (see the article)
      dangerouslyAllowOutsideDevelopment: true
techdocs:
  builder: local
  generator:
    runIn: local
  publisher:
    type: local
catalog:
  rules:
    - allow: [Component, System, API, Resource, Location, Group, User]
  locations:
    - type: file
      target: ./catalog/org.yaml
    - type: file
      target: ./catalog/shop.yaml

ولاحظ أن القوائم في إعداد Backstage لا تدمج وإنما تستبدل، فقائمة catalog.locations في ملفنا ألغت القائمة التي في app-config.production.yaml وفيها الأمثلة الافتراضية، وهذا ما نريده. وملف Compose كما يلي:

name: wr-dp-bs
services:
  db:
    image: postgres:18-alpine
    container_name: wr-dp-bs-db
    environment: { POSTGRES_USER: backstage, POSTGRES_PASSWORD: lab-only-pass }
    volumes: [ "wr-dp-bs-db:/var/lib/postgresql" ]
  backstage:
    image: wr-dp-backstage:1
    container_name: wr-dp-bs
    environment: { POSTGRES_HOST: wr-dp-bs-db, POSTGRES_PORT: "5432", POSTGRES_USER: backstage, POSTGRES_PASSWORD: lab-only-pass }
    ports: [ "127.0.0.1:47007:7007" ]
    # config and catalog from the host, so they can change without a rebuild.
    # The catalog mount must be writable: the TechDocs generator edits mkdocs.yml while it builds.
    volumes: [ "./app-config.lab.yaml:/app/app-config.lab.yaml:ro", "${CATALOG_DIR:-./catalog}:/app/catalog" ]
    depends_on: [db]
volumes:
  wr-dp-bs-db: { name: wr-dp-bs-db }
networks:
  default: { name: wr-dp-net }

مشكلة واجهتنا: الدخول كضيف Guest مرفوض في الإنتاج

في أول تشغيل كان ملف الإعداد يحتوي guest: {} فقط، كما في التطبيق الافتراضي، فعملت البوابة وعرضت صفحة الدخول، ولكن طلب الدخول رجع برمز 403:

{"error":{"name":"NotAllowedError","message":"The guest provider cannot be used outside of a development environment unless 'auth.providers.guest.dangerouslyAllowOutsideDevelopment' is enabled"},"request":{"method":"GET","url":"/guest/refresh"},"response":{"statusCode":403}}

والسبب أن الصورة تعمل بالمتغير NODE_ENV=production، وبحسب توثيق مزود الضيف فهذا المزود يجب أن يفعل في بيئة التطوير فقط، وهو معطل صراحة خارجها لمنع الوصول غير المصرح به، إلا إذا فعلت الخيار dangerouslyAllowOutsideDevelopment. وفي المختبر فعلناه، والاسم نفسه يقول لك لماذا لا تفعله في الإنتاج: كل من يصل إلى عنوان البوابة يدخل دون أي هوية. والبوابة في الإنتاج يجب أن تدخل عبر الدخول الموحد SSO، مثل OIDC من مزود هوية تشغله، كما شرحنا في دليل authentik وشرح OAuth مع OpenID Connect، ثم تربط كل مستخدم يدخل بكيان User في الكتالوج، لكي تعرف البوابة إلى أي فريق ينتمي. وفي السجل كذلك تحذير يتكرر لكل إضافة بأن backend.baseUrl عنوان localhost مع NODE_ENV إنتاج، وهو صحيح في المختبر ولكنه في الإنتاج يجب أن يكون العنوان الحقيقي الذي يصل إليه المستخدمون.

الكتالوج في البوابة Catalog UI

بعد التشغيل أجاب ال API بعد 6 إلى 8 ثوان، وهذا السكربت يعرض الكتالوج عبر ال API بنفس التوكن الذي تأخذه الواجهة:

#!/bin/sh
# Lists the catalog through the Backstage API, as the guest user of the lab: kind, name, owner, relation count, orphans.
B=http://127.0.0.1:47007
T=$(curl -s $B/api/auth/guest/refresh | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')
curl -s -H "Authorization: Bearer $T" "$B/api/catalog/entities?fields=kind,metadata.name,metadata.annotations,spec.owner,relations" |
  node -e '
let s = ""; process.stdin.on("data", d => s += d).on("end", () => {
  for (const e of JSON.parse(s).sort((a, b) => (a.kind + a.metadata.name).localeCompare(b.kind + b.metadata.name))) {
    const orphan = e.metadata.annotations?.["backstage.io/orphan"] === "true" ? "  ORPHAN" : "";
    console.log(e.kind.padEnd(10) + e.metadata.name.padEnd(15) + (e.spec?.owner ?? "-").padEnd(22) + (e.relations?.length ?? 0) + " relations" + orphan);
  }
});'
API       checkout-api   group:team-checkout   3 relations
API       payments-api   group:team-platform   4 relations
Component checkout-api   group:team-checkout   6 relations
Component payments       group:team-platform   3 relations
Component storefront     group:team-checkout   3 relations
Group     team-checkout  -                     6 relations
Group     team-platform  -                     4 relations
Location  generated-049b73936d7204693480057a384b426515620768-                     0 relations
Location  generated-74c5bce943c564b7598ed992aebaf3d5628e6de2-                     0 relations
Resource  orders-db      group:team-platform   3 relations
System    shop           group:team-checkout   7 relations
User      dev-a          -                     1 relations
User      dev-b          -                     1 relations
User      ops-lead       -                     1 relations

في المخرج أعلاه لاحظ التالي:

  • كل الكيانات الأحد عشر التي كتبناها موجودة، ومعها كيانان من نوع Location ولدهما Backstage لكل ملف في الإعداد، وهما الآباء الذين خرجت منهم الكيانات، ولهذا يهمان في قصة الأيتام لاحقاً.
  • عدد العلاقات أكبر مما كتبنا، فالنظام shop له سبع علاقات من نوع hasPart لم نكتب أياً منها، لأن الكتالوج ولدها من حقل system: shop في كل كيان.
  • المالك يظهر كمرجع نصي group:team-checkout، وهذا مهم في التجربة القادمة.

والصور التالية من البوابة نفسها، والأولى قائمة المكونات، والثانية صفحة الخدمة checkout-api بكل ما كتبناه عنها:

قائمة المكونات في كتالوج البوابة: checkout-api وpayments وstorefront مع المالك والنوع ودورة الحياة والوصف
كتالوج المتجر في Backstage
صفحة checkout-api: دورة الحياة production والمالك Checkout team والنظام shop، والواجهات المقدمة checkout-api والمستهلكة payments-api، والاعتماد على المورد orders-db، وفي الجانب الوصف والوسوم ورابط Runbook وزر View TechDocs
كل إجابات المطور الجديد في صفحة واحدة

ولاحظ في صفحة الخدمة أن جدول الواجهات المستهلكة يقول إن payments-api يملكه فريق المنصة، فإذا تعطل الدفع عرف المطور من يكلم دون أن يسأل. والصورة التالية لتبويب تعريف الواجهة payments-api، وفيها عقد OpenAPI معروضاً كما كتبناه:

تعريف payments-api في البوابة: Payments API الإصدار 2.0.0 والمسار POST /charge بعنوان Charge a card، وتبويب Raw للنص الأصلي
عقد ال API في نفس البوابة

مشكلة واجهتنا: TechDocs يكتب في مجلد المصدر

عندما فتحنا تبويب التوثيق لأول مرة ظهر خطأ، وفي سجل ال Backend كان السبب واضحاً:

"code":"EROFS","level":"error","message":"Failed to build the docs page for entity component:default/checkout-api: EROFS: read-only file system, open '/app/catalog/checkout-api/mkdocs.yml'"

فقد ركبنا مجلد الكتالوج للقراءة فقط Read-only، وهذه عادة جيدة، ولكن مولد TechDocs يفتح ملف mkdocs.yml للكتابة أثناء البناء، لأنه يضيف إليه إعدادات مثل اسم الموقع، ثم يعيده كما كان. فجعلنا التركيب قابلاً للكتابة من نسخة من الكتالوج في مجلد مؤقت، وتأكدنا بالأمر diff بعد البناء أن الملفات رجعت كما هي. والدرس أن المصدر الذي يبني منه TechDocs يجب أن يكون نسخة قابلة للكتابة، وهذا يحدث تلقائياً عندما يقرأ من Git لأنه ينسخ المستودع إلى مجلد مؤقت، ولكنه يظهر عندما تستخدم ملفات محلية مثل المختبر. وبعد الإصلاح ظهرت الصفحة:

صفحة TechDocs لخدمة checkout-api داخل البوابة: الشريط العلوي فيه المكون والمالك Checkout team ودورة الحياة، ثم الصفحة Overview بقسمي Run locally وConfiguration وجدول المتغيرات، وفي الجانب صفحة On-call
ملف Markdown من المستودع، داخل صفحة الخدمة

ولاحظ الشريط في أعلى الصفحة، فهو يربط التوثيق بالكيان في الكتالوج: المكون ومالكه ودورة حياته. وهذا الفرق بين TechDocs وموقع توثيق منفصل: القارئ يعرف دائماً لأي خدمة هذه الصفحة ومن يسأل إذا كانت قديمة. وأخذ البناء نفسه 0.71 ثانية بحسب سطر MkDocs Documentation built in 0.71 seconds، والطلب كاملاً من التوليد إلى النشر 1.5 ثانية.

البحث Search: الكتالوج مع التوثيق في مكان واحد

البحث في Backstage هو ما يجعل المطور يبدأ من البوابة بدلاً من أن يبحث في الويكي ثم في Git ثم يسأل في القناة، لأنه يبحث في الكتالوج والتوثيق معاً، وكل نتيجة ترجع إلى صفحة خدمة لها مالك. ويعمل البحث بفهارس Indexes تبنيها مكونات اسمها المجمعات Collators، كل مجمع يقرأ نوعاً من البيانات، واحد للكتالوج وواحد لـ TechDocs، ويعيد بناء الفهرس Index دورياً كما يشرح توثيق البحث. وفي سجل المختبر عند أول تشغيل رأينا ترتيباً يستحق أن تعرفه:

{"documentType":"software-catalog","level":"info","message":"Collating documents for software-catalog succeeded","plugin":"search","service":"backstage"}
{"documentType":"techdocs","level":"warn","message":"Index for techdocs was not replaced: indexer received 0 documents","plugin":"search","service":"backstage"}

فمجمع الكتالوج وجد الكيانات ونجح، أما مجمع TechDocs فلم يجد أي مستند، لأن صفحات التوثيق لم تكن قد بنيت بعد، فمع builder: local لا يبنى التوثيق إلا عند أول زيارة للصفحة. أي أن التوثيق لا يظهر في البحث حتى يفتحه أحد مرة، ثم يأتي دور الفهرسة التالي. وهذا سبب آخر لبناء التوثيق في CI: فهو يجعل كل صفحة موجودة في المخزن قبل أن يحتاجها أحد، فيجدها البحث من البداية.

الصلاحيات Permissions: من يرى ماذا؟

في التطبيق الافتراضي تجد السطر permission: enabled: true، وقد يظن البعض أن هذا يعني أن البوابة محمية. والواقع أن إطار الصلاحيات Permissions في Backstage يعطيك المكان الذي تكتب فيه السياسة Policy، وهي كود TypeScript يقرر هل يستطيع هذا المستخدم أن يفعل هذا الإجراء على هذا المورد، ويقول توثيق الصلاحيات إنك بدون صلاحيات فكل الإجراءات متاحة لكل أحد. ولذلك يجب أن تعرف بالضبط ماذا تفعل السياسة في تطبيقك قبل أن تضع في الكتالوج أي شيء حساس، مثل روابط لوحات داخلية أو أسماء قواعد بيانات الإنتاج. والقاعدة العملية لأغلب الفرق الصغيرة: البوابة نفسها خلف الدخول الموحد، وكل من يدخل من المطورين يرى الكتالوج كاملاً، لأن هدف الكتالوج أن يعرف الناس ما يوجد، ولا يوضع فيه سر أبداً، فالأسرار مكانها مدير الأسرار وليس ملف YAML في مستودع.

ماذا لو أخطأنا في الكتالوج؟ What If

الكتالوج مفيد بقدر ما هو صحيح، والسؤال العملي: ماذا يفعل Backstage عندما يكون الملف خاطئاً؟ فغيرنا في نسخة الكتالوج تغييرين في نفس اللحظة: كتبنا مالك خدمة الدفع بخطأ إملائي group:team-platfrom بدلاً من group:team-platform، وحذفنا المكون storefront من الملف كاملاً، كما يحدث عندما ينقل أحدهم خدمة إلى مستودع آخر وينسى أن يضيف ملفها هناك. ثم شغلنا سكربت الكتالوج كل خمس ثوان حتى ظهر التغيير:

API       checkout-api   group:team-checkout   3 relations
API       payments-api   group:team-platform   4 relations
Component checkout-api   group:team-checkout   5 relations
Component payments       group:team-platfrom   3 relations
Group     team-platform  -                     3 relations
Resource  orders-db      group:team-platform   3 relations

في المخرج أعلاه لاحظ التالي:

  • المالك الخاطئ ظهر في الكتالوج بعد 77 ثانية، ولم يرفضه Backstage، لأن المرجع صحيح الصيغة، والكتالوج لا يشترط أن يوجد الكيان الذي تشير إليه. وفريق المنصة نزلت علاقاته من 4 إلى 3، أي أن الخدمة خرجت من قائمة ما يملكه دون أن يلاحظ أحد.
  • المكون storefront اختفى بعد نحو 88 ثانية من التعديل، ولم يبق كيتيم، لأن السلوك الافتراضي حذف الأيتام. وcheckout-api نزلت علاقاته من 6 إلى 5، لأن علاقة dependencyOf مع storefront ذهبت معه.

والصورة التالية من صفحة خدمة الدفع بعد الخطأ الإملائي، وفيها تحذير واضح بأن للكيان علاقات بكيانات غير موجودة في الكتالوج، والمالك مكتوب كنص بلا رابط:

صفحة payments بعد الخطأ: المالك team-platfrom، وتحذير برتقالي يقول إن للكيان علاقات بكيانات لا توجد في الكتالوج وهي group:default/team-platfrom
Backstage يحذر ولا يرفض

والتحذير مفيد لمن يفتح الصفحة، ولكن لا أحد يفتح صفحة خدمة ليتأكد أن مالكها صحيح. ولذلك الصورة الأهم هي رسم الكتالوج Catalog Graph للنظام بعد التغييرين، فخدمة الدفع ما زالت جزءاً من المتجر، ولكن لا يوجد أي خط بينها وبين فريق المنصة، وصفحة المتجر storefront غير موجودة أصلاً:

رسم الكتالوج لنظام shop بعد التغيير: checkout-api وpayments-api وpayments وorders-db أجزاء من shop، وPlatform team يملك payments-api وorders-db فقط، ولا يوجد storefront
الخدمة بلا مالك في الرسم، والموقع غير موجود

والدرس من التجربة أن صحة الكتالوج لا تأتي من Backstage، وإنما من فحص تضيفه أنت. فالحل العملي خطوة في خط CI لكل مستودع، تقرأ ملف catalog-info.yaml وتتأكد أن المالك موجود في قائمة الفرق عبر ال API كما في سكربت المختبر، فيفشل طلب الدمج قبل أن يصل الخطأ إلى البوابة، وقد شرحنا بناء هذا النوع من الخطوط في مقال CI/CD للمبتدئين. وإذا كنت تخاف من الحذف التلقائي، فضبط catalog.orphanStrategy: keep يجعل الكيان اليتيم يبقى مع التعليق backstage.io/orphan: 'true' حتى يقرر أحد أن يحذفه.

ثم جربنا شيئاً ثالثاً يحدث في كل ترقية: أعدنا إنشاء Container البوابة بالأمر docker compose up -d --force-recreate، وسألنا عن ملف بيانات التوثيق قبل أن يفتح أحد الصفحة:

api answers after 6s
metadata after recreate: 404
13

أي أن الكتالوج بقي كاملاً بكياناته الثلاثة عشر، لأنه في PostgreSQL، أما صفحات التوثيق المبنية فاختفت، لأن الناشر المحلي يحفظها افتراضياً في مجلد داخل node_modules في ال Container نفسه. ومع builder: local تبنى من جديد عند أول زيارة، وهذا مقبول لخدمة واحدة، ولكن مع مئة خدمة فكل ترقية تعني مئة عملية بناء متزامنة عند أول صباح. والحل أن تحدد techdocs.publisher.local.publishDirectory على Volume دائم، أو الأفضل مخزن مثل S3 مع بناء التوثيق في CI.

ملخص الأرقام: البناء create-app في 19 ثانية وإكمال yarn.lock في 98 وdocker build في 424 منها yarn install في 180، وال Image 1.43 جيجابايت، والتشغيل ال API بعد 6 إلى 8 ثوان وBackstage بين 429 و448 ميجابايت وPostgreSQL بين 174 و217، وتجارب ماذا لو: المالك الخاطئ بعد 77 ثانية دون رفض، والحذف بعد 88 ثانية، وإعادة الإنشاء تحذف صفحات TechDocs
ما كلفنا Backstage في المختبر

الكتالوج من Git: التكامل Integrations

في المختبر قرأ الكتالوج ملفات محلية، أما في فريقك فسيقرأ من خادم Git. وفي ملف الإعداد الافتراضي ستجد قسماً جاهزاً لـ GitHub يقرأ التوكن من المتغير GITHUB_TOKEN، وبنفس الطريقة تضيف GitLab أو Gitea أو Bitbucket كما في توثيق التكامل، وقد ربطنا Backstage مع Gitea عملياً في مقال هندسة المنصات. وهنا ثلاثة قرارات يجب أن تأخذها. الأول نوع التوكن: يحتاج الكتالوج صلاحية قراءة المستودعات فقط، فلا تعطه توكن مسؤول، ولا توكن شخص من الفريق، وإنما حساب خدمة Service Account له اسم واضح. والثاني طريقة الاكتشاف: موقع لكل مستودع تسجله يدوياً، أو مزود اكتشاف يمر على كل مستودعات المؤسسة دورياً، والثاني أفضل عندما يزيد عدد المستودعات على عشرين، لأن الخدمة الجديدة تظهر تلقائياً بمجرد أن تحتوي ملف الكتالوج. والثالث حدود الطلبات Rate Limits: مزود الاكتشاف على GitHub مع مئات المستودعات قد يصل إلى حد الطلبات في الساعة، فاجعل فترة التحديث مناسبة لحجمك ولا تتركها بالقيمة الصغيرة التي تناسب المختبر.

كيف تعرف أن البوابة تنجح؟ Adoption

البوابة ليست هدفاً، وإنما وسيلة لتقليل الوقت الذي يضيعه المطورون في البحث والسؤال، ولذلك قس هذا وليس عدد الصفحات. وهذه أرقام تستطيع أن تستخرجها من ال API نفسه كما في سكربت الكتالوج، وتتابعها كل شهر:

  • نسبة الخدمات في الإنتاج التي لها مالك موجود فعلاً: وفي المختبر كانت هذه النسبة ستنزل من 100% إلى ثلثين بعد الخطأ الإملائي وحده.
  • نسبة الخدمات التي لها توثيق TechDocs ورابط دليل تشغيل: وهي التي تحدد هل تنفع البوابة المناوب في الليل.
  • عمر آخر تعديل لملف الكتالوج والتوثيق في كل مستودع: فالملف الذي لم يتغير منذ سنة والخدمة تغيرت كل أسبوع مرشح لأن يكون قديماً.
  • الوقت حتى أول مساهمة للمطور الجديد: وهو الرقم الذي بنيت البوابة لتقصيره، فاسأل كل مطور جديد بعد شهره الأول أين ضاع وقته.
  • عدد الأسئلة «من يملك؟» في قناة الفريق: رقم بسيط تعده يدوياً، وإذا لم ينزل بعد ثلاثة أشهر فالبوابة لا تعمل كما تظن.

كيف تبدأ في فريقك؟ Rollout

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

  1. ابدأ بالخدمات التي يسأل عنها الناس: خمس خدمات أو عشر، وليس كل المستودعات. والخدمة التي لا يسأل عنها أحد لا تحتاج صفحة الآن.
  2. المالك فريق حقيقي: أنشئ الفرق في الكتالوج أولاً، ويفضل أن تأتي من مزود الهوية نفسه عبر مزود Org، لكي لا تحفظ قائمة الأشخاص في مكانين.
  3. الملف في مستودع الخدمة: وليس في مستودع مركزي واحد، لكي يتغير مع الكود. والمستودع المركزي مقبول في البداية كما في المختبر، ولكنه يتقادم بسرعة.
  4. فحص في CI: صيغة الملف، ووجود المالك، ووجود رابط دليل التشغيل للخدمات في الإنتاج.
  5. التوثيق الذي يحتاجه المناوب أولاً: كيف تشغلها محلياً، والمتغيرات، وماذا تفعل عند العطل، وليس تاريخ الخدمة. وصفحة واحدة صحيحة أفضل من عشر قديمة.
  6. اربط ما يعرفه الناس: رابط اللوحة في المراقبة، والمستودع، وخط CI، فتصبح البوابة أول مكان يفتحه المطور، وليس مكاناً إضافياً.
  7. ثم القوالب: عندما يكون عندك طريق ممهد يستحق أن يكرر، كما في مقال هندسة المنصات.

وتذكر أن البوابة نفسها خدمة، فلها صفحة في الكتالوج، ومالك، وترقية دورية. فـ Backstage يصدر إصداراً رئيسياً كل شهر بحسب سياسة الإصدارات، والإصدار الذي بنينا عليه 1.56.3 صدر في 2 نوفمبر 2026 كما في صفحة الإصدار، والترقية تحدث بالأمر yarn backstage-cli versions:bump ثم بناء جديد واختبار، فخصص لها وقتاً في كل ربع سنة على الأقل، وإلا ستجد نفسك بعد سنة أمام ترقية كبيرة لا يجرؤ أحد عليها.

متى لا تحتاج Backstage؟ When Not

قد يتساءل البعض: هل يحتاج كل فريق Backstage؟ والإجابة لا. فالفريق الذي عنده خمس خدمات وستة مطورين يعرف بعضهم بعضاً، يكفيه ملف README جيد في كل مستودع، وجدول في صفحة واحدة فيه الخدمة والمالك والرابط، وتوثيق المعمارية Architecture بمخططات C4 كما في مقال توثيق المعمارية. والسبب أن Backstage تكلفة دائمة: ال Image 1.43 جيجابايت، والسيرفر بنحو نصف جيجابايت من الذاكرة مع قاعدة البيانات، ومطور يعرف TypeScript وReact يصون التطبيق ويرقيه، وكل إضافة تحتاج كوداً. فإذا كانت المشكلة لم تظهر بعد، فلا تبن لها حلاً.

والعلامة أنك أصبحت تحتاجه: عندما تبدأ الأسئلة «من يملك؟» و«أين التوثيق؟» تتكرر من أشخاص مختلفين كل أسبوع، وعندما يأخذ المطور الجديد أسابيع ليعرف أين الأشياء، وعندما تكتشف خدمة في الإنتاج لا يعرف أحد من يملكها. وإذا لم يكن في الفريق من يستطيع أن يصون تطبيق TypeScript، فهناك خدمات مستضافة مبنية على Backstage، وبدائل تجارية مثل Port ذكرناها في مقال هندسة المنصات، ولكن الكتالوج في أي منها يحتاج نفس الانضباط: ملف صحيح ومالك حقيقي.

أخطاء شائعة Common Mistakes

  • البدء بكل المستودعات: كتالوج فيه 300 خدمة نصفها ميت، فيفقد الناس الثقة به من اليوم الأول.
  • المالك شخص: أول مغادرة تترك الخدمة بلا مالك، والمالك يجب أن يكون فريقاً.
  • الثقة بأن Backstage يتحقق من المراجع: المالك الخاطئ ظهر في المختبر دون رفض، مع تحذير لا يراه إلا من يفتح الصفحة.
  • حذف سطر دون معرفة سياسة الأيتام: الحذف الافتراضي يزيل الخدمة من البوابة بعد دقيقة ونصف تقريباً.
  • الدخول كضيف في الإنتاج: الخيار dangerouslyAllowOutsideDevelopment يفتح البوابة لكل من يصل إليها.
  • بناء صورة الإنتاج من ملف قفل فارغ: create-app --skip-install يترك yarn.lock بثلاثة أسطر.
  • صفحات TechDocs داخل ال Container: تختفي عند كل إعادة إنشاء، وتبنى من جديد عند أول زيارة.
  • الإعداد داخل ال Image: كل تغيير في سطر إعداد يعني بناء 1.43 جيجابايت.
  • بوابة بلا مالك ولا ترقية: Backstage يصدر كل شهر، والتأخير سنة يجعل الترقية مشروعاً كاملاً.

قائمة تحقق Checklist

البندكيف تتحقق منه
كل خدمة في الإنتاج لها ملف كتالوجقائمة المستودعات مقابل قائمة الكيانات من ال API
كل مالك فريق موجود في الكتالوجفحص في CI يرفض المرجع إلى فريق غير موجود
دورة الحياة صحيحةالخدمات الموقوفة معلمة deprecated
كل خدمة في الإنتاج لها رابط دليل تشغيلالحقل metadata.links في الفحص
ال APIs كيانات مستقلة بعقد حقيقيالتعريف يشير إلى ملف OpenAPI في المستودع
الدخول عبر SSOلا يوجد guest مع dangerouslyAllowOutsideDevelopment
سياسة الأيتام مقصودةorphanStrategy مكتوبة في الإعداد، وليست الافتراضي بالصدفة
TechDocs يبنى في CI ويحفظ خارج ال Containerbuilder external مع مخزن، أو publishDirectory على Volume
yarn.lock في Gitالبناء بـ --immutable ينجح
للبوابة مالك وموعد ترقيةالإصدار الحالي لا يتأخر أكثر من ثلاثة أشهر

تدريب عملي Practice

  • اكتب سكربتاً صغيراً يشغل في CI، يقرأ ملف الكتالوج ويستخرج كل مرجع owner، ثم يسأل ال API إن كان الفريق موجوداً، ويفشل إذا لم يجده. وجربه على الخطأ الإملائي من المختبر.
  • غير catalog.orphanStrategy إلى keep، واحذف مكوناً من الملف، وابحث عنه في الكتالوج بعد دقيقتين، وانظر إلى التعليق backstage.io/orphan.
  • أضف Volume لمجلد نشر TechDocs عبر publishDirectory، وأعد إنشاء ال Container، وتأكد أن ملف البيانات يرجع 200 دون أن يبنى من جديد.

حذف المختبر Cleanup

docker compose -f lab/compose.yaml down -v
docker rmi wr-dp-backstage:1
rm -rf portal

الخلاصة Summary

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • Backstage إطار مفتوح المصدر من Spotify لبوابة المطورين، وقلبه الكتالوج الذي يجيب عن «من يملك؟ وعلى ماذا يعتمد؟ وأين التوثيق؟» من ملفات تعيش بجانب الكود.
  • الأنواع الأساسية: Component وAPI وResource وSystem وDomain، والمالك Group وليس شخصاً، والعلاقات تكتب من جهة واحدة ويولد الكتالوج عكسها.
  • TechDocs يبني Markdown من المستودع بـ MkDocs ويعرضه داخل صفحة الخدمة، والبنية الموصى بها أن يبنيه CI ويحفظه في مخزن.
  • في المختبر بنينا صورة إنتاج 1.43 جيجابايت في 424 ثانية، بعد ثلاث مشكلات: ملف قفل فارغ من create-app، ورفض الدخول كضيف في الإنتاج، ومولد TechDocs يكتب في مجلد المصدر.
  • المالك الخاطئ مر دون رفض بعد 77 ثانية، والمكون المحذوف اختفى بعد نحو 88 ثانية، وصفحات التوثيق اختفت عند إعادة إنشاء ال Container والكتالوج بقي في PostgreSQL.
  • صحة الكتالوج مسؤولية فحص في CI وانضباط في الفريق، والبوابة نفسها خدمة تحتاج مالكاً وترقية دورية، والفريق الصغير قد لا يحتاجها أصلاً.

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

دليلهندسة المنصات Platform Engineering والمشكلة التي تحلهالماذا تبني الشركات منصة داخلية لمطوريها ومتى لا تحتاجها، مع قالب في Backstage ينشئ خدمة جاهزة بخط CI.دليلDevOps وSRE وهندسة المنصات: أين يلتقي كل منها؟ما الذي يعنيه كل مصطلح فعلاً، وكيف تحسب ميزانية الأخطاء، وما شكل الفريق المناسب لحجم شركتك.دليلتوثيق المعمارية: مخططات C4 وسجلات القرارات المعمارية ADRكيف ترسم نظامك بمخططات C4 يفهمها المطور الجديد، وتحفظ سبب كل قرار مهم في سجل ADR داخل المستودع.دليلدليل التشغيل Runbook: وثق الإجراء قبل أن تحتاجهنكتب دليل تشغيل لقاعدة بيانات امتلأ قرصها، ثم ننفذه بالثواني في يوم تجربة، فنكتشف فيه خطأين لم يظهرا إلا عند التنفيذ.دليلكيف تصمم API يبقى متوافقاً مع عملائه بعد سنةمبادئ تصميم API يتطور دون أن يعطل التطبيقات التي تعتمد عليه، وكيف تختار الشكل المناسب لنظامك.

سجل التحديثات Changelog

  • نوفمبر 2026: كتابة الدليل وتنفيذ المختبر على Backstage 1.56 (create-app 0.9.3، والتوثيق من إصدار 1.56.3) مع Node.js 24.22.1 وPostgreSQL 18.6 وmkdocs-techdocs-core 1.7.1، وDocker Engine 29.8.0.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.