[Solo SaaS]{class="badge positive" title="Solo se aplica a los proyectos de Adobe Commerce as a Cloud Service y Adobe Commerce Optimizer (infraestructura de SaaS administrada por Adobe)."}

Ejecución de una migración masiva de datos

Esta guía es una referencia operativa paso a paso para ejecutar una migración de datos desde un PaaS de Adobe Commerce o una instalación local a Adobe Commerce as a Cloud Service mediante la herramienta de migración de datos en masa. Los valores de configuración reales y los detalles específicos del entorno varían según la configuración.

Antes de empezar, confirme que ha completado todos los elementos de la lista de comprobación de preparación para clientes y que ha verificado el acceso a la API con la guía de acceso al servicio de migración.

Requisitos previos

Configuración del paquete de herramientas

Configure el entorno para la migración masiva de datos:

Archivos de configuración de ejemplo

Los archivos .example.env y .my.cnf.example de la raíz del repositorio son el punto de partida de la configuración. Copie cada archivo en su nombre de trabajo y rellene los valores necesarios.

Configuración del archivo de entorno

El archivo .env en la raíz del proyecto es la configuración de migración y extracción. Controla la canalización de CLI, incluidas las direcciones URL de origen y destino, OAuth, la conexión CDMS remota, la autenticación SaaS e IMS y otros conmutadores.

Edite el archivo .env y establezca al menos los siguientes valores correctamente. Para obtener la lista completa de variables admitidas, consulte las anotaciones en línea de .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>

Configurar credenciales de OAuth de origen

Estos cuatro valores firman solicitudes desde la herramienta de migración a las API del almacén de origen. Para obtenerlas, abra el origen Admin y vaya a Sistema > Extensiones > Integraciones. Cree o abra una integración y copie los valores en .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>

Establezca el token CLI de nube

Alinear configuración de administración de Commerce

Antes de la migración, asegúrese de que las siguientes configuraciones sean coherentes entre el origen y el destino.

Configuración de las credenciales de SaaS e IMS de Target

Estas son las configuraciones de IMS y API de Adobe Commerce as a Cloud Service para el destino. Necesita el ID de inquilino, el ID de organización, las credenciales de servidor a servidor de IMS OAuth y el host de IMS correcto para su entorno. Coordine con su equipo de Adobe el acceso a la organización, al inquilino y al perfil. No intente inferir ni estimar valores sensibles.

Generar credenciales de IMS

Usar Adobe Developer Console. Necesita acceso de Developer o Admin en la organización de Adobe para crear proyectos. Un inicio de sesión básico de usuario no es suficiente para agregar API.

El extremo del token de IMS (ADOBE_IMS_URL) debe coincidir con el entorno de la credencial.

ADOBE_IMS_META_SCOPES debe coincidir con los ámbitos proporcionados en esa credencial. El archivo .example.env incluye la cadena de ámbito separada por comas completa como referencia. Cámbielo únicamente si Adobe le indica que lo haga.

Asignar credenciales de Adobe I/O al archivo de entorno

En Developer Console, los valores de servidor a servidor de OAuth se presentan como un ID de cliente y un secreto de cliente, correspondientes a la siguiente estructura JSON:

