Versie voor upgradeopdracht

U kunt de Adobe Commerce-codebasis upgraden naar een nieuwere versie. Voordat u uw project upgradet, moet u de Systeemvereisten in de Installatie handleiding voor de meest recente vereisten voor softwareversies.

Afhankelijk van uw projectconfiguratie, kunnen uw verbeteringstaken het volgende omvatten:

  • Werk services bij, bijvoorbeeld MariaDB (MySQL), OpenSearch, RabbitMQ en Redis, voor compatibiliteit met nieuwe Adobe Commerce-versies.
  • Converteer een ouder configuratiebeheerbestand.
  • Werk de .magento.app.yaml bestand met nieuwe instellingen voor haken en omgevingsvariabelen.
  • Voer een upgrade uit van externe extensies naar de nieuwste ondersteunde versie.
  • Werk de .gitignore bestand.
TIP
Voordat u met een upgrade of een patchproces begint, maakt u een actieve vertakking vanuit de integratieomgeving en checkt u de nieuwe vertakking uit naar uw lokale werkstation. Als u een vertakking aan de upgrade of het patchproces toewijst, voorkomt u dat uw werk wordt gehinderd.
TIP
Voor Pro-projecten moet u een Adobe Commerce-ondersteuningsticket verzenden installeren of bijwerken diensten in Staging en Production alleen omgevingen.
Geef aan welke servicewijzigingen nodig zijn en neem uw bijgewerkte .magento.app.yaml en services.yaml en geef de PHP-versie op in het ticket. Voor zelfbedieningswijzigingen in PHP-versie, extensies of omgevingen raadpleegt u PHP-instellingen in Toepassingsconfiguratie.
Voor wijzigingen in een leven Productieomgeving (Alleen Pro), moet u een minimale opzegtermijn van 48 uur opgeven om het infrastructuurteam van de cloud voldoende tijd te geven om bronnen te zoeken en een beveiligde upgrade uit te voeren.

Upgrade uitvoeren vanaf oudere versies

Als u een upgrade start vanaf een versie van Commerce die ouder is dan versie 2.1, kunnen sommige beperkingen in de Adobe Commerce-codebasis van invloed zijn op de mogelijkheid om update naar een specifieke ECE-Tools-versie of naar upgrade naar de volgende ondersteunde handelsversie. Gebruik de volgende tabel om het beste pad te bepalen:

Huidige versie
Upgradepad
2.1.3 en eerdere versies
Upgrade Adobe Commerce naar versie 2.1.4 of hoger voordat u verdergaat. Voer vervolgens een eenmalige upgrade voor de installatie van ECE-tools.
2.1.4 - 2.1.14
ECE-gereedschappen bijwerken pakket.
Zie opmerkingen bij de release voor 2002,0,9 en hoger versies van 2002.0.x.
2.1.15 - 2.1.16
ECE-gereedschappen bijwerken pakket.
Zie opmerkingen bij de release voor2002,0,9 en later.
2.2.x en hoger
ECE-gereedschappen bijwerken pakket.
Zie opmerkingen bij de release voor2002,0,8 en later.
NOTE
Als u een versie van Adobe Commerce gebruikt op een cloudinfrastructuur die de ece-tools pakket, dan moet u een eenmalige upgrade naar uw cloud-project om verouderde pakketten te verwijderen. Als u momenteel ece-tools en u moet het pakket bijwerken, zie Het pakket ECE-gereedschappen bijwerken.

Configuratiebeheer

Oudere versies van Adobe Commerce, zoals 2.1.4 of hoger naar 2.2.x of hoger, gebruikten een config.local.php bestand voor configuratiebeheer. Adobe Commerce versie 2.2.0 en hoger config.php bestand, dat precies hetzelfde werkt als het config.local.php bestand, maar het heeft andere configuratie-instellingen die een lijst met de ingeschakelde modules en aanvullende configuratieopties bevatten.

Wanneer u een upgrade uitvoert vanaf een oudere versie, moet u de opdracht config.local.php bestand gebruiken om nieuwer te gebruiken config.php bestand. Gebruik de volgende stappen om een back-up van het configuratiebestand te maken en een bestand te maken.

Een tijdelijke config.php file:

  1. Een kopie maken van config.local.php bestand en noem het bestand config.php.

  2. Dit bestand toevoegen aan de app/etc van uw project.

  3. Voeg het bestand toe en wijs het toe aan uw vertakking.

  4. Verplaats het bestand naar de integratietak.

  5. Ga door met het upgradeproces.

WARNING
Na de upgrade kunt u de config.php en een nieuw, volledig bestand genereren. U kunt dit bestand alleen deze keer verwijderen om het te vervangen. Na het genereren van een nieuwe, volledige config.php kunt u het bestand niet verwijderen om een nieuw bestand te genereren. Zie Configuratiebeheer en implementatie van pijpleidingen.

Afhankelijkheden van Zend Framework-composer verifiëren

