1. 为什么需要开发者门户：wiki 死了，Slack 还在刷屏
微服务一多，知识就碎在 Confluence、Notion、README、Grafana、PagerDuty的夹缝里。 新人 onboarding 像寻宝游戏：找到仓库只是第一步，还要猜集群名、猜 dashboard 链接、猜谁是值班。 门户的价值不是“再做一个网站”，而是把高频路径固化为默认视图：从实体卡片一键跳到监控、流水线与 API 定义。
2. Backstage 是什么：应用壳 + 软件目录 + 插件宇宙
Backstage 是一个前端框架 + 后端插件运行时 + Catalog 服务的组合。 你得到可定制的信息架构（哪些实体、哪些关系），以及可插拔的集成面（Kubernetes、Argo CD、SonarQube 等通过插件呈现）。 与“纯文档站”不同，目录里的实体可与真实系统同步（通过处理器 processors 与 provider），减少“文档与生产不一致”的经典债务。
3. 软件目录实体：用图模型描述组织与技术资产
Backstage 采用实体（Entity）与关系（Relation）：常见有 Component（服务）、API、Resource（DB、队列）、 System（业务系统）、Domain（领域）、Group/User（组织与所有权）。 关键实践：在仓库根放置 catalog-info.yaml，用 Git 做声明式注册；CI 校验 schema，避免“随手改目录把图弄断”。
# catalog-info.yaml — minimal Component (English identifiers)
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payments-api
description: Payment orchestration service
annotations:
backstage.io/techdocs-ref: dir:.
spec:
type: service
lifecycle: production
owner: group:default/team-payments
providesApis:
- payments-public-api
dependsOn:
- resource:default/payments-db4. TechDocs 与 Scaffolder：文档跟代码走，模板一键生成
TechDocs 把文档构建进门户：Markdown 留在仓库，发布流水线生成静态站点，Backstage 内嵌展示——解决“文档永远落后发布两周”的痛点。 Software Templates（Scaffolder）把第 69 章的 Golden Path 按钮化：填表 → 调 actions → 创建仓库 / 注册目录 / 开 PR。 模板本身也要版本化与 code review，否则会变成影子平台。
5. 插件化模型：前端包 + 后端集成
典型插件同时包含UI 扩展与后端代理或数据拉取（避免浏览器直连敏感 API、也统一鉴权）。 选型时关注：维护活跃度、与公司身份体系（OIDC）的契合度、以及实体页面绑定（哪些 kind 显示哪些 widget）。 不要盲目堆插件——每个插件都是运维与升级面。
| Concern | Portal anti-pattern | Healthy pattern |
|---|---|---|
| Ownership | “大概归后端组吧” | explicit owner entity + escalation path |
| Docs | wiki duplicate of README | TechDocs single source in repo |
| Plugins | install 40 tabs nobody uses | curated set aligned to Golden Path |
| Security | shared admin password | OIDC + RBAC + audit on actions |
6. 治理集成：目录即策略的前端
当 lifecycle、owner、依赖关系结构化后，你可以把策略挂钩： 例如生产组件必须有 on-call、必须有 TechDocs、必须接入某类监控。门户从“展示”升级为合规仪表盘，与 OPA、服务评分卡（maturity model）联动。
7. 本章清单
- 理解 Backstage 三分结构：应用壳、软件目录、后端插件。
- 掌握核心实体与关系，能编写基础的 catalog-info.yaml。
- 区分 TechDocs 与 Scaffolder 在 Golden Path 中的角色。
- 能评估插件：价值、维护成本、安全边界（OIDC、RBAC）。
- 把 Discoverability 上升为治理：目录字段与合规要求对齐。
- 下一章：案例 1——从零搭建一条可信 CI 流水线，把前文原则收成可执行蓝图。