Backstage系列教程 - 02 项目架构与目录结构详解

本文选择一部分常用的文件/文件夹进行说明，帮助你快速理解 Backstage 的项目结构。

目录结构总览

1
2
3
4
5
6
7
8
9
10
11

backstage/
├── examples/              # 示例模板与预设数据
│   ├── template/          # 项目模板
│   ├── entities.yaml      # 预设实体配置
│   └── org.yaml           # 预设组织架构
├── node_modules/          # 依赖包
├── packages/              # 核心包目录
│   ├── app/               # 前端应用
│   └── backend/           # 后端服务
├── plugins/               # 自定义插件目录
└── app-config.yaml        # 系统核心配置文件

一、examples 目录

examples 目录存放示例模板和预设数据，用于快速体验 Backstage 的各项功能。

template 目录

这个文件夹下的全部内容都将作为模板创建 GitLab 项目时的初始化文件。当 GitLab 项目创建成功后，仓库中将出现文件夹下的所有文件。

entities.yaml

这三个实体将会在进入 Backstage 系统后显示，除非自行删除。

org.yaml

二、packages 目录

packages 目录是 Backstage 的核心代码目录，分为前端和后端两部分。

app（前端）

前端应用目录，基于 React + Material UI 构建。

1
2
3
4
5
6
7
8
9
10
11
12

packages/app/
├── e2e-tests/        # 端到端测试（功能未知）
├── public/           # 公用文件
└── src/
    ├── components/
    │   ├── catalog/
    │   │   └── EntityPage.tsx  # 定义页面展示内容及各类型实体的页面内容
    │   ├── Root/
    │   └── search/             # 搜索页面
    ├── apis.ts        # 可以设置登录登出逻辑
    ├── App.tsx        # 定义左侧菜单栏以及登录登出逻辑
    └── index.tsx      # 前端页面根组件

关键文件说明：

• 📄 EntityPage.tsx：在这里面定义页面展示内容以及各个类型的实体中展示的页面内容
• 📄 apis.ts：可以设置登录登出逻辑
• 📄 App.tsx：定义左侧菜单栏以及登录登出逻辑
• 📄 index.tsx：前端页面根组件

backend（后端）

后端服务目录，基于 Node.js + Express 构建。

1
2
3

packages/backend/
├── plugins/           # 后端中的自定义插件
└── index.ts           # 后端依赖包配置

三、plugins 目录

plugins 目录是 Backstage 插件开发的核心目录，所有自定义的功能插件都存放在这里。插件是 Backstage 扩展性的核心体现，通过插件机制可以灵活扩展系统功能。

四、app-config.yaml

app-config.yaml 是 Backstage 系统的核心配置文件，包含：

• ⚙️ 系统基础配置
• 🔌 插件配置
• 🔗 集成配置（GitLab、GitHub 等）
• 🔐 认证配置
• 🎨 主题与外观配置
• 📦 数据库配置

总结：Backstage 采用前后端分离的架构设计，通过 packages 目录分离前后端代码，通过 plugins 目录实现插件化扩展，通过 app-config.yaml 统一管理系统配置。理解这套目录结构是进行 Backstage 二次开发的基础。