插件的结构与运维 — 别让门户死掉

一句话总结

Backstage 通过前端、后端两类插件扩展；新的 new backend system 大幅简化安装。生产中真正困难的是认证、身份同步、目录处理周期和数据库，而非炫目的功能。

为什么需要它

门户不会“安装即结束”。系统越多，越要解决：登录者对应哪个 User、属于哪个 Group；仓库多久重读一次；哪些状态存在哪里。身份错会让“我的服务”为空，更新过密触发 API rate limit，过慢使用户失去信任；目录与 Scaffolder 历史都在数据库中。

工作原理

	前端插件	后端插件
形态	React component	Node.js module
功能	route、tab、card、widget	HTTP endpoint、processor、provider、Scaffolder action
credential	不应存在	保存在这里

旧后端需手工连接 router、传依赖；new backend system 只需注册 plugin 和 module，logger、config、database、auth、scheduler 等由依赖注入提供，安装缩为“添加 package + 一行注册”，扩展点也更明确。

认证与身份同步

authentication 是通过 GitHub、Google、Okta、Microsoft、OIDC 登录；sign-in resolver 决定它映射到哪个 Catalog User，可按 email、username 匹配。还需从 GitHub Org、LDAP、Microsoft Entra 定期采集 User/Group，spec.owner: group:team-checkout 才能连接到真实人员。Group 缺失会形成断裂关系，“我的服务”为空后用户不会再来。所有权图未填充前，宁可不要公开门户。

Kubernetes 插件连接方式

Catalog entity 添加 annotation backstage.io/kubernetes-id: <값>，cluster workload 添加同值 label backstage.io/kubernetes-id: <값>。后端按 label selector 查询已注册集群，把结果返回前端。方向不能反：entity 用 annotation，workload 用 label。也可用 backstage.io/kubernetes-namespace 按 Namespace 查找。cluster credential 只留在后端。

运营：处理周期与数据库

entity provider 发现并写入原始实体；processor 验证、计算关系、生成派生实体。周期越短越新鲜，但 SCM API 调用越多；大规模常用 Webhook/event 即时更新，周期扫描作为较长兜底。

开发可用内存 SQLite，但重启会全部消失；生产通常使用 PostgreSQL，保存 Catalog、Scaffolder 历史和搜索索引，因此门户并非无状态，需要备份恢复。Backstage 和自有源码树还需小步定期升级，长期拖延会使一次性升级成本激增。

现场表现

homelab 用 CloudNativePG 运行双实例 PostgreSQL 18 流复制，若部署门户，这会成为目录数据库。但 etcd 即使三节点有 quorum，controlPlaneEndpoint 指向首节点物理 IP 时，该节点故障仍会让数据存活却无法访问 API：数据可用性与访问可用性不同。

数据库复制不代表门户应用能启动；门户存活也不代表 processor 正常，后者会让信息静默过时，往往比显眼故障更危险。KubeVirt 曾显示 AllComponentsReady 却无法启动 VM，同理门户 health 可为绿而 processor 失败，所以必须监控处理成功率和最后更新时间。

下一测验

请再次检查之前练习中 entity 的 backstage.io/kubernetes-id annotation 与 workload label 的配对，以理解插件实际所做工作。