Actualizar la versión de Commerce

Puede actualizar el código base de Adobe Commerce a una versión más reciente. Antes de actualizar el proyecto, revise las Requisitos del sistema en el Instalación para conocer los requisitos de la versión de software más reciente.

Según la configuración del proyecto, las tareas de actualización pueden incluir las siguientes:

  • Actualice los servicios, como MariaDB (MySQL), OpenSearch, RabbitMQ y Redis, para comprobar la compatibilidad con las nuevas versiones de Adobe Commerce.
  • Convertir un archivo de administración de configuración anterior.
  • Actualice el .magento.app.yaml archivo con nueva configuración para vínculos y variables de entorno.
  • Actualice las extensiones de terceros a la última versión compatible.
  • Actualice el .gitignore archivo.
TIP
Antes de comenzar una actualización o un proceso de aplicación de parches, cree una rama activa desde el entorno de integración y extraiga la nueva rama a su estación de trabajo local. La dedicación de una rama al proceso de actualización o de revisión ayuda a evitar interferencias con el trabajo en curso.
TIP
Para proyectos Pro, debe enviar un ticket de asistencia de Adobe Commerce para instalar o actualizar servicios in Staging y Production solo entornos de.
Indique los cambios de servicio necesarios e incluya el actualizado .magento.app.yaml y services.yaml y especifique la versión de PHP en el ticket. Para ver los cambios de autoservicio en la versión, las extensiones o la configuración del entorno de PHP, consulte Configuración de PHP in Configuración de aplicación.
Para cambios en un live Entorno de producción (Solo Pro), debe proporcionar un aviso con un mínimo de 48 horas para permitir que el equipo de infraestructura de Cloud tenga tiempo suficiente para recopilar recursos y realizar una actualización segura.

Actualizar desde versiones anteriores

Si inicia una actualización desde una versión de Commerce anterior a la 2.1, algunas restricciones en la base de código de Adobe Commerce pueden afectar a su capacidad de actualizar a una versión específica de ECE-Tools o a actualización a la siguiente versión de Commerce admitida. Utilice la siguiente tabla para determinar la mejor ruta:

Versión actual
Ruta de actualización
2.1.3 y anteriores
Actualice Adobe Commerce a la versión 2.1.4 o posterior antes de continuar. A continuación, realice una actualización única para instalar ECE-Tools.
2.1.4 - 2.1.14
Actualizar ECE-Tools paquete.
Consulte las notas de la versión para 2.0.9. y versiones posteriores de 2002.0.x.
2.1.15 - 2.1.16
Actualizar ECE-Tools paquete.
Consulte las notas de la versión para2.0.9. y más tarde.
2.2.x y posterior
Actualizar ECE-Tools paquete.
Consulte las notas de la versión para2002.0.8 y más tarde.
NOTE
Si utiliza una versión de Adobe Commerce en una infraestructura en la nube que no contenga el ece-tools paquete, debe realizar una actualización única a su proyecto en la nube para eliminar los paquetes obsoletos. Si usa actualmente la variable ece-tools y debe actualizarlo, consulte la sección Actualizar el paquete ECE-Tools.

Administración de configuración

Las versiones anteriores de Adobe Commerce, como 2.1.4 o posterior a 2.2.x o posterior, utilizaban un config.local.php para la administración de la configuración. Adobe Commerce versión 2.2.0 y posteriores utilizan el config.php , que funciona exactamente igual que el archivo config.local.php , pero tiene diferentes ajustes de configuración que incluyen una lista de los módulos activados y opciones de configuración adicionales.

Al actualizar desde una versión anterior, debe migrar el config.local.php archivo para utilizar el más reciente config.php archivo. Siga estos pasos para realizar una copia de seguridad del archivo de configuración y crear uno.

Para crear un config.php archivo:

  1. Crear una copia de config.local.php y asígnele un nombre config.php.

  2. Añada este archivo al app/etc de su proyecto.

  3. Añada y confirme el archivo en su rama.

  4. Inserte el archivo en la rama de integración.

  5. Continúe con el proceso de actualización.