Bij upgrade naar 2.3.x of hoger vanaf 2.2.x, controleert u of de afhankelijkheden van het Zend Framework zijn toegevoegd aan de autoload eigendom van de composer.json bestand ter ondersteuning van Laminas. Deze insteekmodule ondersteunt nieuwe vereisten voor het Zend Framework, dat naar het Laminas-project is gemigreerd. Zie Migratie van Zend Framework naar het Laminas-project op de Magento DevBlog.

Als u de opdracht auto-load:psr-4 configuratie:

  1. Wijzig op uw lokale werkstation de projectmap.

  2. Ontdek je integratietak.

  3. Open de composer.json in een teksteditor.

  4. Controleer de autoload:psr-4 voor de Zend plugin manager implementatie voor controlemechanismeafhankelijkheid.

    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. Als de Zend-afhankelijkheid ontbreekt, werkt u de composer.json bestand:

    • Voeg de volgende regel toe aan de autoload:psr-4 sectie.

      code language-json
      "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"
      
    • Werk de projectgebiedsdelen bij.

      code language-bash
      composer update
      
    • Wijzigingen in code toevoegen, vastleggen en doorvoeren.

      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>
      
    • Voeg de wijzigingen in de Staging-omgeving en vervolgens in Production samen.

Configuratiebestanden

Voordat u de toepassing kunt upgraden, moet u de projectconfiguratiebestanden bijwerken om rekening te houden met wijzigingen in de standaardconfiguratie-instellingen voor Adobe Commerce op de cloudinfrastructuur of de toepassing. De meest recente standaardwaarden vindt u in het gedeelte magento-cloud GitHub-opslagplaats.

.magento.app.yaml

Controleer altijd de waarden in het dialoogvenster .magento.app.yaml bestand voor uw geïnstalleerde versie, omdat deze de manier bepaalt waarop uw toepassing wordt gebouwd en geïmplementeerd in de cloudinfrastructuur. Het volgende voorbeeld is voor versie 2.4.7 en gebruikt Composer 2.7.2. De build: flavor: eigenschap wordt niet gebruikt voor Composer 2.x; zie Composer 2 installeren en gebruiken.

Als u het dialoogvenster .magento.app.yaml file:

  1. Wijzig op uw lokale werkstation de projectmap.

  2. Open en bewerk de magento.app.yaml bestand.

  3. Werk de PHP-opties bij.

    code language-yaml
    type: php:8.3
    
    build:
        flavor: none
    dependencies:
        php:
            composer/composer: '2.7.2'
    
  4. Wijzig de hooks eigenschap build en deploy opdrachten.

    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. Voeg de volgende omgevingsvariabelen toe aan het einde van het bestand.

    Voor Adobe Commerce 2.2.x tot en met 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'
    

    Voor 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. Sla het bestand op. Breng nog geen wijzigingen aan in de externe omgeving.

  7. Ga door met het upgradeproces.

composer.json

Controleer vóór de upgrade altijd of de afhankelijkheden in de composer.json zijn compatibel met de Adobe Commerce-versie.

Als u het dialoogvenster composer.json bestand voor Adobe Commerce versie 2.4.4 en hoger:

  1. Voeg het volgende toe allow-plugins aan de config sectie:

    code language-json
    "config": {
       "allow-plugins": {
          "dealerdirect/phpcodesniffer-composer-installer": true,
          "laminas/laminas-dependency-plugin": true,
          "magento/*": true
       }
    },
    
  2. Voeg de volgende plug-in toe aan de require sectie:

    code language-json
    "require": {
        "magento/composer-root-update-plugin": "^2.0.3"
    },
    
  3. Voeg de volgende component aan toe extra:component_paths sectie:

    code language-json
    "extra": {
       "component_paths": {
          "tinymce/tinymce": "lib/web/tiny_mce_5"
       },
    },
    
  4. Sla het bestand op. Wijzig de vertakking nog niet en duw er nog niet op.

  5. Ga door met het upgradeproces.

Projectback-up

We raden u aan een back-up van uw project te maken voordat u de upgrade uitvoert. Gebruik de volgende stappen om een back-up te maken van uw integratie-, staging- en productieomgevingen.

Een back-up maken van de database en code van uw integratieomgeving:

  1. Maak een lokale back-up van de externe database.

    code language-bash
    magento-cloud db:dump
    
    note note
    NOTE
    De magento-cloud db:dump bevel stelt het bevel in werking mysqldump gebruiken met de --single-transaction markering, die u aan file uw gegevensbestand toestaat zonder de lijsten te sluiten.
  2. Maak een back-up van code en media.

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

    U kunt desgewenst weglaten [--media] als u een groot aantal statische dossiers hebt die reeds in broncontrole zijn.

Om een back-up te maken van uw milieu-database voor Staging of Productie voordat u deze implementeert:

  1. Gebruik SSH om u aan te melden bij de externe omgeving.

  2. Een databasedruk. Om een doelfolder voor de stortplaats van DB te kiezen, gebruik --dump-directory -optie.

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

    De stortplaatsverrichting leidt tot een dump-<timestamp>.sql.gz archiefbestand in uw externe projectmap. Zie Back-up van database maken.

