Backstage

منصة بوابة المطورين الداخلية مفتوحة المصدر من Spotify لإدارة كتالوج البرمجيات وتجربة المطور.

التثبيت

إنشاء تطبيق جديد

الأمر	الوصف
npx @backstage/create-app@latest	إنشاء تطبيق Backstage جديد
npx @backstage/create-app@latest --skip-install	إنشاء تطبيق بدون تثبيت التبعيات
cd my-backstage-app && yarn install	تثبيت التبعيات
yarn dev	بدء الواجهة الأمامية والخلفية في وضع التطوير
yarn start	بدء الواجهة الأمامية فقط
yarn start-backend	بدء الواجهة الخلفية فقط
yarn build:backend	بناء الواجهة الخلفية للإنتاج
yarn build	بناء جميع الحزم
node_modules/.bin/backstage-cli --version	عرض إصدار CLI الخاص بـ Backstage

نشر Docker

الأمر	الوصف
yarn build:backend --config ../../app-config.yaml	بناء الواجهة الخلفية مع التكوين
docker build -t backstage -f packages/backend/Dockerfile .	بناء صورة Docker
docker run -p 7007:7007 backstage	تشغيل حاوية Backstage

أوامر CLI

إدارة الحزم

الأمر	الوصف
yarn backstage-cli package start	بدء حزمة في وضع التطوير
yarn backstage-cli package build	بناء حزمة
yarn backstage-cli package lint	فحص الكود المصدري للحزمة
yarn backstage-cli package test	تشغيل اختبارات الحزمة
yarn backstage-cli repo build --all	بناء جميع الحزم في المستودع الأحادي
yarn backstage-cli repo lint --all	فحص جميع الحزم
yarn backstage-cli versions:bump	تحديث تبعيات Backstage لأحدث إصدار
yarn backstage-cli versions:bump --release next	التحديث للإصدار التجريبي التالي
yarn backstage-cli migrate package-roles	ترحيل الحزم لاستخدام الأدوار

إنشاء الإضافات

الأمر	الوصف
yarn backstage-cli create-plugin	إنشاء إضافة واجهة أمامية جديدة
yarn backstage-cli create-plugin --backend	إنشاء إضافة واجهة خلفية جديدة
yarn backstage-cli create-plugin --id my-plugin	إنشاء إضافة بمعرف محدد
yarn new	إنشاء مكون تفاعلي من قالب

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

أنواع الكيانات

الأمر	الوصف
إضافة catalog-info.yaml في جذر المستودع	تسجيل مكون في الكتالوج
kind: Component في catalog-info.yaml	تعريف مكون برمجي
kind: API في catalog-info.yaml	تعريف كيان API
kind: System في catalog-info.yaml	تعريف تجميع نظام
kind: Domain في catalog-info.yaml	تعريف مجال عمل
kind: Resource في catalog-info.yaml	تعريف مورد بنية تحتية
kind: Group في catalog-info.yaml	تعريف فريق/مجموعة
kind: User في catalog-info.yaml	تعريف مستخدم
kind: Location في catalog-info.yaml	الإشارة إلى ملفات كتالوج أخرى

خصائص الكيان

الأمر	الوصف
تعيين spec.owner: team-name	تعيين ملكية الكيان
تعيين spec.lifecycle: production	تعيين مرحلة دورة حياة الكيان
تعيين spec.type: service	تعيين نوع المكون (service، website، library)
تعيين spec.dependsOn: ['component:other']	تعريف التبعيات
تعيين spec.providesApis: ['api-name']	الإعلان عن واجهات API المقدمة
تعيين spec.consumesApis: ['api-name']	الإعلان عن واجهات API المستهلكة
تعيين spec.system: system-name	التعيين لنظام
تعيين metadata.annotations للتكاملات	الربط بـ CI/CD والمراقبة وغيرها

مثال catalog-info.yaml

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: يتعامل مع معالجة المدفوعات والفوترة
  annotations:
    github.com/project-slug: org/payment-service
    backstage.io/techdocs-ref: dir:.
    jenkins.io/job-full-name: payment-service/main
    pagerduty.com/service-id: PABC123
    sonarqube.org/project-key: org_payment-service
  tags:
    - java
    - payments
  links:
    - url: https://dashboard.example.com/payments
      title: لوحة المراقبة
      icon: dashboard
    - url: https://wiki.example.com/payment-service
      title: Wiki
