Backstage实践指南

# Catalog 实体生命周期
# location → entity (refreshed) → database → API → UI
apiVersion: backstage.io/v1alpha1
kind: Location
metadata:
  name: order-service-location
spec:
  type: url
  target: https://github.com/acme/order-service/blob/main/catalog-info.yaml
  # 刷新间隔
  refreshInterval: 5m

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

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

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

export const EntityCostCard = costInsightsPlugin.provide(
  createComponentExtension({
    name: 'EntityCostCard',
    component: {
      lazy: () =>
        import('./components/EntityCostCard').then(
          (m) => m.EntityCostCard,
        ),
    },
  }),
);

// plugins/cost-insights/src/components/CostInsightsPage.tsx
import React, { useState, useEffect } from 'react';
import {
  Header,
  Page,
  Content,
  ContentHeader,
  InfoCard,
  Progress,
  WarningPanel,
  Table,
  TableColumn,
  StructuredMetadataTable,
} from '@backstage/core-components';
import { useApi } from '@backstage/core-plugin-api';
import { costInsightsApiRef, CostData } from '../api';

export const CostInsightsPage = () => {
  const [costData, setCostData] = useState<CostData[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const costApi = useApi(costInsightsApiRef);

  useEffect(() => {
    const fetchCostData = async () => {
      try {
        setLoading(true);
        const data = await costApi.getCostInsights();
        setCostData(data);
      } catch (err) {
        setError(err instanceof Error ? err.message : 'Unknown error');
      } finally {
        setLoading(false);
      }
    };
    fetchCostData();
  }, [costApi]);

  if (loading) return <Progress />;
  if (error) {
    return (
      <WarningPanel severity="error" title="Failed to load cost data">
        {error}
      </WarningPanel>
    );
  }

  const columns: TableColumn<CostData>[] = [
    {
      title: '服务',
      field: 'serviceName',
    },
    {
      title: '团队',
      field: 'team',
    },
    {
      title: '月度成本',
      field: 'monthlyCost',
      render: (row) => `$${row.monthlyCost.toLocaleString()}`,
    },
    {
      title: '环比变化',
      field: 'changeRate',
      render: (row) => {
        const color = row.changeRate > 0 ? '#d32f2f' : '#2e7d32';
        return (
          <span style={{ color }}>
            {row.changeRate > 0 ? '+' : ''}
            {row.changeRate.toFixed(1)}%
          </span>
        );
      },
    },
    {
      title: '优化建议',
      field: 'recommendation',
    },
  ];

  const totalCost = costData.reduce((sum, d) => sum + d.monthlyCost, 0);
  const totalChange =
    costData.reduce((sum, d) => sum + d.changeRate, 0) / costData.length;

  return (
    <Page themeId="tool">
      <Header title="成本分析" subtitle="服务基础设施成本概览" />
      <Content>
        <ContentHeader title="成本总览">
          {/* 可以添加操作按钮 */}
        </ContentHeader>
        <InfoCard title="成本摘要">
          <StructuredMetadataTable
            metadata={{
              '月度总成本': `$${totalCost.toLocaleString()}`,
              '服务数量': costData.length,
              '平均环比变化': `${totalChange > 0 ? '+' : ''}${totalChange.toFixed(1)}%`,
              '可优化成本': `$${costData
                .filter((d) => d.recommendation)
                .reduce((sum, d) => sum + d.monthlyCost * 0.2, 0)
                .toLocaleString()}`,
            }}
          />
        </InfoCard>
        <Table
          title="服务成本明细"
          columns={columns}
          data={costData}
          options={{
            paging: true,
            pageSize: 20,
            filtering: true,
            sorting: true,
          }}
        />
      </Content>
    </Page>
  );
};

// plugins/cost-insights/src/components/EntityCostCard.tsx
import React from 'react';
import { InfoCard, StructuredMetadataTable } from '@backstage/core-components';
import { useEntity } from '@backstage/plugin-catalog-react';
import { useApi } from '@backstage/core-plugin-api';
import { costInsightsApiRef } from '../api';

export const EntityCostCard = () => {
  const { entity } = useEntity();
  const costApi = useApi(costInsightsApiRef);

  // 在实际应用中，这里应该从 API 获取数据
  // 此处为简化示例
  const serviceName = entity.metadata.name;

  return (
    <InfoCard title="成本信息">
      <StructuredMetadataTable
        metadata={{
          服务: serviceName,
          月度成本: 'Loading...',
          环比变化: 'Loading...',
        }}
      />
    </InfoCard>
  );
};

// plugins/cost-insights-backend/src/plugin.ts
import {
  createBackendPlugin,
  coreServices,
} from '@backstage/backend-plugin-api';
import { createRouter } from './router';

export const costInsightsBackendPlugin = createBackendPlugin({
  pluginId: 'cost-insights',
  register(env) {
    env.registerInit({
      deps: {
        logger: coreServices.logger,
        config: coreServices.rootConfig,
        httpRouter: coreServices.httpRouter,
        discovery: coreServices.discovery,
      },
      async init({ logger, config, httpRouter, discovery }) {
        const router = await createRouter({
          logger,
          config,
          discovery,
        });
        httpRouter.use(router);
        logger.info('Cost Insights backend plugin initialized');
      },
    });
  },
});

// plugins/cost-insights-backend/src/router.ts
import express from 'express';
import Router from 'express-promise-router';
import { LoggerService } from '@backstage/backend-plugin-api';
import { Config } from '@backstage/config';
import { DiscoveryService } from '@backstage/backend-plugin-api';

export interface RouterOptions {
  logger: LoggerService;
  config: Config;
  discovery: DiscoveryService;
}

export async function createRouter(
  options: RouterOptions,
): Promise<express.Router> {
  const { logger, config } = options;
  const router = Router();
  router.use(express.json());

  // 获取所有服务的成本数据
  router.get('/insights', async (_req, res) => {
    logger.info('Fetching cost insights');

    // 在实际应用中，这里应该调用云厂商的 Cost API
    // 此处为简化示例
    const costData = [
      {
        serviceName: 'order-service',
        team: 'order-team',
        monthlyCost: 2500,
        changeRate: 5.2,
        recommendation: '考虑使用 Reserved Instances',
      },
      {
        serviceName: 'payment-service',
        team: 'payment-team',
        monthlyCost: 1800,
        changeRate: -2.1,
        recommendation: null,
      },
      {
        serviceName: 'user-service',
        team: 'user-team',
        monthlyCost: 1200,
        changeRate: 12.5,
        recommendation: 'HPA 配置过激进，建议调整',
      },
    ];

    res.json(costData);
  });

  // 获取单个服务的成本数据
  router.get('/insights/:serviceName', async (req, res) => {
    const { serviceName } = req.params;
    logger.info(`Fetching cost insights for ${serviceName}`);

    // 简化示例
    res.json({
      serviceName,
      monthlyCost: 2000,
      changeRate: 3.5,
      breakdown: {
        compute: 1200,
        storage: 400,
        network: 200,
        other: 200,
      },
    });
  });

  // 获取成本优化建议
  router.get('/recommendations', async (_req, res) => {
    logger.info('Fetching cost recommendations');

    res.json([
      {
        id: 'rec-001',
        type: 'reserved-instance',
        serviceName: 'order-service',
        potentialSaving: 500,
        description: '将 3 个 On-Demand 实例转为 Reserved Instances',
        priority: 'high',
      },
      {
        id: 'rec-002',
        type: 'right-sizing',
        serviceName: 'user-service',
        potentialSaving: 300,
        description: 'CPU 利用率持续低于 30%，建议降低实例规格',
        priority: 'medium',
      },
    ]);
  });

  // 健康检查
  router.get('/health', async (_req, res) => {
    res.json({ status: 'ok' });
  });

  return router;
}

# helm-values.yaml - Backstage Helm 部署配置
# helm repo add backstage https://backstage.github.io/charts
# helm install backstage backstage/backstage -f helm-values.yaml

backstage:
  appConfig:
    app:
      title: "Acme Developer Platform"
      baseUrl: https://idp.acme.com

    organization:
      name: "Acme Corporation"

    backend:
      baseUrl: https://idp.acme.com
      listen:
        port: 7007
      csp:
        connect-src: ["'self'", 'http:', 'https:']
        # 允许从任何来源加载（生产环境应限制）
        img-src: ["'self'", 'data:', 'https:']
      cors:
        origin: https://idp.acme.com
        methods: [GET, HEAD, PATCH, POST, PUT, DELETE]
        credentials: true
      database:
        client: pg
        connection:
          host: ${POSTGRES_HOST}
          port: '5432'
          user: ${POSTGRES_USER}
          password: ${POSTGRES_PASSWORD}
          database: backstage
          ssl:
            ca: ${POSTGRES_CA_CERT}
            rejectUnauthorized: true

    auth:
      environment: production
      providers:
        github:
          production:
            clientId: ${GITHUB_CLIENT_ID}
            clientSecret: ${GITHUB_CLIENT_SECRET}
        oidc:
          production:
            clientId: ${OIDC_CLIENT_ID}
            clientSecret: ${OIDC_CLIENT_SECRET}
            issuer: ${OIDC_ISSUER}
            callbackUrl: https://idp.acme.com/api/auth/oidc/handler/frame

    integrations:
      github:
        - host: github.com
          token: ${GITHUB_TOKEN}
          apps:
            - appId: ${GITHUB_APP_ID}
              webhookUrl: https://idp.acme.com/api/github/webhook
              privateKey: |
                ${GITHUB_APP_PRIVATE_KEY}
              clientId: ${GITHUB_APP_CLIENT_ID}
              clientSecret: ${GITHUB_APP_CLIENT_SECRET}

    catalog:
      rules:
        - allow: [Component, System, API, Resource, Location, Template, Group, User]
      locations:
        - type: url
          target: https://github.com/acme/idp-catalog/blob/main/catalog.yaml
        - type: url
          target: https://github.com/acme/idp-templates/blob/main/templates.yaml
      providers:
        githubOrg:
          id: acme
          githubUrl: https://github.com
          orgs: [acme]
          schedule:
            frequency: { hours: 1 }
            timeout: { minutes: 5 }

    techdocs:
      builder: 'local'  # 或 'external' 使用外部 CI 构建
      generator:
        runIn: 'docker'  # 安全隔离
      publisher:
        type: 'awsS3'
        awsS3:
          bucketName: ${TECHDOCS_BUCKET}
          region: ${AWS_REGION}
          endpoint: https://s3.${AWS_REGION}.amazonaws.com

    kubernetes:
      serviceLocatorMethod:
        type: multiTenant
      clusterLocatorMethods:
        - type: config
          clusters:
            - name: production
              url: ${K8S_PROD_URL}
              authProvider: serviceAccount
              serviceAccountToken: ${K8S_PROD_TOKEN}
              namespace: backstage
            - name: staging
              url: ${K8S_STAGING_URL}
              authProvider: serviceAccount
              serviceAccountToken: ${K8S_STAGING_TOKEN}
              namespace: backstage

    argocd:
      appLocatorMethods:
        - type: config
          instances:
            - name: production
              url: ${ARGOCD_PROD_URL}
              token: ${ARGOCD_PROD_TOKEN}
            - name: staging
              url: ${ARGOCD_STAGING_URL}
              token: ${ARGOCD_STAGING_TOKEN}

    grafana:
      domain: ${GRAFANA_URL}
      unifyAlerting: true

  # 容器镜像配置
  image:
    registry: ghcr.io
    repository: acme/backstage
    tag: "2.3.0"
    pullPolicy: IfNotPresent

  # 资源配置
  resources:
    requests:
      cpu: 500m
      memory: 512Mi
    limits:
      cpu: "2"
      memory: 2Gi

  # 副本数
  replicas: 3

  # 亲和性配置（跨可用区部署）
  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            labelSelector:
              matchExpressions:
                - key: app.kubernetes.io/name
                  operator: In
                  values:
                    - backstage
            topologyKey: topology.kubernetes.io/zone

# PostgreSQL 数据库配置
postgresql:
  enabled: false  # 使用外部 PostgreSQL

# Ingress 配置
ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
  hosts:
    - host: idp.acme.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: backstage-tls
      hosts:
        - idp.acme.com

# Service Monitor（Prometheus 监控）
serviceMonitor:
  enabled: true
  interval: 30s
  path: /metrics

// packages/backend/src/plugins/permission.ts
import {
  PermissionPolicy,
  PolicyDecision,
  isResourcePermission,
} from '@backstage/plugin-permission-common';
import {
  BackstageIdentityResponse,
  IdentityClient,
} from '@backstage/plugin-auth-node';

export class DefaultPermissionPolicy implements PermissionPolicy {
  async handle(
    request: any,
    identity?: BackstageIdentityResponse,
  ): Promise<PolicyDecision> {
    // 管理员拥有所有权限
    if (identity?.identity.ownershipEntityRefs.includes('group:admin')) {
      return { result: 'ALLOW' };
    }

    // 只读权限：所有认证用户都可以查看
    if (request.permission.name === 'catalog.entity.read') {
      return { result: 'ALLOW' };
    }

    // 写入权限：只有实体所有者可以修改
    if (
      isResourcePermission(request.permission) &&
      request.permission.name === 'catalog.entity.update'
    ) {
      // 检查请求者是否是实体所有者
      if (identity) {
        const entityOwner = request.resourceRef;
        if (
          identity.identity.ownershipEntityRefs.some(
            (ref) => ref === entityOwner,
          )
        ) {
          return { result: 'ALLOW' };
        }
      }
      return { result: 'DENY' };
    }

    // Scaffolder 模板执行权限
    if (request.permission.name === 'scaffolder.template.execute') {
      return { result: 'ALLOW' };
    }

    // 默认拒绝
    return { result: 'DENY' };
    }
}

# .github/workflows/backstage-deploy.yaml
name: Deploy Backstage

on:
  push:
    branches: [main]
    paths:
      - 'packages/**'
      - 'plugins/**'
      - 'app-config.*.yaml'
      - 'helm-values.yaml'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'yarn'

      - name: Install dependencies
        run: yarn install --frozen-lockfile

      - name: Run tests
        run: yarn test:all

      - name: Build backend
        run: yarn workspace backend build

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ghcr.io/acme/backstage:${{ github.sha }}
            ghcr.io/acme/backstage:latest

      - name: Deploy to Kubernetes
        run: |
          helm upgrade backstage backstage/backstage \
            --namespace backstage \
            -f helm-values.yaml \
            --set backstage.image.tag=${{ github.sha }} \
            --wait --timeout 5m