DocumentatieCommerceUpgradehandleiding

[Alleen PaaS]{class="badge informative" title="Is alleen van toepassing op Adobe Commerce op Cloud-projecten (door Adobe beheerde PaaS-infrastructuur) en op projecten in het veld."}

Volledige upgradevoorwaarden

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

Gemaakt voor:

  • Ervaren
  • Beheerder
  • Ontwikkelaar

Het is belangrijk te begrijpen wat nodig is om Adobe Commerce te runnen. U moet eerst de systeemvereistenvoor de versie herzien u van plan bent te bevorderen aan.

Nadat u de systeemvereisten hebt gecontroleerd, moet u aan de volgende voorwaarden voldoen voordat u de upgrade van uw systeem uitvoert:

  • Alle software bijwerken
  • Controleren of een ondersteund zoekprogramma is geïnstalleerd
  • Database-tabelindeling converteren
  • Limiet voor geopende bestanden instellen
  • Controleren of uitsnijdtaken worden uitgevoerd
  • Instellen DATA_CONVERTER_BATCH_SIZE
  • Controleren op bestandssysteemmachtigingen
  • De pub/ hoofdmap instellen
  • Installeer de Composer update plugin

Alle software bijwerken

De systeemvereistenbeschrijven precies welke versies van derdesoftware met de versies van Adobe Commerce zijn getest.

Zorg ervoor dat u alle systeemvereisten en afhankelijkheden in uw omgeving hebt bijgewerkt. Zie PHP 7.4, PHP 8.0, PHP 8.1, en vereiste PHP montages.

NOTE
Voor Adobe Commerce op de Pro projecten van de wolkeninfrastructuur, moet u a 🔗 kaartje van de Steun {creëren 0} om de diensten in het Opvoeren en van de Productie milieu's te installeren of bij te werken. Geef aan welke servicewijzigingen nodig zijn en neem de bijgewerkte .magento.app.yaml - en services.yaml -bestanden en PHP-versie op in het ticket. Het kan tot 48 uur duren voordat het infrastructuurteam van de cloud uw project kan bijwerken. Zie Ondersteunde software en de diensten.

Controleer of een ondersteunde zoekmachine is geïnstalleerd

Adobe Commerce vereist dat Elasticsearch of OpenSearch is geïnstalleerd om de software te kunnen gebruiken.

als u van 2.3.x aan 2.4 bevordert, moet u controleren of u MySQL, Elasticsearch, of een derdeuitbreiding als uw motor van de catalogusonderzoek in uw 2.3.x instantie gebruikt. Het resultaat bepaalt wat u vóór bevordering aan 2.4 moet doen.

als u flardversies binnen de 2.3.x of 2.4.x versielijnen bevordert, als Elasticsearch 7.x reeds geïnstalleerd is, kunt u naar keuze migreren aan OpenSearch.

U kunt de opdrachtregel of de beheerder gebruiken om de zoekengine voor de catalogus te bepalen:

  • Voer de bin/magento config:show catalog/search/engine opdracht in. De opdracht retourneert een waarde van mysql, elasticsearch (die aangeeft dat Elasticsearch 2 is geconfigureerd), elasticsearch5, elasticsearch6, elasticsearch7of een aangepaste waarde, die aangeeft dat u een zoekmachine van derden hebt geïnstalleerd. Voor versies ouder dan 2.4.6 gebruikt u de elasticsearch7 waarde voor de Elasticsearch 7- of OpenSearch-engine. Gebruik voor versie 2.4.6 en hoger de opensearch waarde voor de OpenSearch-engine.

  • Controleer in de beheerder de waarde van het Stores > Settings > Configuration > Catalog > Catalog > Catalog Search > Search Engine veld.

In de volgende secties wordt beschreven welke acties u moet ondernemen voordat u een upgrade naar 2.4.0 uitvoert.

MySQL

Vanaf 2.4, is MySQL niet meer een gesteunde motor van de catalogusonderzoek. U moet Elasticsearch of OpenSearch installeren en configureren voordat u een upgrade uitvoert. Gebruik de volgende bronnen om u door dit proces te begeleiden:

