Aggiorna versione Commerce

Puoi aggiornare la base di codice di Adobe Commerce a una versione più recente. Prima di aggiornare il progetto, controllare i requisiti di sistema nella Guida all'installazione per i requisiti della versione più recente del software.

A seconda della configurazione del progetto, le attività di aggiornamento possono includere quanto segue:

  • I servizi di aggiornamento, come MariaDB (MySQL), OpenSearch, RabbitMQ e Redis, sono compatibili con le nuove versioni di Adobe Commerce.
  • Convertire un file di gestione della configurazione precedente.
  • Aggiornare il file .magento.app.yaml con le nuove impostazioni per hook e variabili di ambiente.
  • Aggiorna le estensioni di terze parti alla versione più recente supportata.
  • Aggiornare il file .gitignore.
TIP
Prima di iniziare un aggiornamento o un processo di applicazione di patch, crea un ramo attivo dall’ambiente di integrazione ed estrai il nuovo ramo sulla workstation locale. La destinazione di un ramo all’aggiornamento o al processo di patch consente di evitare interferenze con il lavoro in corso.
TIP
Per i progetti Pro, è necessario inviare un ticket di supporto Adobe Commerce per installare o aggiornare servizi solo negli ambienti Staging e Production.
Indicare le modifiche necessarie al servizio, includere i file .magento.app.yaml e services.yaml aggiornati e indicare la versione PHP nel ticket. Per le modifiche self-service alle impostazioni di versione PHP, estensioni o ambiente, vedere Impostazioni PHP in Configurazione applicazione.
Per le modifiche a un ambiente di produzione live (Solo Pro), devi fornire un preavviso minimo di 48 ore per consentire al team di infrastruttura cloud di disporre del tempo sufficiente per eseguire il marshalling delle risorse e eseguire un aggiornamento sicuro.

Aggiornamento da versioni precedenti

Se stai iniziando un aggiornamento da una versione di Commerce precedente alla 2.1, alcune restrizioni nella base di codice di Adobe Commerce possono influire sulla possibilità di aggiornare a una versione specifica degli strumenti ECE o di aggiornare alla versione successiva di Commerce supportata. Utilizzare la tabella seguente per determinare il percorso migliore:

Versione corrente
Percorso di aggiornamento
2.1.3 e versioni precedenti
Prima di continuare, aggiorna Adobe Commerce alla versione 2.1.4 o successiva. Quindi esegui un aggiornamento una tantum per installare ECE-Tools.
2.1.4 - 2.1.14
Aggiorna pacchetto ECE-Tools.
Consulta le note sulla versione di 2002.0.9 e successive versioni di 2002.0.x.
2.1.15 - 2.1.16
Aggiorna pacchetto ECE-Tools.
Consulta le note sulla versione di 2002.0.9 e successive.
2.2.x e versioni successive
Aggiorna pacchetto ECE-Tools.
Consulta le note sulla versione di 2002.0.8 e successive.
NOTE
Se utilizzi una versione di Adobe Commerce sull'infrastruttura cloud che non contiene il pacchetto ece-tools, devi eseguire un aggiornamento una tantum al progetto cloud per rimuovere i pacchetti obsoleti. Se si utilizza il pacchetto ece-tools e si desidera aggiornarlo, vedere Aggiornare il pacchetto ECE-Tools.

Gestione della configurazione

Le versioni precedenti di Adobe Commerce, ad esempio 2.1.4 o successive alla versione 2.2.x o successive, utilizzavano un file config.local.php per la gestione della configurazione. Adobe Commerce versione 2.2.0 e successive utilizzano il file config.php, che funziona esattamente come il file config.local.php, ma con impostazioni di configurazione diverse che includono un elenco dei moduli abilitati e opzioni di configurazione aggiuntive.

Quando si esegue l'aggiornamento da una versione precedente, è necessario migrare il file config.local.php per utilizzare il file config.php più recente. Per eseguire il backup del file di configurazione e crearne uno, effettua le seguenti operazioni.

Per creare un file config.php temporaneo:

  1. Creare una copia del file config.local.php e denominarlo config.php.

  2. Aggiungi il file alla cartella app/etc del progetto.

  3. Aggiungi e invia il file al tuo ramo.

  4. Invia il file al ramo di integrazione.

  5. Continuare con il processo di aggiornamento.

WARNING
Dopo l'upgrade, è possibile rimuovere il file config.php e generare un nuovo file completo. Puoi eliminare questo file solo una volta per sostituirlo. Dopo aver generato un nuovo file config.php completo, non è possibile eliminare il file per generarne uno nuovo. Consulta Gestione della configurazione e distribuzione della pipeline.

Verificare le dipendenze del compositore Zend Framework

