> ## 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.

# 迁移你的企业

> 在整个企业范围内逐步推行声明式环境配置：包括 rollout 状态、按 org 覆盖、分阶段迁移 playbook 和监控。

将企业从传统的环境设置迁移到声明式配置，是一项重大变更。Rollout 页面为企业管理员提供了对这一迁移过程的细粒度控制。你可以先为少数试点 org 启用蓝图，按自己的节奏逐步扩大范围，并在出现问题时立即回滚。

<div id="enterprise-rollout-states">
  ## 企业 rollout 状态
</div>

Rollout 页面提供了一个 **Rollout 模式** 选择器，用于控制蓝图向各组织开放的方式。共有三种模式，外加声明式环境启用前的一个初始状态：

| 状态       | 含义                      | 对组织的影响                                                                             |
| -------- | ----------------------- | ---------------------------------------------------------------------------------- |
| **未启用**  | 企业尚未启用声明式环境             | 所有组织都看不到环境页面。所有组织均使用经典设置。请联系你的 Cognition 管理员启用。                                    |
| **测试中**  | 只有手动启用的组织会使用声明式环境       | Enterprise Admin 可在 Rollout 页面中逐个为组织启用。其他所有组织将继续使用经典设置，且看不到任何变化。                   |
| **可用**   | 组织 Admin 会看到迁移提示，并可自行切换 | 使用经典设置的组织 Admin 会在其 Machine Configuration 页面看到迁移提示。他们无需 Enterprise Admin 干预即可自助迁移。 |
| **默认启用** | 新组织默认启用声明式环境            | 所有新组织都会默认使用蓝图。原先使用经典设置且拥有代码仓库的现有组织，将自动获得经典覆盖。                                      |

推进顺序为：**测试中 → 可用 → 默认启用**。你可以使用 Rollout 模式下拉菜单，在 **测试中** 和 **可用** 之间自由切换。不过，**默认启用** 是永久性操作，如无 Cognition 管理员协助则无法撤销。

<Warning>
  **默认启用是永久性的。** 启用此模式后，如不联系你的 Cognition 管理员，将无法恢复为“测试中”或“可用”。请确保你的企业蓝图已得到充分验证，并且大多数组织都已使用蓝图后，再启用此模式。
</Warning>

<div id="testing-mode-details">
  ### 测试模式详情
</div>

在“测试模式”下，尚未选择启用的组织会继续使用传统设置，使用体验不会发生任何变化。企业管理员可以在 Rollout 页面为单个组织启用该功能。只有这些组织会切换到声明式配置。这是在企业首次激活声明式环境时的基线模式。

<div id="available-mode-details">
  ### 可用模式详情
</div>

可用模式会添加迁移提示：仍在使用传统设置的组织管理员会在其 Machine Configuration 页面看到提示信息，鼓励他们迁移到声明式配置。这不会改变他们当前的设置，也不会让他们获得完整环境配置页面的访问权限。它只是让他们知道蓝图现已可用，并提供自助启用路径。这有助于提高认知，并让组织管理员按照自己的节奏进行迁移。

<div id="per-org-overrides">
  ## 按组织覆盖
</div>

Enterprise admins 可以直接在 Rollout 页面的按组织表格中为单个组织覆盖发布状态：

* **在 Testing 或 Available 模式下**：让特定组织 **启用** 蓝图。这些组织会立即从经典设置切换为声明式配置。
* **在 Enabled by default 模式下**：让特定组织 **退出** 蓝图，恢复为经典设置。这些组织会继续使用其经典配置。

覆盖设置是持久的，不会因模式变化而丢失。如果你在 Testing 模式期间为某个组织启用了蓝图，那么当你切换到 Available 或 Enabled by default 时，它仍会保持启用蓝图。

<div id="automatic-classic-overrides">
  ### 自动经典模式覆盖
</div>

当启用 **默认启用** 时，系统会通过一项保护机制避免造成干扰：任何当前使用经典设置**且已配置仓库**的 org，都会自动获得一条显式的经典模式覆盖规则。这意味着，此次切换不会改变那些仍在实际使用经典设置的 org 的状态。它们会保持现状，直到你明确对其进行迁移。

没有仓库的 org (或已经使用蓝图的 org) 不受这项保护机制影响。

<div id="recommended-migration-playbook">
  ## 推荐的迁移 playbook
</div>

最佳做法是在向组织管理员开放之前，先在隔离环境中完成配置并进行验证。不要一次性大规模迁移。先在可控范围内开展，验证无误后再逐步扩大范围。

