Aggiorna versione Commerce

Puoi aggiornare la base di codice di Adobe Commerce a una versione più recente. Prima di aggiornare il progetto, controlla Requisiti di sistema nel 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 .magento.app.yaml con nuove impostazioni per hook e variabili di ambiente.
  • Aggiorna le estensioni di terze parti alla versione più recente supportata.
  • Aggiornare il .gitignore file.
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 invia un ticket di supporto Adobe Commerce per installare o aggiornare servizi in Staging e Production solo ambienti.
Indica le modifiche del servizio necessarie, includi le .magento.app.yaml e services.yaml e indicare la versione PHP nel ticket. Per le modifiche self-service alle impostazioni di versione PHP, estensioni o ambiente, vedi Impostazioni PHP in Configurazione dell’applicazione.
Per le modifiche apportate a live Ambiente di produzione (Solo pro), devi fornire un preavviso minimo di 48 ore per consentire al team dell’infrastruttura Cloud di 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 capacità di aggiorna a una specifica release ECE-Tools o a aggiornamento alla successiva versione supportata di Commerce. 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 una aggiornamento una tantum per installare ECE-Tools.
2.1.4 - 2.1.14
Aggiorna utensili ECE pacchetto.
Consulta le note sulla versione di 2002.0.9. e versioni successive di 2002.0.x.
2.1.15 - 2.1.16
Aggiorna utensili ECE pacchetto.
Consulta le note sulla versione di2002.0.9. e più tardi.
2.2.x e versioni successive
Aggiorna utensili ECE pacchetto.
Consulta le note sulla versione di2002.0.8. e più tardi.
NOTE
Se utilizzi una versione di Adobe Commerce su infrastruttura cloud che non contiene ece-tools , è necessario eseguire una aggiornamento una tantum nel progetto cloud per rimuovere i pacchetti obsoleti. Se al momento utilizzi il ece-tools e devi aggiornarlo, consulta Aggiornare il pacchetto ECE-Strumenti.

Gestione della configurazione

Le versioni precedenti di Adobe Commerce, ad esempio 2.1.4 o successive alla versione 2.2.x o successive, utilizzavano una config.local.php per la gestione della configurazione. Adobe Commerce versione 2.2.0 e successive utilizzano config.php , che funziona esattamente come 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 eseguire la migrazione del config.local.php file per utilizzare il più recente config.php file. Per eseguire il backup del file di configurazione e crearne uno, effettua le seguenti operazioni.

Per creare un file temporaneo config.php file:

  1. Crea una copia di config.local.php file e denominarlo config.php.

  2. Aggiungi questo file al 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 config.php e generare un nuovo file completo. Puoi eliminare questo file solo una volta per sostituirlo. Dopo aver generato un nuovo, completa config.php file, 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 successiva a partire da 2.2.x, verifica che le dipendenze del framework Zend siano state aggiunte al autoload proprietà del composer.json file per supportare Laminas. Questo plug-in supporta i nuovi requisiti per Zend Framework, che è migrato al progetto Laminas. Consulta Migrazione di Zend Framework al progetto Laminas il DevBlog Magento.

Per controllare auto-load:psr-4 configurazione:

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

  2. Consulta il ramo dell’integrazione.

  3. Apri composer.json in un editor di testo.

  4. Controlla la autoload:psr-4 sezione 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, aggiorna il composer.json file:

    • Aggiungi la seguente riga al autoload:psr-4 sezione.

      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. I valori predefiniti più recenti si trovano nella sezione archivio GitHub magento-cloud.

.magento.app.yaml

Esamina sempre i valori contenuti nel .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. Il build: flavor: non viene utilizzata per Composer 2.x; vedi Installazione e utilizzo di Composer 2.

Per aggiornare .magento.app.yaml file:

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

  2. Apri e modifica il magento.app.yaml file.

  3. Aggiornare le opzioni PHP.

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

    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 nella composer.json sono compatibili con la versione di Adobe Commerce.

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

  1. Aggiungi quanto segue allow-plugins al config sezione:

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

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

    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 magento-cloud db:dump il comando esegue mysqldump comando con --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]
    

    Facoltativamente, puoi omettere [--media] se si dispone di un numero elevato di file statici già presenti nel controllo del codice sorgente.

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. Creare un dump del database. Per scegliere una directory di destinazione per il dump del database, utilizzare --dump-directory opzione.

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

    L’operazione di dump crea un dump-<timestamp>.sql.gz archiviare il file nella directory del progetto remoto. Consulta Backup del database.

Aggiornamento dell’applicazione

Rivedi versioni del servizio informazioni sui requisiti della versione più recente del software prima di aggiornare l'applicazione.

Per aggiornare la versione dell'applicazione:

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

  2. Imposta la versione di aggiornamento utilizzando sintassi del vincolo di versione.

    code language-bash
    composer require "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update
    
    note note
    NOTE
    È necessario utilizzare la sintassi del vincolo di versione per aggiornare correttamente ece-tools pacchetto. Puoi trovare il vincolo di versione in composer.json file per la versione di modello di applicazione stai utilizzando 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 vengono utilizzati per il marshalling dei compositori. Entrambi composer install e composer update file di marshalling dal pacchetto di base (magento/magento2-base e magento/magento2-ee-base) nella directory principale 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 della configurazione, dopo l'upgrade, è necessario creare un aggiornamento config.php file. Completa eventuali modifiche aggiuntive alla configurazione tramite l’Amministratore nell’ambiente di integrazione.

Per creare un file di configurazione specifico per il sistema:

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

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

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

    code language-bash
    ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/ece-tools config:dump"
    
  2. Trasferisci il config.php alle 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
    

    Questo genera un aggiornamento /app/etc/config.php file con un elenco di moduli e impostazioni di configurazione.

WARNING
Per un aggiornamento, elimina il config.php file. Una volta aggiunto il file al codice, devi non eliminala. 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.

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 di inclusione delle estensioni aggiornate nel processo di lancio del sito.

NOTE
Quando si aggiorna la versione dell’applicazione, il processo di aggiornamento si aggiorna alla versione più recente del Modulo CDN Fastly automaticamente.

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. Apri ./app/var/report/<error number> file.

  4. Esaminare i registri e determinano 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