TechDocs والإضافات

TechDocs يجلب التوثيق إلى Backstage باستخدام نهج "التوثيق كرمز"، بينما الإضافات توسع وظائف Backstage مع تكاملات لنظامك البيئي الكامل من الأدوات.

TechDocs: التوثيق كرمز

TechDocs يعرض توثيق Markdown مباشرة في Backstage:

التوثيق التقليدي:
┌─────────────┬─────────────┬─────────────┐
│  Confluence │    Notion   │    Wiki     │
└─────────────┴─────────────┴─────────────┘
"التوثيق دائماً قديم ويصعب إيجاده"

TechDocs:
┌─────────────────────────────────────────┐
│            BACKSTAGE                     │
│  ┌───────────────────────────────────┐  │
│  │ الخدمة: user-service              │  │
│  │ [نظرة عامة] [API] [التوثيق] [CI/CD]│  │
│  │                                   │  │
│  │  📄 البدء                         │  │
│  │  📄 الهندسة المعمارية              │  │
│  │  📄 مرجع API                      │  │
│  │  📄 كتاب التشغيل                  │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
"التوثيق يعيش مع الكود، دائماً محدث"

إعداد TechDocs

أضف TechDocs لخدمتك:

# في جذر مستودعك:
# mkdocs.yaml
site_name: توثيق خدمة المستخدم
nav:
  - الرئيسية: index.md
  - البدء: getting-started.md
  - الهندسة المعمارية: architecture.md
  - مرجع API: api.md
  - كتاب التشغيل: runbook.md

plugins:
  - techdocs-core

# المرجع في catalog-info.yaml
# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-service
  annotations:
    backstage.io/techdocs-ref: dir:.  # التوثيق في نفس المستودع
    # أو خارجي: url:https://github.com/acme/user-service-docs

أنشئ توثيقك:

# docs/index.md
# خدمة المستخدم

مرحباً بك في توثيق خدمة المستخدم.

## روابط سريعة

- [البدء](getting-started.md)
- [مرجع API](api.md)
- [كتاب التشغيل](runbook.md)

## نظرة عامة

خدمة المستخدم تتعامل مع المصادقة وإدارة ملف المستخدم.

## الهندسة المعمارية

```mermaid
graph LR
    A[العميل] --> B[بوابة API]
    B --> C[خدمة المستخدم]
    C --> D[(PostgreSQL)]
    C --> E[مزود المصادقة]

التواصل

• المالك: فريق الخلفية
• Slack: #team-backend
• المناوبة: PagerDuty

## تكوين TechDocs

كوّن TechDocs في `app-config.yaml`:

```yaml
# app-config.yaml
techdocs:
  builder: 'local'  # 'local' أو 'external'
  generator:
    runIn: 'local'  # 'local' أو 'docker'
  publisher:
    type: 'local'   # 'local', 'awsS3', 'googleGcs', 'azureBlobStorage'

    # للإنتاج مع S3:
    # type: 'awsS3'
    # awsS3:
    #   bucketName: 'acme-techdocs'
    #   region: 'us-east-1'

نظام الإضافات البيئي

قوة Backstage تأتي من الإضافات. إليك الأساسية:

# إضافات Backstage الأساسية
plugins:

  infrastructure:
    - name: "@backstage/plugin-kubernetes"
      purpose: "إظهار حالة البود، السجلات، الأحداث"
      config: |
        kubernetes:
          serviceLocatorMethod:
            type: multiTenant
          clusterLocatorMethods:
            - type: config
              clusters:
                - name: production
                  url: https://k8s.acme.com
                  authProvider: serviceAccount

    - name: "@backstage/plugin-catalog-backend-module-aws"
      purpose: "اكتشاف موارد AWS"

  ci_cd:
    - name: "@backstage/plugin-github-actions"
      purpose: "إظهار حالة GitHub Actions"

    - name: "@roadiehq/backstage-plugin-argo-cd"
      purpose: "إظهار نشر ArgoCD"

  monitoring:
    - name: "@backstage/plugin-prometheus"
      purpose: "عرض مقاييس Prometheus"

    - name: "@grafana/plugin-grafana"
      purpose: "تضمين لوحات Grafana"

  incident_management:
    - name: "@backstage/plugin-pagerduty"
      purpose: "إظهار المناوبة، إنشاء الحوادث"

    - name: "@backstage/plugin-opsgenie"
      purpose: "تكامل OpsGenie"

  security:
    - name: "@backstage/plugin-security-insights"
      purpose: "إظهار تنبيهات Dependabot"

    - name: "@roadiehq/backstage-plugin-snyk"
      purpose: "عرض ثغرات Snyk"

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

أضف الإضافات لتطبيق Backstage:

# إضافة إضافة (من جذر تطبيق backstage)
yarn add --cwd packages/app @backstage/plugin-kubernetes

# لإضافات الخلفية
yarn add --cwd packages/backend @backstage/plugin-kubernetes-backend

سجّل في تطبيقك:

// packages/app/src/App.tsx
import { KubernetesPage } from '@backstage/plugin-kubernetes';

const routes = (
  <FlatRoutes>
    {/* ... مسارات أخرى */}
    <Route path="/kubernetes" element={<KubernetesPage />} />
  </FlatRoutes>
);

مثال إضافة Kubernetes

إظهار حالة Kubernetes في الوقت الفعلي:

# catalog-info.yaml - تمكين إضافة Kubernetes
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-service
  annotations:
    # ربط موارد Kubernetes
    backstage.io/kubernetes-id: user-service
    backstage.io/kubernetes-namespace: production
    backstage.io/kubernetes-label-selector: 'app=user-service'

# app-config.yaml - تكوين Kubernetes
kubernetes:
  serviceLocatorMethod:
    type: 'multiTenant'
  clusterLocatorMethods:
    - type: 'config'
      clusters:
        - name: production
          url: ${K8S_CLUSTER_URL}
          authProvider: serviceAccount
          serviceAccountToken: ${K8S_SERVICE_ACCOUNT_TOKEN}
          skipTLSVerify: false
          skipMetricsLookup: false

بناء إضافات مخصصة

أنشئ إضافات خاصة بالمؤسسة:

// plugins/acme-cost-insights/src/plugin.ts
import {
  createPlugin,
  createRoutableExtension,
} from '@backstage/core-plugin-api';

export const acmeCostInsightsPlugin = createPlugin({
  id: 'acme-cost-insights',
  routes: {
    root: rootRouteRef,
  },
});

export const AcmeCostInsightsPage = acmeCostInsightsPlugin.provide(
  createRoutableExtension({
    name: 'AcmeCostInsightsPage',
    component: () =>
      import('./components/CostInsightsPage').then(m => m.CostInsightsPage),
    mountPoint: rootRouteRef,
  }),
);

سوق الإضافات

اعثر على المزيد من الإضافات في:

• سوق إضافات Backstage: https://backstage.io/plugins
• إضافات Roadie: https://roadie.io/backstage/plugins/
• إضافات المجتمع: https://github.com/backstage/community-plugins

في الوحدة التالية، سنستكشف Crossplane لتوفير البنية التحتية—المحرك الذي يشغل طلبات البنية التحتية ذاتية الخدمة. :::