Uppgradera Commerce

Du kan uppgradera Adobe Commerce kodbas till en nyare version. Innan du uppgraderar ditt projekt bör du läsa Systemkraven i installationshandboken för att få information om de senaste programvaruversionskraven.

Beroende på din projektkonfiguration kan din uppgradering innehålla följande:

  • Uppdateringstjänster - som MariaDB (MySQL), OpenSearch, RabbitMQ och Redis - för kompatibilitet med nya Adobe Commerce-versioner.
  • Konvertera en äldre konfigurationshanteringsfil.
  • Uppdatera filen .magento.app.yaml med nya inställningar för kopplingar och miljövariabler.
  • Uppgradera tillägg från tredje part till den senaste version som stöds.
  • Uppdatera filen .gitignore.
TIP
Innan du påbörjar en uppgradering eller en korrigeringsprocess skapar du en aktiv gren i integreringsmiljön och checkar ut den nya grenen till din lokala arbetsstation. Genom att dedikera en gren till uppgraderingen eller korrigeringsprocessen undviker du störningar i pågående arbete.
TIP
För Pro-projekt måste du skicka en Adobe Commerce Support-biljett om du bara vill installera eller uppdatera tjänster i Staging- och Production-miljöer.
Ange vilka tjänständringar som krävs, inkludera dina uppdaterade .magento.app.yaml- och services.yaml-filer och ange PHP-versionen i biljetten. Om du vill göra ändringar i PHP-version, tillägg eller miljöinställningar för självbetjäning läser du PHP-inställningar i Programkonfiguration.
Om du vill ändra en live-produktionsmiljö (endast för Pro) måste du ange minst 48 timmars varsel för att molninfrastrukturteamet ska få tillräckligt med tid för att dela resurser och genomföra en säker uppgradering.

Uppgradera från äldre versioner

Om du påbörjar en uppgradering från en version av Commerce som är äldre än 2.1 kan vissa begränsningar i Adobe Commerce kodbas påverka din möjlighet att uppdatera till en specifik ECE-verktygsversion eller att uppgradera till nästa version av Commerce som stöds. Använd följande tabell för att fastställa den bästa banan:

Aktuell version
Uppgraderingssökväg
2.1.3 och tidigare versioner
Uppgradera Adobe Commerce till version 2.1.4 eller senare innan du fortsätter. Utför sedan en engångsuppgradering för att installera ECE-Tools.
2.1.4 - 2.1.14
Uppdatera ECE-verktygspaket.
Se versionsinformation för 2002.0.9 och senare versioner av 2002.0.x.
2.1.15 - 2.1.16
Uppdatera ECE-verktygspaket.
Se versionsinformation för 2002.0.9 och senare.
2.2.x och senare
Uppdatera ECE-verktygspaket.
Se versionsinformation för 2002.0.8 och senare.
NOTE
Om du använder en version av Adobe Commerce i molninfrastrukturen som inte innehåller paketet ece-tools måste du utföra en engångsuppgradering till ditt molnprojekt för att ta bort föråldrade paket. Om du för närvarande använder paketet ece-tools och behöver uppdatera det, se Uppdatera paketet ECE-Tools.

Konfigurationshantering

Äldre versioner av Adobe Commerce, som 2.1.4 eller senare till 2.2.x eller senare, använde en config.local.php-fil för Configuration Management. I Adobe Commerce version 2.2.0 och senare används filen config.php, som fungerar exakt som filen config.local.php men som har olika konfigurationsinställningar som innehåller en lista över aktiverade moduler och ytterligare konfigurationsalternativ.

När du uppgraderar från en äldre version måste du migrera filen config.local.php för att kunna använda den nyare filen config.php. Gör så här för att säkerhetskopiera konfigurationsfilen och skapa en.

Så här skapar du en tillfällig config.php fil:

  1. Skapa en kopia av filen config.local.php och ge den namnet config.php.

  2. Lägg till den här filen i mappen app/etc i ditt projekt.

  3. Lägg till och implementera filen på din gren.

  4. Skicka filen till din integrationsgren.

  5. Fortsätt med uppgraderingsprocessen.

WARNING
När du har uppgraderat kan du ta bort filen config.php och generera en ny, fullständig fil. Du kan bara ta bort den här filen om du vill ersätta den här gången. När du har genererat en ny, fullständig config.php-fil kan du inte ta bort filen för att skapa en ny. Se Konfigurationshantering och distribution av pipeline.

Verifiera Zend Framework Composer-beroenden