WARNING
Después de la actualización, puede quitar el config.php y generar un nuevo archivo completo. Solo puede eliminar este archivo para reemplazarlo esta vez. Después de generar un nuevo, complete config.php , no puede eliminar el archivo para generar uno nuevo. Consulte Administración de configuración e implementación de canalización.

Verificar las dependencias del compositor de Zend Framework

Al actualizar a 2.3.x o posterior desde 2.2.x, compruebe que las dependencias de Zend Framework se han agregado a autoload propiedad del composer.json para apoyar a Laminas. Este complemento admite nuevos requisitos para el marco Zend, que ha migrado al proyecto Laminas. Consulte Migración de Zend Framework al Proyecto Laminas en el Magento DevBlog.

Para comprobar la auto-load:psr-4 configuración:

  1. En la estación de trabajo local, cambie al directorio del proyecto.

  2. Consulte la rama de integración.

  3. Abra el composer.json en un editor de texto.

  4. Compruebe la autoload:psr-4 para la implementación de Zend plugin manager para la dependencia de controladores.

    code language-json
     "autoload": {
        "psr-4": {
           "Magento\\Framework\\": "lib/internal/Magento/Framework/",
           "Magento\\Setup\\": "setup/src/Magento/Setup/",
           "Magento\\": "app/code/Magento/",
           "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"
        },
    }
    
  5. Si falta la dependencia Zend, actualice el composer.json archivo:

    • Añada la línea siguiente a autoload:psr-4 sección.

      code language-json
      "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"
      
    • Actualice las dependencias del proyecto.

      code language-bash
      composer update
      
    • Agregar, confirmar y enviar cambios de código.

      code language-bash
      git add -A
      
      code language-bash
      git commit -m "Add Zend plugin manager implementation for controllers dependency for Laminas support"
      
      code language-bash
      git push origin <branch-name>
      
    • Combine los cambios en el entorno de ensayo y, a continuación, en Producción.

Archivos de configuración

Antes de actualizar la aplicación, debe actualizar los archivos de configuración del proyecto para tener en cuenta los cambios en los valores de configuración predeterminados de Adobe Commerce en la infraestructura en la nube o en la aplicación. Los valores predeterminados más recientes se encuentran en repositorio de GitHub de magento en la nube.

.magento.app.yaml

Revise siempre los valores contenidos en .magento.app.yaml para la versión instalada, ya que controla la forma en que la aplicación se genera e implementa en la infraestructura de la nube. El siguiente ejemplo es para la versión 2.4.7 y utiliza Composer 2.7.2. El build: flavor: no se usa para Composer 2.x; consulte Instalación y uso de Composer 2.

Para actualizar el .magento.app.yaml archivo:

  1. En la estación de trabajo local, cambie al directorio del proyecto.

  2. Abra y edite el magento.app.yaml archivo.

  3. Actualice las opciones de PHP.

    code language-yaml
    type: php:8.3
    
    build:
        flavor: none
    dependencies:
        php:
            composer/composer: '2.7.2'
    
  4. Modifique la hooks propiedad build y deploy comandos.

    code language-yaml
    hooks:
        # We run build hooks before your application has been packaged.
        build: |
            set -e
            composer install
            php ./vendor/bin/ece-tools run scenario/build/generate.xml
            php ./vendor/bin/ece-tools run scenario/build/transfer.xml
        # We run deploy hook after your application has been deployed and started.
        deploy: |
            php ./vendor/bin/ece-tools run scenario/deploy.xml
        # We run post deploy hook to clean and warm the cache. Available with ECE-Tools 2002.0.10.
        post_deploy: |
            php ./vendor/bin/ece-tools run scenario/post-deploy.xml
    
  5. Agregue las siguientes variables de entorno al final del archivo.

    Para Adobe Commerce 2.2.x a 2.3.x-

    code language-yaml
    variables:
        env:
            CONFIG__DEFAULT__PAYPAL_ONBOARDING__MIDDLEMAN_DOMAIN: 'payment-broker.magento.com'
            CONFIG__STORES__DEFAULT__PAYMENT__BRAINTREE__CHANNEL: 'Magento_Enterprise_Cloud_BT'
            CONFIG__STORES__DEFAULT__PAYPAL__NOTATION_CODE: 'Magento_Enterprise_Cloud'
    

    Para Adobe Commerce 2.4.x-

    code language-yaml
    variables:
        env:
            CONFIG__DEFAULT__PAYPAL_ONBOARDING__MIDDLEMAN_DOMAIN: 'payment-broker.magento.com'
            CONFIG__STORES__DEFAULT__PAYPAL__NOTATION_CODE: 'Magento_Enterprise_Cloud'
    
  6. Guarde el archivo. No confirme ni inserte cambios en el entorno remoto aún.

  7. Continúe con el proceso de actualización.