spec:
  type: service
  lifecycle: production
  owner: team-payments
  system: billing
  providesApis:
    - payment-api
  consumesApis:
    - user-api
    - notification-api
  dependsOn:
    - resource:payments-db
    - component:auth-service

مثال كيان API

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: payment-api
  description: واجهة REST API لمعالجة المدفوعات
  tags:
    - rest
    - payments
spec:
  type: openapi
  lifecycle: production
  owner: team-payments
  system: billing
  definition: |
    openapi: "3.0.0"
    info:
      title: Payment API
      version: 1.0.0
    paths:
      /payments:
        post:
          summary: إنشاء دفعة
          responses:
            "201":
              description: تم إنشاء الدفعة

مثال النظام والمجال

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: billing
  description: نظام الفوترة ومعالجة المدفوعات
spec:
  owner: team-payments
  domain: commerce
---
apiVersion: backstage.io/v1alpha1
kind: Domain
metadata:
  name: commerce
  description: مجال التجارة الإلكترونية يغطي الطلبات والمدفوعات والتسليم
spec:
  owner: group:engineering-leadership

القوالب

خصائص القوالب

الأمر	الوصف
kind: Template في template.yaml	تعريف قالب برمجي
تعيين spec.type: service	القالب ينشئ خدمة
تعيين spec.steps[] لإجراءات القالب	تعريف خطوات التهيئة
action: fetch:template	جلب وعرض ملفات القالب
action: publish:github	نشر المستودع المُنشأ على GitHub
action: publish:github:pull-request	إنشاء PR بدلاً من مستودع جديد
action: catalog:register	تسجيل الكيان المُنشأ في الكتالوج
action: github:actions:dispatch	تشغيل سير عمل GitHub Actions
استخدام ${{ parameters.name }} في القوالب	الإشارة إلى معلمات إدخال المستخدم
تعيين spec.parameters[] لحقول النموذج	تعريف نموذج إدخال القالب
استخدام ui:widget: textarea في المعلمات	تخصيص عنصر حقل النموذج

مثال تعريف القالب

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: microservice-template
  title: إنشاء خدمة مصغرة
  description: تهيئة خدمة مصغرة جديدة مع CI/CD والمراقبة والوثائق
  tags:
    - recommended
    - microservice
spec:
  owner: team-platform
  type: service
  parameters:
    - title: تفاصيل الخدمة
      required:
        - name
        - description
        - owner
      properties:
        name:
          title: اسم الخدمة
          type: string
          description: اسم فريد للخدمة
          ui:autofocus: true
          ui:options:
            rows: 5
        description:
          title: الوصف
          type: string
        owner:
          title: المالك
          type: string
          description: الفريق المالك لهذه الخدمة
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
    - title: البنية التحتية
      properties:
        language:
          title: اللغة
          type: string
          enum: ["go", "java", "python", "typescript"]
          default: go
        database:
          title: قاعدة البيانات
          type: string
          enum: ["postgres", "mysql", "none"]
          default: postgres
        enableMonitoring:
          title: تفعيل المراقبة
          type: boolean
          default: true
  steps:
    - id: fetch-base
      name: جلب القالب الأساسي
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          owner: ${{ parameters.owner }}
          language: ${{ parameters.language }}
    - id: publish
      name: النشر على GitHub
      action: publish:github
      input:
        allowedHosts: ["github.com"]
        repoUrl: github.com?owner=my-org&repo=${{ parameters.name }}
        description: ${{ parameters.description }}
        defaultBranch: main
        repoVisibility: internal
    - id: register
      name: التسجيل في الكتالوج
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml
  output:
    links:
      - title: المستودع
        url: ${{ steps['publish'].output.remoteUrl }}
      - title: فتح في الكتالوج
        icon: catalog
        entityRef: ${{ steps['register'].output.entityRef }}

الإضافات

تثبيت الإضافات

الأمر	الوصف
yarn add @backstage/plugin-catalog	تثبيت إضافة الكتالوج
yarn add @backstage/plugin-techdocs	تثبيت إضافة TechDocs
yarn add @backstage/plugin-kubernetes	تثبيت إضافة Kubernetes
yarn add @backstage/plugin-github-actions	تثبيت إضافة GitHub Actions
yarn add @backstage/plugin-search	تثبيت إضافة البحث
yarn add @backstage/plugin-scaffolder	تثبيت إضافة المُنشئ
yarn add @backstage/plugin-api-docs	تثبيت إضافة وثائق API
yarn add @backstage/plugin-cost-insights	تثبيت إضافة رؤى التكاليف

