在 Backstage 中启用公共入口点将未认证登录页与受保护主应用拆分的实验特性实战【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读本文围绕 Backstage 官方教程《Enabling a public entry point实验特性》展开讲解如何把 Backstage 应用打包产物拆分为仅含登录页的公共入口与登录后可见的受保护主入口并借助app-backend插件按认证状态分发不同入口。读完本文你将掌握index-public-experimental.tsx的编写约定、新前端系统下的最小实现、本地验证流程以及app-backend在源码层面是如何完成未认证用户看公共页、已认证用户看主应用这一分发逻辑的。本文面向新的前端系统Backstage 新应用默认启用。如果你的应用仍在使用旧前端系统请阅读旧前端系统版本的教程。特性原理一份应用两个入口该特性的核心思路是把应用打包产物bundle拆成两个代码入口公共入口点public entry point只包含登录页sign-in pages相关代码受保护主入口点protected main entry point包含登录后看到的主应用全部代码。随后Backstage 的 CLI 与后端会检测到公共入口点的存在对未认证用户返回公共入口登录页对已认证用户才返回受保护的主入口。换句话说主应用的index.html不会在未认证状态下被直接交付给浏览器从而把主应用主体真正保护起来。从源码结构看这一检测与分发能力由app-backend插件承担详见下文后端源码解析一节。当前该特性仍处于实验阶段官方预期会在后续迭代中继续打磨因此文中方案属于简化的可用版本。前置要求启用公共入口点需要满足两个条件缺一不可应用必须由app-backend插件提供服务否则该特性不生效例如用静态文件服务器直接托管dist目录的场景不适用必须使用backstage-cli来构建build与服务serveBackstage 应用即采用标准的yarn workspace app start/yarn backstage-cli app:build流程。分步实现编写公共入口文件第 1 步创建index-public-experimental.tsx在应用包的src目录下新建文件以仓库内置应用为例即packages/app/src/index-public-experimental.tsximport ReactDOM from react-dom/client; import { signInPageModule } from ./overrides/SignInPage; import { appModulePublicSignIn } from backstage/plugin-app/alpha; import { createApp } from backstage/frontend-defaults; const app createApp({ features: [signInPageModule, appModulePublicSignIn], }); ReactDOM.createRoot(document.getElementById(root)!).render( app.createRoot(), );需要特别注意的是文件名index-public-experimental.tsx是一种约定convention当前版本不可配置。CLI 会在打包时识别该约定文件将其构建为独立的公共入口若文件名不同则不会被识别。第 2 步理解两个关键模块signInPageModule你自己的自定义登录页扩展通常已经在应用中配置好。在这个公共入口里它就是未认证用户能看到的所有内容。appModulePublicSignIn来自backstage/plugin-app/alpha它提供了CookieAuthRedirect组件负责在登录完成后发起已认证重定向把用户带回主应用。从源码实现看见 plugins/app/src/alpha/appModulePublicSignIn.tsxappModulePublicSignIn会通过createFrontendModule以app为插件 ID 注册扩展并覆盖app/layout扩展用内部的InternalCookieAuthRedirect替换默认布局。这意味着公共入口会忽略大多数常规应用安装的扩展例如导航、主页等布局类扩展只保留 API 与根元素类扩展因此典型配置就是只装一个自定义登录页。InternalCookieAuthRedirect的工作流程是登录后从identityApi获取 Backstage token然后渲染一个隐藏表单以POST方式把typesign-in与token提交到当前 URLwindow.location.href由后端完成 cookie 签发后重定向回主应用。另外官方在文档中特别说明前端会自动处理 cookie 的刷新cookie refreshing无需你额外关心。本地验证从项目根目录执行以下两条命令分别构建/启动应用与后端# 构建并启动 app 包开发模式 yarn workspace app start # 启动后端 API yarn start-backend随后访问 http://localhost:7007 验证打开页面检查返回的index.html响应——它应当只包含一个极简应用即公共入口只有登录页相关代码点击登录并完成认证后你将被重定向到主应用首页此时在开发者工具中检查网络请求可以看到重定向后受保护的主 bundle 是从app-backend返回的。官方同时给出一个重要说明常规的应用服务regular app serving始终会不经认证地提供受保护应用——也就是说只有配置了公共入口点构建产物中存在public目录时app-backend才会启用受保护模式的分发逻辑。后端源码解析app-backend如何分发两个入口该特性的后端核心逻辑位于 plugins/app-backend/src/service/router.ts。从源码可以看到完整的分发链路1. 检测公共入口目录。插件会计算publicDistDir resolvePath(appDistDir, public)即打包产物dist下是否存在public子目录由index-public-experimental.tsx构建产生。只有当public目录存在且配置未禁用时才进入受保护模式const disablePublicEntryPoint config.getOptionalBoolean( app.disablePublicEntryPoint, ); const enablePublicEntryPoint !disablePublicEntryPoint (await fs.pathExists(publicDistDir));2. 认证分流中间件。公共路由会先通过httpAuth.credentials(req, { allow: [user, service, none], allowLimitedAccess: true })解析请求凭据若credentials.principal.type none未认证继续走公共入口路由返回登录页否则已认证next(router)跳过公共路由交给外层主入口路由处理。3. 登录回传POST sign-in。公共路由对POST *请求启用express.urlencoded解析当请求体type sign-in时用auth.authenticate(req.body.token)校验 token确认是user主体后通过httpAuth.issueUserCookie签发用户 cookie然后把请求方法改写为GET并next(router)交由受保护的主入口路由正常返回主应用index.html。4. 静态资源与缓存。公共入口与主入口分别通过createEntryPointRouter提供服务公共入口的静态资源缓存使用独立的assetStore.withNamespace(public)命名空间避免与主入口资产相互污染。配置项app.disablePublicEntryPoint如果你虽然构建了公共入口但希望临时关闭该行为例如回退到始终返回主入口可以在app-config.yaml中设置app: disablePublicEntryPoint: true该配置项定义于 plugins/app-backend/config.d.ts当应用带有index-public-experimental入口时app-backend默认会自动把它提供给未认证用户设为true后则跳过该行为始终提供主入口。该开关在app-backend的 CHANGELOG 中也有记录可作为版本升级时的参考。测试用例佐证app-backend的单元测试plugins/app-backend/src/service/router.test.ts完整覆盖了上述三条核心行为可作为理解与回归验证的依据serves the public entry point to unauthenticated users未携带 cookie 请求/index.html返回公共入口的public index.html状态码 200serves the main entry point to authenticated users携带用户 cookie 请求/index.html返回主入口的index.htmlhandles sign-in and issues a user cookiePOST /提交typesign-in与有效 token 后响应包含set-cookie头且最终返回主入口index.htmlrejects POST requests without a sign-in type提交非sign-in类型的 POST 请求会被拒绝。旧前端系统说明与限制若应用仍运行在旧前端系统上公共入口的实现方式不同它使用backstage/app-defaults的createApp、backstage/core-components的SignInPage/AlertDisplay/OAuthRequestDialog以及backstage/plugin-auth-react的CookieAuthRedirect并需显式装配AppRouter。具体代码与说明见旧版教程。最后提醒三点使用限制公共入口点特性依赖app-backend与backstage-cli的配合脱离任一条件均不生效文件名index-public-experimental.tsx为硬编码约定暂不支持自定义该特性仍处于实验阶段官方表示会在后续迭代中继续完善生产环境采用前请评估其稳定性与安全边界。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/13 19:01:39 · 阅读 1.2k 在 Backstage 中启用公共入口点：将未认证登录页与受保护主应用拆分的实验特性实战
在 Backstage 中启用公共入口点将未认证登录页与受保护主应用拆分的实验特性实战【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读本文围绕 Backstage 官方教程《Enabling a public entry point实验特性》展开讲解如何把 Backstage 应用打包产物拆分为仅含登录页的公共入口与登录后可见的受保护主入口并借助app-backend插件按认证状态分发不同入口。读完本文你将掌握index-public-experimental.tsx的编写约定、新前端系统下的最小实现、本地验证流程以及app-backend在源码层面是如何完成未认证用户看公共页、已认证用户看主应用这一分发逻辑的。本文面向新的前端系统Backstage 新应用默认启用。如果你的应用仍在使用旧前端系统请阅读旧前端系统版本的教程。特性原理一份应用两个入口该特性的核心思路是把应用打包产物bundle拆成两个代码入口公共入口点public entry point只包含登录页sign-in pages相关代码受保护主入口点protected main entry point包含登录后看到的主应用全部代码。随后Backstage 的 CLI 与后端会检测到公共入口点的存在对未认证用户返回公共入口登录页对已认证用户才返回受保护的主入口。换句话说主应用的index.html不会在未认证状态下被直接交付给浏览器从而把主应用主体真正保护起来。从源码结构看这一检测与分发能力由app-backend插件承担详见下文后端源码解析一节。当前该特性仍处于实验阶段官方预期会在后续迭代中继续打磨因此文中方案属于简化的可用版本。前置要求启用公共入口点需要满足两个条件缺一不可应用必须由app-backend插件提供服务否则该特性不生效例如用静态文件服务器直接托管dist目录的场景不适用必须使用backstage-cli来构建build与服务serveBackstage 应用即采用标准的yarn workspace app start/yarn backstage-cli app:build流程。分步实现编写公共入口文件第 1 步创建index-public-experimental.tsx在应用包的src目录下新建文件以仓库内置应用为例即packages/app/src/index-public-experimental.tsximport ReactDOM from react-dom/client; import { signInPageModule } from ./overrides/SignInPage; import { appModulePublicSignIn } from backstage/plugin-app/alpha; import { createApp } from backstage/frontend-defaults; const app createApp({ features: [signInPageModule, appModulePublicSignIn], }); ReactDOM.createRoot(document.getElementById(root)!).render( app.createRoot(), );需要特别注意的是文件名index-public-experimental.tsx是一种约定convention当前版本不可配置。CLI 会在打包时识别该约定文件将其构建为独立的公共入口若文件名不同则不会被识别。第 2 步理解两个关键模块signInPageModule你自己的自定义登录页扩展通常已经在应用中配置好。在这个公共入口里它就是未认证用户能看到的所有内容。appModulePublicSignIn来自backstage/plugin-app/alpha它提供了CookieAuthRedirect组件负责在登录完成后发起已认证重定向把用户带回主应用。从源码实现看见 plugins/app/src/alpha/appModulePublicSignIn.tsxappModulePublicSignIn会通过createFrontendModule以app为插件 ID 注册扩展并覆盖app/layout扩展用内部的InternalCookieAuthRedirect替换默认布局。这意味着公共入口会忽略大多数常规应用安装的扩展例如导航、主页等布局类扩展只保留 API 与根元素类扩展因此典型配置就是只装一个自定义登录页。InternalCookieAuthRedirect的工作流程是登录后从identityApi获取 Backstage token然后渲染一个隐藏表单以POST方式把typesign-in与token提交到当前 URLwindow.location.href由后端完成 cookie 签发后重定向回主应用。另外官方在文档中特别说明前端会自动处理 cookie 的刷新cookie refreshing无需你额外关心。本地验证从项目根目录执行以下两条命令分别构建/启动应用与后端# 构建并启动 app 包开发模式 yarn workspace app start # 启动后端 API yarn start-backend随后访问 http://localhost:7007 验证打开页面检查返回的index.html响应——它应当只包含一个极简应用即公共入口只有登录页相关代码点击登录并完成认证后你将被重定向到主应用首页此时在开发者工具中检查网络请求可以看到重定向后受保护的主 bundle 是从app-backend返回的。官方同时给出一个重要说明常规的应用服务regular app serving始终会不经认证地提供受保护应用——也就是说只有配置了公共入口点构建产物中存在public目录时app-backend才会启用受保护模式的分发逻辑。后端源码解析app-backend如何分发两个入口该特性的后端核心逻辑位于 plugins/app-backend/src/service/router.ts。从源码可以看到完整的分发链路1. 检测公共入口目录。插件会计算publicDistDir resolvePath(appDistDir, public)即打包产物dist下是否存在public子目录由index-public-experimental.tsx构建产生。只有当public目录存在且配置未禁用时才进入受保护模式const disablePublicEntryPoint config.getOptionalBoolean( app.disablePublicEntryPoint, ); const enablePublicEntryPoint !disablePublicEntryPoint (await fs.pathExists(publicDistDir));2. 认证分流中间件。公共路由会先通过httpAuth.credentials(req, { allow: [user, service, none], allowLimitedAccess: true })解析请求凭据若credentials.principal.type none未认证继续走公共入口路由返回登录页否则已认证next(router)跳过公共路由交给外层主入口路由处理。3. 登录回传POST sign-in。公共路由对POST *请求启用express.urlencoded解析当请求体type sign-in时用auth.authenticate(req.body.token)校验 token确认是user主体后通过httpAuth.issueUserCookie签发用户 cookie然后把请求方法改写为GET并next(router)交由受保护的主入口路由正常返回主应用index.html。4. 静态资源与缓存。公共入口与主入口分别通过createEntryPointRouter提供服务公共入口的静态资源缓存使用独立的assetStore.withNamespace(public)命名空间避免与主入口资产相互污染。配置项app.disablePublicEntryPoint如果你虽然构建了公共入口但希望临时关闭该行为例如回退到始终返回主入口可以在app-config.yaml中设置app: disablePublicEntryPoint: true该配置项定义于 plugins/app-backend/config.d.ts当应用带有index-public-experimental入口时app-backend默认会自动把它提供给未认证用户设为true后则跳过该行为始终提供主入口。该开关在app-backend的 CHANGELOG 中也有记录可作为版本升级时的参考。测试用例佐证app-backend的单元测试plugins/app-backend/src/service/router.test.ts完整覆盖了上述三条核心行为可作为理解与回归验证的依据serves the public entry point to unauthenticated users未携带 cookie 请求/index.html返回公共入口的public index.html状态码 200serves the main entry point to authenticated users携带用户 cookie 请求/index.html返回主入口的index.htmlhandles sign-in and issues a user cookiePOST /提交typesign-in与有效 token 后响应包含set-cookie头且最终返回主入口index.htmlrejects POST requests without a sign-in type提交非sign-in类型的 POST 请求会被拒绝。旧前端系统说明与限制若应用仍运行在旧前端系统上公共入口的实现方式不同它使用backstage/app-defaults的createApp、backstage/core-components的SignInPage/AlertDisplay/OAuthRequestDialog以及backstage/plugin-auth-react的CookieAuthRedirect并需显式装配AppRouter。具体代码与说明见旧版教程。最后提醒三点使用限制公共入口点特性依赖app-backend与backstage-cli的配合脱离任一条件均不生效文件名index-public-experimental.tsx为硬编码约定暂不支持自定义该特性仍处于实验阶段官方表示会在后续迭代中继续完善生产环境采用前请评估其稳定性与安全边界。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考