内部开发者平台（IDP）设计

# 安装 Backstage CLI
npx @backstage/create-app@latest

# 进入项目目录
cd my-idp-platform

# 项目结构
# ├── packages/
# │   ├── app/          # 前端应用
# │   └── backend/      # 后端服务
# ├── plugins/          # 自定义插件
# ├── app-config.yaml   # 主配置文件
# └── app-config.production.yaml  # 生产配置

# app-config.yaml - Backstage 核心配置
app:
  title: Internal Developer Platform
  baseUrl: http://localhost:3000

organization:
  name: Acme Corporation

backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007
  csp:
    connect-src: ["'self'", 'http:', 'https:']
  cors:
    origin: http://localhost:3000
    methods: [GET, HEAD, PATCH, POST, PUT, DELETE]
    credentials: true
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
      database: backstage_plugin

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

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

catalog:
  rules:
    - allow: [Component, System, API, Resource, Location, Template]
  locations:
    # 组织级模板
    - type: url
      target: https://github.com/acme/idp-templates/blob/main/templates.yaml
    # 组织级文档
    - type: url
      target: https://github.com/acme/idp-docs/blob/main/catalog-info.yaml

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

argocd:
  username: admin
  password: ${ARGOCD_PASSWORD}
  appLocatorMethods:
    - type: config
      instances:
        - name: production
          url: ${ARGOCD_PROD_URL}
          token: ${ARGOCD_PROD_TOKEN}

# templates/microservice/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: microservice-template
  title: Microservice Golden Path
  description: |
    创建一个标准的微服务项目，包含：
    - 标准化的项目结构
    - CI/CD 流水线配置
    - Kubernetes 部署清单
    - 可观测性配置（指标、日志、链路追踪）
    - 服务目录注册信息
  tags:
    - microservice
    - golden-path
spec:
  owner: platform-team
  type: service

  parameters:
    - title: 服务基本信息
      required:
        - name
        - owner
        - description
      properties:
        name:
          title: 服务名称
          type: string
          description: 服务的唯一标识，使用小写字母和连字符
          pattern: "^[a-z][a-z0-9-]*$"
          ui:autofocus: true
        owner:
          title: 负责团队
          type: string
          description: 负责该服务的团队
          ui:field: OwnerPicker
          ui:options:
            allowedKinds:
              - Group
        description:
          title: 服务描述
          type: string
          description: 一句话描述服务的业务功能
        language:
          title: 开发语言
          type: string
          default: go
          enum:
            - go
            - java
            - python
            - node
          enumNames:
            - Go
            - Java (Spring Boot)
            - Python (FastAPI)
            - Node.js (Express)

    - title: 基础设施配置
      required:
        - environment
      properties:
        environment:
          title: 部署环境
          type: string
          default: staging
          enum:
            - staging
            - production
            - staging-and-production
        replicas:
          title: 副本数
          type: number
          default: 2
          minimum: 1
          maximum: 10
        enableCanary:
          title: 启用金丝雀发布
          type: boolean
          default: true

  steps:
    - id: fetch-template
      name: 获取项目模板
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}
          description: ${{ parameters.description }}
          language: ${{ parameters.language }}
          environment: ${{ parameters.environment }}
          replicas: ${{ parameters.replicas }}
          enableCanary: ${{ parameters.enableCanary }}

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

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

    - id: create-argocd-app
      name: 创建 ArgoCD 应用
      action: argocd:create-app
      input:
        appName: ${{ parameters.name }}
        project: default
        sourceRepo: https://github.com/acme/${{ parameters.name }}.git
        sourcePath: k8s
        destinationCluster: https://kubernetes.default.svc
        destinationNamespace: ${{ parameters.name }}

  output:
    links:
      - title: 代码仓库
        url: https://github.com/acme/${{ parameters.name }}
      - title: 服务目录
        url: https://idp.acme.com/catalog/default/component/${{ parameters.name }}
      - title: ArgoCD 应用
        url: https://argocd.acme.com/applications/${{ parameters.name }}

