> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 最佳实践

> 企业在大规模场景下组织蓝图、管理 secrets、监控构建、固定版本和迁移的最佳实践。

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

<div id="organizing-blueprints-across-tiers">
  ## 跨层级组织蓝图
</div>

企业管理员最常问的问题是：“这个配置应该放在哪里？”

答案很简单：**默认放到企业蓝图中。** 企业蓝图适合放置所有适用于 (或可能适用于) 全部组织的内容。这包括语言运行时、安全工具、企业证书、内部 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 配置就应该放在该团队的组织蓝图中，而不是企业蓝图中。

如果某项内容适用于所有组织，就放到企业层级。 如果它是仓库级的，就放到仓库蓝图中。 组织层级只用于处理这两者之间的例外情况。

<Warning>
  不要把仓库级命令 (例如 `npm install`) 放到企业蓝图或组织蓝图中。 这些层级是在主目录中运行，而不是在仓库目录中运行，因此仓库级命令会失败，或者
  安装到错误的位置。
</Warning>

<div id="use-knowledge-items-at-the-right-tier">
  ### 在合适的层级使用 Knowledge 条目
</div>

Knowledge 条目会在各个层级中叠加生效，Devin 可以看到全部内容。可据此分层提供指导：

* **Enterprise knowledge**：适用于整个公司的编码标准、安全审查要求和内部文档链接。
* **Org knowledge**：团队规范、共享库的使用方式，以及团队特有的部署步骤。
* **Repo knowledge**：特定项目的 lint、测试和构建命令。

<div id="secrets-management-at-scale">
  ## 大规模 Secrets 管理
</div>

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

<div id="where-to-define-secrets">
  ### 在何处定义 secrets
</div>

| Secret scope     | 用途               | 示例                                                      |
| ---------------- | ---------------- | ------------------------------------------------------- |
| **Enterprise**   | 在所有 orgs 之间共享的凭据 | 内部 registry 令牌、corporate 代理认证、内部服务共用的 API key           |
| **Organization** | Team 专用凭据        | Team deployment 密钥、Team 服务的 API 令牌、Team 专用的 registry 认证 |
| **Repository**   | 仓库级凭据            | 各项目的 API key、项目专用的 service account                      |

**将 secrets 放在适用的最高层级。** 如果每个 org 都需要访问内部 npm registry，只需将该令牌定义一次为 enterprise secret。不要在 50 个 org 配置中重复定义。

<div id="secret-hygiene">
  ### secrets 使用规范
</div>

* **绝不要将 secrets 写入 YAML。** 始终使用 secrets 管理界面。写在 YAML 中的 secrets 最终会出现在日志、构建产物和审计记录中。
* **定期轮换 secrets。** 当你在界面中轮换某个 secret 时，新值会在下一次构建时生效。无需修改 blueprint。
* **使用描述性名称。** `INTERNAL_NPM_TOKEN` 比 `TOKEN_1` 更好。其他管理员 (以及未来的你) 需要清楚每个 secret 的用途。
* **审查 secret 的使用情况。** 定期检查现有哪些 secrets，以及它们是否仍然需要。删除未使用的 secrets，以减少攻击面。

<Info>
  如果组织级 secret 和企业级 secret 同名，则组织级 secret 优先。仓库级 secrets 覆盖组织级 secrets 也是如此。请有意识地利用这一点。例如，某个组织可能会用团队专用的令牌覆盖企业级 registry 令牌，而该令牌具有不同的权限。
</Info>

<div id="build-health-monitoring">
  ## 构建健康监测
</div>

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

<div id="establish-a-review-cadence">
  ### 建立定期审查机制
</div>

每周检查所有组织的构建健康状况。重点关注：

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

<div id="respond-to-enterprise-blueprint-failures">
  ### 应对企业蓝图故障
</div>

如果企业蓝图变更导致大范围故障：