Durante l'aggiornamento a 2.3.x o versione successiva dalla versione 2.2.x, verificare che le dipendenze di Zend Framework siano state aggiunte alla proprietà autoload del file composer.json per supportare Laminas. Questo plug-in supporta i nuovi requisiti per Zend Framework, che è migrato al progetto Laminas. Vedi Migrazione di Zend Framework al progetto Laminas nel DevBlog Magento.

Per controllare la configurazione auto-load:psr-4:

  1. Sulla workstation locale, passa alla directory del progetto.

  2. Consulta il ramo dell’integrazione.

  3. Aprire il file composer.json in un editor di testo.

  4. Controllare la sezione autoload:psr-4 per l'implementazione del gestore del plug-in Zend per la dipendenza dei controller.

    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. Se manca la dipendenza Zend, aggiornare il file composer.json:

    • Aggiungere la riga seguente alla sezione autoload:psr-4.

      code language-json
      "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"
      
    • Aggiornare le dipendenze del progetto.

      code language-bash
      composer update
      
    • Aggiungi, conferma e invia modifiche al codice.

      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>
      
    • Unisci le modifiche apportate all’ambiente di staging e quindi a Produzione.

File di configurazione

Prima di aggiornare l’applicazione, è necessario aggiornare i file di configurazione del progetto per tenere conto delle modifiche alle impostazioni di configurazione predefinite per Adobe Commerce sull’infrastruttura cloud o l’applicazione. Le impostazioni predefinite più recenti si trovano nell'archivio GitHub magento-cloud.

.magento.app.yaml

Controlla sempre i valori contenuti nel file .magento.app.yaml per la versione installata, in quanto controlla il modo in cui l'applicazione viene generata e distribuita nell'infrastruttura cloud. L’esempio seguente è per la versione 2.4.7 e utilizza Composer 2.7.2. La proprietà build: flavor: non è utilizzata per Composer 2.x; vedere Installazione e utilizzo di Composer 2.

Per aggiornare il file .magento.app.yaml:

  1. Sulla workstation locale, passa alla directory del progetto.

  2. Aprire e modificare il file magento.app.yaml.

  3. Aggiornare le opzioni PHP.

    code language-yaml
    type: php:8.3
    
    build:
        flavor: none
    dependencies:
        php:
            composer/composer: '2.7.2'
    
  4. Modificare la proprietà hooks build e i comandi deploy.

    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. Aggiungi le seguenti variabili di ambiente alla fine del file.

    Per Adobe Commerce da 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'
    

    Per 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. Salva il file. Non eseguire ancora il commit o il push delle modifiche nell'ambiente remoto.

  7. Continuare con il processo di aggiornamento.

composer.json

Prima di eseguire l'aggiornamento, verificare sempre che le dipendenze nel file composer.json siano compatibili con la versione di Adobe Commerce.

Per aggiornare il file composer.json per Adobe Commerce versione 2.4.4 e successive:

  1. Aggiungi allow-plugins alla sezione config:

    code language-json
    "config": {
       "allow-plugins": {
          "dealerdirect/phpcodesniffer-composer-installer": true,
          "laminas/laminas-dependency-plugin": true,
          "magento/*": true
       }
    },
    
  2. Aggiungi il seguente plug-in alla sezione require:

    code language-json
    "require": {
        "magento/composer-root-update-plugin": "^2.0.3"
    },
    
  3. Aggiungi il seguente componente alla sezione extra:component_paths:

    code language-json
    "extra": {
       "component_paths": {
          "tinymce/tinymce": "lib/web/tiny_mce_5"
       },
    },
    
  4. Salva il file. Non eseguire ancora il commit o il push delle modifiche nel ramo.

  5. Continuare con il processo di aggiornamento.

Backup del progetto

È consigliabile creare un backup del progetto prima di un aggiornamento. Utilizza i seguenti passaggi per eseguire il backup degli ambienti di integrazione, staging e produzione.

Per eseguire il backup del database e del codice dell'ambiente di integrazione:

  1. Creare un backup locale del database remoto.

    code language-bash
    magento-cloud db:dump
    
    note note
    NOTE
    Il comando magento-cloud db:dump esegue il comando mysqldump con il flag --single-transaction, che consente di eseguire il backup del database senza bloccare le tabelle.
  2. Eseguire il backup del codice e dei supporti.

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

    Se si desidera, è possibile omettere [--media] se il numero di file statici che si trovano già nel controllo del codice sorgente è elevato.

Per eseguire il backup del database dell'ambiente di staging o di produzione prima della distribuzione:

  1. Utilizza SSH per accedere all’ambiente remoto.

  2. Crea un dump del database 🔗. Per scegliere una directory di destinazione per il dump del database, utilizzare l'opzione --dump-directory.

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

    L'operazione di dump crea un file di archivio dump-<timestamp>.sql.gz nella directory di progetto remota. Vedere Backup del database.