<div id="phase-1-build-and-verify-in-isolation-testing">
  ### 第 1 阶段：在隔离环境中构建并验证 (测试)
</div>

首先让企业处于 **测试** 模式。各组织不能自行选择启用，因此你可以完全掌控。

1. 为企业**启用声明式环境**。你的 Cognition 管理员会启用此功能，从而使企业进入测试模式。
2. **创建一个专用测试组织**，用于测试环境配置。该组织仅用于验证你的蓝图。
3. 仅为该测试组织**启用声明式配置** (通过 Rollout 页面上的按组织覆盖) 。
4. **配置企业蓝图**：安装所有共享的语言运行时、安全工具、企业证书、内部 CLI、代理设置和 registry 身份验证。这是每个组织都会继承的基础层。
5. 为测试组织**配置组织蓝图**，加入任何组织级工具或 registry 配置。
6. 为一组有代表性的代码仓库**添加代码仓库蓝图**。选择能覆盖你最常见技术栈的代码仓库。
7. **进行端到端验证**：在这些代码仓库上启动 Devin 会话，并确认一切正常。代码仓库应能成功克隆，依赖应能正确安装，lint/test/build 命令应能正常运行，且所有工具都处于预期版本。

<Tip>
  不要只检查构建是否成功。构建通过并不总是意味着环境可用。缺少 PATH 条目、工具版本错误或缺失 registry 身份验证等问题，都可能被忽略。务必通过
  运行一次真实的 Devin 会话来验证。
</Tip>

<div id="phase-2-enable-opt-in-for-org-admins-available">
  ### 阶段 2：让 org 管理员可自行启用 (可用)
</div>

一旦你确认 enterprise → org → repo 蓝图栈能够正确组合并生成可用环境：

1. **在内部沟通**，告知 org 管理员声明式配置现已可用，并已准备就绪。
2. **切换到可用模式**：将 Rollout mode 下拉菜单从 Testing 更改为 Available。使用经典设置方式的 org 管理员现在会看到鼓励他们迁移的提示。
3. **org 管理员现在可以迁移**各自的组织。由于 enterprise 蓝图已提供基础层 (运行时、工具、证书、制品仓库) ，org 管理员只需配置其团队和 repo 特有的内容。

每位 org 管理员都可以使用 **迁移助手** 轻松完成此操作。Devin 可以检查该组织现有的快照，并自动生成等效的蓝图配置。有关详细步骤，请参阅[迁移到声明式配置](/zh/onboard-devin/environment/migration)。

为你最常见的技术栈 (Node.js、Python、Java、Go、多语言 monorepo) 建立一个模板蓝图库，并在内部共享，这样 org 管理员就不必从零开始。[模板库](/zh/onboard-devin/environment/templates) 是一个很好的基础。

<div id="phase-3-expand-and-clean-up-enabled-by-default">
  ### 第 3 阶段：扩展并清理 (默认启用)
</div>

1. 当大多数组织都已切换到蓝图后，**启用“默认启用”**。这是一项永久性操作——此前使用带有 repo 的经典设置的组织会自动获得经典覆盖，因此对它们不会有任何影响。
2. 在此之后**新创建的组织**将默认启用蓝图。
3. **监控 Rollout 页面**，查看所有组织的构建健康状况。按“Classic”筛选即可查看哪些组织尚未迁移。
4. **与其余组织管理员协作**，迁移剩余未完成的组织。迁移助手可让这一过程变得非常直接。
5. 当所有组织都已在蓝图上完成验证后，**移除经典覆盖**。

<Info>
  经典配置始终会被保留。组织切换到蓝图时不会删除任何内容。如果出现问题，企业管理员可以使用按组织的覆盖从
  Rollout 页面将任何组织切换回经典设置。
</Info>

<div id="accelerated-migration-strategy">
  ### 加速迁移策略
</div>

对于希望快速推进的企业，下面是一种尽量降低各组织迁移负担的方法：