När du uppgraderar till 2.3.x eller senare från 2.2.x kontrollerar du att Zend Framework-beroenden har lagts till i autoload -egenskapen för composer.json-filen som stöder Laminas. Denna plugin stöder nya krav för Zend Framework, som har migrerat till Laminas-projektet. Se Migrering av Zend Framework till Laminas ProjectMagento DevBlog.

Så här kontrollerar du auto-load:psr-4-konfigurationen:

  1. Byt till din projektkatalog på din lokala arbetsstation.

  2. Ta en titt på er integreringsgren.

  3. Öppna filen composer.json i en textredigerare.

  4. Kontrollera avsnittet autoload:psr-4 för Zend plugin-hanterarimplementering för styrenheternas beroende.

    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. Om Zend-beroendet saknas uppdaterar du filen composer.json:

    • Lägg till följande rad i avsnittet autoload:psr-4.

      code language-json
      "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"
      
    • Uppdatera projektberoenden.

      code language-bash
      composer update
      
    • Lägg till, implementera och push-ändra kod.

      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>
      
    • Sammanfoga ändringarna i mellanlagringsmiljön och sedan till Produktion.

Konfigurationsfiler

Innan du uppgraderar programmet måste du uppdatera dina projektkonfigurationsfiler så att de tar hänsyn till ändringar av standardkonfigurationsinställningarna för Adobe Commerce i molninfrastrukturen eller för programmet. De senaste standardvärdena finns i GitHub-databasen magento-cloud.

.magento.app.yaml

Granska alltid värdena i filen .magento.app.yaml för den installerade versionen, eftersom den styr hur programmet bygger och distribuerar till molninfrastrukturen. Följande exempel är för version 2.4.7 och använder Composer 2.7.2. Egenskapen build: flavor: används inte för Composer 2.x; se Installera och använda Composer 2.

Så här uppdaterar du .magento.app.yaml-filen:

  1. Byt till din projektkatalog på din lokala arbetsstation.

  2. Öppna och redigera filen magento.app.yaml.

  3. Uppdatera PHP-alternativen.

    code language-yaml
    type: php:8.3
    
    build:
        flavor: none
    dependencies:
        php:
            composer/composer: '2.7.2'
    
  4. Ändra kommandona för hooks-egenskapen build och deploy.

    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. Lägg till följande miljövariabler i slutet av filen.

    För Adobe Commerce 2.2.x till 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'
    

    För 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. Spara filen. Verkställ eller skicka inga ändringar till fjärrmiljön än.

  7. Fortsätt med uppgraderingsprocessen.

composer.json

Kontrollera alltid att beroendena i filen composer.json är kompatibla med Adobe Commerce-versionen innan du uppgraderar.

Så här uppdaterar du composer.json-filen för Adobe Commerce version 2.4.4 och senare:

  1. Lägg till följande allow-plugins i avsnittet config:

    code language-json
    "config": {
       "allow-plugins": {
          "dealerdirect/phpcodesniffer-composer-installer": true,
          "laminas/laminas-dependency-plugin": true,
          "magento/*": true
       }
    },
    
  2. Lägg till följande plugin-program i avsnittet require:

    code language-json
    "require": {
        "magento/composer-root-update-plugin": "^2.0.3"
    },
    
  3. Lägg till följande komponent i avsnittet extra:component_paths:

    code language-json
    "extra": {
       "component_paths": {
          "tinymce/tinymce": "lib/web/tiny_mce_5"
       },
    },
    
  4. Spara filen. Verkställ eller skicka inte ändringar till din gren än.

  5. Fortsätt med uppgraderingsprocessen.

Säkerhetskopiering av projekt

Vi rekommenderar att du skapar en säkerhetskopia av ditt projekt före en uppgradering. Gör så här för att säkerhetskopiera integrerings-, mellanlagrings- och produktionsmiljöer.

Så här säkerhetskopierar du databasen och koden för integreringsmiljön:

  1. Skapa en lokal säkerhetskopia av fjärrdatabasen.

    code language-bash
    magento-cloud db:dump
    
    note note
    NOTE
    Kommandot magento-cloud db:dump kör kommandot mysqldump med flaggan --single-transaction som gör att du kan säkerhetskopiera databasen utan att låsa tabellerna.
  2. Säkerhetskopiera kod och media.

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

    Du kan också utelämna [--media] om du har ett stort antal statiska filer som redan finns i källkontrollen.

Så här säkerhetskopierar du databasen för förproduktionsmiljö eller produktionsmiljö innan du distribuerar:

  1. Använd SSH för att logga in i fjärrmiljön.

  2. Skapa en databasdump. Om du vill välja en målkatalog för DB-dumpen använder du alternativet --dump-directory.

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

    Dumpningsåtgärden skapar en dump-<timestamp>.sql.gz-arkivfil i fjärrprojektkatalogen. Se Säkerhetskopiera databas.