Aggiornamento dell’applicazione

Prima di aggiornare l'applicazione, esaminare le informazioni sulle versioni del servizio per conoscere i requisiti delle versioni più recenti del software.

Per aggiornare la versione dell'applicazione:

  1. Sulla workstation locale, passa alla directory del progetto.

  2. Impostare la versione di aggiornamento utilizzando la sintassi version constraint.

    code language-bash
    composer require "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update
    
    note note
    NOTE
    Per aggiornare correttamente il pacchetto ece-tools, è necessario utilizzare la sintassi del vincolo di versione. È possibile trovare il vincolo di versione nel file composer.json per la versione del modello di applicazione utilizzato per l'aggiornamento.
  3. Aggiorna il progetto.

    code language-bash
    composer update
    
  4. Aggiungi, conferma e invia modifiche al codice.

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

    git add -A è necessario per aggiungere tutti i file modificati al controllo del codice sorgente a causa del modo in cui i pacchetti di base di Marshals Composer vengono eseguiti. Entrambi i file di marshalling composer install e composer update dal pacchetto di base (magento/magento2-base e magento/magento2-ee-base) nella radice del pacchetto.

    I file che Composer marshalling appartengono alla nuova versione di Adobe Commerce, per sovrascrivere la versione obsoleta degli stessi file. Attualmente, il marshalling è disabilitato in Adobe Commerce, pertanto è necessario aggiungere i file marshallati al controllo del codice sorgente.

  5. Attendere il completamento della distribuzione.

  6. Verifica l’aggiornamento nell’ambiente di integrazione, staging o produzione utilizzando SSH per accedere e controllare la versione.

    code language-bash
    php bin/magento --version
    

Creare un file config.php

Come indicato in Gestione configurazione, dopo l'aggiornamento è necessario creare un file config.php aggiornato. Completa eventuali modifiche aggiuntive alla configurazione tramite l’Amministratore nell’ambiente di integrazione.

Per creare un file di configurazione specifico del sistema:

  1. Dal terminale, utilizzare un comando SSH per generare il file /app/etc/config.php per l'ambiente.

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

    Ad esempio, per Pro, per eseguire scd-dump sul ramo integration:

    code language-bash
    ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/ece-tools config:dump"
    
  2. Trasferire il file config.php nelle workstation locali utilizzando rsync o scp. Puoi aggiungere questo file al ramo solo localmente.

    code language-bash
    rsync <SSH-URL>:app/etc/config.php ./app/etc/config.php
    
  3. Aggiungi, conferma e invia modifiche al codice.

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

    Viene generato un file /app/etc/config.php aggiornato con un elenco di moduli e impostazioni di configurazione.

WARNING
Per un aggiornamento, eliminare il file config.php. Una volta aggiunto il file al codice, devi non eliminarlo. Se è necessario rimuovere o modificare le impostazioni, modificare il file manualmente.

Aggiornare le estensioni

Controlla le pagine delle estensioni e dei moduli di terze parti nel Marketplace o in altri siti aziendali e verifica il supporto per Adobe Commerce e Adobe Commerce sull’infrastruttura cloud. Se devi aggiornare estensioni e moduli di terze parti, l’Adobe consiglia di lavorare in un nuovo ramo di integrazione con le estensioni disabilitate.

Per verificare e aggiornare le estensioni:

  1. Crea una filiale sulla workstation locale.

  2. Disattiva le estensioni in base alle esigenze.

  3. Se disponibile, scarica gli aggiornamenti dell'estensione.

  4. Installa l’aggiornamento come descritto nella documentazione di terze parti.

  5. Abilita e verifica l’estensione.

  6. Aggiungi, esegui il commit e invia le modifiche al codice in remoto.

  7. Effettua il push e il test nell’ambiente di integrazione.

  8. Effettua il push all’ambiente di staging per il test in un ambiente di pre-produzione.

L'Adobe consiglia vivamente di aggiornare l'ambiente di produzione prima includendo le estensioni aggiornate nella procedura di avvio del sito.

NOTE
Quando si aggiorna la versione dell'applicazione, il processo di aggiornamento viene aggiornato automaticamente alla versione più recente del modulo CDN Fastly.

Risoluzione dei problemi di aggiornamento

Se l’aggiornamento non è riuscito, viene visualizzato un messaggio di errore nel browser che indica che non è possibile accedere alla vetrina o al pannello di amministrazione:

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

Per risolvere l'errore:

  1. Sulla workstation locale, passa alla directory del progetto.

  2. Utilizza SSH per accedere all’ambiente remoto.

    code language-bash
    magento-cloud ssh
    
  3. Aprire il file ./app/var/report/<error number>.

  4. Esaminare i registri e determinare l'origine del problema.

  5. Aggiungi, conferma e invia modifiche al codice.

    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