تسجيل الإضافات

تسجيل إضافات الواجهة الأمامية في packages/app/src/App.tsx:

import { CatalogGraphPage } from '@backstage/plugin-catalog-graph';
import { TechDocsReaderPage } from '@backstage/plugin-techdocs';
import { SearchPage } from '@backstage/plugin-search';

const routes = (
  <FlatRoutes>
    <Route path="/catalog" element={<CatalogIndexPage />} />
    <Route path="/catalog/:namespace/:kind/:name" element={<CatalogEntityPage />}>
      <EntityLayout>
        <EntityLayout.Route path="/" title="Overview">
          <EntityOverviewContent />
        </EntityLayout.Route>
        <EntityLayout.Route path="/api" title="API">
          <EntityApiContent />
        </EntityLayout.Route>
        <EntityLayout.Route path="/docs" title="Docs">
          <EntityTechDocsContent />
        </EntityLayout.Route>
      </EntityLayout>
    </Route>
    <Route path="/docs" element={<TechDocsReaderPage />} />
    <Route path="/search" element={<SearchPage />} />
    <Route path="/catalog-graph" element={<CatalogGraphPage />} />
  </FlatRoutes>
);

تسجيل إضافات الواجهة الخلفية في packages/backend/src/index.ts:

import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

backend.add(import('@backstage/plugin-app-backend'));
backend.add(import('@backstage/plugin-catalog-backend'));
backend.add(import('@backstage/plugin-catalog-backend-module-github-org'));
backend.add(import('@backstage/plugin-scaffolder-backend'));
backend.add(import('@backstage/plugin-techdocs-backend'));
backend.add(import('@backstage/plugin-search-backend'));
backend.add(import('@backstage/plugin-search-backend-module-catalog'));
backend.add(import('@backstage/plugin-search-backend-module-techdocs'));
backend.add(import('@backstage/plugin-auth-backend'));
backend.add(import('@backstage/plugin-auth-backend-module-github-provider'));
backend.add(import('@backstage/plugin-kubernetes-backend'));

backend.start();

TechDocs

عمليات TechDocs

الأمر	الوصف
npx @techdocs/cli serve	معاينة TechDocs محلياً
npx @techdocs/cli serve --docker-image techdocs-container	التقديم باستخدام صورة Docker مخصصة
npx @techdocs/cli generate	توليد موقع TechDocs الثابت
npx @techdocs/cli generate --source-dir .	التوليد من دليل محدد
npx @techdocs/cli publish --publisher-type googleGcs	نشر TechDocs على GCS
npx @techdocs/cli publish --publisher-type awsS3	نشر TechDocs على S3
إضافة تعليق backstage.io/techdocs-ref	تفعيل TechDocs للكيان
إنشاء دليل docs/ مع mkdocs.yml	إعداد مصدر TechDocs
تعيين techdocs.builder: 'local' في التكوين	استخدام بانٍ TechDocs محلي
تعيين techdocs.builder: 'external' في التكوين	استخدام بانٍ CI/CD خارجي

مثال mkdocs.yml لـ TechDocs

site_name: Payment Service
nav:
  - Home: index.md
  - Architecture: architecture.md
  - API Reference: api-reference.md
  - Runbooks:
      - Deployment: runbooks/deployment.md
      - Incident Response: runbooks/incident-response.md
plugins:
  - techdocs-core
markdown_extensions:
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences

البحث

إعداد البحث

الأمر	الوصف
yarn add @backstage/plugin-search	تثبيت واجهة البحث الأمامية
yarn add @backstage/plugin-search-backend	تثبيت واجهة البحث الخلفية
yarn add @backstage/plugin-search-backend-module-catalog	إضافة جامع بحث الكتالوج
yarn add @backstage/plugin-search-backend-module-techdocs	إضافة جامع بحث TechDocs
تكوين محرك البحث في app-config.yaml	إعداد Lunr أو Elasticsearch أو PgStore
تعيين search.pg في التكوين	استخدام PostgreSQL للبحث
تعيين search.elasticsearch في التكوين	استخدام Elasticsearch للبحث

التكوين

الإعدادات الأساسية

