DocumentazioneCommerceGuida all’aggiornamento

[Solo PaaS]{class="badge informative" title="Applicabile solo ai progetti Adobe Commerce on Cloud (infrastruttura PaaS gestita da Adobe) e ai progetti on-premise."}

Tutte le applicazioni prerequisiti per l'aggiornamento

Last update: Mon May 05 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Argomenti:

Creato per:

  • Esperto
  • Amministratore
  • Sviluppatore

È importante comprendere ciò che è necessario per eseguire Adobe Systems Commerce. È innanzitutto necessario esaminare i requisiti di sistema per la versione che si desidera aggiornare.

Dopo aver esaminato i requisiti di sistema, è necessario completare i seguenti prerequisiti prima di aggiornare il sistema:

  • Aggiorna tutto il software
  • Verificare che sia installato un motore di ricerca supportato
  • Converti formato tabella database
  • Impostare il limite dei file aperti
  • Verificare che i processi cron siano in esecuzione
  • Imposta DATA_CONVERTER_BATCH_SIZE
  • Verificare le autorizzazioni del file system
  • Imposta la directory principale pub/
  • Installare il plug-in di aggiornamento Composer

Aggiorna tutto il software

I requisiti di sistema descrivono esattamente quali versioni di software di terze parti sono state testate con le versioni di Adobe Commerce.

Assicurati di aver aggiornato tutti i requisiti di sistema e le dipendenze nell’ambiente. Vedere PHP 7.4, PHP 8.0, PHP 8.1 e impostazioni PHP richieste.

NOTE
Per i progetti Adobe Commerce su infrastruttura cloud Pro, è necessario creare un ticket Supporto per installare o aggiornare i servizi negli ambienti di staging e produzione. Indicare le modifiche necessarie al servizio e includere nel ticket i file .magento.app.yaml e services.yaml aggiornati e la versione PHP. L’aggiornamento del progetto da parte del team di infrastruttura Cloud può richiedere fino a 48 ore. Consulta Software e servizi supportati.

Verificare che sia installato un motore di ricerca supportato

Adobe Commerce richiede l’installazione di Elasticsearch o OpenSearch per poter utilizzare il software.

Se si esegue l'aggiornamento da 2.3.x a 2.4, è necessario verificare se si utilizza MySQL, Elasticsearch o un'estensione di terze parti come motore di ricerca del catalogo nell'istanza 2.3.x. Il risultato determina cosa devi fare prima dell'aggiornamento a 2.4.

Se si stanno aggiornando le versioni patch nelle righe della versione 2.3.x o 2.4.x, se Elasticsearch 7.x è già installato, è possibile migrare a OpenSearch.

Puoi utilizzare la riga di comando o l’amministratore per determinare il motore di ricerca del catalogo:

  • Immettere il comando bin/magento config:show catalog/search/engine. Il comando restituisce un valore di mysql, elasticsearch (che indica che Elasticsearch 2 è configurato), elasticsearch5, elasticsearch6, elasticsearch7 o un valore personalizzato, che indica che è stato installato un motore di ricerca di terze parti. Per le versioni precedenti alla 2.4.6, utilizzare il valore elasticsearch7 per il motore di Elasticsearch 7 o OpenSearch. Per le versioni 2.4.6 e successive, utilizzare il valore opensearch per il motore OpenSearch.

  • Dall'amministratore, controllare il valore del campo Stores > Settings > Configuration > Catalog > Catalog > Catalog Search > Search Engine.

Le sezioni seguenti descrivono le azioni da intraprendere prima di eseguire l’aggiornamento alla versione 2.4.0.

MySQL

A partire dalla versione 2.4, MySQL non è più un motore di ricerca catalogo supportato. È necessario installare e configurare Elasticsearch o OpenSearch prima dell'aggiornamento. Utilizza le risorse seguenti per aiutarti a seguire questo processo:

Alcuni motori di ricerca di cataloghi di terze parti vengono eseguiti sul motore di ricerca di Adobe Commerce. Contatta il fornitore per determinare se è necessario aggiornare l’estensione.

Modifiche a MySQL 8.4

Adobe ha aggiunto il supporto per MySQL 8.4 nella versione 2.4.8.
In questa sezione vengono descritte le principali modifiche apportate a MySQL 8.4 di cui gli sviluppatori devono essere a conoscenza.

Chiave non standard obsoleta

L'utilizzo di chiavi non univoche o parziali come chiavi esterne non è standard ed è obsoleto in MySQL 8.4. A partire da MySQL 8.4.0, è necessario abilitare esplicitamente tali chiavi impostando restrict_fk_on_non_standard_key su OFF oppure avviando il server con l'opzione --skip-restrict-fk-on-non-standard-key.

