هندسة المنصات وتجربة المطورين

Backstage وكتالوجات الخدمات

18 دقيقة الدرس 3 من 28

Backstage وكتالوجات الخدمات

أطلقت شركة Spotify نظام Backstage كمشروع مفتوح المصدر عام 2020، بعد بنائه داخليًا للسيطرة على أكثر من 2,000 خدمة مصغرة، و1,600 مهندس، ومئات مكونات البنية التحتية التي لم يكن لها مرجع موحّد. أصبح هذا النظام المعيار الفعلي لمنصات المطورين الداخلية (IDP)، وانضم إلى مشاريع CNCF الناشئة عام 2022. يقوم Backstage على ثلاثة ركائز أساسية: كتالوج البرمجيات، وقوالب البرمجيات، وTechDocs. يتناول هذا الدرس هذه الركائز الثلاث بالعمق اللازم لتشغيلها في بيئات الإنتاج.

كتالوج البرمجيات

الكتالوج هو سجل حي لكل كيان تمتلكه مؤسستك: الخدمات، والمكتبات، والمواقع، والبيبلاين، وواجهات APIs، والموارد (حاويات S3، وقواعد بيانات RDS)، والأنظمة، والنطاقات. يُوصَف كل كيان بملف YAML — يُسمى واصف الكتالوج — يعيش جنبًا إلى جنب مع الكود الذي يصفه.

يتبع كل واصف مخططًا موحدًا بحقول apiVersion، وkind، وmetadata، وspec. كتلة metadata.annotations هي المكان الذي تقرأ منه إضافات Backstage إعداداتها — معرّفات خدمة PagerDuty، وروابط لوحات Datadog، ومسارات GitHub Actions، وأسماء تطبيقات ArgoCD وغيرها.

# catalog-info.yaml — ضعه في جذر أي مستودع
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payments-service
  description: Handles all payment processing and ledger reconciliation
  annotations:
    github.com/project-slug: acme-corp/payments-service
    pagerduty.com/service-id: P1A2B3C
    datadog/dashboard-url: https://app.datadoghq.com/dashboard/abc-xyz
    argocd/app-name: payments-service-prod
    backstage.io/techdocs-ref: dir:.
  tags:
    - payments
    - pci-dss
    - go
  links:
    - url: https://payments.internal.acme.com/metrics
      title: Metrics Dashboard
      icon: dashboard
spec:
  type: service
  lifecycle: production
  owner: team:payments
  system: checkout-platform
  dependsOn:
    - component:fraud-detection-service
    - resource:payments-postgres-prod
  providesApis:
    - payments-api-v2

يكتشف Backstage الواصفات عبر مزودي الكتالوج. يستطيع مزود GitHub استيعاب كل ملفات catalog-info.yaml عبر جميع المستودعات في المؤسسة في دقائق. أما مزود URL فيتولى التسجيل الفردي. على نطاق واسع، تهيئ معظم الفرق الاكتشاف التلقائي بحيث أن إنشاء مستودع جديد يحتوي على catalog-info.yaml يُسجّل الكيان تلقائيًا في دورة المزامنة التالية (الافتراضي: 5 دقائق).

يُشير حقل spec.owner إلى كيان من نوع Group أو User. إذا لم يكن المالك المُشار إليه موجودًا في الكتالوج، يُعلّم Backstage المكون بتحذير "يتيم". احتفظ بواصفات Group في مستودع مخصص org/ مُزامَن مع مزود الهوية الخاص بك (Okta أو Azure AD أو Google Workspace) — هذا هو المصدر الموثوق لهيكل المؤسسة.

تتضاعف قوة الكتالوج من خلال العلاقات. عندما يُعلن مكون عن dependsOn، يبني Backstage رسمًا بيانيًا ثنائي الاتجاه. على صفحة المكون، يرى المهندسون فورًا التبعيات الصاعدة والنازلة، وجدول مناوبات الفريق المالك، وآخر 72 ساعة من الحوادث، وآخر عمليات النشر، وطلبات السحب المفتوحة — كلها مجمّعة من إضافات تقرأ تلك التعليقات التوضيحية. هذه هي نظرة السياق الكامل التي تُلغي سؤال "أين توثيق هذا الشيء؟".

