开发者门户与自助服务

# catalog-entities/groups.yaml
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: order-domain
  description: 订单域团队
spec:
  type: business-domain
  parent: engineering
  children:
    - order-team
    - payment-team
---
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: order-team
  description: 订单服务团队
spec:
  type: team
  parent: order-domain
  members:
    - zhang-san
    - li-si
    - wang-wu
---
apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  name: zhang-san
spec:
  profile:
    displayName: 张三
    email: zhangsan@acme.com
  memberOf:
    - order-team

# catalog-entities/order-system.yaml
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: order-system
  description: 订单处理系统
  tags:
    - order
    - core-business
spec:
  owner: order-domain
  domain: commerce
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: 订单核心服务
  annotations:
    backstage.io/source-location: url:https://github.com/acme/order-service/tree/main
    backstage.io/techdocs-ref: dir:.
    github.com/project-slug: acme/order-service
    argocd/app-name: order-service
    grafana/alert-label-selector: "service=order-service"
    grafana/dashboard-tag: order-service
    prometheus.io/alert: "order-service"
    backstage.io/kubernetes-namespace: order-service
    pagerduty.com/service-id: PXXXXXX
  tags:
    - go
    - microservice
    - grpc
  links:
    - url: https://order-service.staging.acme.com/swagger
      title: API 文档
      icon: api
    - url: https://grafana.acme.com/d/order-service-overview
      title: 监控面板
      icon: dashboard
    - url: https://opsgenie.acme.com/service/order-service
      title: On-Call
      icon: alert
spec:
  type: service
  lifecycle: production
  owner: order-team
  system: order-system
  dependsOn:
    - component:payment-service
    - component:inventory-service
    - resource:order-db
  providesApis:
    - order-api
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: order-api
  description: 订单服务 gRPC API
spec:
  type: grpc
  lifecycle: production
  owner: order-team
  system: order-system
  definition: |
    syntax = "proto3";
    package order.v1;

    service OrderService {
      rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
      rpc GetOrder(GetOrderRequest) returns (GetOrderResponse);
      rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse);
    }
---
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: order-db
  description: 订单数据库
  annotations:
    amazon.com/aws-rds-cluster: order-db-cluster
spec:
  type: database
  lifecycle: production
  owner: order-team
  system: order-system

order-service/
├── catalog-info.yaml          # 服务目录元数据
├── docs/
│   ├── index.md              # 文档首页
│   ├── architecture.md       # 架构设计
│   ├── api-reference.md      # API 参考
│   ├── runbook.md            # 运维手册
│   └── onboarding.md         # 新人上手指南
├── mkdocs.yaml               # MkDocs 配置
└── src/
    └── ...                   # 服务源代码

# catalog-info.yaml - TechDocs 配置
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  annotations:
    backstage.io/techdocs-ref: dir:.    # 文档在当前仓库根目录
    # 或者指向另一个仓库
    # backstage.io/techdocs-ref: url:https://github.com/acme/order-service-docs
spec:
  type: service
  lifecycle: production
  owner: order-team

# mkdocs.yaml - TechDocs 构建配置
site_name: Order Service Documentation

nav:
  - Home: index.md
  - Architecture: architecture.md
  - API Reference: api-reference.md
  - Runbook: runbook.md
  - Onboarding: onboarding.md

plugins:
  - techdocs-core:
      # 启用 Mermaid 图表支持
      mermaid: true
      # 启用代码块复制按钮
      add_copy_button: true

markdown_extensions:
  - admonition
  - codehilite
  - footnotes
  - meta
  - toc:
      permalink: true
  - pymdownx.tabbed
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

<!-- docs/runbook.md -->
# Order Service Runbook

## 告警响应

### High Error Rate

**告警条件**：5 分钟内错误率超过 1%

**排查步骤**：

