Completare i prerequisiti per l’aggiornamento

È importante comprendere cosa è necessario per eseguire Adobe 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
  • Imposta il limite di 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 l'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 versione 2.4.6, utilizzare il valore elasticsearch7 per il motore 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.

MariaDB

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

È necessario installare e configurare Elasticsearch 7.6 o versione successiva o OpenSearch 1.2 prima di eseguire l’aggiornamento a 2.4.0. 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 dell'Elasticsearch a una versione supportata.

Consulta l'Elasticsearch sull'aggiornamento 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 dell'Elasticsearch, potrebbe essere necessario o meno un riavvio completo del cluster.

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

OpenSearch

OpenSearch è un fork open-source di Elasticsearch 7.10.2, a seguito della modifica delle licenze di Elasticsearch. Nelle seguenti versioni di Adobe Commerce è stato introdotto 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

È possibile migrare da Elasticsearch a OpenSearch solo se si esegue l'aggiornamento a una versione di Adobe Commerce elencata sopra (o successiva).

OpenSearch richiede JDK 1.8 o versione successiva. 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.

Elasticsearch di aggiornamento

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

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

  2. Abilitare 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 l'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
    
  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
    

Elasticsearch di downgrade

Se aggiorni inavvertitamente la versione di Elasticsearch sul server o stabilisci che devi 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 operativo. 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.

L'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 funzionalità richiedono almeno un processo cron in esecuzione come proprietario del file system.

Per verificare che il processo cron sia configurato correttamente, controllare la scheda cronica immettendo il comando seguente come proprietario del file system:

NOTE
Crontab è il file di configurazione responsabile dell'esecuzione dei processi cron.
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 in Admin:

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

Per ulteriori informazioni, vedere Configurare ed eseguire cron.

Imposta DATA_CONVERTER_BATCH_SIZE

Adobe 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, puoi annullare l’impostazione della variabile:

    code language-bash
    unset DATA_CONVERTER_BATCH_SIZE
    

Verificare le autorizzazioni del file system

Per motivi di sicurezza, Adobe Commerce richiede determinate autorizzazioni sul file system. Le autorizzazioni sono diverse da proprietà. La proprietà determina chi può eseguire azioni sul file system; le autorizzazioni determinano ciò che l’utente può fare.

Le directory nel file system devono essere scrivibili dal gruppo 🔗 del 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