2. Backstage 插件开发环境搭建：Node.js、Yarn、Docker 环境配置，创建 Backstage 应用实例，插件脚手架初始化
在开始移植 IDP 制品签名链路之前，必须搭建一套标准、可复现的 Backstage 插件开发环境。本章将指导你完成从基础运行时配置到插件脚手架初始化的全流程，确保后续开发工作在一个干净、隔离的容器化环境中进行。
2.1 环境依赖清单与版本对齐
Backstage 官方推荐使用 Node.js 18 LTS 或 20 LTS，搭配 Yarn 3.x (Berry) 作为包管理器。Docker 用于运行本地数据库（PostgreSQL）和构建容器镜像。以下表格列出了核心依赖及其推荐版本：
| 依赖项 | 推荐版本 | 用途 |
|---|---|---|
| Node.js | 18.20.x 或 20.12.x (LTS) | 运行时环境，执行 TypeScript 编译与后端服务 |
| Yarn | 3.8.x (Berry) | 包管理、工作空间（workspace）管理、插件依赖解析 |
| Docker | 24.x 或 25.x | 本地数据库容器、镜像构建、集成测试 |
| Docker Compose | 2.24.x | 编排多容器环境（如 PostgreSQL + Redis） |
| Git | 2.40+ | 版本控制，Backstage 模板仓库克隆 |
版本对齐提示： 不要使用 Node.js 21+ 或 Yarn 1.x (Classic)。Backstage 的依赖解析器（@yarnpkg/plugin-backstage）在 Yarn 3.x 下工作最佳。如果本地已安装旧版本 Yarn，请使用
corepack enable 启用 Corepack 并切换版本。
2.2 环境配置步骤
以下步骤按顺序执行，确保每个环节验证通过后再进入下一步。
-
安装 Node.js (LTS)
使用 nvm（Node Version Manager）管理多版本：
# 安装 nvm（macOS/Linux） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 安装并切换到 Node.js 18 LTS nvm install 18 nvm use 18 node --version # 应输出 v18.20.x -
启用 Corepack 并安装 Yarn 3.x
corepack enable corepack prepare yarn@3.8.1 --activate yarn --version # 应输出 3.8.1 -
安装 Docker 与 Docker Compose
访问 Docker 官网 下载对应操作系统安装包。安装后验证：
docker --version # 应输出 Docker version 24.x docker compose version # 应输出 Docker Compose version 2.24.x -
配置 Git 全局用户信息
git config --global user.name "Your Name" git config --global user.email "your.email@example.com"
2.3 创建 Backstage 应用实例
使用 Backstage 官方 CLI 工具 @backstage/create-app 创建新项目。该工具会生成一个包含前端（app）、后端（backend）和通用包（common）的多工作区结构。
# 创建应用（替换 my-backstage 为你的项目名）
npx @backstage/create-app@latest --skip-install
# 进入项目目录
cd my-backstage
# 安装依赖（使用 Yarn Berry 的零安装模式）
yarn install
# 启动开发服务器
yarn dev首次启动时，Backstage 会检查本地环境并提示缺失的配置。默认情况下，后端会尝试连接本地 PostgreSQL 数据库。如果未安装 PostgreSQL，可以使用 Docker 快速启动一个测试实例：
docker run -d --name backstage-db \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=backstage \
-p 5432:5432 \
postgres:16-alpine
常见问题： 如果
yarn dev 后前端页面空白或后端报错 "connect ECONNREFUSED 127.0.0.1:5432"，请检查 PostgreSQL 容器是否运行，以及 app-config.yaml 中的数据库连接字符串是否正确。开发阶段可临时使用 SQLite 替代：在 app-config.local.yaml 中设置 backend.database.client: sqlite3。
2.4 插件脚手架初始化
Backstage 提供了两种插件脚手架生成方式：CLI 命令 和 模板向导。对于 IDP 制品签名链路移植，我们推荐使用 CLI 命令创建 后端插件，因为签名验证逻辑通常运行在后端服务中。
2.4.1 使用 CLI 创建后端插件
# 在项目根目录执行
yarn new --select backend-plugin
# 交互式输入插件 ID（例如：idp-signature）
# 插件 ID 将决定目录名和包名
# 输出示例：
# ? Enter the ID of the plugin in kebab-case » idp-signature
# ? Enter the owner of the plugin (e.g. "user:default/me") » user:default/guest
# 生成后的目录结构
plugins/
└── idp-signature/
├── package.json
├── src/
│ ├── index.ts # 插件入口
│ ├── router.ts # Express 路由
│ ├── service/ # 业务逻辑层
│ └── types.ts # 类型定义
├── dev/ # 开发环境入口
└── README.md2.4.2 插件脚手架结构说明
| 文件/目录 | 作用 | 后续移植适配关注点 |
|---|---|---|
src/index.ts |
导出插件实例、路由、类型 | 需要添加签名验证中间件导出 |
src/router.ts |
定义 REST API 端点 | 将添加 /verify-signature、/attest 等端点 |
src/service/ |
核心业务逻辑（签名验证、证书管理） | 移植 Cosign / Sigstore 验证逻辑的主要位置 |
dev/ |
独立开发运行入口，不依赖主应用 | 用于本地测试签名链路，无需启动完整 Backstage |
package.json |
插件元数据与依赖声明 | 需要添加 @sigstore/sign、cosign 等依赖 |
2.5 环境验证与开发工作流
完成脚手架初始化后，执行以下验证步骤确保环境就绪：
- 验证插件可独立启动： 进入
plugins/idp-signature目录，运行yarn start，确认开发服务器在http://localhost:3001启动。 - 验证主应用可加载插件： 在根目录运行
yarn dev，访问http://localhost:3000，确认插件路由可访问。 - 验证 Docker 容器连通性： 使用
docker ps确认 PostgreSQL 容器运行，并尝试从后端服务连接数据库。
开发工作流建议： 在
plugins/idp-signature/dev/ 目录下进行签名逻辑的快速迭代，使用 yarn start 独立运行；当需要与 Backstage 主应用的认证、权限系统集成时，再通过 yarn dev 启动完整应用进行端到端测试。这种分离方式可以大幅缩短开发反馈周期。
2.6 常见环境问题与解决方案
| 问题现象 | 根因 | 解决方案 |
|---|---|---|
yarn install 报错 "The remote archive doesn't match the expected checksum" |
Yarn Berry 零安装缓存与远程包校验不一致 | 删除 .yarn/cache 目录，重新执行 yarn install --immutable |
yarn dev 后端启动失败，端口 7007 被占用 |
上次开发进程未正常退出 | lsof -i :7007 | grep LISTEN 找到 PID 并 kill -9 |
| 插件路由返回 404 | 插件未在 packages/backend/src/index.ts 中注册 |
添加 backend.add(import('@internal/plugin-idp-signature')); |
| Docker 容器无法连接 | Docker 网络模式或端口映射错误 | 使用 docker network ls 检查网络，确保容器在 host 或 bridge 模式下端口正确暴露 |
完成以上步骤后，你的开发环境已具备移植 IDP 制品签名链路的所有前置条件。下一阶段将深入分析签名链路的组件构成与 Backstage 插件模型的映射关系。