composer.json

Antes de actualizar, compruebe siempre que las dependencias del composer.json son compatibles con la versión de Adobe Commerce.

Para actualizar el composer.json para Adobe Commerce versión 2.4.4 y posterior:

  1. Añada lo siguiente allow-plugins a la config sección:

    code language-json
    "config": {
       "allow-plugins": {
          "dealerdirect/phpcodesniffer-composer-installer": true,
          "laminas/laminas-dependency-plugin": true,
          "magento/*": true
       }
    },
    
  2. Añada el siguiente complemento a require sección:

    code language-json
    "require": {
        "magento/composer-root-update-plugin": "^2.0.3"
    },
    
  3. Añada el siguiente componente a extra:component_paths sección:

    code language-json
    "extra": {
       "component_paths": {
          "tinymce/tinymce": "lib/web/tiny_mce_5"
       },
    },
    
  4. Guarde el archivo. Aún no confirme ni inserte cambios en la rama.

  5. Continúe con el proceso de actualización.

Copia de seguridad del proyecto

Se recomienda crear una copia de seguridad del proyecto antes de una actualización. Siga estos pasos para realizar una copia de seguridad de los entornos de integración, ensayo y producción.

Para realizar una copia de seguridad de la base de datos y el código del entorno de integración:

  1. Cree una copia de seguridad local de la base de datos remota.

    code language-bash
    magento-cloud db:dump
    
    note note
    NOTE
    El magento-cloud db:dump ejecuta el comando mysqldump con el comando --single-transaction , que le permite realizar una copia de seguridad de la base de datos sin bloquear las tablas.
  2. Haga una copia de seguridad del código y los medios.

    code language-bash
    php bin/magento setup:backup --code [--media]
    

    Opcionalmente, puede omitir [--media] si tiene un gran número de archivos estáticos que ya están en el control de código fuente.

Para realizar una copia de seguridad de la base de datos del entorno de ensayo o producción antes de implementar:

  1. Utilice SSH para iniciar sesión en el entorno remoto.

  2. Crear un volcado base datos. Para elegir un directorio de destino para el volcado de la base de datos, utilice el --dump-directory opción.

    code language-bash
    vendor/bin/ece-tools db-dump
    

    La operación de volcado crea un dump-<timestamp>.sql.gz archive el archivo en el directorio de proyecto remoto. Consulte Copia de seguridad de base de datos.

Actualización de aplicación

Revise la versiones de servicio información sobre los requisitos de la última versión del software antes de actualizar la aplicación.

Para actualizar la versión de la aplicación:

  1. En la estación de trabajo local, cambie al directorio del proyecto.

  2. Establezca la versión de actualización con el sintaxis de restricción de versión.

    code language-bash
    composer require "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update
    
    note note
    NOTE
    Debe utilizar la sintaxis de restricción de versión para actualizar correctamente la variable ece-tools paquete. Puede encontrar la restricción de versión en la composer.json para la versión de. plantilla de aplicación que está utilizando para la actualización.
  3. Actualice el proyecto.

    code language-bash
    composer update
    
  4. Agregar, confirmar y enviar cambios de código.

    code language-bash
    git add -A
    
    code language-bash
    git commit -m "Upgrade"
    
    code language-bash
    git push origin <branch-name>
    

    git add -A es necesario para agregar todos los archivos modificados al control de código fuente debido a la forma en que Composer calcula los paquetes base. Ambos composer install y composer update ordenar archivos del paquete base (magento/magento2-base y magento/magento2-ee-base) en la raíz del paquete.

    Los archivos a los que Composer calcula las referencias pertenecen a la nueva versión de Adobe Commerce, para sobrescribir la versión obsoleta de esos mismos archivos. En la actualidad, el cálculo de referencias está deshabilitado en Adobe Commerce, por lo que debe agregar los archivos para calcular referencias al control de código fuente.

  5. Espere a que se complete la implementación.

  6. Compruebe la actualización en el entorno de integración, ensayo o producción utilizando SSH para iniciar sesión y comprobar la versión.

    code language-bash
    php bin/magento --version
    

