跨层级组织蓝图
使用组织蓝图而不是企业蓝图的唯一原因，就是你明确不希望某项内容应用到每个组织。 例如，如果某个团队使用的是其他团队不应有权限访问的私有 npm registry，那么这个 registry 配置就应该放在该团队的组织蓝图中，而不是企业蓝图中。
如果某项内容适用于所有组织，就放到企业层级。 如果它是仓库级的，就放到仓库蓝图中。 组织层级只用于处理这两者之间的例外情况。
在合适的层级使用 Knowledge 条目
- Enterprise knowledge：适用于整个公司的编码标准、安全审查要求和内部文档链接。
- Org knowledge：团队规范、共享库的使用方式，以及团队特有的部署步骤。
- Repo knowledge：特定项目的 lint、测试和构建命令。
大规模 Secrets 管理
在何处定义 secrets
将 secrets 放在适用的最高层级。 如果每个 org 都需要访问内部 npm registry，只需将该令牌定义一次为 enterprise secret。不要在 50 个 org 配置中重复定义。
secrets 使用规范
- 绝不要将 secrets 写入 YAML。 始终使用 secrets 管理界面。写在 YAML 中的 secrets 最终会出现在日志、构建产物和审计记录中。
- 定期轮换 secrets。 当你在界面中轮换某个 secret 时，新值会在下一次构建时生效。无需修改 blueprint。
- 使用描述性名称。
INTERNAL_NPM_TOKEN比TOKEN_1更好。其他管理员 (以及未来的你) 需要清楚每个 secret 的用途。 - 审查 secret 的使用情况。 定期检查现有哪些 secrets，以及它们是否仍然需要。删除未使用的 secrets，以减少攻击面。
如果组织级 secret 和企业级 secret 同名，则组织级 secret 优先。仓库级 secrets 覆盖组织级 secrets 也是如此。请有意识地利用这一点。例如，某个组织可能会用团队专用的令牌覆盖企业级 registry 令牌，而该令牌具有不同的权限。
构建健康监测
建立定期审查机制
- 构建失败：企业级或组织蓝图中的严重故障，会阻塞所有仓库。
- 部分构建：部分仓库构建失败。这通常表明存在依赖项问题或蓝图已过时。
- 过旧构建：某些组织的最新构建时间异常久远，这可能表示构建队列已卡住。
应对企业蓝图故障
- 评估影响范围。 在 Rollout 页面查看有多少组织受到影响。
- 回退企业蓝图 到上一个已知正常的蓝图，并立即保存。这会在所有受影响的组织中触发重建。
- 隔离排查。 在再次全面推出之前，先在单个试点组织中测试你的更改。
部分构建是一种信号
- 仓库级依赖问题 (如锁文件损坏、软件包被移除)
- 缺少仅某个项目所需的系统库
- 过时的 blueprint，尚未更新以匹配仓库变更
何时固定构建
适合固定 build 的情形
- 关键发布进行中。 在接下来 48 小时的发布期间，你需要一个稳定且已验证可用的环境。
- 正在积极调试。 你正在排查 build 问题，不希望自动更新在过程中悄悄改变环境。
- 回滚。 新 build 引入了回归问题，因此你需要立即回退，同时修复 blueprint。
不应锁定的错误理由
- 为了逃避修复。 如果某个构建坏了，就去修复 blueprint。锁定只会掩盖问题，而且由于锁定不会自动失效，被遗忘的锁定可能会让你长期运行在陈旧的环境上。
- “以防万一。” 自动更新会让依赖保持最新，并尽早发现问题。没有任何明确理由就把它关闭，只会把问题往后拖。
迁移企业
常见架构模式
单仓库组织
npm install，在后端目录中运行 uv sync) 放在 仓库蓝图 中。只有当该组织有不应应用于其他组织的工具或配置时，才需要组织蓝图。
使用带有 subshells 的单个蓝图来处理多个项目：
多仓库组织
maintenance 和 knowledge。这样可以避免在各个仓库中重复编写设置命令。
设置：指一个平台或 DevOps 组织，为其他团队提供共享服务。
方法：企业蓝图负责覆盖通用基础部分。共享基础架构组织的蓝图会安装其代码仓库所需的平台专用工具 (Terraform、kubectl、云 CLI) 。其他组织不会配备这些工具；它们只会获得企业蓝图中的内容，以及各自组织的配置。
相互隔离的项目组织
拿不准时，就放到企业蓝图里。如果某个组织有明确理由排除某项内容 (例如工具版本冲突或访问受限) ，可以在组织级别进行覆盖。维护一套全面的企业基线环境，比在多个组织蓝图中重复配置更容易。