TiDB X 实例的项目迁移常见问题

TiDB X 实例是面向服务的 TiDB Cloud 产品，基于 TiDB X architecture 构建，包括 TiDB Cloud Starter 和 TiDB Cloud Essential 实例。

本常见问题解答说明了为什么 TiDB Cloud console 会提示你将 TiDB Cloud Starter 和 Essential 实例移动到 TiDB X 项目中、迁移过程中会发生哪些变化，以及你需要执行哪些后续操作。

为什么 TiDB Cloud console 会提示我移动我的 TiDB Cloud Starter 和 Essential 实例？

在 2026 年 4 月 15 日之前，TiDB Cloud 使用单一的 TiDB dedicated project 类型来管理所有 TiDB Cloud 资源。此类项目可以同时包含 TiDB Cloud Dedicated 集群和 TiDB X 实例。然而，在一个项目中混合不同类型的资源会增加管理复杂性，原因如下：

• TiDB dedicated project 最初是为 TiDB Cloud Dedicated 集群设计的。
• TiDB X 实例和 TiDB Cloud Dedicated 集群具有不同的行为方式和管理模型。

从 2026 年 4 月 15 日起，TiDB Cloud 引入了独立的项目类型，以便在不同资源类型之间提供清晰的隔离。现在，每种项目类型都只承载其对应的资源类型：

• TiDB dedicated project：用于 TiDB Cloud Dedicated 集群
• TiDB X project：用于 TiDB X 实例
• TiDB X virtual project：用于未归入任何 TiDB X project 的 TiDB X 实例

TiDB X project 对 TiDB X 实例来说是轻量且可选的，而 dedicated project 对 TiDB Cloud Dedicated 集群来说是必需的。将这些资源分开可以确保更一致的用户体验，并消除关于哪些项目能力适用的困惑。

由于这种分离，dedicated project 将不再能够包含 TiDB X 实例。如果你的组织在 dedicated project 中已有 TiDB Cloud Starter 或 Essential 资源，TiDB Cloud 会提示你将它们移动到 TiDB X project 中，以符合新的资源模型。

TiDB Cloud 中有哪些可用的项目类型？

TiDB Cloud 为不同的资源类型和使用场景提供三种项目类型。

• TiDB dedicated project：此项目类型仅用于 TiDB Cloud Dedicated 集群。

  • 它帮助你按项目分别管理 TiDB Cloud Dedicated 集群的设置，例如 RBAC、网络、维护、告警订阅和加密访问。
  • 每个 TiDB Cloud Dedicated 集群都必须属于一个 dedicated project。
  • 由于基础设施绑定，TiDB Cloud Dedicated 集群不能在项目之间移动。

• TiDB X project：此项目类型仅用于 TiDB X 实例。

  • 它帮助你按项目管理 TiDB X 实例的 RBAC。
  • TiDB X project 是轻量且可选的，因此你可以在不将 TiDB X 实例分配到项目的情况下创建它们。
  • 当你希望组织和分组 TiDB X 实例时，项目会很有用，但并非必需。
  • 你可以在 TiDB X project 之间移动 TiDB X 实例，或将其移回组织级别。

• TiDB X virtual project：此项目是虚拟的，不提供任何管理能力。

  • 它充当不属于任何项目的 TiDB X 实例的逻辑容器，因此可以通过使用项目 ID 通过 TiDB Cloud API 访问这些实例。
  • 每个组织都有一个唯一的 virtual project ID。
  • 你可以通过 TiDB Cloud API 的 List all accessible projects 端点获取此 ID。

下表列出了这些项目类型之间的差异：

我需要移动我的 TiDB Cloud Starter 和 Essential 实例吗？

这取决于你当前项目的结构：

• 如果你的项目仅包含 TiDB Cloud Starter 和 Essential 实例，TiDB Cloud 会在 2026 年 4 月 15 日自动将该项目转换为 TiDB X project。无需进一步操作。
• 如果你的项目同时包含 TiDB Cloud Dedicated 集群以及 TiDB Cloud Starter 或 Essential 实例，TiDB Cloud console 会提示你点击顶部横幅中的 Move & Unlock，将 TiDB Cloud Starter 和 Essential 实例移动到新的 TiDB X project。

谁可以执行迁移？

只有具有 Organization Owner 角色的用户才能启动并完成迁移。

如果我的项目仅包含 TiDB Cloud Starter 和 Essential 实例，会发生什么？

仅包含 TiDB Cloud Starter 和 Essential 实例的项目会在 2026 年 4 月 15 日自动转换为 TiDB X project。

迁移后会发生的变化：

• 该项目会变为 TiDB X project。
• 新的 TiDB X project 不包含 dedicated project 设置，例如网络设置、CMEK 设置和维护配置。

迁移后不会发生变化的内容：

• 你现有的实例及其数据、可用性和性能。
• 你的计费和使用情况。
• 项目名称和项目 ID。

如果我的项目同时包含 TiDB Cloud Dedicated 集群以及 TiDB Cloud Starter 或 Essential 实例，会发生什么？

随着为不同 TiDB Cloud 资源引入独立的项目类型，dedicated project 将不再能够承载 TiDB X 实例。

如果一个项目同时包含 TiDB Cloud Dedicated 集群以及 TiDB Cloud Starter 或 Essential 实例，TiDB Cloud 会在顶部横幅中提示你将该项目中的 TiDB Cloud Starter 和 Essential 实例移动到新的 TiDB X project。

如果你是 Organization Owner，可以点击顶部横幅中的 Move & Unlock，并按照迁移向导完成迁移。

迁移向导会显示要移动的 TiDB Cloud Starter 和 Essential 实例列表，并允许你为新的 TiDB X project 指定一个新名称。

迁移后会发生的变化：

• TiDB Cloud Starter 和 Essential 实例会被移动到一个新创建的 TiDB X project 中。
• 迁移后，被移动的实例将属于一个新的项目 ID。
• 项目级 RBAC 权限会被复制到新项目中。

迁移后不会发生变化的内容：

• 你的实例数据。
• 你的实例可用性。
• 你的实例性能。
• 你的计费和使用情况。
• 你的实例的底层基础设施。
• TiDB Cloud Dedicated 集群会保留在当前项目中，不会被移动。

此迁移不会产生额外费用。

迁移后，你可以通过 TiDB X project（或在组织级别）管理你的 TiDB X 实例，并继续通过 dedicated project 管理你的 TiDB Cloud Dedicated 集群。

迁移后需要执行哪些操作？

如果你的 TiDB Cloud Starter 或 Essential 实例被移动到新的 TiDB X project，请检查任何依赖原始项目 ID 或原始项目级设置的内容，例如以下各项：

• 自动化或脚本
• 集成
• 基于项目的运维工作流
• 用户访问和 RBAC 分配
• Data Service 设置
• Data Apps
• Data Service API keys

项目级 RBAC 权限会被复制到新项目中，但迁移后你仍必须检查访问设置，以确保用户和工作流仍能按预期工作。

如果你使用 TiDB Cloud API 管理实例，请参阅 Project API Migration Guide for TiDB Cloud Starter and Essential 以更新你的 API 调用。

我可以在哪里获得帮助？

如果你不确定你的自动化、集成或 Data Service 设置是否依赖原始项目 ID，请在开始迁移之前通过 support@pingcap.com 联系 TiDB Cloud 支持团队。