1. **从测试模式开始** (这样每个组织都可以单独选择加入) 。
2. **先配置企业蓝图。** 让 Admin 在企业蓝图中配置共享运行时、工具、证书和注册表设置。这是所有组织都会继承的基础层。
3. **切换到 Available 模式。** 这会启用迁移提示，因此组织 Admin 会在其 Machine Configuration 页面上看到相关提示，并可自助完成迁移。
4. **通过现有的内部渠道广泛传播文档** (Slack、电子邮件、wiki) ，并鼓励组织 Admin 自行选择加入。迁移助手让组织 Admin 可以自助完成这一过程。
5. **对当前已配置 0 个仓库的组织自动启用。** 这些组织没有任何内容需要迁移——将它们切换到蓝图没有风险，因为它们没有需要保留的现有经典设置。
6. **逐步迁移其余组织，一次一个。** 由于企业蓝图已配置完成，每个组织迁移只需在其基础上添加组织级和仓库级配置。这比从头开始迁移简单得多。
7. **当大多数组织完成迁移后，启用“默认开启”。** 此后新创建的组织将默认启用蓝图。

这种方法将企业蓝图配置 (也就是收益最大的工作) 前置完成，然后让各个组织以最小的工作量按自己的节奏迁移。

<div id="rolling-back">
  ## 回滚
</div>

事情并不总能一帆风顺。发布系统在各个层级都支持回滚。

<div id="per-org-rollback">
  ### 按组织回滚
</div>

Enterprise 管理员可以在 Rollout 页面将任意单个组织切换回经典设置：

* 该组织会**立即恢复**为使用其经典设置快照。
* 经典配置会被**保留**。组织切换到蓝图时不会丢失任何内容，因此切换回去是安全的。
* 活跃会话不受影响。更改会在下一个会话生效。

<div id="mode-rollback">
  ### 模式回滚
</div>

Enterprise 管理员可以使用 rollout 模式下拉菜单，在 **Testing** 和 **Available** 之间自由切换。如果你想在排查问题期间暂停自助迁移，这会很有帮助。

<Warning>
  企业管理员**无法从 Enabled by default 回退**。如果你需要从 Enabled by default 回退，请联系你的 Cognition 管理员。你仍然可以随时使用按组织设置的覆盖，将单个组织切换回经典设置。
</Warning>

<Info>
  回滚不会删除蓝图或经典配置。无论当前启用的是哪种模式，两者都会被保留，因此你可以在 Testing 和 Available 之间来回切换而不会丢失已有工作成果。
</Info>

<div id="monitoring-rollout-health">
  ## 监控发布运行状况
</div>

Rollout 页面提供了一个仪表板，用于跟踪整个企业范围内的迁移进度。

<div id="kpi-row">
  ### KPI 行
</div>

在页面顶部，汇总指标可帮助你快速了解发布进度：

* **Blueprint 组织**：当前使用 Blueprint 的组织数量
* **Rollout 百分比**：使用 Blueprint 的组织占组织总数的比例
* **构建健康状况**：所有 Blueprint 组织的构建状态汇总

<div id="per-org-table">
  ### 各组织表格
</div>

在 KPI 下方，详细表格会显示每个组织的信息：

| 列                   | 说明                        |
| ------------------- | ------------------------- |
| **Organization**    | 组织名称                      |
| **State**           | 当前模式：Blueprints 或 Classic |
| **Override**        | 该组织的状态是否为显式覆盖，而不是采用企业默认值  |
| **Classic repos**   | 使用 Classic 设置配置的 repo 数量  |
| **Blueprint repos** | 使用 Blueprints 的 repo 数量   |
| **Latest build**    | 最近一次构建的状态 (成功、部分成功、失败等)   |

<div id="filtering">
  ### 筛选
</div>

可按以下条件筛选表格：

* **全部**：企业中的所有组织
* **Blueprints**：当前使用蓝图的组织
* **Classic**：当前使用经典配置的组织
* **Overrides**：具有显式状态覆盖的组织 (包括任一方向的覆盖)

<div id="concurrency-safety">
  ## 并发安全
</div>

状态转换机制可防止同时发生的更改。如果你加载页面后到提交更改前的这段时间内，另一位管理员更改了企业状态，该请求会因冲突错误而被拒绝。

这可防止多位企业管理员同时操作时意外覆盖彼此的更改。如果你的更改被拒绝，请刷新页面查看当前状态，并在确认仍适用后重新提交。

<div id="audit-logging">
  ## 审计日志记录
</div>

所有 rollout 状态变更都会记录在审计日志中：

* Enterprise 模式变更 (Testing → Available、启用“默认启用”等)
* 各 org 的覆盖设置变更 (org 选择加入、org 选择退出、移除覆盖)
* 由哪位 Admin 在何时进行了更改

这些日志可通过你所在 Enterprise 的标准审计日志界面查看。