Aggiornamento da MySQL 8.0 ( o versioni precedenti ) a MySQL 8.4

Per aggiornare correttamente MySQL dalla versione 8.0 alla versione 8.4, è necessario seguire i passaggi seguenti nell'ordine in cui si desidera eseguire:

  1. Abilita modalità di manutenzione:

    code language-bash 
    bin/magento maintenance:enable

  2. Eseguire un backup del database:

    code language-bash 
    bin/magento setup:backup --db

  3. Aggiornare MySQL alla versione 8.4.

  4. Imposta restrict_fk_on_non_standard_key su OFF in [mysqld] nel file my.cnf.

    code language-bash 
    [mysqld]
restrict_fk_on_non_standard_key = OFF
    note warning
    WARNING
    Se non si modifica il valore di restrict_fk_on_non_standard_key in OFF, verrà visualizzato il seguente errore durante l'importazione:
    code language-sql 
     ERROR 6125 (HY000) at line 2164: Failed to add the foreign key constraint. Missing unique key for constraint 'CAT_PRD_FRONTEND_ACTION_PRD_ID_CAT_PRD_ENTT_ENTT_ID' in the referenced table 'catalog_product_entity'

    1. Riavviare il server MySQL.

  5. Importare i dati di backup in MySQL.

  6. Pulisci la cache:

    code language-bash 
    bin/magento cache:clean

  7. Disattiva modalità di manutenzione:

    code language-bash 
    bin/magento maintenance:disable

MariaDB

[Solo PaaS]{class="badge informative" title="Applicabile solo ai progetti Adobe Commerce on Cloud (infrastruttura PaaS gestita da Adobe) e ai progetti on-premise."}

La reindicizzazione su MariaDB 10.4 e 10.6 richiede più tempo rispetto alle versioni precedenti di MariaDB o MySQL. Per accelerare la reindicizzazione, si consiglia di impostare i seguenti parametri di configurazione MariaDB:

Se si verifica un peggioramento delle prestazioni non correlato all'indicizzazione dopo l'aggiornamento a MariaDB 10.6, provare ad abilitare l'impostazione --query-cache-type. Ad esempio, --query-cache-type=ON.

