3. IDP 门户搭建基础：软件模板（Software Templates）的工作原理与常见配置错误

软件模板（Software Templates）是 Backstage IDP 门户的核心生产力引擎。它通过“模板 + 参数 + 步骤”的声明式组合，将基础设施代码化、标准化，让开发者无需手动创建仓库、配置 CI/CD、编写 Kubernetes 资源清单，即可一键生成符合组织规范的新服务或组件。

理解模板的工作原理，并掌握常见配置错误的排查方法，是搭建稳定 IDP 自助门户的必备技能。

3.1 核心工作原理：三步流水线

一个软件模板的执行本质是一个 Scaffolder 动作流水线。当开发者在门户点击“创建”并填写参数后，Backstage 后端会按以下三个阶段依次执行：

1. 输入阶段（Input）：解析 template.yaml 中定义的 parameters，渲染表单 UI，收集用户输入。
2. 获取阶段（Fetch）：根据 steps 中的 fetch:template 或 fetch:plain 动作，从 Git 仓库或本地路径拉取骨架代码（Skeleton）。
3. 发布阶段（Publish & Register）：执行 publish:github / publish:gitlab 等动作，将渲染后的代码推送到远程仓库，并通过 catalog:register 将新组件注册到 Backstage 软件目录中。

3.2 模板 YAML 结构解析

一个标准的 template.yaml 包含以下四个顶级字段。任何字段的缺失或格式错误都会导致模板无法加载或执行失败。

3.3 常见配置错误与排查方法

根据生产环境故障统计，以下四类错误占据了软件模板问题的 80% 以上。我们逐一分析其根因与修复方案。

3.3.1 变量引用错误（占 35%）

模板步骤之间通过 \${{ parameters.xxx }} 或 \${{ steps.xxx.output }} 传递数据。最常见的错误是变量名拼写不一致或作用域理解错误。

修复方案： 在模板 YAML 中统一变量命名规范，推荐使用 camelCase，并在每个步骤前添加 debug:log 动作输出当前上下文，辅助排查。

# 错误示例：变量名不匹配
parameters:
  - title: 服务名称
    properties:
      service_name:   # 下划线命名
        type: string
steps:
  - id: fetch
    name: Fetch Template
    action: fetch:template
    input:
      url: ./skeleton
      values:
        componentId: \${{ parameters.service_name }}  # 正确引用

# 正确做法：保持命名一致
parameters:
  - title: 服务名称
    properties:
      componentId:   # 统一使用 camelCase
        type: string
steps:
  - id: fetch
    name: Fetch Template
    action: fetch:template
    input:
      url: ./skeleton
      values:
        componentId: \${{ parameters.componentId }}

3.3.2 骨架仓库路径错误（占 25%）

fetch:template 动作的 url 字段指向骨架代码的存放位置。路径错误会导致模板在“获取阶段”直接失败。

• 相对路径陷阱： 当模板文件与骨架目录在同一仓库时，应使用相对路径 ./skeleton，而非路径 /skeleton 或 ../skeleton。
• Git 子路径遗漏： 当骨架存放在 Git 仓库的子目录时，需在 URL 后追加 ?path=subdir/skeleton 参数。
• 分支未指定： 默认拉取 master 分支，若骨架在 main 分支，需显式添加 ?targetBranch=main。

3.3.3 注册阶段 catalog-info.yaml 缺失或格式错误（占 20%）

模板执行完代码推送后，会通过 catalog:register 动作将新组件注册到 Backstage 目录。如果推送后的仓库中缺少 catalog-info.yaml，或该文件中的 metadata.name 与模板参数未正确绑定，注册将失败。

# 骨架仓库中的 catalog-info.yaml 示例（必须包含占位符）
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: \${{ values.componentId }}    # 必须与模板 steps 中传递的 values 键名一致
  description: \${{ values.description }}
  annotations:
    github.com/project-slug: \${{ values.repoUrl }}
spec:
  type: service
  lifecycle: experimental
  owner: \${{ values.owner }}

常见错误： 开发者直接在骨架中写死 name: my-service，导致所有通过该模板创建的服务都注册为同一个名称，引发目录冲突。

3.3.4 动作版本不兼容（占 10%）

Backstage 持续演进，部分内置动作（如 publish:github、fetch:template）的参数签名会随版本变化。使用旧版本文档中的参数格式，在新版本中可能失效。

3.4 模板调试三板斧

当模板执行失败时，不要盲目修改 YAML。按照以下步骤系统化排查：

1. 查看 Backstage 后端日志： 使用 kubectl logs -n backstage deployment/backstage --tail=200 | grep -i template 定位错误栈。重点关注 ScaffolderTaskContext 和 ActionContext 的输出。
2. 启用 Dry-Run 模式： 在模板步骤中临时添加 dryRun: true，模拟执行但不实际推送代码，观察变量渲染结果。
3. 本地验证骨架渲染： 使用 npx @backstage/create-app --template ./skeleton --values values.json 在本地测试骨架模板的占位符替换是否正确。