Bepaalde zoekprogramma's voor catalogi van derden worden boven op de zoekfunctie van Adobe Commerce uitgevoerd. Neem contact op met de leverancier om te bepalen of u de extensie moet bijwerken.

Wijzigingen in MySQL 8.4

Adobe heeft in de release 2.4.8 ondersteuning toegevoegd voor MySQL 8.4.
Deze sectie beschrijft belangrijke veranderingen in MySQL 8.4 dat de ontwikkelaars zich van bewust zouden moeten zijn.

Vervangen niet-standaardsleutel

Het gebruik van niet-unieke of gedeeltelijke sleutels als refererende sleutels is niet-standaard en wordt afgeschaft in MySQL 8.4. Vanaf MySQL 8.4.0 moet u dergelijke sleutels expliciet inschakelen door deze in te stellen restrict_fk_on_non_standard_key op OFF, of door de server te starten met de --skip-restrict-fk-on-non-standard-key optie.

Upgraden van MySQL 8.0 (of oudere versies) naar MySQL 8.4

Om MySQL correct te upgraden van versie 8.0 naar versie 8.4, moet u de volgende stappen volgen:

  1. Onderhoudsmodus inschakelen:

    code language-bash 
    bin/magento maintenance:enable

  2. Maak een back-up van de database:

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

  3. Upgrade MySQL naar versie 8.4.

  4. Stel restrict_fk_on_non_standard_key in op OFF in [mysqld] in het my.cnf -bestand.

    code language-bash 
    [mysqld]
restrict_fk_on_non_standard_key = OFF
    note warning
    WARNING
    Als u de waarde van restrict_fk_on_non_standard_key niet wijzigt in OFF , treedt de volgende fout op tijdens het importeren:
    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. Start de MySQL-server opnieuw.

  5. Importeer de back-upgegevens in MySQL.

  6. De cache reinigen:

    code language-bash 
    bin/magento cache:clean

  7. Onderhoudsmodus uitschakelen:

    code language-bash 
    bin/magento maintenance:disable

MariaDB

[Alleen PaaS]{class="badge informative" title="Is alleen van toepassing op Adobe Commerce op Cloud-projecten (door Adobe beheerde PaaS-infrastructuur) en op projecten in het veld."}

Het opnieuw indexeren op MariaDB 10.4 en 10.6 vergt meer tijd in vergelijking met vorige versies MariaDB of MySQL. Om het opnieuw indexeren te versnellen, adviseren wij plaatsend deze MariaDB configuratieparameters:

Als u prestatiesdegradatie niet verwant met indexatie na bevordering aan MariaDB 10.6 ervaart, denk na toelatend het --query-cache-typeplaatsen. Bijvoorbeeld --query-cache-type=ON .

Alvorens Adobe Commerce op de projecten van de wolkeninfrastructuur te bevorderen, kunt u ook MariaDB moeten bevorderen ( zie MariaDB beste praktijkenbevorderen).

Bijvoorbeeld:

  • Adobe Commerce 2.4.6 met MariaDB versie 10.5.1 of hoger
  • Adobe Commerce 2.3.5 met MariaDB versie 10.3 of lager

Naast deze aanbevelingen, zou u met uw gegevensbestandbeheerder over het vormen van de volgende parameters moeten raadplegen:

NOTE
Deze montages zijn beschikbaar voor op-gebouw slechts plaatsingen. Adobe Commerce op klanten met cloudinfrastructuur hebben geen toegang tot deze instellingen.

Zoekmachine

U moet Elasticsearch 7.6 of hoger of OpenSearch 1.2 installeren en configureren voordat u de upgrade naar 2.4.0 uitvoert. Adobe biedt niet langer ondersteuning voor Elasticsearch 2.x, 5.x en 6.x. de motorconfiguratie van het Onderzoekin de Gids van de Configuratie beschrijft de taken u na de bevordering van Elasticsearch aan een gesteunde versie moet uitvoeren.