{
  "client_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Asignarlos a .env (marcadores de posición de ejemplo):

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

Los hosts de la API de SaaS difieren entre la preproducción y la producción. TARGET_INSTANCE_REST_URL y TARGET_INSTANCE_GRAPHQL_URL deben usar el mismo entorno de API de Commerce que la migración, ya sea de preproducción o de producción. No mezcle un nivel con el CDMS o inquilino del otro nivel.

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

Para los hosts SaaS de producción, reemplace na1-sandbox por na1 en ambas direcciones URL TARGET_INSTANCE_*. Utilice el(la) ADOBE_IMS_URL coincidente para ese nivel, como se muestra en la tabla anterior.

Establezca el punto final de CDMS

Dirija la herramienta de migración al host de la API de CDMS que coincida con el entorno al que está migrando. Establezca CDMS_HOST (y normalmente CDMS_PORT=443) en .env. Utilice un host, ya sea de preproducción o de producción, no ambos.

Establezca o quite los comentarios del bloque que coincida con la ejecución:

# 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

Configuración del código de tienda

STORE_CODE es el código de vista de tienda que usa la herramienta de migración para las llamadas a la API de REST de instancia de origen, la creación de clientes de prueba sintética y la limpieza de datos. También se envía como encabezado x-store-code durante la fase de carga.

STORE_CODE toma como valor predeterminado default en .example.env. Compruebe que coincida con el código de vista de tienda predeterminado de la instancia de origen. Para comprobarlo, en el origen Admin vaya a Tiendas > Todas las tiendas y observe la columna Código para ver la vista de la tienda que se debe usar. Si el código que se muestra allí no es default, actualice STORE_CODE en .env para que coincida.

Configurar el archivo de conexión a base de datos

El archivo .my.cnf proporciona la configuración de conexión MySQL para la extracción de la herramienta de migración. Créelo copiando .my.cnf.example a .my.cnf en la raíz del proyecto. El nombre de sección debe coincidir con SOURCE_CONNECTION_NAME en .env.

Para una fuente local o autoalojada:

[<connection-name>]
user=<db_user>
password='<db_password>'
host=<db_host>
port=3306
database=<db_name>

Para un origen de Adobe Commerce on Cloud:

[<connection-name>]
id=<project_id>:<environment>

El campo id= indica a la herramienta que el origen es PaaS y la configuración del túnel de déclencheur mediante MAGENTO_CLOUD_CLI_TOKEN. Los valores project_id y environment están disponibles en Cloud Console o mediante los comandos magento-cloud project:list y magento-cloud environment:list.

Preparar la red y las instancias

La autenticación básica de HTTP delante de la tienda puede bloquear el tráfico de API y herramientas. Asegúrese de que esté desactivado para la URL de origen utilizada por la migración o que las rutas de la herramienta estén permitidas, de modo que las solicitudes REST y GraphQL puedan llegar a la tienda.

Mantener estabilidad de base de datos de origen durante la extracción

Mientras la herramienta extrae datos de la base de datos de origen, ningún otro proceso debe escribirle. Las escrituras concurrentes pueden generar una instantánea incoherente.

Target

Si es necesario borrar el catálogo de destino antes de la migración, elimine los productos de Admin en lotes pequeños, por ejemplo, de 200 a la vez, para evitar conflictos de catálogo duplicados y tiempos de espera de eliminación en lotes.

Cree y ejecute la migración

Trabaje desde el directorio del proyecto extraído con acceso de escritura.

Mantener la sesión activa a través de SSH

Si se conecta a través de SSH, una red perdida puede acabar con su shell e interrumpir una migración prolongada. El comando GNU screen mantiene la sesión activa en el servidor:

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"

También puede usar tmux si está disponible en el servidor.

Crear la imagen de Docker

Genere la imagen Docker utilizada por bin/console, que contiene PHP, CLI y dependencias. Ejecute esto antes de la primera ejecución o después de que Dockerfile o la imagen base cambien.

./bin/console build

Inicio de los servicios de backup

Inicie los servicios de copia de seguridad de Docker Compose para la herramienta, como la base de datos de prueba local y, cuando esté habilitada en .env, los servicios locales opcionales. Los servicios exactos dependen de la configuración. Ejecute esto después de una compilación correcta y antes de los comandos shell, migration o phase.

./bin/console start

Inicialice el contenedor CLI

Inicie el contenedor CLI una vez para que el punto de entrada pueda finalizar la instalación, como una instalación de Composer si es necesario, en el proyecto montado. Ejecute esto una vez antes de la primera ejecución de la migración en un entorno nuevo.

./bin/console shell
exit

Ejecute la migración

La herramienta admite dos métodos de migración. Elija el que se adapte a su caso de uso.

Migración en una sola fase

No se requiere ningún modo de mantenimiento en la instancia de origen. Ejecute la canalización de migración completa con un solo comando:

./bin/console migration

El comando ejecuta todos los pasos de la canalización automáticamente, de extremo a extremo, en el siguiente orden.

Utilice esta opción cuando no se requiera ninguna ventana de mantenimiento, lo que es típico para ejecuciones en seco de extremo a extremo, entornos de desarrollo o de zona protegida, o cualquier migración en la que el origen pueda permanecer activo durante la extracción.

Migración multifase con modo de mantenimiento

Se requiere el modo de mantenimiento en la instancia de origen para garantizar la coherencia de los datos durante la extracción. La migración se divide en distintas fases que debe ejecutar en orden.

Fase 1: antes del mantenimiento (el origen está activo)

Ejecute mientras la instancia de origen está activa y acepta tráfico. El acceso de REST y GraphQL al origen debe estar totalmente disponible. No activar el modo de mantenimiento antes de que finalice esta fase.

Vuelva a la raíz del servidor y ejecute:

./bin/console migration:before-maintenance

Fase 2 — Habilitar modo de mantenimiento (manual)

Habilite el modo de mantenimiento en el origen y ponga en pausa todas las actividades que escriben en la base de datos o que afectan a ella, incluidos los trabajos programados, las integraciones de terceros, el procesamiento de pedidos y la sincronización de recursos de medios.

En el servidor Commerce de origen (raíz de instalación), ejecute:

bin/magento maintenance:enable

Fase 3: durante el mantenimiento (el origen está congelado)

Ejecutar con la instancia de origen en modo de mantenimiento. La fuente debe permanecer congelada durante toda esta fase. No desactive el modo de mantenimiento hasta que la Fase 3 se complete correctamente.

./bin/console migration:during-maintenance

Fase 4: deshabilitar el modo de mantenimiento (manual, condicional)

Esta fase desactiva el modo de mantenimiento y vuelve a habilitar el tráfico en la instancia de origen. Este paso es necesario antes de ejecutar la fase de limpieza, ya que la limpieza se comunica con el origen a través de REST y falla con HTTP 503 si el modo de mantenimiento aún está activo.

En el servidor Commerce de origen, ejecute:

bin/magento maintenance:disable

Fase 5 — Limpieza (opcional, el origen debe estar activo)

Elimine los clientes de prueba sintética y los pedidos creados en Phase 1 de la instancia de origen mediante REST. Esta fase solo se puede ejecutar después de desactivar el modo de mantenimiento.

Vuelva a la raíz del servidor y ejecute:

./bin/console migration:cleanup

Reanudar o volver a ejecutar una migración

La herramienta de migración realiza un seguimiento del progreso mediante un archivo de .migration_id en la raíz del proyecto. Este archivo se crea automáticamente cuando se inicia una nueva migración y registra el identificador de migración actual.

Reanudar tras un error

Si una ejecución de migración falla o se interrumpe, vuelva a ejecutar el mismo comando para reanudarlo desde el último paso correcto (extracción, carga o verificación) en lugar de reiniciar desde cero. Los pasos ya completados se omiten automáticamente.

Iniciar una nueva migración

Para descartar una ejecución anterior e iniciar una migración completamente nueva, elimine el archivo .migration_id antes de iniciar la siguiente migración:

rm .migration_id

Si .migration_id existe y la migración anterior ya se ha completado, la herramienta imprime un mensaje que indica que la migración ya ha finalizado y le recomienda que elimine el archivo.

Revisar registros y depurar

Todos los registros de migración se escriben en el directorio logs/ de la raíz del proyecto y se organizan en subdirectorios con marca de tiempo:

logs/
  2026-03-23_14-30-00/     ← one directory per run
    index.log              ← main pipeline log (start here)
    ...