Toepassingsupgrade

Controleer de serviceversies informatie voor de meest recente vereisten voor softwareversies voordat u uw toepassing upgradet.

De toepassingsversie upgraden:

  1. Wijzig op uw lokale werkstation de projectmap.

  2. De upgradeversie instellen met de syntaxis voor versiebeperking.

    code language-bash
    composer require "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update
    
    note note
    NOTE
    U moet de syntaxis van de versiebeperking gebruiken om de ece-tools pakket. U kunt de versiebeperking vinden in de composer.json bestand voor de versie van het toepassingssjabloon u gebruikt voor de upgrade.
  3. Werk het project bij.

    code language-bash
    composer update
    
  4. Wijzigingen in code toevoegen, vastleggen en doorvoeren.

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

    git add -A is vereist om alle veranderde dossiers aan broncontrole wegens de manier toe te voegen Composer basispakketten marshals. Beide composer install en composer update marshal-bestanden uit het basispakket (magento/magento2-base en magento/magento2-ee-base) in de hoofdmap van het pakket.

    De bestanden die Composer marshals hebben, horen bij de nieuwe versie van Adobe Commerce, om de verouderde versie van dezelfde bestanden te overschrijven. Op dit moment is het rangschikken in Adobe Commerce uitgeschakeld, dus u moet de gemarcheerde bestanden toevoegen aan bronbesturing.

  5. Wacht tot de implementatie is voltooid.

  6. Verifieer de verbetering in uw Integratie, het Staging, of milieu van de Productie door SSH te gebruiken om login en de versie te controleren.

    code language-bash
    php bin/magento --version
    

Een bestand config.php maken

Zoals vermeld in Configuratiebeheer, na de upgrade moet u een bijgewerkte config.php bestand. Voltooi eventuele aanvullende configuratiewijzigingen via de beheerfunctie in uw integratieomgeving.

Een systeemspecifiek configuratiebestand maken:

  1. Van de terminal, gebruik een bevel van SSH om te produceren /app/etc/config.php bestand voor de omgeving.

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

    Bijvoorbeeld voor Pro, om scd-dump op de integration vertakking:

    code language-bash
    ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/ece-tools config:dump"
    
  2. Breng de config.php bestand naar uw lokale werkstations met rsync of scp. U kunt dit bestand alleen lokaal aan de vertakking toevoegen.

    code language-bash
    rsync <SSH-URL>:app/etc/config.php ./app/etc/config.php
    
  3. Wijzigingen in code toevoegen, vastleggen en doorvoeren.

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

    Hiermee wordt een bijgewerkte versie gegenereerd /app/etc/config.php bestand met een modulelijst en configuratie-instellingen.

WARNING
Voor een upgrade verwijdert u het dialoogvenster config.php bestand. Nadat dit bestand aan de code is toegevoegd, moet u niet verwijderen. Als u instellingen moet verwijderen of bewerken, bewerkt u het bestand handmatig.

Extensies upgraden

Bekijk de extensie- en modulepagina's van derden in Marketplace of andere bedrijfssites en controleer de ondersteuning voor Adobe Commerce en Adobe Commerce op cloudinfrastructuur. Als u extensies en modules van derden moet bijwerken, raadt de Adobe aan te werken in een nieuwe integratievertakking met uw extensies uitgeschakeld.

Uw extensies verifiëren en upgraden:

  1. Maak een vertakking op uw lokale werkstation.

  2. Schakel de extensies desgewenst uit.

  3. Indien beschikbaar, downloadextensies voor upgrades.

  4. Installeer de upgrade zoals wordt beschreven in de documentatie van derden.

  5. Schakel de extensie in en test deze.

  6. Voeg de wijzigingen aan de externe code toe, wijs deze aan en duw erop.

  7. Zet uw integratieomgeving aan en test deze.

  8. Druk op de testomgeving om te testen in een pre-productieomgeving.

Adobe beveelt ten zeerste aan uw productieomgeving te upgraden voor inclusief de bijgewerkte extensies in het startproces van uw site.

NOTE
Wanneer u uw toepassingsversie verbetert, werkt het verbeteringsproces aan de recentste versie van het Fastly CDN-module automatisch.

Upgrade problemen oplossen

Als de upgrade is mislukt, ontvangt u een foutbericht in de browser waarin wordt aangegeven dat u geen toegang hebt tot uw winkel of het deelvenster Beheer:

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

De fout oplossen:

  1. Wijzig op uw lokale werkstation de projectmap.

  2. Gebruik SSH om u aan te melden bij de externe omgeving.

    code language-bash
    magento-cloud ssh
    
  3. Open de ./app/var/report/<error number> bestand.

  4. De logboeken controleren en bepaalt u de bron van de uitgave.

  5. Wijzigingen in code toevoegen, vastleggen en doorvoeren.

    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