Programuppgradering

Granska informationen om tjänstversionerna för de senaste programversionskraven innan du uppgraderar ditt program.

Så här uppgraderar du programversionen:

  1. Byt till din projektkatalog på din lokala arbetsstation.

  2. Ange uppgraderingsversionen med syntaxen för versionsbegränsning.

    code language-bash
    composer require "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update
    
    note note
    NOTE
    Du måste använda syntaxen för versionsbegränsning för att kunna uppdatera paketet ece-tools. Du hittar versionsbegränsningen i filen composer.json för den version av programmallen som du använder för uppgraderingen.
  3. Uppdatera projektet.

    code language-bash
    composer update
    
  4. Lägg till, implementera och push-ändra kod.

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

    git add -A krävs för att lägga till alla ändrade filer i källkontrollen på grund av hur Composer konverterar baspaket. Både composer install och composer update konverterar filer från baspaketet (magento/magento2-base och magento/magento2-ee-base) till paketroten.

    De filer som Composer konverterar tillhör den nya versionen av Adobe Commerce, som skriver över den gamla versionen av samma filer. För närvarande är konvertering inaktiverat i Adobe Commerce, så du måste lägga till de konverterade filerna i källkontrollen.

  5. Vänta tills distributionen är klar.

  6. Verifiera uppgraderingen i integrerings-, mellanlagrings- eller produktionsmiljön genom att använda SSH för att logga in och kontrollera versionen.

    code language-bash
    php bin/magento --version
    

Skapa filen config.php

Som nämndes i Konfigurationshantering måste du skapa en uppdaterad config.php-fil efter uppgraderingen. Slutför eventuella ytterligare konfigurationsändringar via administratören i din integreringsmiljö.

Så här skapar du en systemspecifik konfigurationsfil:

  1. Använd ett SSH-kommando från terminalen för att generera filen /app/etc/config.php för miljön.

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

    Om du till exempel vill köra scd-dump på grenen integration i Pro:

    code language-bash
    ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/ece-tools config:dump"
    
  2. Överför filen config.php till dina lokala arbetsstationer med rsync eller scp. Du kan bara lägga till den här filen lokalt i grenen.

    code language-bash
    rsync <SSH-URL>:app/etc/config.php ./app/etc/config.php
    
  3. Lägg till, implementera och push-ändra kod.

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

    Detta genererar en uppdaterad /app/etc/config.php-fil med en modullista och konfigurationsinställningar.

WARNING
Om du vill uppgradera tar du bort filen config.php. När den här filen har lagts till i koden ska du inte ta bort den. Om du måste ta bort eller redigera inställningar redigerar du filen manuellt.

Uppgradera tillägg

Granska tillägg- och modulsidor från tredje part på Marketplace eller andra företagswebbplatser och verifiera stödet för Adobe Commerce och Adobe Commerce i molninfrastrukturen. Om du måste uppgradera tillägg och moduler från tredje part rekommenderar Adobe att du arbetar i en ny integreringsgren med dina tillägg inaktiverade.

Så här verifierar och uppgraderar du dina tillägg:

  1. Skapa en gren på din lokala arbetsstation.

  2. Inaktivera tilläggen efter behov.

  3. Ladda ned tilläggsuppgraderingar när de blir tillgängliga.

  4. Installera uppgraderingen enligt dokumentationen från tredje part.

  5. Aktivera och testa tillägget.

  6. Lägg till, implementera och skicka kodändringarna till fjärrkontrollen.

  7. Kör till och testa i er integreringsmiljö.

  8. Kör till mellanlagringsmiljön för att testa i en förproduktionsmiljö.

Adobe rekommenderar starkt att du uppgraderar din produktionsmiljö före, inklusive de uppgraderade tilläggen i din webbplatsstartprocess.

NOTE
När du uppgraderar din programversion uppdateras uppgraderingsprocessen automatiskt till den senaste versionen av modulen Snabbt CDN .

Felsök uppgraderingen

Om uppgraderingen misslyckades får du ett felmeddelande i webbläsaren om att du inte kan komma åt butiken eller administrationspanelen:

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

Så här löser du felet:

  1. Byt till din projektkatalog på din lokala arbetsstation.

  2. Använd SSH för att logga in i fjärrmiljön.

    code language-bash
    magento-cloud ssh
    
  3. Öppna filen ./app/var/report/<error number>.

  4. Granska loggarna och ta reda på orsaken till problemet.

  5. Lägg till, implementera och push-ändra kod.

    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