Backstage v1.5.0-next.3 版本解读ADR 插件 entityRef 破坏性变更与 readTree ZIP 解压安全加固【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于仓库中的 docs/releases/v1.5.0-next.3-changelog.md 展开对 Backstage v1.5.0 发布前的第三个预发布版本next.3所包含的变更进行技术解读。文章聚焦两大核心内容ADRArchitecture Decision Records插件系列引入entityRef字段的破坏性变更以及backend-common中readTree()返回的 ZIP 归档解压路径安全加固。读完本文你将清楚了解AdrDocument数据结构的变化与自定义AdrParser的迁移方法理解 UrlReader 树读取接口的目录穿越防护原理并掌握next.x预发布版本在 Backstage 发布流程中的定位。版本概览next.x 预发布版本在做什么Backstage 采用「预发布版本滚动确认最后统一发布正式版」的节奏。v1.5.0-next.3表示 v1.5.0 的第三个预发布迭代它汇总了多个包的最新变更供使用者提前验证当所有变更稳定后会以 docs/releases/v1.5.0-changelog.md 的形式发布正式版 v1.5.0。仓库的 docs/releases 目录中同时保留了每个版本的*-next.*-changelog.md与正式版 changelog可以对照阅读追溯某项变更从预发布到正式发布的过程。本次v1.5.0-next.3涉及 5 个包包版本变更级别backstage/plugin-adr0.2.0-next.2Minor含 BREAKINGbackstage/plugin-adr-backend0.2.0-next.1Minor含 BREAKINGbackstage/plugin-adr-common0.2.0-next.1Minor含 BREAKINGbackstage/backend-common0.15.0-next.2Patch安全加固backstage/create-app0.4.30-next.3Patch版本提升其中ADR 插件三个包前端plugin-adr、后端plugin-adr-backend、共享类型plugin-adr-common的变更属于同一项特性而backend-common的变更是独立的目录穿越安全修复。ADR 插件搜索结果显示关联实体标签chip变更内容本次 ADR 插件系列plugin-adr、plugin-adr-backend、plugin-adr-common的共同变更由提交bfc7c50a09引入Display associated entity as a chip inAdrSearchResultListItem即在 ADR 搜索结果列表项组件AdrSearchResultListItem中将与该 ADR 文档关联的 Catalog 实体以 chip标签/胶囊的形式展示出来。搜索用户可以在结果列表中直接看到每条 ADR 属于哪个实体例如某个System、Component或API实体不必进入详情页即可判断相关性。破坏性变更AdrDocument 新增 entityRef要实现「结果列表展示关联实体」前提是搜索索引里的 ADR 文档数据本身携带实体引用信息。因此该变更对文档数据结构做了调整BREAKING:AdrDocumentnow includes aentityRefproperty, if you have a customAdrParseryou will have to supply this property in your returned documentsAdrDocument定义在plugin-adr-common中新增了必填属性entityRef。AdrParser是 ADR 后端用来把仓库中的 ADR 原始文件解析为搜索文档的解析器如果你使用了自定义AdrParser则解析返回的文档对象必须补上entityRef属性否则 TypeScript 类型检查会直接报错。自定义 AdrParser 的迁移方式假设此前自定义解析器的返回对象大致如下const doc: AdrDocument { title: Use Luxon for date handling, text: ..., location: https://example.com/adr/0001-luxon.md, };升级到plugin-adr-common0.2.0之后需要为每个返回文档补充entityRef字段指向该 ADR 所属的 Catalog 实体const doc: AdrDocument { title: Use Luxon for date handling, text: ..., location: https://example.com/adr/0001-luxon.md, entityRef: component:my-service, // 新增关联的 Catalog 实体引用 };entityRef使用 Backstage 标准的实体引用语法如component:default/my-service或省略默认命名空间的简写形式其格式规范可参见 docs/architecture-decisions/adr009-entity-references.md。该文档同时描述了实体引用的解析规则与本次 ADR 文档结构变更直接相关。对于没有自定义AdrParser的使用者无需任何改动官方内置解析器已经在新版本中自动填充entityRef。需要说明的是当前仓库的plugins目录已不再包含 adr 插件源码该插件在后续版本中被移除/归档本文的迁移示例基于 changelog 声明的接口契约整理。与仓库内 ADR 内容的关联ADRArchitecture Decision Records本身是记录架构决策的轻量级文档。本仓库就在 docs/architecture-decisions 目录下维护着一套完整的 ADR 日志adr000起例如adr001-add-adr-log.md、adr010-luxon-date-library.md、adr014-use-fetch.md等索引见 docs/architecture-decisions/index.md。ADR 插件的作用正是索引这类文档并通过 Backstage 搜索提供检索。结合 docs/releases/v1.5.0-changelog.md 可以看到同一变更在正式版中随plugin-adr0.2.0一起发布前端还同步升级了core-components、plugin-search-react、plugin-catalog-react等依赖以支持 chip 渲染。backend-commonreadTree ZIP 解压目录穿越加固变更内容backstage/backend-common0.15.0-next.2的补丁变更提交5e4dc173f7如下Added a second validation to thedir()method of ZIP archive responses returned fromreadTree()that ensures that extracted files do not fall outside the target directory.readTree()是 Backstage UrlReader 服务UrlReaderService的核心方法之一用于把远程仓库GitHub、GitLab、Bitbucket、Gerrit 等的目录树拉取下来返回UrlReaderServiceReadTreeResponse。调用方可以对该响应执行三种消费方式files()枚举所有文件、archive()获取归档流、dir()解压到本地目录并返回目录路径。模板脚手架Software Templates在fetch:template、catalog:fetch等场景中会频繁使用readTree()。本次加固针对 ZIP 归档响应的dir()方法在原有校验之外增加第二重校验确保解压出的文件不会落到目标目录之外——这是典型的 ZIP 路径穿越Zip Slip防护。恶意构造的 ZIP 归档可以在条目文件名中包含../之类的相对路径例如../../etc/cron.d/evil如果解压逻辑不校验目标路径写入文件时就会逃逸出目标目录造成任意文件写入。源码级原理虽然当前仓库中backend-common已拆分重构为backend-defaults但 ZipArchiveResponse 的实现与修复思路一脉相承。核心实现在 packages/backend-defaults/src/entrypoints/urlReader/lib/tree/ZipArchiveResponse.tsforEveryZipEntryL117-L152使用yauzl以lazyEntries模式逐个读取 ZIP 条目dir()方法L197-L226对每个条目计算目标路径并统一通过resolveSafeChildPath(dir, entryPath)解析目录名与写入路径L212、L215resolveSafeChildPath由backstage/backend-plugin-api导出见 L28 的 import它会在拼接路径时校验结果必须位于基目录之内一旦发现越界立即拒绝从根上阻断../逃逸。也就是说解压写入文件fs.createWriteStream和创建中间目录fs.mkdirp两条路径都经过resolveSafeChildPath约束这正是 changelog 中所说的「第二重 validation」。对应的测试见 ZipArchiveResponse.test.ts。另外同一个ZipArchiveResponse在 v1.5.0 发布周期内还伴随了另一项健壮性修复见 docs/releases/v1.5.0-changelog.md 中cfa078e255通过先将 ZIP 流写入临时文件、再从磁盘解析的方式规避损坏 ZIP 导致 inflater 抛错或解析器无限挂起的问题。这两项变更共同提升了readTree()在不可信输入下的安全性与稳定性。升级影响与验证本项变更为纯加固性质不改变readTree()的公开接口签名普通使用方无需修改代码。受影响的主要是两类人自实现 UrlReader 插件/扩展如果你的自定义 reader 返回 ZIP 归档响应建议同步采用「先落临时文件 安全路径解析」的实现模式安全审查人员升级后可用包含../条目的测试 ZIP 验证dir()是否会抛错并拒绝写入仓库测试用例即按此思路覆盖。其他变更create-app 版本提升backstage/create-app0.4.30-next.3仅包含Bumped create-app version属于常规的脚手架版本对齐无功能性变更。create-app是npx backstage/create-app创建新 Backstage 应用的引导工具它的版本号跟着仓库整体节奏提升确保新应用生成时默认依赖解析到最新的稳定预发布组合。升级建议与验证路径如果你正在使用 ADR 插件且维护了自定义AdrParser请在升级到plugin-adr系列0.2.0版本时优先处理entityRef必填字段backend-common的安全加固建议尽早合入。升级后可以通过以下方式验证运行 TypeScript 类型检查确认所有AdrDocument构造点都已补全entityRef在 Backstage 前端执行 ADR 搜索确认AdrSearchResultListItem正确渲染关联实体的 chip对使用fetch:template等依赖readTree()的模板做一次冒烟测试确认 ZIP 读取与解压行为正常。完整的正式版变更清单可对照 docs/releases/v1.5.0-changelog.md该文件还包含本次预发布未涉及的其他变更如plugin-catalog的创建按钮自定义、BitbucketServerEntityProvider新插件、publish:gerrit:reviewscaffolder action 等可作为 v1.5.0 升级评估的完整依据。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考