Verwijs naar Bevorderend Elasticsearchvoor volledige instructies bij het steunen van uw gegevens, het ontdekken van potentiële migratiekwesties, en het testen van verbeteringen alvorens aan productie op te stellen. Afhankelijk van uw huidige versie van Elasticsearch is het mogelijk dat een volledige cluster opnieuw moet worden opgestart.

Elasticsearch vereist Java Development Kit (JDK) 1.8 of hoger. Zie de Uitrusting van de Ontwikkeling van de Software van Java installeren (JDK)om te controleren welke versie van JDK geïnstalleerd is.

OpenSearch

OpenSearch is een open-source vork van Elasticsearch 7.10.2, na de licentiewijziging van Elasticsearch. In de volgende versies van Adobe Commerce wordt ondersteuning voor OpenSearch geïntroduceerd:

  • 2.4.6 (OpenSearch heeft een aparte module en instellingen)
  • 2.4.5.
  • 2.4.4.
  • 2.4.3-p2
  • 2.3.7-p3

U kunt migreren van Elasticsearch aan OpenSearchslechts als u aan een versie van hierboven vermelde Adobe Commerce (of hoger) bevordert.

Voor OpenSearch is JDK 1.8 of hoger vereist. Zie de Uitrusting van de Ontwikkeling van de Software van Java installeren (JDK)om te controleren welke versie van JDK geïnstalleerd is.

de motorconfiguratie van het Onderzoekbeschrijft de taken u na het veranderen van onderzoeksmotoren moet uitvoeren.

Upgrade uitvoeren voor Elasticsearch

Elasticsearch 8.x werd in Adobe Commerce 2.4.6 ondersteund. De volgende instructies tonen een voorbeeld van het upgraden van Elasticsearch van 7.x naar 8.x:

NOTE
In de aanstaande versie 2.4.8, zullen deze stappen niet noodzakelijk zijn omdat Elasticsearch 8 module door gebrek inbegrepen is en u zult niet het moeten afzonderlijk installeren.

  1. Upgrade de Elasticsearch 7.x server naar 8.x en zorg ervoor dat deze actief is. Zie de documentatie van Elasticsearch.

  2. Schakel het veld id_field_data in door de volgende configuratie aan uw elasticsearch.yml -bestand toe te voegen en de Elasticsearch 8.x-service opnieuw te starten.

    code language-yaml 
    indices:
  id_field_data:
    enabled: true
    note info
    INFO
    Ter ondersteuning van Elasticsearch 8.x wordt in Adobe Commerce 2.4.6 de eigenschap indices.id_field_data standaard uitgeschakeld en wordt het veld _id in de eigenschap docvalue_fields gebruikt.

  3. Werk in de hoofdmap van uw Adobe Commerce-project uw Composer-afhankelijkheden bij om de module Magento_Elasticsearch7 te verwijderen en de module Magento_Elasticsearch8 te installeren.

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

    Als u een gebiedsdeelfout voor psr/http-message ontmoet, klik om de volgende het oplossen van problemensectie uit te breiden:

    accordion
    Problemen oplossen

    Als er afhankelijkheidsconflicten optreden tijdens de installatie van Elasticsearch 8, met name met psr/http-message , kunt u dit oplossen door de volgende stappen uit te voeren:

    1. Ten eerste hebt u de Elasticsearch 8-module nodig zonder andere afhankelijkheden bij te werken:

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

    2. Werk vervolgens de Elasticsearch 8-module en aws/aws-sdk-php -pakketten bij:

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

    Deze aanpak werkt voor 2.4.7-p4 met PHP 8.3. Het probleem doet zich voor omdat aws/aws-sdk-php psr/http-message >= 2.0 vereist, wat conflicten kan veroorzaken. De bovenstaande stappen helpen deze afhankelijkheidsproblemen op te lossen.

  4. Werk uw projectcomponenten bij.

    code language-bash 
    bin/magento setup:upgrade

  5. Configureer Elasticsearch in de Admin.

  6. Indexeer de catalogusindex opnieuw.

    code language-bash 
    bin/magento indexer:reindex catalogsearch_fulltext

  7. Verwijder alle items uit de ingeschakelde cachetypen.

    code language-bash 
    bin/magento cache:clean

