551 lines
13 KiB
Markdown
551 lines
13 KiB
Markdown
# 黄金路径模板示例
|
||
|
||
基于Backstage Software Templates的黄金路径实现参考。
|
||
|
||
## 黄金路径设计原则
|
||
|
||
### 核心理念
|
||
- **降低认知负荷**：封装复杂性，暴露简单接口
|
||
- **默认安全**：安全配置内置，合规自动满足
|
||
- **自助服务**：开发者无需等待审批即可启动
|
||
- **透明可学**：生成代码可读可改，作为教学工具
|
||
|
||
### 模板分层架构
|
||
|
||
```
|
||
开发者输入 (元数据)
|
||
│
|
||
▼
|
||
┌───────────────────┐
|
||
│ 软件模板 │ ← Backstage Scaffolder
|
||
│ (YAML定义) │
|
||
└─────────┬─────────┘
|
||
│
|
||
▼
|
||
┌───────────────────┐
|
||
│ 骨架代码 │ ← 标准化项目结构
|
||
│ (Skeleton) │
|
||
└─────────┬─────────┘
|
||
│
|
||
▼
|
||
┌───────────────────┐
|
||
│ IaC模块 │ ← Terraform/Helm封装
|
||
│ (基础设施) │
|
||
└─────────┬─────────┘
|
||
│
|
||
▼
|
||
┌───────────────────┐
|
||
│ GitOps配置 │ ← ArgoCD/Flux部署
|
||
│ (CD流水线) │
|
||
└───────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 模板示例一：后端微服务
|
||
|
||
### template.yaml
|
||
|
||
```yaml
|
||
apiVersion: scaffolder.backstage.io/v1beta3
|
||
kind: Template
|
||
metadata:
|
||
name: backend-service-go
|
||
title: Go 后端微服务
|
||
description: |
|
||
创建一个生产就绪的Go微服务，包含:
|
||
- Gin框架 + 标准项目结构
|
||
- OpenTelemetry可观测性
|
||
- Docker + Kubernetes部署
|
||
- GitHub Actions CI/CD
|
||
- SLSA L3合规
|
||
tags:
|
||
- go
|
||
- backend
|
||
- microservice
|
||
- recommended
|
||
spec:
|
||
owner: platform-team
|
||
type: service
|
||
|
||
parameters:
|
||
- title: 服务基本信息
|
||
required:
|
||
- name
|
||
- owner
|
||
- description
|
||
properties:
|
||
name:
|
||
title: 服务名称
|
||
type: string
|
||
description: 唯一的服务标识符 (小写字母、数字、连字符)
|
||
pattern: '^[a-z0-9-]+$'
|
||
ui:autofocus: true
|
||
owner:
|
||
title: 负责团队
|
||
type: string
|
||
ui:field: OwnerPicker
|
||
ui:options:
|
||
catalogFilter:
|
||
kind: Group
|
||
description:
|
||
title: 服务描述
|
||
type: string
|
||
description: 简短描述服务用途
|
||
|
||
- title: 技术配置
|
||
properties:
|
||
database:
|
||
title: 数据库
|
||
type: string
|
||
enum:
|
||
- none
|
||
- postgresql
|
||
- mysql
|
||
default: none
|
||
description: 选择需要的数据库类型
|
||
cache:
|
||
title: 缓存
|
||
type: boolean
|
||
default: false
|
||
description: 是否需要Redis缓存
|
||
messageQueue:
|
||
title: 消息队列
|
||
type: string
|
||
enum:
|
||
- none
|
||
- kafka
|
||
- sqs
|
||
default: none
|
||
|
||
- title: 部署配置
|
||
properties:
|
||
environment:
|
||
title: 初始环境
|
||
type: array
|
||
items:
|
||
type: string
|
||
enum:
|
||
- development
|
||
- staging
|
||
- production
|
||
default:
|
||
- development
|
||
- staging
|
||
region:
|
||
title: 部署区域
|
||
type: string
|
||
enum:
|
||
- ap-northeast-1
|
||
- us-east-1
|
||
- eu-west-1
|
||
default: ap-northeast-1
|
||
|
||
steps:
|
||
# Step 1: 生成代码骨架
|
||
- id: fetch-skeleton
|
||
name: 获取代码骨架
|
||
action: fetch:template
|
||
input:
|
||
url: ./skeleton
|
||
values:
|
||
name: ${{ parameters.name }}
|
||
owner: ${{ parameters.owner }}
|
||
description: ${{ parameters.description }}
|
||
database: ${{ parameters.database }}
|
||
cache: ${{ parameters.cache }}
|
||
messageQueue: ${{ parameters.messageQueue }}
|
||
|
||
# Step 2: 生成基础设施代码
|
||
- id: generate-infra
|
||
name: 生成基础设施配置
|
||
action: fetch:template
|
||
input:
|
||
url: ./infra-template
|
||
targetPath: ./infra
|
||
values:
|
||
name: ${{ parameters.name }}
|
||
environments: ${{ parameters.environment }}
|
||
region: ${{ parameters.region }}
|
||
database: ${{ parameters.database }}
|
||
cache: ${{ parameters.cache }}
|
||
|
||
# Step 3: 创建代码仓库
|
||
- id: publish-github
|
||
name: 创建GitHub仓库
|
||
action: publish:github
|
||
input:
|
||
allowedHosts: ['github.com']
|
||
repoUrl: github.com?owner=our-org&repo=${{ parameters.name }}
|
||
description: ${{ parameters.description }}
|
||
defaultBranch: main
|
||
protectDefaultBranch: true
|
||
requireCodeOwnerReviews: true
|
||
requiredStatusChecks:
|
||
- ci/build
|
||
- ci/test
|
||
- security/scan
|
||
|
||
# Step 4: 注册到软件目录
|
||
- id: register-catalog
|
||
name: 注册到软件目录
|
||
action: catalog:register
|
||
input:
|
||
repoContentsUrl: ${{ steps['publish-github'].output.repoContentsUrl }}
|
||
catalogInfoPath: /catalog-info.yaml
|
||
|
||
# Step 5: 创建ArgoCD应用
|
||
- id: create-argocd-app
|
||
name: 配置GitOps部署
|
||
action: argocd:create-resources
|
||
input:
|
||
appName: ${{ parameters.name }}
|
||
projectName: default
|
||
repoUrl: ${{ steps['publish-github'].output.remoteUrl }}
|
||
path: ./infra/k8s
|
||
|
||
output:
|
||
links:
|
||
- title: 代码仓库
|
||
url: ${{ steps['publish-github'].output.remoteUrl }}
|
||
- title: 软件目录
|
||
icon: catalog
|
||
entityRef: ${{ steps['register-catalog'].output.entityRef }}
|
||
- title: CI流水线
|
||
url: ${{ steps['publish-github'].output.remoteUrl }}/actions
|
||
```
|
||
|
||
### 骨架代码结构
|
||
|
||
```
|
||
skeleton/
|
||
├── cmd/
|
||
│ └── server/
|
||
│ └── main.go
|
||
├── internal/
|
||
│ ├── handler/
|
||
│ │ └── health.go
|
||
│ ├── middleware/
|
||
│ │ ├── logging.go
|
||
│ │ └── tracing.go
|
||
│ ├── repository/
|
||
│ └── service/
|
||
├── pkg/
|
||
│ └── config/
|
||
│ └── config.go
|
||
├── api/
|
||
│ └── openapi.yaml
|
||
├── .github/
|
||
│ └── workflows/
|
||
│ ├── ci.yaml
|
||
│ └── release.yaml
|
||
├── Dockerfile
|
||
├── Makefile
|
||
├── go.mod
|
||
├── catalog-info.yaml
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 模板示例二：前端应用
|
||
|
||
### template.yaml
|
||
|
||
```yaml
|
||
apiVersion: scaffolder.backstage.io/v1beta3
|
||
kind: Template
|
||
metadata:
|
||
name: frontend-nextjs
|
||
title: Next.js 前端应用
|
||
description: |
|
||
创建一个现代化的Next.js前端应用，包含:
|
||
- Next.js 14 App Router
|
||
- TypeScript + Tailwind CSS
|
||
- shadcn/ui组件库
|
||
- 国际化(i18n)支持
|
||
- Vercel/容器化部署
|
||
tags:
|
||
- nextjs
|
||
- frontend
|
||
- typescript
|
||
- recommended
|
||
spec:
|
||
owner: platform-team
|
||
type: website
|
||
|
||
parameters:
|
||
- title: 应用基本信息
|
||
required:
|
||
- name
|
||
- owner
|
||
properties:
|
||
name:
|
||
title: 应用名称
|
||
type: string
|
||
pattern: '^[a-z0-9-]+$'
|
||
owner:
|
||
title: 负责团队
|
||
type: string
|
||
ui:field: OwnerPicker
|
||
|
||
- title: 功能配置
|
||
properties:
|
||
authentication:
|
||
title: 认证方案
|
||
type: string
|
||
enum:
|
||
- none
|
||
- nextauth
|
||
- auth0
|
||
- custom
|
||
default: none
|
||
i18n:
|
||
title: 国际化
|
||
type: boolean
|
||
default: false
|
||
analytics:
|
||
title: 分析集成
|
||
type: string
|
||
enum:
|
||
- none
|
||
- google-analytics
|
||
- posthog
|
||
- mixpanel
|
||
default: none
|
||
|
||
- title: 部署方式
|
||
properties:
|
||
deployTarget:
|
||
title: 部署目标
|
||
type: string
|
||
enum:
|
||
- vercel
|
||
- kubernetes
|
||
- cloudflare-pages
|
||
default: vercel
|
||
|
||
steps:
|
||
- id: fetch-skeleton
|
||
name: 获取代码骨架
|
||
action: fetch:template
|
||
input:
|
||
url: ./skeleton-nextjs
|
||
values:
|
||
name: ${{ parameters.name }}
|
||
authentication: ${{ parameters.authentication }}
|
||
i18n: ${{ parameters.i18n }}
|
||
analytics: ${{ parameters.analytics }}
|
||
|
||
- id: install-shadcn
|
||
name: 配置shadcn/ui
|
||
action: run:command
|
||
input:
|
||
command: npx shadcn-ui@latest init -y
|
||
|
||
- id: publish-github
|
||
name: 创建GitHub仓库
|
||
action: publish:github
|
||
input:
|
||
repoUrl: github.com?owner=our-org&repo=${{ parameters.name }}
|
||
|
||
- id: register-catalog
|
||
name: 注册到软件目录
|
||
action: catalog:register
|
||
input:
|
||
repoContentsUrl: ${{ steps['publish-github'].output.repoContentsUrl }}
|
||
catalogInfoPath: /catalog-info.yaml
|
||
```
|
||
|
||
---
|
||
|
||
## 模板示例三：数据管道
|
||
|
||
### template.yaml
|
||
|
||
```yaml
|
||
apiVersion: scaffolder.backstage.io/v1beta3
|
||
kind: Template
|
||
metadata:
|
||
name: data-pipeline
|
||
title: 数据处理管道
|
||
description: |
|
||
创建一个数据处理管道，包含:
|
||
- Python + Pandas/PySpark
|
||
- Airflow DAG定义
|
||
- dbt数据转换
|
||
- 数据质量检查(Great Expectations)
|
||
tags:
|
||
- data
|
||
- python
|
||
- airflow
|
||
- etl
|
||
spec:
|
||
owner: data-platform-team
|
||
type: pipeline
|
||
|
||
parameters:
|
||
- title: 管道基本信息
|
||
required:
|
||
- name
|
||
- owner
|
||
- schedule
|
||
properties:
|
||
name:
|
||
title: 管道名称
|
||
type: string
|
||
owner:
|
||
title: 负责团队
|
||
type: string
|
||
ui:field: OwnerPicker
|
||
schedule:
|
||
title: 调度频率
|
||
type: string
|
||
enum:
|
||
- '@hourly'
|
||
- '@daily'
|
||
- '@weekly'
|
||
- custom
|
||
default: '@daily'
|
||
|
||
- title: 数据源配置
|
||
properties:
|
||
sources:
|
||
title: 数据源
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
type:
|
||
type: string
|
||
enum:
|
||
- postgresql
|
||
- mysql
|
||
- s3
|
||
- bigquery
|
||
- api
|
||
connection:
|
||
type: string
|
||
```
|
||
|
||
---
|
||
|
||
## IaC模块封装示例
|
||
|
||
### 简化的Terraform模块接口
|
||
|
||
```hcl
|
||
# 开发者只需提供这些参数
|
||
module "backend_service" {
|
||
source = "git::https://github.com/our-org/terraform-modules//backend-service"
|
||
|
||
# 必填参数
|
||
name = "order-service"
|
||
environment = "production"
|
||
owner = "commerce-team"
|
||
|
||
# 可选参数 (有合理默认值)
|
||
replicas = 3
|
||
cpu = "500m"
|
||
memory = "1Gi"
|
||
|
||
# 数据库配置
|
||
database = {
|
||
type = "postgresql"
|
||
size = "large" # small/medium/large，平台团队定义具体规格
|
||
}
|
||
|
||
# 缓存配置
|
||
cache = {
|
||
enabled = true
|
||
size = "medium"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 模块内部封装的复杂性
|
||
|
||
```hcl
|
||
# 开发者不需要关心的内部实现
|
||
# terraform-modules/backend-service/main.tf
|
||
|
||
locals {
|
||
# 平台团队定义的规格映射
|
||
db_sizes = {
|
||
small = { instance_class = "db.t3.micro", storage = 20 }
|
||
medium = { instance_class = "db.t3.small", storage = 50 }
|
||
large = { instance_class = "db.r5.large", storage = 100 }
|
||
}
|
||
}
|
||
|
||
resource "aws_security_group" "db" {
|
||
# 安全组配置 - 默认最小权限
|
||
ingress {
|
||
from_port = 5432
|
||
to_port = 5432
|
||
cidr_blocks = [data.aws_vpc.main.cidr_block]
|
||
}
|
||
# ... 更多安全配置
|
||
}
|
||
|
||
resource "aws_db_instance" "main" {
|
||
# 数据库实例配置
|
||
instance_class = local.db_sizes[var.database.size].instance_class
|
||
allocated_storage = local.db_sizes[var.database.size].storage
|
||
|
||
# 默认启用的安全配置
|
||
storage_encrypted = true
|
||
deletion_protection = var.environment == "production"
|
||
backup_retention_period = 7
|
||
|
||
# 默认启用的监控
|
||
performance_insights_enabled = true
|
||
monitoring_interval = 60
|
||
|
||
# ... 更多配置
|
||
}
|
||
|
||
resource "aws_kms_key" "db_encryption" {
|
||
# 自动创建的加密密钥
|
||
description = "KMS key for ${var.name} database encryption"
|
||
deletion_window_in_days = 30
|
||
enable_key_rotation = true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 模板质量检查清单
|
||
|
||
创建新模板前，确认满足以下要求：
|
||
|
||
### 可用性
|
||
- [ ] 参数名称清晰易懂
|
||
- [ ] 提供合理的默认值
|
||
- [ ] 必填项最小化
|
||
- [ ] 有完整的描述信息
|
||
|
||
### 安全性
|
||
- [ ] 默认启用加密
|
||
- [ ] 默认最小权限
|
||
- [ ] 集成安全扫描
|
||
- [ ] 无硬编码密钥
|
||
|
||
### 可观测性
|
||
- [ ] 集成日志收集
|
||
- [ ] 集成指标采集
|
||
- [ ] 集成分布式追踪
|
||
- [ ] 健康检查端点
|
||
|
||
### 可维护性
|
||
- [ ] 生成代码可读
|
||
- [ ] 包含README文档
|
||
- [ ] 遵循团队规范
|
||
- [ ] 版本化模板
|
||
|
||
### 合规性
|
||
- [ ] 满足SLSA要求
|
||
- [ ] 自动生成SBOM
|
||
- [ ] 符合组织策略
|
||
- [ ] 资源标签完整
|