1. 检查 Grafana 面板：[Order Service Dashboard](https://grafana.acme.com/d/order-service)
2. 查看最近部署：[ArgoCD Application](https://argocd.acme.com/applications/order-service)
3. 检查依赖服务状态：
   - Payment Service
   - Inventory Service
4. 查看日志：[Loki Log Explorer](https://grafana.acme.com/explore)

**缓解措施**：

- 如果是最近部署导致，执行回滚
- 如果是依赖服务问题，联系对应团队

### Database Connection Pool Exhausted

**告警条件**：连接池使用率超过 90%

**排查步骤**：

1. 检查数据库连接数：`SHOW PROCESSLIST`
2. 检查慢查询日志
3. 检查连接泄漏

**缓解措施**：

- 临时增加连接池大小
- 重启服务释放僵尸连接

# templates/create-microservice/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: create-microservice
  title: 创建微服务
  description: |
    通过黄金路径模板创建标准微服务项目。
    包含：项目骨架、CI/CD 流水线、K8s 部署清单、可观测性配置。
spec:
  owner: platform-team
  type: service

  parameters:
    - title: 基本信息
      required:
        - componentName
        - owner
      properties:
        componentName:
          title: 组件名称
          type: string
          description: 服务的唯一标识
          pattern: "^[a-z][a-z0-9-]*$"
          ui:autofocus: true
        owner:
          title: 负责团队
          type: string
          ui:field: OwnerPicker
          ui:options:
            allowedKinds:
              - Group
        description:
          title: 服务描述
          type: string
          ui:widget: textarea
        system:
          title: 所属系统
          type: string
          ui:field: EntityPicker
          ui:options:
            allowedKinds:
              - System

    - title: 技术选型
      required:
        - language
      properties:
        language:
          title: 开发语言
          type: string
          default: go
          enum:
            - go
            - java
            - python
            - node
        database:
          title: 数据库
          type: string
          default: none
          enum:
            - none
            - postgresql
            - mysql
            - mongodb
            - redis
        messaging:
          title: 消息队列
          type: string
          default: none
          enum:
            - none
            - kafka
            - rabbitmq

    - title: 基础设施
      required:
        - environment
      properties:
        environment:
          title: 初始部署环境
          type: string
          default: staging
          enum:
            - staging
            - production
        enableCanary:
          title: 启用金丝雀发布
          type: boolean
          default: true
        enableAutoscaling:
          title: 启用自动扩缩容
          type: boolean
          default: true

  steps:
    # Step 1: 从模板生成项目
    - id: fetch
      name: 生成项目骨架
      action: fetch:template
      input:
        url: ./skeleton
        values:
          componentName: ${{ parameters.componentName }}
          owner: ${{ parameters.owner }}
          description: ${{ parameters.description }}
          system: ${{ parameters.system }}
          language: ${{ parameters.language }}
          database: ${{ parameters.database }}
          messaging: ${{ parameters.messaging }}
          environment: ${{ parameters.environment }}
          enableCanary: ${{ parameters.enableCanary }}
          enableAutoscaling: ${{ parameters.enableAutoscaling }}

    # Step 2: 发布到 GitHub
    - id: publish
      name: 创建代码仓库
      action: publish:github
      input:
        allowedHosts: ["github.com"]
        repoUrl: github.com?owner=acme&repo=${{ parameters.componentName }}
        description: ${{ parameters.description }}
        defaultBranch: main
        protectDefaultBranch: true
        repoVisibility: internal

    # Step 3: 注册到服务目录
    - id: register
      name: 注册服务目录
      action: catalog:register
      input:
        catalogInfoUrl: https://github.com/acme/${{ parameters.componentName }}/blob/main/catalog-info.yaml

  output:
    links:
      - title: 代码仓库
        url: https://github.com/acme/${{ parameters.componentName }}
      - title: 服务详情
        url: https://idp.acme.com/catalog/default/component/${{ parameters.componentName }}
    text:
      title: 下一步
      content: |
        服务已创建成功！接下来你可以：

        1. 克隆代码仓库开始开发
        2. 推送代码触发首次 CI/CD 流水线
        3. 在服务详情页查看部署状态和监控信息

skeleton/
├── catalog-info.yaml.tmpl
├── README.md.tmpl
├── .github/
│   └── workflows/
│       └── ci.yaml.tmpl
├── k8s/
│   ├── base/
│   │   ├── deployment.yaml.tmpl
│   │   ├── service.yaml.tmpl
│   │   ├── hpa.yaml.tmpl
│   │   └── kustomization.yaml.tmpl
│   ├── overlays/
│   │   ├── staging/
│   │   │   └── kustomization.yaml.tmpl
│   │   └── production/
│   │       └── kustomization.yaml.tmpl
│   └── canary.yaml.tmpl
├── docs/
│   └── index.md.tmpl
├── mkdocs.yaml
├── Dockerfile.tmpl
└── Makefile.tmpl

# app-config.yaml - Search 配置
search:
  # 启用搜索能力
  collators:
    catalog:
      # 每小时重新索引服务目录
      schedule:
        frequency: { hours: 1 }
        timeout: { minutes: 5 }
    techdocs:
      # 每 30 分钟重新索引文档
      schedule:
        frequency: { minutes: 30 }
        timeout: { minutes: 5 }

  # 搜索引擎配置
  engine:
    # 使用 PostgreSQL 全文搜索（默认）
    # 或配置 Elasticsearch 以获得更好的搜索性能
    type: postgresql

// plugins/order-service-actions/src/components/DeployAction.tsx
import React, { useState } from 'react';
import {
  Header,
  Page,
  Content,
  ContentHeader,
  SupportButton,
  InfoCard,
  Progress,
  Button,
  Select,
  Alert,
} from '@backstage/core-components';
import { useApi } from '@backstage/core-plugin-api';
import { catalogApiRef } from '@backstage/plugin-catalog-react';
import { argocdApiRef } from '@backstage/plugin-argocd';

export const DeployAction = ({ entity }: { entity: any }) => {
  const [environment, setEnvironment] = useState('staging');
  const [version, setVersion] = useState('');
  const [deploying, setDeploying] = useState(false);
  const [result, setResult] = useState<'success' | 'error' | null>(null);
  const argocdApi = useApi(argocdApiRef);

  const handleDeploy = async () => {
    setDeploying(true);
    setResult(null);
    try {
      // 通过 ArgoCD API 触发同步
      await argocdApi.sync({
        appName: entity.metadata.annotations?.['argocd/app-name'],
        namespace: entity.metadata.name,
        revision: version || 'HEAD',
      });
      setResult('success');
    } catch (err) {
      setResult('error');
    } finally {
      setDeploying(false);
    }
  };

  return (
    <InfoCard title="部署操作">
      <Select
        label="目标环境"
        items={[
          { value: 'staging', label: 'Staging' },
          { value: 'production', label: 'Production' },
        ]}
        onChange={setEnvironment}
        value={environment}
      />
      <br />
      <Button
        variant="contained"
        color="primary"
        onClick={handleDeploy}
        disabled={deploying}
      >
        {deploying ? '部署中...' : `部署到 ${environment}`}
      </Button>
      {deploying && <Progress />}
      {result === 'success' && (
        <Alert severity="success">部署已触发，请查看 ArgoCD 面板</Alert>
      )}
      {result === 'error' && (
        <Alert severity="error">部署触发失败，请检查配置</Alert>
      )}
    </InfoCard>
  );
};

# .github/workflows/catalog-validate.yaml
name: Validate Catalog Info
on:
  pull_request:
    paths:
      - 'catalog-info.yaml'
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate catalog-info.yaml
        run: |
          npx @backstage/catalog-model validate catalog-info.yaml