跳转到主要内容
在企业范围内运行 Devin，意味着需要为数十个组织和数百个代码仓库管理环境。本页介绍适用于大规模场景的有效做法，以及需要避免的常见错误。

​
跨层级组织蓝图

企业管理员最常问的问题是：“这个配置应该放在哪里？” 答案很简单：默认放到企业蓝图中。 企业蓝图适合放置所有适用于 (或可能适用于) 全部组织的内容。这包括语言运行时、安全工具、企业证书、内部 CLI、代理配置以及共享 registry 认证。即使并非每个组织都会用到其中的所有内容，在这里安装多种语言和工具也完全没问题。
Blueprint tier何时使用示例
Enterprise所有共享配置的默认放置位置Python 3.12、Node 20、Go 1.22、Rust、安全扫描器、企业 CA 证书、内部 CLI、代理配置、共享 registry 令牌
Organization仅当某项内容不应适用于每个组织时使用团队专用的 private registry、仅限特定团队使用的工具、组织专属的 lint 配置
Repository在仓库目录中运行的单仓库设置npm install、uv sync、项目专用的 Knowledge items、仓库级 .envrc 文件
使用组织蓝图而不是企业蓝图的唯一原因，就是你明确不希望某项内容应用到每个组织。 例如，如果某个团队使用的是其他团队不应有权限访问的私有 npm registry，那么这个 registry 配置就应该放在该团队的组织蓝图中，而不是企业蓝图中。 如果某项内容适用于所有组织，就放到企业层级。 如果它是仓库级的，就放到仓库蓝图中。 组织层级只用于处理这两者之间的例外情况。
不要把仓库级命令 (例如 npm install) 放到企业蓝图或组织蓝图中。 这些层级是在主目录中运行，而不是在仓库目录中运行，因此仓库级命令会失败，或者 安装到错误的位置。

​
在合适的层级使用 Knowledge 条目

Knowledge 条目会在各个层级中叠加生效，Devin 可以看到全部内容。可据此分层提供指导：
  • Enterprise knowledge：适用于整个公司的编码标准、安全审查要求和内部文档链接。
  • Org knowledge：团队规范、共享库的使用方式，以及团队特有的部署步骤。
  • Repo knowledge：特定项目的 lint、测试和构建命令。

​
大规模 Secrets 管理

Secrets 按照与蓝图相同的层级结构逐层继承，其中更具体的 secrets 优先。

​
在何处定义 secrets

Secret scope用途示例
Enterprise在所有 orgs 之间共享的凭据内部 registry 令牌、corporate 代理认证、内部服务共用的 API key
OrganizationTeam 专用凭据Team deployment 密钥、Team 服务的 API 令牌、Team 专用的 registry 认证
Repository仓库级凭据各项目的 API key、项目专用的 service account
将 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 令牌，而该令牌具有不同的权限。

​
构建健康监测

在企业级环境中，构建失败在所难免。关键是尽早发现并快速解决。

​
建立定期审查机制

每周检查所有组织的构建健康状况。重点关注：
  • 构建失败：企业级或组织蓝图中的严重故障，会阻塞所有仓库。
  • 部分构建：部分仓库构建失败。这通常表明存在依赖项问题或蓝图已过时。
  • 过旧构建：某些组织的最新构建时间异常久远，这可能表示构建队列已卡住。

​
应对企业蓝图故障

如果企业蓝图变更导致大范围故障：
  1. 评估影响范围。 在 Rollout 页面查看有多少组织受到影响。
  2. 回退企业蓝图 到上一个已知正常的蓝图，并立即保存。这会在所有受影响的组织中触发重建。
  3. 隔离排查。 在再次全面推出之前，先在单个试点组织中测试你的更改。
调试时，不要让有问题的企业蓝图继续生效。它每多故障一分钟，就会有更多组织遭遇构建失败。

​
部分构建是一种信号

部分构建表示一个组织中的某些仓库构建成功，而另一些则失败了。通常是由以下原因造成的：
  • 仓库级依赖问题 (如锁文件损坏、软件包被移除)
  • 缺少仅某个项目所需的系统库
  • 过时的 blueprint，尚未更新以匹配仓库变更
部分构建仍会为成功的仓库生成可用的快照。但你应排查失败原因；如果忽视，它们往往会不断累积。

​
何时固定构建

固定构建会将 org 的环境锁定到特定快照。请谨慎使用。

​
适合固定 build 的情形

  • 关键发布进行中。 在接下来 48 小时的发布期间，你需要一个稳定且已验证可用的环境。
  • 正在积极调试。 你正在排查 build 问题，不希望自动更新在过程中悄悄改变环境。
  • 回滚。 新 build 引入了回归问题，因此你需要立即回退，同时修复 blueprint。

​
不应锁定的错误理由

  • 为了逃避修复。 如果某个构建坏了，就去修复 blueprint。锁定只会掩盖问题，而且由于锁定不会自动失效，被遗忘的锁定可能会让你长期运行在陈旧的环境上。
  • “以防万一。” 自动更新会让依赖保持最新，并尽早发现问题。没有任何明确理由就把它关闭，只会把问题往后拖。
你只能锁定 7 天内 的构建。锁定后，它会一直保持生效，直到被手动移除。它不会过期。被遗忘的锁定意味着你的团队运行的将是越来越陈旧的 快照。

​
迁移企业

有关推荐的分阶段迁移 playbook (从初始测试到全面上线) ，请参阅迁移企业。

​
常见架构模式

不同的企业结构适合采用不同的蓝图方案。

​
单仓库组织

设置：一个组织使用单个大型代码仓库来承载多个项目。 方法：企业蓝图负责处理所有共享工具 (运行时、全局 CLI 工具、注册表) 。将项目特定的设置 (如在前端目录中运行 npm install，在后端目录中运行 uv sync) 放在 仓库蓝图 中。只有当该组织有不应应用于其他组织的工具或配置时，才需要组织蓝图。 
# 单体仓库的 Repo blueprint
maintenance:
  - name: "Frontend dependencies"
    run: (cd frontend && npm install)

  - name: "Backend dependencies"
    run: (cd backend && uv sync)

knowledge:
  - name: lint
    contents: |
      Frontend: cd frontend && npm run lint
      Backend: cd backend && uv run ruff check .

​
多仓库组织

设置：适用于包含多个相关代码仓库的组织 (例如微服务团队) 。 方法：将共享工具和 registry 配置放在组织蓝图中。每个仓库都有自己的蓝图，只保留 maintenance 和 knowledge。这样可以避免在各个仓库中重复编写设置命令。

​
共享基础架构组织

设置：指一个平台或 DevOps 组织，为其他团队提供共享服务。 方法：企业蓝图负责覆盖通用基础部分。共享基础架构组织的蓝图会安装其代码仓库所需的平台专用工具 (Terraform、kubectl、云 CLI) 。其他组织不会配备这些工具；它们只会获得企业蓝图中的内容，以及各自组织的配置。

​
相互隔离的项目组织

设置：彼此独立的团队，除基础工具外不共享其他工具。 方法：企业蓝图仍负责通用基础：包括你所有的标准语言运行时、安全工具和企业基础架构。每个组织只在自己的蓝图中放入该团队确实独有、且不应与其他团队共享的工具或配置。Repo 蓝图负责各项目的设置。
拿不准时，就放到企业蓝图里。如果某个组织有明确理由排除某项内容 (例如工具版本冲突或访问受限) ，可以在组织级别进行覆盖。维护一套全面的企业基线环境，比在多个组织蓝图中重复配置更容易。