Elasticsearch downgraden

Als u onbedoeld de versie van Elasticsearch op uw server verbetert of om een andere reden bepaalt dat u moet degraderen, moet u ook uw Adobe Commerce-projectgebiedsdelen bijwerken. Bijvoorbeeld om van Elasticsearch 8.x naar 7.x te verlagen

  1. Verlaag de Elasticsearch 8.x-server naar 7.x en zorg ervoor dat deze actief is. Zie de documentatie van Elasticsearch.

  2. Werk in de hoofdmap van uw Adobe Commerce-project uw Composer-afhankelijkheden bij om de module Magento_Elasticsearch8 en de bijbehorende Composer-afhankelijkheden te verwijderen en installeer de module Magento_Elasticsearch7 .

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

  3. Werk uw projectcomponenten bij.

    code language-bash 
    bin/magento setup:upgrade

  4. vorm Elasticsearchin Admin.

  5. Indexeer de catalogusindex opnieuw.

    code language-bash 
    bin/magento indexer:reindex catalogsearch_fulltext

  6. Verwijder alle items uit de ingeschakelde cachetypen.

    code language-bash 
    bin/magento cache:clean

Extensies van derden

We raden u aan contact op te nemen met uw leverancier van zoekprogramma's om te bepalen of uw extensie volledig compatibel is met een Adobe Commerce-versie.

Database-tabelindeling converteren

U moet de indeling van alle databasetabellen omzetten van COMPACT in DYNAMIC . U moet ook het type opslagengine omzetten van MyISAM in InnoDB . Bekijk best practices.

De limiet voor geopende bestanden instellen

Door de limiet voor open bestanden (ulimit) in te stellen, kunt u voorkomen dat er fouten optreden door meerdere recursieve aanroepen van lange queryreeksen of problemen met het gebruik van de bin/magento setup:rollback opdracht. Dit commando is verschillend voor verschillende UNIX-shells. Raadpleeg uw individuele smaak voor meer informatie over het ulimit commando.

Adobe raadt aan om de geopende bestanden u-limit in te stellen op een waarde van 65536 of meer, maar u kunt indien nodig een grotere waarde gebruiken. U kunt de ulimit instellen op de opdrachtregel of u kunt er een permanente instelling van maken voor de shell van de gebruiker.

U stelt de limiet in vanaf de opdrachtregel:

  1. Schakelaar aan de eigenaar van het dossiersysteem.

  2. Stel de limiet in op 65536 .

    code language-bash 
    ulimit -n 65536

De waarde in de Bash-shell instellen:

  1. Schakelaar aan de eigenaar van het dossiersysteem.

  2. Open /home/<username>/.bashrc in een teksteditor.

  3. Voeg de volgende regel toe:

    code language-bash 
    ulimit -n 65536

  4. Sla de wijzigingen op in het .bashrc -bestand en sluit de teksteditor af.

IMPORTANT
We raden u aan geen waarde in te stellen voor de eigenschap pcre.recursion_limit in het php.ini -bestand, omdat dit kan leiden tot onvolledige terugdraaiversies zonder foutmelding.

Controleren of uitsnijdtaken worden uitgevoerd

De UNIX-taakplanner cron is van essentieel belang voor dagelijkse Adobe Commerce-bewerkingen. Het plant dingen zoals het opnieuw indexeren, nieuwsbrieven, e-mail, en sitemaps. Voor verschillende functies is minstens één snijtaak vereist die wordt uitgevoerd als de eigenaar van het bestandssysteem.

Als u wilt controleren of de uitsnijdtaak op de juiste wijze is ingesteld, controleert u de tab door de volgende opdracht in te voeren als de eigenaar van het bestandssysteem:

NOTE
De tab is het configuratiebestand dat verantwoordelijk is voor het uitvoeren van snijtaken.
crontab -l