الأمر	الوصف
تحرير app-config.yaml	ملف التكوين الرئيسي
تحرير app-config.local.yaml	تجاوزات التطوير المحلي
تحرير app-config.production.yaml	تكوين الإنتاج
تعيين app.baseUrl في التكوين	تكوين URL الواجهة الأمامية
تعيين backend.baseUrl في التكوين	تكوين URL الواجهة الخلفية
تعيين backend.database في التكوين	تكوين اتصال قاعدة البيانات
تعيين backend.cors.origin في التكوين	تكوين أصول CORS
تعيين auth.providers في التكوين	تكوين مزودي المصادقة
تعيين catalog.locations[] في التكوين	إضافة مصادر كيانات الكتالوج
تعيين catalog.rules[] في التكوين	تعريف قواعد التحقق من الكيانات
تعيين integrations.github[] في التكوين	تكوين رمز تكامل GitHub

مثال app-config.yaml

app:
  title: بوابة المطورين لشركتي
  baseUrl: http://localhost:3000

organization:
  name: شركتي

backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007
  cors:
    origin: http://localhost:3000
    methods: [GET, HEAD, PATCH, POST, PUT, DELETE]
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

auth:
  environment: development
  providers:
    github:
      development:
        clientId: ${GITHUB_CLIENT_ID}
        clientSecret: ${GITHUB_CLIENT_SECRET}

catalog:
  import:
    entityFilename: catalog-info.yaml
    pullRequestBranchName: backstage-integration
  rules:
    - allow: [Component, System, API, Resource, Location, Domain, Group, User]
  locations:
    - type: url
      target: https://github.com/my-org/backstage-catalog/blob/main/all-components.yaml
    - type: github-discovery
      target: https://github.com/my-org
    - type: github-org
      target: https://github.com/my-org

techdocs:
  builder: local
  generator:
    runIn: local
  publisher:
    type: local

kubernetes:
  serviceLocatorMethod:
    type: multiTenant
  clusterLocatorMethods:
    - type: config
      clusters:
        - url: ${K8S_CLUSTER_URL}
          name: production
          authProvider: serviceAccount
          serviceAccountToken: ${K8S_TOKEN}

مخطط علاقات الكيانات

العلاقة	من	إلى	الوصف
ownerOf	Group/User	Component/API	المجموعة تملك الكيان
ownedBy	Component/API	Group/User	الكيان مملوك للمجموعة
consumesApi	Component	API	المكون يستخدم واجهة API
providesApi	Component	API	المكون يكشف واجهة API
dependsOn	Component	Component/Resource	المكون يعتمد على آخر
dependencyOf	Component/Resource	Component	هو تبعية لـ
partOf	Component	System	المكون ينتمي للنظام
hasPart	System	Component	النظام يحتوي على مكون
parentOf	Group	Group	علاقة الفريق الأب
childOf	Group	Group	علاقة الفريق الابن
memberOf	User	Group	المستخدم ينتمي للمجموعة
hasMember	Group	User	المجموعة تحتوي على مستخدم

أفضل الممارسات

1. استخدام catalog-info.yaml في كل مستودع — تأكد من تسجيل جميع الخدمات والمكتبات وواجهات API في الكتالوج للحصول على رؤية كاملة.

2. تعيين ملكية ذات معنى — يجب أن يكون لكل كيان حقل owner يشير إلى Group صالح، مما يتيح المساءلة والتوجيه.

3. إضافة تعليقات توضيحية غنية للكيانات — أضف تعليقات لـ CI/CD والمراقبة وPagerDuty والوثائق لجعل الكتالوج مركزاً حقيقياً.

4. إنشاء قوالب للمسارات الذهبية — استخدم المُنشئ لتعريف طرق موحدة لإنشاء خدمات جديدة، مما يضمن الاتساق.

5. تنفيذ TechDocs — احتفظ بالوثائق بجانب الكود باستخدام إضافة TechDocs وmkdocs.yml للوثائق الحية.

6. استخدام اكتشاف GitHub — كوّن github-discovery في مواقع الكتالوج لاكتشاف وتسجيل المستودعات تلقائياً.

7. نمذجة مؤسستك — عرّف Groups وUsers لتعكس هيكل فريقك، مما يتيح تتبع الملكية وصفحات الفرق.

8. الحفاظ على app-config.yaml واعياً بالبيئة — استخدم app-config.local.yaml للتطوير ومتغيرات البيئة لأسرار الإنتاج.

9. بناء نظام إضافات — أنشئ إضافات واجهة أمامية وخلفية مخصصة لتوسيع Backstage بأدوات مؤسستك المحددة.

10. تعريف Systems وDomains — نمذج البنية عالية المستوى باستخدام Systems وDomains لمنح المطورين خريطة لمنصتك.