Crear un archivo config.php

Como se menciona en Administración de configuración, después de la actualización, debe crear un config.php archivo. Complete los cambios de configuración adicionales mediante el Administrador en su entorno de integración.

Para crear un archivo de configuración específico del sistema:

  1. Desde el terminal, utilice un comando SSH para generar el /app/etc/config.php para el entorno.

    code language-bash
    ssh <SSH-URL> "<Command>"
    

    Por ejemplo, para Pro, para ejecutar el scd-dump en el integration rama:

    code language-bash
    ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/ece-tools config:dump"
    
  2. Transfiera el config.php a las estaciones de trabajo locales mediante rsync o scp. Solo puede agregar este archivo a la rama localmente.

    code language-bash
    rsync <SSH-URL>:app/etc/config.php ./app/etc/config.php
    
  3. Agregar, confirmar y enviar cambios de código.

    code language-bash
    git add app/etc/config.php && git commit -m "Add system-specific configuration" && git push origin master
    

    Esto genera un /app/etc/config.php archivo con una lista de módulos y opciones de configuración.

WARNING
Para una actualización, se elimina el config.php archivo. Una vez agregado este archivo al código, debería no elimínelo. Si debe quitar o editar la configuración, edite el archivo manualmente.

Actualización de extensiones

Revise las páginas de módulos y extensiones de terceros en Marketplace u otros sitios de la empresa y compruebe la compatibilidad con Adobe Commerce y Adobe Commerce en la infraestructura en la nube. Si debe actualizar cualquier extensión y módulo de terceros, Adobe recomienda trabajar en una nueva rama de integración con las extensiones deshabilitadas.

Para verificar y actualizar las extensiones:

  1. Cree una rama en la estación de trabajo local.

  2. Deshabilite las extensiones según sea necesario.

  3. Cuando esté disponible, descargue las actualizaciones de extensión.

  4. Instale la actualización según lo documentado por la documentación de terceros.

  5. Habilite y pruebe la extensión de.

  6. Agregue, confirme e inserte los cambios de código en el control remoto.

  7. Envíe a y pruebe en su entorno de integración.

  8. Insertar en el entorno de ensayo para realizar pruebas en un entorno de preproducción.

Adobe recomienda encarecidamente actualizar el entorno de producción antes incluir las extensiones actualizadas en el proceso de lanzamiento del sitio.

NOTE
Al actualizar la versión de la aplicación, el proceso de actualización se actualiza a la última versión del Módulo de CDN de Fastly automáticamente.

Solución de problemas de actualización

Si la actualización falla, recibe un mensaje de error en el explorador que indica que no puede acceder a la tienda o al panel Administración:

There has been an error processing your request
Exception printing is disabled by default for security reasons.
  Error log record number: <error-number>

Para resolver el error:

  1. En la estación de trabajo local, cambie al directorio del proyecto.

  2. Utilice SSH para iniciar sesión en el entorno remoto.

    code language-bash
    magento-cloud ssh
    
  3. Abra el ./app/var/report/<error number> archivo.

  4. Examinar los registros y determinar el origen del problema.

  5. Agregar, confirmar y enviar cambios de código.

    code language-bash
    git add -A && git commit -m "Fixed deployment failure" && git push origin <branch-name>
    
recommendation-more-help
05f2f56e-ac5d-4931-8cdb-764e60e16f26