运行批量数据迁移
本指南是一个分步操作参考，介绍了如何使用批量数据迁移工具将数据从Adobe Commerce PaaS或内部部署安装迁移到Adobe Commerce as a Cloud Service。 实际配置值和特定于环境的详细信息因您的设置而异。
在开始之前，请确认您已完成客户准备工作清单中的每个项目，并通过迁移服务访问指南验证API访问。
先决条件
- 必须在运行迁移的计算机上安装 Docker 和Docker Compose。
- 运行迁移的用户必须具有执行
docker和docker compose（或旧版docker-compose）命令的权限。 在Linux，用户必须属于docker组。 在macOS和Windows上，Docker Desktop必须运行并可访问。 迁移CLI重复调用Docker，此处出现的权限错误会阻止运行。 - 在运行迁移之前，源系统和目标系统之间的核心配置必须一致。 此工具不会迁移核心配置数据，例如存储设置和系统配置。 请在目标系统上单独设置它，并在迁移之前使其与源系统保持一致。
设置工具包
设置批量数据迁移的环境：
-
提取
ccsaas-migration-tools.tar.gz的内容。 -
从提取的
ccsaas-migration-tools文件夹运行所有命令，其中bin/console位于该文件夹中。 -
确保该文件夹对于日志、缓存、Composer和生成的文件是可写的。
将该目录下所有文件和子文件夹的所有权更改给运行迁移的操作系统用户，以便该工具可以一致地读取和写入。 例如，在Linux上：
chown -R <user>:<group> <project-root>。 -
通过复制示例文件（
.example.env到.env和.my.cnf.example到.my.cnf）在项目根中创建.env和.my.cnf文件，然后填写以下部分中描述的值。
示例配置文件
存储库根目录中的.example.env和.my.cnf.example文件是配置的起点。 将每个文件复制到其工作名称并填充所需的值。
.example.env.env.my.cnf中设置id=时MAGENTO_CLOUD_CLI_TOKEN）。 .env文件中提供了完整的变量列表。.my.cnf.example.my.cnfid=project:environment)引用[section]布局。 [section]名称必须与.env中的SOURCE_CONNECTION_NAME匹配。 针对PaaS的字段包括user、password、host、port、database和id=。配置环境文件
项目根目录中的.env文件是迁移和提取配置。 它驱动CLI管道，包括源和目标URL、OAuth、远程CDMS连接、SaaS和IMS身份验证以及其他开关。
https://example.com而不是https://example.com/。编辑.env文件并正确设置至少以下值。 有关支持的变量的完整列表，请参阅.example.env中的内联注释。
SOURCE_INSTANCE_URL=https://<source-host>
SOURCE_INSTANCE_GRAPHQL_URL=https://<source-host>/graphql
SOURCE_INSTANCE_REST_URL=https://<source-host>/rest
SOURCE_INSTANCE_CONSUMER_KEY=<consumer_key>
SOURCE_INSTANCE_CONSUMER_SECRET=<consumer_secret>
SOURCE_INSTANCE_ACCESS_TOKEN=<access_token>
SOURCE_INSTANCE_ACCESS_TOKEN_SECRET=<access_token_secret>
配置源OAuth凭据
这四个值表示从迁移工具到源存储API的请求。 若要获取它们，请打开源Admin，然后转到系统 > 扩展 > 集成。 创建或打开集成，然后将值复制到.env：
SOURCE_INSTANCE_CONSUMER_KEY=<consumer_key>
SOURCE_INSTANCE_CONSUMER_SECRET=<consumer_secret>
SOURCE_INSTANCE_ACCESS_TOKEN=<access_token>
SOURCE_INSTANCE_ACCESS_TOKEN_SECRET=<access_token_secret>
设置云CLI令牌
.my.cnf中检测源类型。 如果SOURCE_CONNECTION_NAME节包含id=行（例如，id=project:production），则源是Adobe Commerce on Cloud，需要MAGENTO_CLOUD_CLI_TOKEN。 对于没有id=的内部部署源，不需要此令牌，并跳过通道设置。-
转到
https://accounts.magento.cloud并登录。 -
单击您的配置文件图像，然后选择帐户设置。
-
转到 API令牌 部分。
-
选择创建API令牌，为其提供描述性名称，并复制生成的令牌。
-
在
.env中设置令牌：code language-text MAGENTO_CLOUD_CLI_TOKEN=<your_magento_cloud_api_token>
调整Commerce管理设置
在迁移之前，请确保源和目标之间的以下设置一致。
配置目标SaaS和IMS凭据
这些是目标的Adobe Commerce as a Cloud Service IMS和API设置。 您需要环境的租户ID、组织ID、IMS OAuth服务器到服务器凭据以及正确的IMS主机。 与您的Adobe团队协调以访问组织、租户和配置文件。 请勿尝试推断或估计敏感值。
生成IMS凭据
使用Adobe Developer Console。 您需要Adobe组织上的Developer或Admin访问权限才能创建项目。 基本用户登录不足以添加API。
-
创建一个项目或打开一个现有项目，然后选择Add API。
-
选择 Adobe Commerce as a Cloud Service 并继续。
-
选择 OAuth服务器到服务器 作为身份验证类型并继续。
-
选择您的Adobe团队希望此租户使用的产品配置文件，然后选择保存配置的API。
-
在项目侧边栏中，打开OAuth服务器到服务器（或凭据），然后将客户端ID和客户端密钥作为
ADOBE_IMS_CLIENT_ID和ADOBE_IMS_CLIENT_SECRET复制到.env中。
IMS令牌终结点(ADOBE_IMS_URL)必须与凭据的环境匹配。
ADOBE_IMS_URLhttps://ims-na1-stg1.adobelogin.comhttps://ims-na1.adobelogin.comna1表示配置目标实例的区域。 如果您的实例配置在不同的区域，请将其替换为相应的区域标识符。ADOBE_IMS_META_SCOPES必须匹配在该凭据上设置的作用域。 .example.env文件包含完整的逗号分隔范围字符串作为引用。 仅当Adobe指示您进行更改时，才应更改此设置。
将Adobe I/O凭据映射到环境文件
在Developer Console中，OAuth服务器到服务器值显示为客户端ID和客户端密钥，对应于以下JSON结构：
{
"client_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxx",
"client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
将它们映射到.env（占位符示例）：
TARGET_ORG_ID=<org_id>@AdobeOrg
ADOBE_IMS_URL=https://ims-na1.adobelogin.com
ADOBE_IMS_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxx
ADOBE_IMS_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxx
ADOBE_IMS_META_SCOPES=AdobeID,openid,additional_info.projectedProductContext
SaaS API主机在生产前和生产中有所不同。 TARGET_INSTANCE_REST_URL和TARGET_INSTANCE_GRAPHQL_URL必须使用与迁移相同的Commerce API环境，即预生产环境或生产环境。 不要将一个层与另一层的CDMS或租户混合。
TARGET_INSTANCE_*_URL中的典型主机https://na1-sandbox.api.commerce.adobe.com/{tenantId}https://na1.api.commerce.adobe.com/{tenantId}na1表示配置目标实例的区域。 如果您的实例配置在不同的区域，请将其替换为相应的区域标识符。TARGET_TENANT_ID=<tenant_id>
TARGET_ORG_ID=<org_id>@AdobeOrg
ADOBE_IMS_URL=https://ims-na1.adobelogin.com
ADOBE_IMS_CLIENT_ID=<client_id>
ADOBE_IMS_CLIENT_SECRET=<client_secret>
ADOBE_IMS_META_SCOPES=AdobeID,openid,additional_info.projectedProductContext
TARGET_INSTANCE_REST_URL=https://na1-sandbox.api.commerce.adobe.com/{tenantId}
TARGET_INSTANCE_GRAPHQL_URL=https://na1-sandbox.api.commerce.adobe.com/{tenantId}/graphql
对于生产SaaS主机，请将TARGET_INSTANCE_* URL中的na1-sandbox替换为na1。 对该层使用匹配的ADOBE_IMS_URL，如上表所示。
设置CDMS端点
将迁移工具指向与要迁移到的环境匹配的CDMS API主机。 在.env中设置CDMS_HOST（通常为CDMS_PORT=443）。 使用一台主机（预生产或生产），而不是同时使用两者。
CDMS_HOSThttps://commerce-data-migration-service-preprod-external.adobe.iohttps://commerce-data-migration-service-prod-external.adobe.io设置或取消注释与运行匹配的块：
# Pre-production CDMS
CDMS_HOST=https://commerce-data-migration-service-preprod-external.adobe.io
CDMS_PORT=443
# Production CDMS (use for prod cutover only)
# CDMS_HOST=https://na1.api.commerce.adobe.com
# CDMS_PORT=443
设置商店代码
STORE_CODE是迁移工具用于源实例REST API调用、综合测试客户创建和数据清理的存储视图代码。 在加载阶段还会作为x-store-code标头发送。
STORE_CODE在.example.env中默认为default。 验证它是否与源实例的默认存储视图代码匹配。 若要查看，请在源Admin中转到商店 > 所有商店，然后查看 代码 列以了解应使用的商店视图。 如果显示的代码没有default，请更新.env中的STORE_CODE以匹配。
配置数据库连接文件
.my.cnf文件为迁移工具的提取端提供MySQL连接设置。 通过将.my.cnf.example复制到项目根目录中的.my.cnf来创建它。 分区名称必须与.env中的SOURCE_CONNECTION_NAME匹配。
对于内部部署或自托管源：
[<connection-name>]
user=<db_user>
password='<db_password>'
host=<db_host>
port=3306
database=<db_name>
对于Adobe Commerce on Cloud源：
[<connection-name>]
id=<project_id>:<environment>
id=字段告知工具源是PaaS，并使用MAGENTO_CLOUD_CLI_TOKEN触发通道设置。 project_id和environment值在Cloud Console中或通过magento-cloud project:list和magento-cloud environment:list命令提供。
准备网络和实例
商店前面的HTTP基本身份验证可以阻止API和工具流量。 请确保为迁移使用的源URL禁用了该设置，或者允许该工具的路径，以便REST和GraphQL请求可以到达存储区。
在提取期间维护源数据库的稳定性
虽然该工具会从源数据库提取数据，但其他进程都不应写入源数据库。 并发写入可能会导致快照不一致。
- 停止源上的cron，以及运行
bin/magento或其他写入程序的任何操作系统计划程序（对于提取窗口），或确保它们在提取期间无法运行。 - 查看其他集成，例如ERP、OMS、PIM、自定义作业和写入同一数据库的第三方API。 暂停或阻止对提取窗口的写入，以便在提取运行时没有任何内容会更改表。
- 这补充了维护模式和通道或数据库访问。 它们一起减少了店面和API流量。 Cron和集成是单独的写入源，您必须显式控制这些写入源。
目标
如果必须在迁移之前清除目标目录，请以小批量（例如一次删除200个）删除Admin中的产品，以避免重复目录冲突和批量删除超时。
构建并运行迁移
从具有写入权限的提取项目目录工作。
通过SSH使会话保持活动状态
如果通过SSH进行连接，则断开的网络可能会终止外壳并中断长时间的迁移。 GNU screen命令使会话在服务器上保持活动状态：
screen -S migration # new session named "migration"
# run ./bin/console commands here; when you want to disconnect without stopping work:
# press Ctrl+A, release, then press d # detach
screen -ls # list sessions
screen -x migration # reattach to "migration"
如果服务器上有tmux，您也可以使用该服务器。
构建Docker图像
生成bin/console使用的Docker映像，其中包含PHP、CLI和依赖项。 在首次运行之前，或在Dockerfile或基本映像更改之后运行它。
./bin/console build
启动后备服务
启动该工具的Docker Compose支持服务，例如本地测试数据库，在.env中启用时，启动可选的本地服务。 确切的服务取决于您的配置。 在成功构建之后并在shell、迁移或分阶段命令之前运行此命令。
./bin/console start
初始化CLI容器
启动一次CLI容器，以便入口点可以针对已装载的项目完成安装，例如根据需要完成Composer安装。 首次在新的环境中运行迁移之前，请运行一次。
./bin/console shell
exit
运行迁移
该工具支持两种迁移方法。 选择适合您的用例的库。
单相迁移
源实例上不需要维护模式。 使用单个命令运行完整的迁移管道：
./bin/console migration
该命令按照以下顺序自动运行所有管道步骤（从头到尾）。
- 配置检查 — 验证环境变量和工具设置。
- 环境初始化 — 启动Docker服务，打开云隧道（如果适用），并运行单元测试。
- 集成测试和CDMS初始化 — 运行集成测试并初始化CDMS API连接。
- 创建迁移 — 向CDMS注册迁移并等待目标架构分析。 迁移ID已保存到
.migration_id。 - 功能测试和测试数据生成 — 运行功能测试并在源上生成综合测试数据以进行完整性验证（如果已启用）。
- 数据提取 — 从源实例提取数据。
- 加载到目标 — 将提取的数据加载到目标Adobe Commerce as a Cloud Service实例。 源上的暂存视图会被清除，源测试数据会通过REST与负载并行删除。
- 数据完整性验证 — 触发校验和验证并运行本地API验证测试。 结果将被记录，并且失败不会停止管道。
- 目标上的测试数据清理 — 从目标实例中删除合成测试数据。
- 处理结果 — 生成迁移摘要并可以选择从存储中下载项目。
当不需要维护窗口时（典型情况是端到端练习、开发或沙盒环境，或任何在提取期间源可以保持活动状态的迁移），可使用此选项。
具有维护模式的多阶段迁移
源实例上需要维护模式，以确保提取期间的数据一致性。 迁移将拆分为不同的阶段，您必须按顺序运行这些阶段。
./bin/console命令从迁移工具项目根目录运行。 bin/magento maintenance:*命令在源Adobe Commerce应用程序服务器上运行，通过SSH到安装根或通过Admin。 该工具不代表您发出Magento个维护命令。migration:before-maintenancemigration:during-maintenancemigration:cleanup （可选）阶段1 — 维护之前（源已上线）
在源实例处于活动状态并接受流量时运行。 必须完全提供REST和GraphQL对源的访问权限。 在此阶段完成之前不要启用维护模式。
返回到服务器根目录并运行：
./bin/console migration:before-maintenance
- 配置检查 — 验证环境变量和工具设置。
- 环境初始化 — 启动Docker服务，打开PaaS云隧道（如果适用）并运行单元测试。
- 集成测试和CDMS初始化 — 运行集成测试并初始化CDMS API连接。
- 创建迁移 — 向CDMS注册迁移并等待目标架构分析。 迁移ID已保存到
.migration_id。 - 功能测试 — 针对实时源运行功能测试。
- 测试数据生成 — 在源上创建综合测试客户和订单以进行完整性验证（如果已启用）。
阶段2 — 启用维护模式（手动）
在源系统上启用维护模式并暂停所有写入或影响数据库的活动，包括计划作业、第三方集成、订单处理和媒体资产同步。
在源Commerce服务器（安装根目录）上，运行：
bin/magento maintenance:enable
阶段3 — 维护期间（源已冻结）
在维护模式下使用源实例运行。 在此阶段的整个过程中，源必须保持冻结。 在 阶段3 成功完成之前，请勿禁用维护模式。
./bin/console migration:during-maintenance
- 云隧道设置 — 对于Adobe Commerce on Cloud源实例，重新打开云隧道并验证数据库连接。 已自动跳过本地实例。
- 数据提取 — 从冻结的源实例提取数据。
- 临时视图清理 — 使用直接数据库连接（在维护模式下安全）从源中删除临时视图。
- 加载到目标 — 将提取的数据加载到目标Adobe Commerce as a Cloud Service实例并等待完成。
- 数据完整性验证 — 触发CDMS校验和验证并运行本地API验证测试。 结果将被记录，并且失败不会停止管道。
- 目标上的测试数据清理 — 从目标实例中删除合成测试数据。
- 处理结果 — 生成迁移摘要并可以选择从存储中下载项目。
阶段4 — 禁用维护模式（手动，有条件）
此阶段将禁用维护模式，并重新启用到源实例的流量。 运行清理阶段之前需要执行此步骤，因为清理通过REST与源进行通信，如果维护模式仍处于活动状态，则清理将失败并显示HTTP 503。
在源Commerce服务器上，运行：
bin/magento maintenance:disable
阶段5 — 清理（可选，源必须处于活动状态）
通过REST从源实例中删除在 阶段1 中创建的合成测试客户和订单。 此阶段只能在禁用维护模式后运行。
SKIP_TEST_DATA_CREATION=true在.env中设置，则跳过此阶段，因为未创建测试数据。返回到服务器根目录并运行：
./bin/console migration:cleanup
- 数据库连接设置 — 对于Adobe Commerce on Cloud源实例，重新打开云隧道。 对于内部部署实例，建立并验证直接数据库连接。
- Source REST清理 — 通过REST API从源中删除合成测试客户和订单。
恢复或重新运行迁移
迁移工具使用项目根目录中的.migration_id文件跟踪进度。 此文件会在新迁移开始时自动创建，并记录当前的迁移标识符。
失败后恢复
如果迁移运行失败或中断，请重新运行同一命令以从上一个成功步骤（提取、加载或验证）中恢复，而不是从头开始重新启动。 已完成的步骤会自动跳过。
migration:during-maintenance阶段时，源必须始终处于维护模式。 如果源已退出维护或在运行之间更改了数据，则继续迁移可能会产生不一致的结果。开始新的迁移
要放弃上一次运行并开始全新的迁移，请在开始下一次迁移之前删除.migration_id文件：
rm .migration_id
如果.migration_id存在并且上一次迁移已经完成，则工具会打印一条消息，说明迁移已经完成，建议您删除该文件。
查看日志并调试
所有迁移日志将写入项目根目录中的logs/目录，并组织为带时间戳的子目录：
logs/
2026-03-23_14-30-00/ ← one directory per run
index.log ← main pipeline log (start here)
...
index.log是主管道业务流程日志。 如果某个步骤失败，则会显示使用非零代码退出的脚本以及原因。- 每个步骤的日志，如
09b_run_load.log和11_verify_data_integrity_local.log，包含每个阶段的详细输出。