Backstage 升级指南使用 backstage-cli 与 yarn 插件保持实例与最新版本同步【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage 官方将自身定位为“框架/库”而非一次性交付的“应用”因此backstage/create-app生成的实例只是一个起点需要跟随上游持续演进。本文基于 Backstage 官方文档 docs/golden-path/create-app/keeping-backstage-updated.md完整讲解如何用backstage-cli versions:bump批量升级依赖、如何跟踪create-app模板变更、如何通过 Backstage yarn 插件管理包版本、如何处理依赖重复与代理环境以及如何借助 Knex 手动回滚数据库迁移帮助你在 monorepo 结构下安全、可复现地完成版本升级。Backstage 是“库”而不是“应用”版本需要持续跟进Backstage 始终在持续改进因此与最新 release 保持同步是运行维护的日常工作。与create-react-app类似backstage/create-app工具为你提供了一个“起点模板”模板本身会随仓库演进但你在create-app时生成的本地app与backend包并不会自动获得模板更新需要你主动去升级。理解这一点是后续所有升级操作的前提。使用 backstage-cli 批量升级版本一条命令升级所有backstage包Backstage CLI 提供了专用命令versions:bump它会把 monorepo 中所有backstage包及依赖一次性升级到最新版本yarn backstage-cli versions:bump之所以要“一次性”升级所有backstage包是因为这些包之间存在相互依赖关系例如backstage/core-plugin-api与backstage/core-components版本需配套逐个升级很容易破坏版本一致性。从源码看该命令位于 packages/cli-module-migrate/src/commands/versions/bump.ts核心流程为加载根目录yarn.lockLockfile.load通过mapDependencies(targetPaths.dir, pattern)发现仓库内所有匹配 pattern 的依赖并发concurrencyFactor: 4向 npm registry 查询各包的可用版本将各包package.json中的版本范围统一改写为^目标版本最后执行yarn install落地变更。命令默认的处理范围是dependencies、devDependencies、peerDependencies、optionalDependencies四种依赖类型见 bump.ts。跟随不同的 release 线默认情况下versions:bump会升级到每月发布一次的mainrelease 线。如果你希望更激进地跟踪每周发布的next线可以指定--release选项yarn backstage-cli versions:bump --release next源码中release参数默认值为main见 bump.ts。其解析逻辑bump.ts为若设置了环境变量BACKSTAGE_MANIFEST_FILE则直接读取本地 manifest 文件若--release传的是合法 semver 版本号则严格按该版本获取 manifest否则按 release 线main/next获取 manifest其中next线会比较next与main两份 manifest 的releaseVersion取较新者。通过--pattern扩展升级范围如果你还使用了其他组织维护的插件例如roadiehq/*可以传--pattern扩展匹配范围而不仅仅升级backstage/*yarn backstage-cli versions:bump --pattern {backstage,roadiehq}/*注意源码会拒绝过宽的*通配符Rejected pattern *见 bump.ts并要求 pattern 以/*结尾且能覆盖backstage/前缀extendsDefaultPattern。测试用例 packages/cli-module-migrate/src/commands/versions/bump.test.ts 中包含了默认 pattern、自定义 pattern、--skip-install、指定精确版本等场景的验证例如should bump backstage dependencies and dependencies matching pattern glob。此外versions:bump还支持--skip-install跳过yarn install步骤与--skip-migrate跳过已迁移包的迁移步骤两个选项适合在 CI 中分步执行。跟踪 create-app 模板变更backstage/create-app命令基于模板生成初始结构模板源位于本仓库的 packages/create-app。模板会定期更新但本地已经生成好的app与backend包不会自动同步模板改动。因此模板的任何变更都会连同升级说明记录在backstage/create-app包的 changelog仓库中对应 packages/create-app/CHANGELOG.md中升级包时建议先翻阅该 changelog确认是否有需要手动同步的模板改动也可以借助 Backstage Upgrade Helper 工具获得两个版本之间所有变更的汇总视图你当前安装的 Backstage 版本记录在仓库根目录的backstage.json中该文件由 CLI 在创建应用时生成并维护升级前先确认它升级后再核验它是否被正确更新。使用 Backstage yarn 插件管理包版本插件解决什么问题在传统方式下升级时需要逐个修改 monorepo 中每个package.json里的backstage依赖版本且新增依赖时还要手动查“当前 release 对应哪个版本”。Backstage yarn 插件本仓库实现位于 packages/yarn-plugin通过引入backstage:^版本协议解决了这个问题它会根据backstage.json中记录的整体 Backstage 版本为每个包自动确定合适的版本。安装要求使用该插件要求 yarn 版本为4.1.1 或更高。插件源码在启动时会用semverUtils.satisfiesWithPrereleases(YarnVersion, ^4.1.1)做版本校验不满足时直接打印错误并建议yarn plugin remove yarnpkg/plugin-backstage见 packages/yarn-plugin/src/index.ts。安装步骤在 Backstage monorepo 根目录执行yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin该命令会向.yarnrc.yml写入插件配置并下载插件 bundle产生的文件系统变更应提交到版本库。官方建议在准备进行 Backstage 升级时安装该插件这样更容易确认一切工作正常——因为versions:bump会检测到插件存在并自动把整个 monorepo 的依赖迁移到backstage:^协议相关行为在测试 bump.test.ts 中有明确覆盖日志会提示 “this bump used backstage:^ versions … To migrate back to explicit npm versions, remove the plugin … then repeat this command”。使用方式插件安装后已发布backstage包的版本可以替换为字符串backstage:^{ dependencies: { backstage/core-app-api: backstage:^, backstage/core-components: backstage:^ } }backstage:^的语义类似 yarn workspaces 的workspace:范围本地解析时始终取backstage.json中对应 Backstage release 在 manifest 里记录的精确版本若依赖包被发布则版本会以^前缀形式出现。注意backstage.json是插件工作的关键文件务必确保它被包含在 CI/CD 流水线和容器构建产物中否则插件将无法确定目标版本。插件的底层实现原理从 packages/yarn-plugin/README.md 的 Architecture 一节可以了解其内部机制插件由以下组件协同工作reduceDependencyhook在 yarn 解析工作区直接/间接依赖时被调用把backstage:^改写为带参数的backstage:^::backstage版本npm版本。实现见 packages/yarn-plugin/src/handlers/reduceDependency.ts只接受 selector 为^的范围否则抛错随后通过getCurrentBackstageVersion()读取backstage.json中的版本、通过getPackageVersion()从 manifest 取 npm 包版本并绑定到 descriptor 上BackstageNpmResolver负责把backstage:描述符解析为对应的 npm 包实现见 packages/yarn-plugin/src/resolvers/BackstageNpmResolver.ts。它从 descriptor 的npm参数取出版本委托NpmSemverResolver处理并在getResolutionDependencies中额外插入npm:^版本描述符——这样 lockfile 中同时保留backstage:^与对应npm:^两条记录确保在发布包或用backstage-cli build-workspace构建 dist workspace 时backstage:^与npm:范围互相切换不会意外解锁依赖beforeWorkspacePackinghook发布打包前把所有backstage:^替换回对应 npm 版本范围保证发布到 npm 的包不包含自定义协议afterWorkspaceDependencyAddition/afterWorkspaceDependencyReplacementhook插件把既有依赖转成backstage:^后新增的backstage/*依赖也会自动被改写为backstage:^当yarn add一个已是目标包依赖的backstage/*包时会打印警告提醒该操作会把backstage:^替换为实际 npm 版本范围可能并非你所期望。插件还支持两个环境变量用于离线/内网环境BACKSTAGE_VERSIONS_BASE_URL版本 manifest 的基础 URL默认为https://versions.backstage.io/v1/releases/VERSION/manifest.json注意只填主机部分路径由插件追加适合通过镜像或代理访问BACKSTAGE_MANIFEST_FILE本地 manifest 文件路径设置后插件不再从网络获取 manifest适合完全无外网的环境。深入理解依赖不匹配duplicate dependenciesBackstage 采用 Yarn workspaces 结构的 monorepoapp、backend以及你添加的自定义插件都是拥有独立package.json和依赖的独立包当某个依赖在不同包中的版本相同时yarn 会把它提升hoist到 monorepo 根目录的node_modules中共享当出现不同版本时yarn 会在对应包内部创建各自的node_modules导致同一应用中出现同一包的多个版本。所有 Backstage 核心包在实现上都保证“包重复不是问题”例如backstage/core-plugin-api、backstage/core-components、backstage/plugin-catalog-react、backstage/backend-plugin-api的重复安装都是可接受的。尽管如此为优化 bundle 体积与安装速度仍建议使用yarn dedupe之类的去重工具削减重复包数量。代理环境Proxy配置Backstage CLI 在设置NODE_USE_ENV_PROXY1时会遵循标准的HTTP_PROXY、HTTPS_PROXY、NO_PROXY环境变量完整细节参见 docs/tutorials/corporate-proxy.md。此外在受限网络环境中yarn本身有时也需要代理配置且它的配置方式与其他模块不同如果使用上文提到的 Backstage yarn 插件必须额外配置 yarn 的代理值才能安装插件并运行versions:bump命令如果所有环境都需要代理可在.yarnrc.yml中添加httpProxy和httpsProxy配置如果只有部分环境需要如开发机需要、AWS 上的 CI 构建机不需要则不建议改.yarnrc.yml而是在需要的环境中设置环境变量YARN_HTTP_PROXY与YARN_HTTPS_PROXY如果不打算使用 yarn 插件仅配置上述 CLI 代理通常就够了。代理配置示例export HTTP_PROXYhttp://proxy.company.com:8080 export HTTPS_PROXYhttp://proxy.company.com:8080 export NO_PROXYlocalhost,internal.company.com export NODE_USE_ENV_PROXY1 export YARN_HTTP_PROXY${HTTP_PROXY} # optional export YARN_HTTPS_PROXY${HTTPS_PROXY} # optional数据库迁移回滚Rollback migrations某些情况下你可能需要降级 Backstage 实例例如新版本出现问题或是在测试环境中验证新版本后再回退。数据库迁移的回滚可参考 docs/tutorials/manual-knex-rollback.md该指南讲解了如何使用 Knex 手动回滚迁移Backstage 后端插件如 catalog、scaffolder 等的数据库迁移记录在各自的migrations目录中每个迁移按顺序执行并记录于 schema 的迁移表内手动回滚时需要确认当前迁移序号再通过 knex CLI 执行对应次数的down。这一操作通常在“升级后发现兼容性问题、需要临时回到旧版本”的场景下与版本降级配合使用。小结一份完整的升级检查清单确认根目录backstage.json中记录的当前版本推荐安装 Backstage yarn 插件yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin并确认 yarn ≥ 4.1.1查阅backstage/create-app的 changelogpackages/create-app/CHANGELOG.md确认是否有需要手动同步的模板变更执行yarn backstage-cli versions:bump默认main线或yarn backstage-cli versions:bump --release next跟踪周更若需同时升级其他生态插件追加--pattern {backstage,roadiehq}/*在受限网络环境中按需配置 CLI 代理与 yarn 代理环境变量提交versions:bump产生的package.json、yarn.lock、.yarnrc.yml与backstage.json变更升级后如有异常可借助 docs/tutorials/manual-knex-rollback.md 回滚数据库迁移再降级相关包。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考