قوالب البرمجيات (Scaffolder)

القوالب هي الآلية التي تقف خلف المسارات الذهبية. يختار مهندس قالبًا، يملأ استمارة قصيرة، فيُنشئ Backstage مستودعًا مُهيَّئًا مسبقًا ببيبلاين CI الخاص بشركتك، وDockerfile، ومخطط Helm، ومراقبي Datadog، وخدمة PagerDuty، وقواعد حماية فروع GitHub، وملف catalog-info.yaml — كلها مُترابطة وجاهزة للتسليم الأول. يُسمى هذا أحيانًا أتمتة اليوم-0.

القوالب هي بحد ذاتها واصفات YAML من نوع kind: Template. تُعلن عن مخطط input (حقول الاستمارة)، ومجموعة steps يُنفّذها Scaffolder على الخادم، وكتلة output تُحيل إلى الموارد المُنشأة.

# template.yaml — المسار الذهبي لخدمة Go
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: go-microservice
  title: Go Microservice (Golden Path)
  description: Spins up a production-ready Go service with CI, Helm, and observability
  tags: [go, microservice, golden-path]
spec:
  owner: team:platform
  type: service

  parameters:
    - title: Service Details
      required: [name, description, team]
      properties:
        name:
          type: string
          title: Service Name
          pattern: '^[a-z][a-z0-9-]{2,39}$'
        description:
          type: string
          title: Short description
        team:
          type: string
          title: Owning team
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
        pagerdutyServiceId:
          type: string
          title: PagerDuty Service ID (optional)

  steps:
    - id: fetch-template
      name: Fetch skeleton
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          team: ${{ parameters.team }}

    - id: create-repo
      name: Create GitHub repo
      action: github:repo:create
      input:
        repoUrl: github.com?owner=acme-corp&repo=${{ parameters.name }}
        defaultBranch: main
        repoVisibility: private
        requiredStatusChecks:
          - ci/lint
          - ci/test
          - ci/build

    - id: push-content
      name: Push skeleton to repo
      action: github:repo:push
      input:
        repoUrl: github.com?owner=acme-corp&repo=${{ parameters.name }}
        defaultBranch: main

    - id: register
      name: Register in catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['create-repo'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

  output:
    links:
      - title: Repository
        url: ${{ steps['create-repo'].output.remoteUrl }}
      - title: Open in catalog
        entityRef: ${{ steps.register.output.entityRef }}

احتفظ بهياكل القوالب في مستودع منفصل scaffolder-templates، لا داخل مستودع تطبيق Backstage. أشر إليها بعناوين URL مطلقة. يتيح ذلك لفرق المنصة تحديث القوالب دون إعادة نشر Backstage، ويمكن للفرق تثبيت إصدار معين لتحقيق الاستقرار.

تدفق تنفيذ Scaffolder: تقديم استمارة واحدة يُطلق إنشاء المستودع وتوفير PagerDuty وتسجيل الكتالوج بالتسلسل.

TechDocs

يحل TechDocs مشكلة "التوثيق الذي يتعفّن في Confluence" بمعالجة التوثيق ككود. يكتب المهندسون Markdown في المستودع (باستخدام MkDocs كمولّد)، ينشر CI المحتوى المُصيَّر إلى تخزين الكائنات (S3 أو GCS)، ويعرضه Backstage مُضمَّنًا في تبويب Docs للمكون. تُخبر التعليمة التوضيحية backstage.io/techdocs-ref: dir:. في واصف الكتالوج Backstage بمكان ملف mkdocs.yml.

# mkdocs.yml — في جذر المستودع جنبًا إلى جنب مع catalog-info.yaml
site_name: Payments Service
site_description: Architecture, runbooks, and on-call guide for payments-service
docs_dir: docs/

nav:
  - Home: index.md
  - Architecture: architecture.md
  - Runbooks:
      - Incident Response: runbooks/incident-response.md
      - Database Failover: runbooks/db-failover.md
  - ADRs: adrs/index.md
  - API Reference: api-reference.md

plugins:
  - techdocs-core    # مُحقَن بواسطة صورة TechDocs builder الخاصة بـ Backstage

# في CI (GitHub Actions)، انشر عند كل دمج مع main:
# - run: pip install mkdocs-techdocs-core
# - run: mkdocs build --config-file mkdocs.yml
# - run: aws s3 sync site/ s3://acme-techdocs/payments-service/ --delete

يعمل TechDocs builder في وضعين: محلي (يبني Backstage التوثيق عند الطلب) أو خارجي (يبني CI التوثيق وينشره إلى التخزين). يجب أن تستخدم عمليات نشر الإنتاج الوضع الخارجي — الوضع المحلي يحجب عملية Node الخاصة بـ Backstage ولا يتوسّع.

وضع البناء المحلي في TechDocs خطأ شائع في الإنتاج. بالنسبة للمؤسسات الكبيرة التي تضم مئات الخدمات، تتسبب عمليات البناء عند الطلب في انهيار حاويات Backstage بسبب تجاوز الذاكرة، وتأخيرات تحميل أول مرة تصل إلى 30 ثانية. هيّئ دائمًا وضع البناء الخارجي مع CI الذي ينشر إلى GCS أو S3، واضبط techdocs.builder: 'external' في app-config.yaml. أضف CDN أمام حاوية التخزين لخفض أوقات تحميل التوثيق من ~800 مللي ثانية إلى أقل من 100 مللي ثانية.

اعتبارات النشر في الإنتاج

على نطاق واسع، Backstage تطبيق Node.js يمكن أن يستهلك موارد كبيرة. الإعدادات الإنتاجية الرئيسية التي تحتاج إلى ضبط:

فترة تحديث الكتالوج: الافتراضي 5 دقائق؛ زدها إلى 15-30 دقيقة للمؤسسات التي تضم أكثر من 5,000 كيان لتقليل الضغط على حصة GitHub API.
قاعدة البيانات: استبدل المخزن الافتراضي في الذاكرة بـ PostgreSQL (مطلوب لأي نشر يتجاوز حاوية واحدة).
المصادقة: ادمج مع مزود الهوية الخاص بك (Okta أو GitHub OAuth أو Azure AD) باستخدام خلفية auth الخاصة بـ Backstage. وصول الضيوف مُعطَّل في الإنتاج.
عزل الإضافات: كل إضافة Backstage تعمل في نفس عملية Node. إضافة معطوبة (مثل إضافة بها رفض Promise غير مُعالَج) يمكنها إسقاط التطبيق بأكمله. ثبّت إصدارات الإضافات واستخدم مجسّات liveness وreadiness لاكتشاف الأعطال وإعادة التشغيل بسرعة.

تعامل مع Backstage نفسه كمنتج له SLOs. تتبّع اكتمال الكتالوج (ما نسبة خدمات الإنتاج التي تمتلك catalog-info.yaml)، واعتماد القوالب (ما نسبة المستودعات الجديدة التي أُنشئت عبر قالب مسار ذهبي)، وتغطية TechDocs (الخدمات التي لديها توثيق منشور). هذه المقاييس الثلاثة هي أكثر المؤشرات قابلية للتنفيذ على صحة IDP وعائد الاستثمار في تجربة المطور.

كتالوج البرمجيات وقوالب البرمجيات وTechDocs هي أساس كل شيء آخر في Backstage. بمجرد تسجيل الكيانات ونشر التوثيق، تقرأ كل إضافة أخرى — رؤية التكاليف، والوضع الأمني، وتكرار النشر، وعبء المناوبات — تعليقات الكيانات التوضيحية وتُثري نفس اللوحة الموحدة. هذا الأثر التراكمي هو ما يُبرر الاستثمار في البنية التحتية.