# catalog-info.yaml - 服务目录元数据
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: 订单处理微服务
  annotations:
    backstage.io/source-location: url:https://github.com/acme/order-service
    backstage.io/techdocs-ref: dir:.
    argocd/app-name: order-service
    grafana/dashboard-selector: "order-service"
    prometheus.io/alert: "order-service-alerts"
    backstage.io/kubernetes-namespace: order-service
  tags:
    - go
    - microservice
    - order-domain
  links:
    - url: https://order-service.staging.acme.com/health
      title: 健康检查
      icon: cloud
    - url: https://grafana.acme.com/d/order-service
      title: 监控面板
      icon: dashboard
spec:
  type: service
  lifecycle: production
  owner: order-team
  system: order-system
  dependsOn:
    - component:payment-service
    - component:inventory-service
  providesApis:
    - order-api
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: order-api
  description: 订单服务 REST API
spec:
  type: openapi
  lifecycle: production
  owner: order-team
  system: order-system
  definition: |
    openapi: 3.0.0
    info:
      title: Order Service API
      version: "1.0"
    paths:
      /orders:
        get:
          summary: List orders
          responses:
            '200':
              description: A list of orders

// cmd/platform/main.go - Platform CLI 示例
package main

import (
	"fmt"
	"os"

	"github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
	Use:   "platform",
	Short: "Internal Developer Platform CLI",
	Long:  "Platform CLI 提供自助服务命令，用于服务创建、部署和环境管理",
}

var createCmd = &cobra.Command{
	Use:   "create [service-name]",
	Short: "创建新服务",
	Args:  cobra.ExactArgs(1),
	Run: func(cmd *cobra.Command, args []string) {
		template, _ := cmd.Flags().GetString("template")
		language, _ := cmd.Flags().GetString("language")
		owner, _ := cmd.Flags().GetString("owner")

		fmt.Printf("Creating service '%s' with template '%s'\n", args[0], template)
		fmt.Printf("  Language: %s\n", language)
		fmt.Printf("  Owner: %s\n", owner)

		// 调用 Backstage Scaffolder API
		if err := createService(args[0], template, language, owner); err != nil {
			fmt.Fprintf(os.Stderr, "Error: %v\n", err)
			os.Exit(1)
		}
		fmt.Printf("Service '%s' created successfully!\n", args[0])
	},
}

var deployCmd = &cobra.Command{
	Use:   "deploy [service-name]",
	Short: "部署服务到指定环境",
	Args:  cobra.ExactArgs(1),
	Run: func(cmd *cobra.Command, args []string) {
		env, _ := cmd.Flags().GetString("env")
		version, _ := cmd.Flags().GetString("version")

		fmt.Printf("Deploying '%s' version '%s' to '%s'\n", args[0], version, env)

		// 触发 GitOps 发布流程
		if err := deployService(args[0], env, version); err != nil {
			fmt.Fprintf(os.Stderr, "Error: %v\n", err)
			os.Exit(1)
		}
		fmt.Printf("Deployment initiated for '%s'\n", args[0])
	},
}

func createService(name, template, language, owner string) error {
	// 调用 Backstage Scaffolder API 创建服务
	// POST /api/scaffolder/v2/tasks
	return nil
}

func deployService(name, env, version string) error {
	// 通过 GitOps 方式触发部署
	// 更新 ArgoCD Application 的目标版本
	return nil
}

func init() {
	createCmd.Flags().String("template", "microservice", "服务模板名称")
	createCmd.Flags().String("language", "go", "开发语言")
	createCmd.Flags().String("owner", "", "负责团队")

	deployCmd.Flags().String("env", "staging", "目标环境")
	deployCmd.Flags().String("version", "latest", "部署版本")

	rootCmd.AddCommand(createCmd)
	rootCmd.AddCommand(deployCmd)
}

func main() {
	if err := rootCmd.Execute(); err != nil {
		os.Exit(1)
	}
}

自助服务率 = 自助完成操作数 / 总操作数 × 100%

NPS = 推荐者百分比(9-10分) - 贬损者百分比(0-6分)