脚手架为什么是动作的组合 — 以及 TechDocs 为什么用 mkdocs

一句话总结

Backstage Software Template 分为表单（parameters）→ 工作列表（steps）→ 结果（output）三层，每个 step 调用可复用的action。这种组装方式让不同组织用相同部件构造各自黄金路径。

概念图: 表单（parameters）→ 工作列表（steps）→ 结果（output） · action · parameters · steps

为什么需要它

“创建新服务”的 shell 脚本通常要：收集名称、owner、语言、环境；验证 DNS 命名；取 skeleton 并替换值；建 Git 仓库并 push；配置 CI；注册 Catalog；显示结果链接。脚本往往弱化验证，把 token 放在开发者本地，没有结果页，并为每种语言复制大部分逻辑。

Scaffolder 把输入定义为 JSON Schema，把工作拆成 action，把结果放到 output。Node 和 Python 模板只需在 skeleton 等差异处不同，其他 action 可复用。

工作原理

Template manifest 的三层

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: node-service
  title: Node.js 서비스
spec:
  owner: group:team-platform
  type: service
  parameters:      # ← 사용자에게 보여 줄 폼 (JSON Schema)
    - title: 기본 정보
      required: [name, owner]
      properties:
        name:
          type: string
          pattern: '^[a-z0-9-]+$'
        owner:
          type: string
          ui:field: OwnerPicker
  steps:           # ← 실제로 하는 일
    - id: fetch
      name: 뼈대 가져오기
      action: fetch:template
    - id: publish
      name: 저장소 만들기
      action: publish:github
    - id: register
      name: 카탈로그 등록
      action: catalog:register
  output:          # ← 끝나고 보여 줄 것
    links:
      - title: Repository

parameters 使用 JSON Schema，type、required、pattern、enum 可在表单阶段阻止错误输入。Backstage 的 ui: 键指定 OwnerPicker、RepoUrlPicker、EntityPicker 等 widget，消除自由文本，避免把拼错的 owner 写入目录。

steps 各含 id、name、action、input。常见 action：

action	作用
`fetch:template`	获取 skeleton、替换变量并展开到 workspace
`fetch:plain`	不替换地复制文件
`publish:github` / `publish:gitlab`	创建仓库并 push
`catalog:register`	注册生成的 `catalog-info.yaml`
`fs:rename`, `fs:delete`	操作 workspace 文件

表单输入用 parameters，前一步结果用 steps.<id>.output.<필드>。publish:github 输出 remoteUrl、repoContentsUrl，catalog:register 返回实体引用。output 显示完成后的链接和文字，避免用户看到“已创建”后再次搜索去向。

publish:github 由 Backstage 后端执行，token 留在服务器，浏览器用户看不到。这就是门户自助比向所有人分发 token 更安全的原因。

TechDocs 与 docs-as-code

TechDocs 使用 mkdocs：源文件是 Markdown，配置只有 mkdocs.yml，结果为可托管的静态文件。流程是：仓库放 mkdocs.yml 和 docs/index.md；实体添加 backstage.io/techdocs-ref: dir:.；构建结果存入 storage 并在 Docs 标签渲染。

本地构建由门户按请求构建，简单但慢且不适合大规模；外部构建由 CI 生成并上传 object storage，是生产推荐。文档与代码同仓库、同 PR、同评审，能显著减少偏差；过时文档比没有文档更危险。

现场表现

homelab 的事故说明 scaffolding 不只是少打字。Gateway API 必须使用 CRD v1.6.1，v1.2 的 tlsroutes、referencegrants 不是 v1，Cilium controller 会拒绝启动；KubeVirt 的 containerDisk 缺陷需绕到 DataVolume(PVC)；GPU Operator 曾因 containerd runtime 配置出事故。这些一次踩过就不应再踩的坑，应固化在 skeleton 和文档中，让经过验证的路径成为默认值。

另一个例子是 kubeadm init 把 --control-plane-endpoint 设为首节点物理 IP 而非 VIP/DNS，后来即使有三个 control plane，首节点故障仍切断 API。此类初始选择后续极难修改，最适合固化为模板默认值。

下一步

将在 /root/cba-template/ 编写 Template manifest，包括 parameters JSON Schema、steps action/input、output links；再编写 mkdocs.yml、docs/index.md 和 skeleton catalog-info.yaml 的 TechDocs annotation，最后把模板生成的 manifest 应用到真实集群验证。