Backstage 本地开发环境实战yarn start 双进程架构、SQLite 数据模型与热重载机制解析【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文是 Backstage Golden Path 系列的本地开发篇围绕yarn start一条命令展开它会同时在同一个终端窗口里拉起前端[0]与后端[1]两个进程分别运行在 3000 与 7007 端口上。读完本文你将掌握 Backstage 本地开发环境的前后端架构、SQLite 内存数据库的使用边界以及双端热重载的行为特征并能结合仓库源码定位相关配置与实现。从安装到启动一条命令拉起整个 Backstage 应用当 Backstage 应用通过 Golden Path 安装篇 创建完成后整个应用已经就绪。此时进入应用目录并执行yarn start即可启动完整的前后端开发环境cd my-backstage-app # 替换为你自己的应用名 yarn startyarn start会在同一个终端窗口内同时启动两个独立进程分别以[0]和[1]为前缀输出日志。前端需要一小段时间完成编译编译成功后浏览器窗口会自动打开如果浏览器没有自动弹出看到[0] webpack compiled successfully提示后直接访问http://localhost:3000即可看到你的 Backstage 门户。前端进程3000 端口上的 React 应用与 rspack 编译[0]进程对应的前端站点位于packages/app。它本质上是一个 React 应用并带有大量插件友好的默认配置。从 packages/app/package.json 可以看到前端包的backstage.role为frontend其start脚本执行的是backstage-cli package start由 Backstage CLI 统一驱动开发服务器。在本地开发中前端使用rspack完成编译以提供快速的编译速度和近乎即时的反馈。仓库中的 packages/cli/src/types.d.ts 也直接引用了rspack/core的Stats类型印证了 rspack 已深度集成进 Backstage CLI 的构建链。因此本地开发时你看到的编译成功提示通常是Rspack compiled successfully前端的监听端口默认为3000这一设定同时反映在 app-config.yaml 中app: title: Backstage Example App baseUrl: http://localhost:3000app.baseUrl不仅用于本地访问也是后端校验 CORS 来源、生成各类回调地址的重要依据与下文的backend.cors.origin一一对应。后端进程7007 端口上的 Node.js 服务与插件体系[1]进程对应的后端位于packages/backend。它是一个 Node.js 应用内部通过express提供 HTTP 服务并连接数据库。packages/backend/package.json 中后端包的backstage.role为backendstart脚本为start: backstage-cli package start --require ./src/instrumentation.js其中--require ./src/instrumentation.js会在启动早期加载可观测性埋点如 OpenTelemetry这是示例后端预置的增强项。后端的入口逻辑集中在 packages/backend/src/index.ts它通过backstage/backend-defaults的createBackend()创建后端实例然后逐一backend.add(...)注册 auth、catalog、scaffolder、search、techdocs、signals、notifications 等几十个后端插件最后调用backend.start()启动。搜索相关插件还通过createBackendFeatureLoader分组按需加载当配置中存在search.elasticsearch时才动态引入 Elasticsearch 模块。从源码结构看backend.start()会启动内嵌的 express HTTP 服务器并统一监听在配置指定的端口上。后端的默认监听端口为7007对应的配置位于 app-config.yaml 的backend段backend: baseUrl: http://localhost:7007 listen: port: 7007 database: client: better-sqlite3 connection: :memory: cors: origin: http://localhost:3000 methods: [GET, HEAD, PATCH, POST, PUT, DELETE] credentials: true这里有三个要点baseUrl与listen.port共同决定了后端对外暴露的地址http://localhost:7007cors.origin明确允许来自前端http://localhost:3000的跨域请求并开启credentials保证登录态 Cookie 可以在前后端之间传递database段则定义了本地数据库的类型与连接方式见下一节。SQLite 内存数据库本地开发的数据真相本地开发时Backstage 默认使用sqlite作为数据库。正如 app-config.yaml 所示具体实现是better-sqlite3驱动连接串为:memory:即一个运行在内存中的数据库。这意味着本地开发数据库具备两个关键特性瞬时性ephemeral内存数据库的生命周期与后端进程绑定一旦yarn start结束数据即全部丢失。因此不要依赖本地数据库在多次启动之间保留数据例如手动注册的实体、任务记录等重启后需要重新导入。热重载期间持续保留与完全重启进程不同在热重载hot reload过程中数据库并不会被重置——后端进程仍在运行内存中的连接与数据得以延续。这也是日常改代码时不会频繁丢失本地数据的原因。从源码角度印证packages/backend在示例后端中依赖backstage/backend-defaults其数据库服务会读取上述backend.database配置来实例化连接当配置为内存 SQLite 时所有插件共享同一个内存实例。需要说明的是SQLite 仅是本地开发与示例的默认选择Golden Path 的 部署篇 会介绍生产架构下如何替换为真正的持久化数据库如 PostgreSQL并配合外部存储承载 TechDocs 等数据。双端热重载编辑即反馈的开发体验本地开发的另一大特性是前后端均支持热重载两者的行为略有差异前端只要保存了 React 应用所使用的文件稍等片刻就会看到编译成功的提示形如Rspack compiled successfully随后浏览器中的页面会自动刷新/热更新无需手动重启。后端保存后端源码后会先看到Change detected, restarting the development server...紧接着输出服务器重启过程中的初始化日志即backend.start()启动各插件时的日志。后端采用检测到变更→重启开发服务器的模式因此重启后会重新执行一遍插件注册与数据库连接流程对内存 SQLite 而言热重载时数据库得以保留如前文所述。本地开发架构一览综合上文可以用一张速查表概括本地开发环境的关键事实均可在本仓库对应文件中找到依据项目值依据文件前端目录packages/approle: frontendpackages/app/package.json前端端口3000app-config.yaml 中app.baseUrl前端编译器rspack提示Rspack compiled successfullypackages/cli/src/types.d.ts后端目录packages/backendrole: backendpackages/backend/package.json后端端口7007app-config.yaml 中backend.listen.port后端 HTTP 框架express由backend.start()启动packages/backend/src/index.ts本地数据库SQLite 内存库better-sqlite3/:memory:app-config.yaml 中backend.database前后端跨域CORS origin 指向http://localhost:3000app-config.yaml 中backend.cors热重载前端编译即刷新后端检测变更→重启服务器命令行输出信息小结从本地开发到生产架构yarn start之所以能在单窗口内并行跑起前后端是因为 Backstage 将应用拆成了packages/appReact 门户与packages/backendNode.js 插件服务两个可独立运行的部分并通过 app-config.yaml 统一定义端口、数据库与跨域策略。本地开发中 rspack 的快速编译、SQLite 内存库的低成本启动以及双端热重载共同构成了开箱即用的开发体验。需要提醒的是本节仅覆盖本地开发形态内存 SQLite 不适合承载真实数据rspack 开发服务器也不等于生产构建产物。Golden Path 的部署篇见 docs/golden-path/deployment/会进一步讲解生产环境的架构演进包括持久化数据库、构建产物与部署拓扑等话题。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Backstage 本地开发环境实战yarn start 双进程架构、SQLite 数据模型与热重载机制解析【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文是 Backstage Golden Path 系列的本地开发篇围绕yarn start一条命令展开它会同时在同一个终端窗口里拉起前端[0]与后端[1]两个进程分别运行在 3000 与 7007 端口上。读完本文你将掌握 Backstage 本地开发环境的前后端架构、SQLite 内存数据库的使用边界以及双端热重载的行为特征并能结合仓库源码定位相关配置与实现。从安装到启动一条命令拉起整个 Backstage 应用当 Backstage 应用通过 Golden Path 安装篇 创建完成后整个应用已经就绪。此时进入应用目录并执行yarn start即可启动完整的前后端开发环境cd my-backstage-app # 替换为你自己的应用名 yarn startyarn start会在同一个终端窗口内同时启动两个独立进程分别以[0]和[1]为前缀输出日志。前端需要一小段时间完成编译编译成功后浏览器窗口会自动打开如果浏览器没有自动弹出看到[0] webpack compiled successfully提示后直接访问http://localhost:3000即可看到你的 Backstage 门户。前端进程3000 端口上的 React 应用与 rspack 编译[0]进程对应的前端站点位于packages/app。它本质上是一个 React 应用并带有大量插件友好的默认配置。从 packages/app/package.json 可以看到前端包的backstage.role为frontend其start脚本执行的是backstage-cli package start由 Backstage CLI 统一驱动开发服务器。在本地开发中前端使用rspack完成编译以提供快速的编译速度和近乎即时的反馈。仓库中的 packages/cli/src/types.d.ts 也直接引用了rspack/core的Stats类型印证了 rspack 已深度集成进 Backstage CLI 的构建链。因此本地开发时你看到的编译成功提示通常是Rspack compiled successfully前端的监听端口默认为3000这一设定同时反映在 app-config.yaml 中app: title: Backstage Example App baseUrl: http://localhost:3000app.baseUrl不仅用于本地访问也是后端校验 CORS 来源、生成各类回调地址的重要依据与下文的backend.cors.origin一一对应。后端进程7007 端口上的 Node.js 服务与插件体系[1]进程对应的后端位于packages/backend。它是一个 Node.js 应用内部通过express提供 HTTP 服务并连接数据库。packages/backend/package.json 中后端包的backstage.role为backendstart脚本为start: backstage-cli package start --require ./src/instrumentation.js其中--require ./src/instrumentation.js会在启动早期加载可观测性埋点如 OpenTelemetry这是示例后端预置的增强项。后端的入口逻辑集中在 packages/backend/src/index.ts它通过backstage/backend-defaults的createBackend()创建后端实例然后逐一backend.add(...)注册 auth、catalog、scaffolder、search、techdocs、signals、notifications 等几十个后端插件最后调用backend.start()启动。搜索相关插件还通过createBackendFeatureLoader分组按需加载当配置中存在search.elasticsearch时才动态引入 Elasticsearch 模块。从源码结构看backend.start()会启动内嵌的 express HTTP 服务器并统一监听在配置指定的端口上。后端的默认监听端口为7007对应的配置位于 app-config.yaml 的backend段backend: baseUrl: http://localhost:7007 listen: port: 7007 database: client: better-sqlite3 connection: :memory: cors: origin: http://localhost:3000 methods: [GET, HEAD, PATCH, POST, PUT, DELETE] credentials: true这里有三个要点baseUrl与listen.port共同决定了后端对外暴露的地址http://localhost:7007cors.origin明确允许来自前端http://localhost:3000的跨域请求并开启credentials保证登录态 Cookie 可以在前后端之间传递database段则定义了本地数据库的类型与连接方式见下一节。SQLite 内存数据库本地开发的数据真相本地开发时Backstage 默认使用sqlite作为数据库。正如 app-config.yaml 所示具体实现是better-sqlite3驱动连接串为:memory:即一个运行在内存中的数据库。这意味着本地开发数据库具备两个关键特性瞬时性ephemeral内存数据库的生命周期与后端进程绑定一旦yarn start结束数据即全部丢失。因此不要依赖本地数据库在多次启动之间保留数据例如手动注册的实体、任务记录等重启后需要重新导入。热重载期间持续保留与完全重启进程不同在热重载hot reload过程中数据库并不会被重置——后端进程仍在运行内存中的连接与数据得以延续。这也是日常改代码时不会频繁丢失本地数据的原因。从源码角度印证packages/backend在示例后端中依赖backstage/backend-defaults其数据库服务会读取上述backend.database配置来实例化连接当配置为内存 SQLite 时所有插件共享同一个内存实例。需要说明的是SQLite 仅是本地开发与示例的默认选择Golden Path 的 部署篇 会介绍生产架构下如何替换为真正的持久化数据库如 PostgreSQL并配合外部存储承载 TechDocs 等数据。双端热重载编辑即反馈的开发体验本地开发的另一大特性是前后端均支持热重载两者的行为略有差异前端只要保存了 React 应用所使用的文件稍等片刻就会看到编译成功的提示形如Rspack compiled successfully随后浏览器中的页面会自动刷新/热更新无需手动重启。后端保存后端源码后会先看到Change detected, restarting the development server...紧接着输出服务器重启过程中的初始化日志即backend.start()启动各插件时的日志。后端采用检测到变更→重启开发服务器的模式因此重启后会重新执行一遍插件注册与数据库连接流程对内存 SQLite 而言热重载时数据库得以保留如前文所述。本地开发架构一览综合上文可以用一张速查表概括本地开发环境的关键事实均可在本仓库对应文件中找到依据项目值依据文件前端目录packages/approle: frontendpackages/app/package.json前端端口3000app-config.yaml 中app.baseUrl前端编译器rspack提示Rspack compiled successfullypackages/cli/src/types.d.ts后端目录packages/backendrole: backendpackages/backend/package.json后端端口7007app-config.yaml 中backend.listen.port后端 HTTP 框架express由backend.start()启动packages/backend/src/index.ts本地数据库SQLite 内存库better-sqlite3/:memory:app-config.yaml 中backend.database前后端跨域CORS origin 指向http://localhost:3000app-config.yaml 中backend.cors热重载前端编译即刷新后端检测变更→重启服务器命令行输出信息小结从本地开发到生产架构yarn start之所以能在单窗口内并行跑起前后端是因为 Backstage 将应用拆成了packages/appReact 门户与packages/backendNode.js 插件服务两个可独立运行的部分并通过 app-config.yaml 统一定义端口、数据库与跨域策略。本地开发中 rspack 的快速编译、SQLite 内存库的低成本启动以及双端热重载共同构成了开箱即用的开发体验。需要提醒的是本节仅覆盖本地开发形态内存 SQLite 不适合承载真实数据rspack 开发服务器也不等于生产构建产物。Golden Path 的部署篇见 docs/golden-path/deployment/会进一步讲解生产环境的架构演进包括持久化数据库、构建产物与部署拓扑等话题。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