1. **评估影响范围。** 在 Rollout 页面查看有多少组织受到影响。
2. **回退企业蓝图** 到上一个已知正常的蓝图，并立即保存。这会在所有受影响的组织中触发重建。
3. **隔离排查。** 在再次全面推出之前，先在单个试点组织中测试你的更改。

调试时，不要让有问题的企业蓝图继续生效。它每多故障一分钟，就会有更多组织遭遇构建失败。

<div id="partial-builds-are-a-signal">
  ### 部分构建是一种信号
</div>

部分构建表示一个组织中的某些仓库构建成功，而另一些则失败了。通常是由以下原因造成的：

* 仓库级依赖问题 (如锁文件损坏、软件包被移除)
* 缺少仅某个项目所需的系统库
* 过时的 blueprint，尚未更新以匹配仓库变更

部分构建仍会为成功的仓库生成可用的快照。但你应排查失败原因；如果忽视，它们往往会不断累积。

<div id="when-to-pin-builds">
  ## 何时固定构建
</div>

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

<div id="good-reasons-to-pin">
  ### 适合固定 build 的情形
</div>

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

<div id="bad-reasons-to-pin">
  ### 不应锁定的错误理由
</div>

* **为了逃避修复。** 如果某个构建坏了，就去修复 blueprint。锁定只会掩盖问题，而且由于锁定不会自动失效，被遗忘的锁定可能会让你长期运行在陈旧的环境上。
* **“以防万一。”** 自动更新会让依赖保持最新，并尽早发现问题。没有任何明确理由就把它关闭，只会把问题往后拖。

<Warning>
  你只能锁定 **7 天内** 的构建。锁定后，它会一直保持生效，直到被手动移除。它不会过期。被遗忘的锁定意味着你的团队运行的将是越来越陈旧的
  快照。
</Warning>

<div id="migrating-your-enterprise">
  ## 迁移企业
</div>

有关推荐的分阶段迁移 playbook (从初始测试到全面上线) ，请参阅[迁移企业](/zh/enterprise/environment-management/rollout#recommended-migration-playbook)。

<div id="common-architectural-patterns">
  ## 常见架构模式
</div>

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

<div id="monorepo-organizations">
  ### 单仓库组织
</div>

**设置**：一个组织使用单个大型代码仓库来承载多个项目。

**方法**：**企业蓝图**负责处理所有共享工具 (运行时、全局 CLI 工具、注册表) 。将项目特定的设置 (如在前端目录中运行 `npm install`，在后端目录中运行 `uv sync`) 放在 **仓库蓝图** 中。只有当该组织有不应应用于其他组织的工具或配置时，才需要组织蓝图。

使用带有 subshells 的单个蓝图来处理多个项目：

```yaml theme={null}
# 单体仓库的 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 .
```

<div id="multi-repo-organizations">
  ### 多仓库组织
</div>

**设置**：适用于包含多个相关代码仓库的组织 (例如微服务团队) 。

**方法**：将共享工具和 registry 配置放在**组织蓝图**中。每个仓库都有自己的蓝图，只保留 `maintenance` 和 `knowledge`。这样可以避免在各个仓库中重复编写设置命令。

<div id="shared-infrastructure-org">
  ### 共享基础架构组织
</div>

**设置**：指一个平台或 DevOps 组织，为其他团队提供共享服务。

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

<div id="isolated-project-orgs">
  ### 相互隔离的项目组织
</div>

**设置**：彼此独立的团队，除基础工具外不共享其他工具。

**方法**：**企业蓝图**仍负责通用基础：包括你所有的标准语言运行时、安全工具和企业基础架构。每个组织只在自己的蓝图中放入该团队确实独有、且不应与其他团队共享的工具或配置。Repo 蓝图负责各项目的设置。

<Info>
  拿不准时，就放到企业蓝图里。如果某个组织有明确理由排除某项内容 (例如工具版本冲突或访问受限) ，可以在组织级别进行覆盖。维护一套全面的企业基线环境，比在多个组织蓝图中重复配置更容易。
</Info>