Resultaten die vergelijkbaar zijn met het volgende, moeten worden weergegeven:

#~ 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

Een ander symptoom van niet-actieve kroon is de volgende fout in de Admin:

de berichten van het Systeem - krong loopt niet

Om de fout te zien, klik Berichten van het Systeem bij de bovenkant van het venster als volgt:

de berichten van het Systeem bericht

Zie uitsnedevoor meer informatie vormen en in werking stellen.

DATA_CONVERTER_BATCH_SIZE instellen

Adobe Commerce 2.4 bevat beveiligingsverbeteringen waarvoor bepaalde gegevens moeten worden omgezet van geserialiseerde gegevens in JSON. Deze conversie vindt plaats tijdens de upgrade en kan lang duren, afhankelijk van de hoeveelheid gegevens in de database.

De volgende tabellen worden het meest beïnvloed:

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

Als u veel gegevens hebt, kunt u de prestaties verbeteren door de waarde van een omgevingsvariabele in te stellen, DATA_CONVERTER_BATCH_SIZE . De waarde wordt standaard ingesteld op 50,000 .

De omgevingsvariabele instellen:

  1. Schakelaar aan de eigenaar van het dossiersysteem.

  2. Stel de variabele in:

    code language-bash 
    export DATA_CONVERTER_BATCH_SIZE=100000
    note note
    NOTE
    Voor DATA_CONVERTER_BATCH_SIZE is geheugen vereist. Stel dit niet in op een grote waarde (ongeveer 1 GB) zonder deze eerst te testen.

  3. Nadat de upgrade is voltooid, kunt u de instelling van de variabele ongedaan maken:

    code language-bash 
    unset DATA_CONVERTER_BATCH_SIZE

Controleren op bestandssysteemmachtigingen

Om veiligheidsredenen vereist Adobe Commerce bepaalde machtigingen voor het bestandssysteem. De toestemmingen zijn verschillend van eigendom. Eigendom bepaalt wie handelingen op het bestandssysteem kan uitvoeren; machtigingen bepalen wat de gebruiker kan doen.

De folders in het dossiersysteem moeten door de 🔗 groep van de eigenaar van het 0} dossiersysteem kunnen worden geschreven.

Om te controleren of de machtigingen voor het bestandssysteem correct zijn ingesteld, meldt u zich aan bij de toepassingsserver of gebruikt u de toepassing van het bestandsbeheer van de hostingprovider.

Voer bijvoorbeeld de volgende opdracht in als de toepassing is geïnstalleerd in /var/www/html/magento2 :

ls -l /var/www/html/magento2

Voorbeelduitvoer:

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

Zie het volgende voor een verklaring van de steekproefoutput:

  • De meeste bestanden zijn -rw-rw---- , dat is 660
  • drwxrwx--- = 770
  • -rw-rw-rw- = 666
  • De eigenaar van het bestandssysteem is magento_user

Als u meer gedetailleerde informatie wilt, voert u de volgende opdracht in:

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

Omdat Adobe Commerce statische bestandselementen naar submappen van pub implementeert, is het een goed idee om ook daar machtigingen en eigendom te controleren.

Voor meer informatie, zie {de systeemtoestemmingen en eigendom van het 0} Dossier 🔗.

De hoofdmap van de map pub/ instellen

Zie docroot wijzigen om veiligheidvoor meer details te verbeteren.

De plug-in Composer-update installeren

De magento/composer-root-update-pluginComposer-plug-in verhelpt wijzigingen die moeten worden aangebracht in het hoofdprojectbestand composer.json voordat de toepassing wordt bijgewerkt naar een nieuwe productvereiste.

De plug-in automatiseert de handmatige upgrade gedeeltelijk door afhankelijkheidsconflicten te identificeren en te helpen oplossen in plaats van deze handmatig te hoeven identificeren en te corrigeren.

De insteekmodule installeren:

  1. Voeg het pakket toe aan het composer.json -bestand.

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

  2. Werk de gebiedsdelen bij:

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