偶尔喝醉 發表於 2026-4-14 09:35:00

backstage~开始一个backstage应用

<h1 id="应该如何创建自己公司的backstage平台">应该如何创建自己公司的backstage平台</h1>
<h3 id="1-两种方式的本质区别">1. 两种方式的本质区别</h3>
<table>
<thead>
<tr>
<th style="text-align: left">特性</th>
<th style="text-align: left"><strong><code>npx @backstage/create-app</code></strong></th>
<th style="text-align: left"><strong>从 GitHub 下载源代码</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left"><strong>产出物</strong></td>
<td style="text-align: left">一个<strong>完整的、可立即运行和开发</strong>的 Backstage 应用。</td>
<td style="text-align: left">Backstage 项目<strong>框架本身的源代码</strong>，不是你应用的代码。</td>
</tr>
<tr>
<td style="text-align: left"><strong>目的</strong></td>
<td style="text-align: left"><strong>创建你自己的、个性化的 Backstage 开发者门户。</strong> 这是官方推荐的、标准的启动方式。</td>
<td style="text-align: left">用于<strong>贡献代码、深度研究框架内核</strong>。比如你想为 Backstage 项目本身修复Bug或开发新功能。</td>
</tr>
<tr>
<td style="text-align: left"><strong>关系</strong></td>
<td style="text-align: left">这个命令<strong>内部</strong>会去获取 GitHub 上最新的 Backstage 框架，并为你生成一个预配置好的应用。</td>
<td style="text-align: left">是 <code>create-app</code> 命令所依赖的“原材料”。</td>
</tr>
<tr>
<td style="text-align: left"><strong>适合场景</strong></td>
<td style="text-align: left">99.9% 的公司部署和定制场景。</td>
<td style="text-align: left">0.1% 的 Backstage 核心开发者或研究者。</td>
</tr>
</tbody>
</table>
<h3 id="2-详细解释">2. 详细解释</h3>
<p><strong>关于 <code>npx @backstage/create-app</code>：</strong></p>
<ul>
<li>这个命令是<strong>一键式脚手架工具</strong>。它会：
<ol>
<li>从 npm 仓库获取最新的创建工具。</li>
<li>为你交互式地创建一个<strong>新的项目目录</strong>（比如 <code>my-backstage</code>）。</li>
<li>在这个目录里，生成一个<strong>完整的、单体式的 Backstage 应用</strong>，这个应用<strong>已经集成了所有核心插件</strong>（软件目录、模板、文档等）。</li>
<li>自动安装好所有依赖。</li>
</ol>
</li>
<li><strong>是的，这个命令创建出来的应用，就是一个完整的、需要你后续部署和定制的 Backstage 服务平台</strong>。你可以立刻在本地运行它（<code>yarn dev</code>），它就是一个拥有基础功能的开发者门户。你之后的所有定制化开发（添加公司Logo、配置认证、接入内部系统、编写自定义插件）都将基于这个项目进行。</li>
</ul>
<p><strong>关于从 GitHub 下载源码：</strong></p>
<ul>
<li>如果你直接克隆 Backstage 的主仓库（<code>https://github.com/backstage/backstage</code>），你会得到一个包含 <strong>Backstage 框架本身、所有核心插件源码、以及大量示例和开发工具</strong> 的巨型代码库。</li>
<li>这个代码库结构复杂，<strong>并不是一个可以直接运行的应用</strong>。它更像是一个“工厂”，而 <code>create-app</code> 是这个“工厂”生产出的“标准产品”。</li>
<li>直接基于这个代码库开始构建你的应用，会异常困难，你需要手动处理极其复杂的项目配置、依赖管理和构建流程，这几乎是一条不归路。</li>
</ul>
<h3 id="结论与建议">结论与建议</h3>
<p><strong>对于希望部署自己平台的公司，正确的启动步骤是：</strong></p>
<ol>
<li><strong>使用脚手架创建</strong>：在你的开发机器上，运行 <code>npx @backstage/create-app</code>。按照提示输入应用名称（如 <code>company-dev-portal</code>）。</li>
<li><strong>获取专属代码库</strong>：命令完成后，你会得到一个名为 <code>company-dev-portal</code> 的文件夹。<strong>这就是你公司专属的 Backstage 平台的源代码</strong>。你应该立即将它推送到你公司的内部 Git 仓库（如 GitLab, Gitee, 内部GitLab）中进行版本管理。</li>
<li><strong>本地运行与探索</strong>：进入该目录，运行 <code>yarn install</code> 和 <code>yarn dev</code>，即可在本地启动一个基础版的门户。通过访问 <code>http://localhost:3000</code> 来熟悉它。</li>
<li><strong>开始定制化</strong>：基于这个生成的项目，你可以：
<ul>
<li>修改 <code>app-config.yaml</code> 配置文件（设置后端地址、数据库、认证等）。</li>
<li>在 <code>/packages/app</code> 下定制前端界面（如主题、Logo）。</li>
<li>通过 <code>yarn backstage-cli plugin add</code> 添加新的社区插件。</li>
<li>创建自己的软件模板和编写技术文档。</li>
</ul>
</li>
</ol>
<p><strong>简单来说：<code>npx @backstage/create-app</code> 是“购买一套精装修房的毛坯房”，你只需要在此基础上进行个性化装修。而从 GitHub 下载源码是“买下整块地和水泥钢筋，从打地基开始自己盖楼”。</strong> 对于绝大多数团队，前者是唯一明智的选择。</p>
<h1 id="源码用来开发npx-backstagecreate-app产品用来部署">源码用来开发，npx @backstage/create-app产品用来部署</h1>
<p>你的理解完全正确！<strong>是第二种情况</strong>。这是一个非常重要的概念区分，很多新手都会在这里产生混淆。</p>
<p>让我来清晰地解释一下：</p>
<h3 id="核心比喻">核心比喻</h3>
<ul>
<li><strong><code>npx @backstage/create-app</code></strong>：就像是<strong>平台团队</strong>购买并搭建好一台“服务器”和“网站框架”。</li>
<li><strong>部署后的 Backstage 平台</strong>：就是运行在那台服务器上的<strong>公司内部网站</strong>，比如叫 <code>dev-portal.company.com</code>。</li>
<li><strong>其他开发者</strong>：是<strong>这个内部网站的“用户”</strong>，他们通过浏览器访问这个网站来使用各种服务，<strong>完全不需要自己运行 <code>create-app</code></strong>。</li>
</ul>
<h3 id="详细分工">详细分工</h3>
<p><strong>1. 平台团队的工作（一次性的）</strong></p>
<ul>
<li>使用 <code>npx @backstage/create-app</code> <strong>创建唯一的一个 Backstage 应用项目</strong>（例如 <code>company-backstage</code>）。</li>
<li>对这个项目进行定制化配置（设置公司认证、连接内部Git仓库、配置数据库、设计主题等）。</li>
<li>将这个项目构建、部署到公司的服务器或Kubernetes集群上，使其成为一个<strong>长期运行、可供所有人访问的Web服务</strong>。</li>
</ul>
<p><strong>2. 普通开发者的工作（日常的）</strong></p>
<ul>
<li><strong>访问平台</strong>：在浏览器中打开公司部署好的 Backstage 门户地址（如 <code>https://internal-dev-portal.com</code>）。</li>
<li><strong>注册/发现项目</strong>：在平台的“软件目录”中，为自己负责的微服务或应用<strong>注册一个实体</strong>。这通常是通过在项目的代码仓库根目录添加一个 <code>catalog-info.yaml</code> 文件来实现的。平台会扫描这个文件，将项目信息展示在目录中。</li>
<li><strong>使用模板创建新项目</strong>：当需要新建一个微服务时，不是手动复制项目，而是去 Backstage 的 <strong>“模板”</strong> 页面，选择一个预设好的模板（如“Spring Boot 微服务模板”）。点击一下，填写项目名等参数，平台就会自动在GitLab/GitHub上创建一个结构规范、配置齐全的新项目仓库。</li>
<li><strong>查看文档与运维信息</strong>：在平台上找到自己的服务页面，查看相关文档、CI/CD状态、Kubernetes部署情况、监控链接等。</li>
</ul>
<h3 id="插件">插件</h3>
<ul>
<li>插件安装 yarn workspace backend add</li>
<li>github登录 @backstage/plugin-auth-backend-module-github-provider</li>
<li>/api/signals @backstage/plugin-signals-backend</li>
</ul>
<h3 id="工作流程图示">工作流程图示</h3>
<pre><code>平台工程师：
[执行 npx @backstage/create-app] --&gt; [得到一个代码项目: my-company-portal] --&gt; [定制、部署] --&gt; [一个运行中的网站: https://portal.example.com]

应用开发者A：
[浏览器访问 https://portal.example.com] --&gt; [使用模板创建"订单服务"] --&gt; [平台自动生成 Git 仓库 /order-service]
应用开发者B：
[浏览器访问 https://portal.example.com] --&gt; [在目录中搜索并查看"用户服务"] --&gt; [查看其CI状态和文档]
</code></pre>
<h3 id="总结">总结</h3>
<ul>
<li><strong><code>npx @backstage/create-app</code> 是一个“构建平台”的命令</strong>，由<strong>平台团队</strong>执行<strong>一次</strong>，用于生成你们公司专属的 Backstage 门户的源代码。</li>
<li><strong>部署后的 Backstage 是一个“使用平台”的Web界面</strong>，由<strong>全体开发者</strong>日常访问，用于<strong>管理他们自己的业务项目</strong>（注册、创建、查看）。</li>
</ul>
<p>所以，绝对不要要求每个开发者在开发新功能时都去运行 <code>create-app</code>。他们只需要使用你们已经部署好的那个统一的 Backstage 门户。</p>
<h1 id="backstage产品项目目录">backstage产品项目目录</h1>
<ul>
<li>app-config.yaml：应用配置文件(docs/conf/defining.md)</li>
<li>catalog-info.yaml：组件元数据描述文件(docs/features/software-catalog/descriptor-format.md)</li>
<li>packages/app：前端应用代码</li>
<li>packages/backend：后端服务代码</li>
</ul>


</div>
<div id="MySignature" role="contentinfo">
    <p></p>
<div class="navgood">
<p>作者：仓储大叔，张占岭，<br>
荣誉：微软MVP<br>QQ：853066980</p>

<p><strong>支付宝扫一扫，为大叔打赏!</strong>
<br><img src="https://images.cnblogs.com/cnblogs_com/lori/237884/o_IMG_7144.JPG"></p>
</div><br><br>
来源：https://www.cnblogs.com/lori/p/19863329
頁: [1]
查看完整版本: backstage~开始一个backstage应用