Prima di aggiornare Adobe Commerce ai progetti di infrastruttura cloud, potrebbe essere necessario aggiornare anche MariaDB (consulta le best practice per l'aggiornamento di MariaDB).

Ad esempio:

  • Adobe Commerce 2.4.6 con MariaDB versione 10.5.1 o successiva
  • Adobe Commerce 2.3.5 con MariaDB versione 10.3 o precedente

Oltre a questi consigli, è necessario consultare l'amministratore del database per configurare i seguenti parametri:

NOTE
Queste impostazioni sono disponibili solo per le distribuzioni locali. I clienti di Adobe Commerce su infrastruttura cloud non hanno accesso a queste impostazioni.

Motore di ricerca

Prima di eseguire l’aggiornamento a 2.4.0, è necessario installare e configurare Elasticsearch 7.6 o versione successiva o OpenSearch 1.2. Adobe non supporta più Elasticsearch 2.x, 5.x e 6.x. Configurazione del motore di ricerca nella Guida alla configurazione descrive le attività da eseguire dopo l'aggiornamento di Elasticsearch a una versione supportata.

Consulta Aggiornamento di Elasticsearch per istruzioni complete sul backup dei dati, l'individuazione di potenziali problemi di migrazione e il test degli aggiornamenti prima della distribuzione in produzione. A seconda della versione corrente di Elasticsearch, potrebbe essere necessario o meno un riavvio completo del cluster.

Elasticsearch richiede Java Development Kit (JDK) 1.8 o versione successiva. Consultate Installare Java Software Development Kit (JDK) per verificare quale versione di JDK è installata.

Ricerca aperta

OpenSearch è un fork open source di Elasticsearch 7.10.2, in seguito al cambio di licenza di Elasticsearch. Le seguenti versioni di Adobe Systems Commerce introducono il supporto per OpenSearch:

  • 2.4.6 (OpenSearch ha un modulo e impostazioni separati)
  • 2.4.5.
  • 2.4.4.
  • 2.4.3-p2
  • 2.3.7-p3

Puoi migrare da Elasticsearch a OpenSearch solo se esegui l'aggiornamento a una versione di Adobe Commerce elencata sopra (o successiva).

OpenSearch richiede JDK 1.8 o superiore. Consulta Installare Java Software Development Kit (JDK) per verificare quale versione di JDK è installata.

Configurazione del motore di ricerca descrive le attività da eseguire dopo la modifica dei motori di ricerca.

Aggiornare Elasticsearch

Il supporto per Elasticsearch 8.x è stato introdotto in Adobe Commerce 2.4.6. Le istruzioni seguenti mostrano un esempio di aggiornamento di Elasticsearch da 7.x a 8.x:

NOTE
Nella prossima versione di 2.4.8, questi passaggi non saranno necessari perché il modulo Elasticsearch 8 è incluso per impostazione predefinita e non sarà necessario installarlo separatamente.

  1. Aggiorna il server Elasticsearch 7.x a 8.x e assicurati che sia operativo. Consulta la documentazione di Elasticsearch.

  2. Abilita il campo id_field_data aggiungendo la seguente configurazione al file elasticsearch.yml e riavviando il servizio Elasticsearch 8.x.

    code language-yaml 
    indices:
  id_field_data:
    enabled: true
    note info
    INFO
    Per supportare Elasticsearch 8.x, Adobe Commerce 2.4.6 non consente la proprietà indices.id_field_data per impostazione predefinita e utilizza il campo _id nella proprietà docvalue_fields.

  3. Nella directory principale del progetto Adobe Commerce, aggiorna le dipendenze del Compositore per rimuovere il modulo Magento_Elasticsearch7 e installare il modulo Magento_Elasticsearch8.

    code language-bash 
    composer require magento/module-elasticsearch-8 --update-with-all-dependencies

    Se si verifica un errore di dipendenza per psr/http-message, fare clic per espandere la seguente sezione di risoluzione dei problemi:

    accordion
    Risoluzione dei problemi

    Se si verificano conflitti di dipendenza durante l'installazione di Elasticsearch 8, in particolare con psr/http-message, è possibile risolvere il problema seguendo la procedura riportata di seguito:

    1. Innanzitutto, devi richiedere il modulo Elasticsearch 8 senza aggiornare altre dipendenze:

      code language-bash 
      composer require magento/module-elasticsearch-8 --no-update

    2. Quindi aggiorna il modulo Elasticsearch 8 e aws/aws-sdk-php pacchetti:

      code language-bash 
      composer update magento/module-elasticsearch-8 aws/aws-sdk-php -W

    Questo approccio funziona per 2,4,7-p4 con PHP 8,3. Il problema si verifica perché aws/aws-sdk-php richiede psr/http-message >= 2.0, che può causare conflitti. I passaggi precedenti aiutano a risolvere questi problemi di dipendenza.

  4. Aggiorna i componenti del progetto.

    code language-bash 
    bin/magento setup:upgrade

  5. Configura Elasticsearch in Admin.

  6. Reindicizza l’indice del catalogo.

    code language-bash 
    bin/magento indexer:reindex catalogsearch_fulltext

  7. Elimina tutti gli elementi dai tipi di cache abilitati.

    code language-bash 
    bin/magento cache:clean

Downgrade di Elasticsearch

Se aggiorni inavvertitamente la versione di Elasticsearch sul server o stabilisci che è necessario effettuare il downgrade per qualsiasi altro motivo, devi aggiornare anche le dipendenze dei progetti Adobe Commerce. Ad esempio, per effettuare il downgrade da Elasticsearch 8.x a 7.x

  1. Esegui il downgrade del server Elasticsearch 8.x alla versione 7.x e accertati che sia funzionante. Consulta la documentazione di Elasticsearch.

  2. Nella directory principale del progetto Adobe Commerce, aggiornare le dipendenze del Compositore per rimuovere il modulo Magento_Elasticsearch8 e le relative dipendenze del Compositore e installare il modulo Magento_Elasticsearch7.

    code language-bash 
    composer remove magento/module-elasticsearch-8

  3. Aggiorna i componenti del progetto.

    code language-bash 
    bin/magento setup:upgrade

  4. Configura Elasticsearch in Admin.

  5. Reindicizza l’indice del catalogo.

    code language-bash 
    bin/magento indexer:reindex catalogsearch_fulltext

  6. Elimina tutti gli elementi dai tipi di cache abilitati.

    code language-bash 
    bin/magento cache:clean

Estensioni di terze parti

Contatta il fornitore del motore di ricerca per determinare se l’estensione è completamente compatibile con una versione di Adobe Commerce.

Converti formato tabella database

È necessario convertire il formato di tutte le tabelle di database da COMPACT a DYNAMIC. È inoltre necessario convertire il tipo di motore di archiviazione da MyISAM a InnoDB. Consulta best practice.

Imposta il limite di file aperti

L'impostazione del limite dei file aperti (ulimit) consente di evitare errori dovuti a più chiamate ricorsive di stringhe di query lunghe o problemi con l'utilizzo del comando bin/magento setup:rollback. Questo comando è diverso per le diverse shell UNIX. Per informazioni specifiche sul comando ulimit, consultare la versione personalizzata.

Adobe consiglia di impostare i file aperti ulimit su un valore pari o superiore a 65536, ma se necessario è possibile utilizzare un valore maggiore. È possibile impostare il limite massimo sulla riga di comando oppure impostarlo come impostazione permanente per la shell dell'utente.

Per impostare il limite dalla riga di comando:

  1. Passa al proprietario del file system.

  2. Impostare il limite su 65536.

    code language-bash 
    ulimit -n 65536

Per impostare il valore nella shell Bash:

  1. Passa al proprietario del file system.

  2. Apri /home/<username>/.bashrc in un editor di testo.

  3. Aggiungi la seguente riga:

    code language-bash 
    ulimit -n 65536

  4. Salvare le modifiche apportate al file .bashrc e uscire dall'editor di testo.

IMPORTANT
È consigliabile evitare di impostare un valore per la proprietà pcre.recursion_limit nel file php.ini, in quanto potrebbe causare rollback incompleti senza alcun avviso di errore.

Verificare che i processi cron siano in esecuzione

L'Utilità di pianificazione UNIX cron è fondamentale per le operazioni quotidiane di Adobe Commerce. Pianifica elementi come reindicizzazione, newsletter, e-mail e sitemap. Diverse funzioni richiedono almeno un cron job in esecuzione come file system proprietario.

Per verificare che il tuo cron job sia impostato correttamente, controlla il crontab inserendo il seguente comando come file system proprietario:

NOTE
Il crontab è il file di configurazione responsabile dell'esecuzione dei cron job.
crontab -l

Dovrebbero essere visualizzati risultati simili ai seguenti:

#~ MAGENTO START c5f9e5ed71cceaabc4d4fd9b3e827a2b
* * * * * /usr/bin/php /var/www/html/magento2/bin/magento cron:run 2>&1 | grep -v "Ran jobs by schedule" >> /var/www/html/magento2/var/log/magento.cron.log
#~ MAGENTO END c5f9e5ed71cceaabc4d4fd9b3e827a2b

Un altro sintomo di cron non in esecuzione è il seguente errore nell'amministratore:

Messaggi di sistema - cron non in esecuzione

Per visualizzare l'errore, fare clic su Messaggi di sistema nella parte superiore della finestra nel modo seguente:

Notifica messaggi di sistema

Per ulteriori informazioni, vedere Configurare ed eseguire cron.

Imposta DATA_CONVERTER_BATCH_SIZE

Adobe Systems Commerce 2.4 include miglioramenti della sicurezza che richiedono la conversione di alcuni dati da serializzati a JSON. Questa conversione si verifica durante l'aggiornamento e può richiedere molto tempo, a seconda della quantità di dati presenti nel database.

Le tabelle seguenti sono quelle maggiormente interessate:

  • catalogrule
  • core_config_data
  • magento_reward_history
  • quote_payment
  • quote
  • sales_order_payment
  • sales_order
  • salesrule
  • url_rewrite

Se la quantità di dati è elevata, è possibile migliorare le prestazioni impostando il valore di una variabile di ambiente, DATA_CONVERTER_BATCH_SIZE. Per impostazione predefinita, il valore è impostato su 50,000.

Per impostare la variabile di ambiente:

  1. Passa al proprietario del file system.

  2. Imposta la variabile:

    code language-bash 
    export DATA_CONVERTER_BATCH_SIZE=100000
    note note
    NOTE
    DATA_CONVERTER_BATCH_SIZE richiede memoria; evitare di impostarla su un valore elevato (circa 1 GB) senza prima testarla.

  3. Al termine dell'aggiornamento, è possibile annullare la configurazione della variabile:

    code language-bash 
    unset DATA_CONVERTER_BATCH_SIZE

Verificare le autorizzazioni del file system

Per motivi di sicurezza, Adobe Systems Commerce richiede determinate autorizzazioni sul file system. Le autorizzazioni sono diverse dalla proprietà. La proprietà determina chi può eseguire azioni sul file system; Le autorizzazioni determinano le operazioni che la utente può eseguire.

Le directory nel file system devono essere scrivibili dal gruppo di proprietario del file system.

Per verificare che le autorizzazioni del file system siano impostate correttamente, accedere al server applicazioni o utilizzare l'applicazione di gestione file del provider di hosting.

Ad esempio, immettere il seguente comando se l'applicazione è installata in /var/www/html/magento2:

ls -l /var/www/html/magento2

Output di esempio:

total 1028
drwxrwx---. 12 magento_user apache   4096 Jun  7 07:55 .
drwxr-xr-x.  3 root         root     4096 May 11 14:29 ..
drwxrwx---.  4 magento_user apache   4096 Jun  7 07:53 app
drwxrwx---.  2 magento_user apache   4096 Jun  7 07:53 bin
-rw-rw----.  1 magento_user apache 439792 Apr 27 21:23 CHANGELOG.md
-rw-rw----.  1 magento_user apache   3422 Apr 27 21:23 composer.json
-rw-rw----.  1 magento_user apache 425214 Apr 27 21:27 composer.lock
-rw-rw----.  1 magento_user apache   3425 Apr 27 21:23 CONTRIBUTING.md
-rw-rw----.  1 magento_user apache  10011 Apr 27 21:23 CONTRIBUTOR_LICENSE_AGREEMENT.html
-rw-rw----.  1 magento_user apache    631 Apr 27 21:23 COPYING.txt
drwxrwx---.  4 magento_user apache   4096 Jun  7 07:53 dev
-rw-rw----.  1 magento_user apache   2926 Apr 27 21:23 Gruntfile.js
-rw-rw----.  1 magento_user apache   7592 Apr 27 21:23 .htaccess
-rw-rw----.  1 magento_user apache   6419 Apr 27 21:23 .htaccess.sample
drwxrwx---.  4 magento_user apache   4096 Jun  7 07:53 lib
-rw-rw----.  1 magento_user apache  10376 Apr 27 21:23 LICENSE_AFL.txt
-rw-rw----.  1 magento_user apache  30634 Apr 27 21:23 LICENSE_EE.txt
-rw-rw----.  1 magento_user apache  10364 Apr 27 21:23 LICENSE.txt
-rw-rw----.  1 magento_user apache   4108 Apr 27 21:23 nginx.conf.sample
-rw-rw----.  1 magento_user apache   1427 Apr 27 21:23 package.json
-rw-rw----.  1 magento_user apache   1659 Apr 27 21:23 .php_cs
-rw-rw----.  1 magento_user apache    804 Apr 27 21:23 php.ini.sample
drwxrwx---.  2 magento_user apache   4096 Jun  7 07:53 phpserver
drwxrwx---.  6 magento_user apache   4096 Jun  7 07:53 pub
-rw-rw----.  1 magento_user apache   2207 Apr 27 21:23 README_EE.md
drwxrwx---.  7 magento_user apache   4096 Jun  7 07:53 setup
-rw-rw----.  1 magento_user apache   3731 Apr 27 21:23 .travis.yml
drwxrwx---.  7 magento_user apache   4096 Jun  7 07:53 update
drwxrws---. 11 magento_user apache   4096 Jun 13 16:05 var
drwxrws---. 29 magento_user apache   4096 Jun  7 07:53 vendor

Per una spiegazione dell'output di esempio, vedere quanto segue:

  • La maggior parte dei file sono -rw-rw----, ovvero 660
  • drwxrwx--- = 770
  • -rw-rw-rw- = 666
  • Il proprietario del file system è magento_user

Per ottenere informazioni più dettagliate, è possibile immettere il seguente comando:

ls -la /var/www/html/magento2/pub

Poiché Adobe Commerce distribuisce risorse di file statici nelle sottodirectory di pub, è consigliabile verificare anche le autorizzazioni e la proprietà in tali sottodirectory.

Per ulteriori informazioni, vedere Autorizzazioni e proprietà del file system.

Imposta la directory principale pub/

Per ulteriori dettagli, vedere Modificare la directory principale dei documenti per migliorare la protezione.

Installare il plug-in di aggiornamento Composer

Il plug-in magento/composer-root-update-plugin Composer risolve le modifiche che devono essere apportate al file di progetto principale composer.json prima di eseguire l'aggiornamento a un nuovo requisito di prodotto.

Il plug-in automatizza parzialmente l’aggiornamento manuale identificando e aiutandoti a risolvere i conflitti di dipendenza invece di richiedere di identificarli e correggerli manualmente.

Per installare il plug-in:

  1. Aggiungi il pacchetto al file composer.json.

    code language-bash 
    composer require magento/composer-root-update-plugin ~2.0 --no-update

  2. Aggiornare le dipendenze:

    code language-bash 
    composer update
recommendation-more-help
83a60e0e-8849-4685-a8cd-c129ecd795ea