Commerce-Version aktualisieren

Sie können die Adobe Commerce-Code-Basis auf eine neuere Version aktualisieren. Bevor Sie Ihr Projekt aktualisieren, lesen Sie Systemanforderungen im Installationshandbuch, um die neuesten Anforderungen an die Softwareversion zu ermitteln.

Abhängig von Ihrer Projektkonfiguration können Ihre Upgrade-Aufgaben Folgendes umfassen:

  • Aktualisierungsdienste wie MariaDB (MySQL), OpenSearch, RabbitMQ und Redis für die Kompatibilität mit neuen Adobe Commerce-Versionen.
  • Konvertieren Sie eine ältere Konfigurationsverwaltungsdatei.
  • Aktualisieren Sie die .magento.app.yaml Datei mit neuen Einstellungen für Erweiterungspunkte und Umgebungsvariablen.
  • Aktualisieren Sie Erweiterungen von Drittanbietern auf die neueste unterstützte Version.
  • Aktualisieren Sie die .gitignore.
TIP
Bevor Sie mit einem Upgrade oder einem Patch-Vorgang beginnen, erstellen Sie eine aktive Verzweigung aus der Integrationsumgebung und checken Sie die neue Verzweigung auf Ihrer lokalen Workstation aus. Wenn Sie dem Upgrade- oder Patch-Prozess eine Verzweigung zuweisen, vermeiden Sie Konflikte mit laufenden Arbeiten.
TIP
Bei Pro-Projekten müssen Sie ein Adobe Commerce-Support-Ticket einreichen um Services nur in Staging und Production zu installieren oder zu aktualisieren.
Geben Sie an, welche Service-Änderungen erforderlich sind, schließen Sie Ihre aktualisierten .magento.app.yaml- und services.yaml-Dateien ein und geben Sie die PHP-Version im Ticket an. Informationen zu Self-Service-Änderungen an PHP-Versionen, Erweiterungen oder Umgebungseinstellungen finden Sie unter PHP-Einstellungen unter Anwendungskonfiguration.
Bei Änderungen an einer Live-Produktionsumgebung nur Pro ist eine Vorankündigung von mindestens 48 Stunden erforderlich. Dadurch hat das Cloud-Infrastruktur-Team genügend Zeit, Ressourcen zu mobilisieren und ein sicheres Upgrade durchzuführen. Die Kündigungsfrist beginnt, wenn das Infrastruktur-Team die Anfrage bestätigt und das Upgrade plant, mit Ausnahme der Wochenenden. Damit beispielsweise Service-Upgrades an einem Montag abgeschlossen werden, muss bis Mittwoch eine Bestätigung des geplanten Upgrades empfangen werden. In Spitzenzeiten kann die Verarbeitung Ihrer Anfrage länger dauern.

Upgrade von älteren Versionen

Wenn Sie mit dem Upgrade von einer Commerce-Version beginnen, die älter als 2.1 ist, können einige Einschränkungen in der Adobe Commerce-Code-Basis Ihre Möglichkeit beeinträchtigen, Update auf eine bestimmte ECE-Tools-Version oder Upgrade auf die nächste unterstützte Commerce-Version durchzuführen. Verwenden Sie die folgende Tabelle, um den besten Pfad zu ermitteln:

Aktuelle Version
Aktualisierungspfad
2.1.3 und früher
Aktualisieren Sie Adobe Commerce auf Version 2.1.4 oder höher, bevor Sie fortfahren. Führen Sie dann ein einmaliges Upgrade durch, um ECE-Tools zu installieren.
2.1.4 - 2.1.14
ECE-Tools-Paket.
Siehe Versionshinweise für 2002.0.9 und spätere Versionen von 2002.0.x.
2.1.15 - 2.1.16
ECE-Tools-Paket.
Siehe Versionshinweise für .2002.0. und höher.
2.2.x und höher
ECE-Tools-Paket.
Siehe Versionshinweise für .2002.0.8höher.
NOTE
Wenn Sie eine Version von Adobe Commerce in der Cloud-Infrastruktur verwenden, die nicht das ece-tools enthält, müssen Sie ein einmaliges Upgrade“Ihr Cloud-Projekt durchführen, um veraltete Pakete zu entfernen. Wenn Sie das ece-tools derzeit verwenden und aktualisieren müssen, finden Sie weitere Informationen unter Aktualisieren des ECE-Tools-Pakets.

Konfigurationsverwaltung

In älteren Adobe Commerce-Versionen (z. B. 2.1.4 oder höher bis 2.2.x oder höher) wurde eine config.local.php-Datei für die Konfigurationsverwaltung verwendet. Adobe Commerce Version 2.2.0 und höher verwendet die config.php-Datei, die genau wie die config.local.php-Datei funktioniert, aber unterschiedliche Konfigurationseinstellungen hat, die eine Liste Ihrer aktivierten Module und zusätzliche Konfigurationsoptionen enthalten.

Beim Upgrade von einer älteren Version müssen Sie die config.local.php migrieren, um die neuere config.php-Datei zu verwenden. Führen Sie die folgenden Schritte aus, um Ihre Konfigurationsdatei zu sichern und eine zu erstellen.

Erstellen einer temporären config.php-Datei:

  1. Erstellen Sie eine Kopie config.local.php Datei und benennen Sie sie config.php.

  2. Fügen Sie diese Datei zum app/etc Ihres Projekts hinzu.

  3. Fügen Sie die Datei zu Ihrer Verzweigung hinzu und übertragen Sie sie.

  4. Übertragen Sie die Datei in die Integrationsverzweigung.

  5. Fahren Sie mit dem Upgrade-Prozess fort.

WARNING
Nach einem Upgrade können Sie die config.php-Datei entfernen und eine neue, vollständige Datei erstellen. Sie können diese Datei nur löschen, um sie dieses Mal zu ersetzen. Nach dem Generieren einer neuen, vollständigen config.php können Sie die Datei nicht löschen, um eine neue zu generieren. Siehe Konfigurationsverwaltung und Pipeline-.

Überprüfen von Zend Framework Composer-Abhängigkeiten

Beim Upgrade auf 2.3.x oder höher von 2.2.x, stellen Sie sicher, dass die Abhängigkeiten des Zend-Frameworks zur autoload-Eigenschaft der composer.json-Datei hinzugefügt wurden, um Laminas zu unterstützen. Dieses Plug-in unterstützt neue Anforderungen für das Zend Framework, das zum Laminas-Projekt migriert wurde. Siehe Migration von Zend Framework zum Laminas-Projekt auf dem Magento DevBlog.

So überprüfen Sie die auto-load:psr-4-Konfiguration:

  1. Wechseln Sie auf Ihrer lokalen Workstation in Ihr Projektverzeichnis.

  2. Sehen Sie sich Ihre Integrationsverzweigung an.

  3. Öffnen Sie die composer.json in einem Texteditor.

  4. Überprüfen Sie den autoload:psr-4 Abschnitt für die Zend Plug-in Manager Implementierung auf die Abhängigkeit von Controllern.

    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. Wenn die Zend-Abhängigkeit fehlt, aktualisieren Sie die composer.json:

    • Fügen Sie dem Abschnitt autoload:psr-4 die folgende Zeile hinzu.

      code language-json
      "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"
      
    • Aktualisieren Sie die Projektabhängigkeiten.

      code language-bash
      composer update
      
    • Code-Änderungen hinzufügen, übertragen und per Push übertragen.

      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>
      
    • Zusammenführen von Änderungen in der Staging-Umgebung und anschließend in der Produktion.

Konfigurationsdateien

Vor dem Upgrade der Anwendung müssen Sie Ihre Projektkonfigurationsdateien aktualisieren, um Änderungen an den Standardkonfigurationseinstellungen für Adobe Commerce in der Cloud-Infrastruktur oder der Anwendung zu berücksichtigen. Die neuesten Standardeinstellungen finden Sie im Magento-Cloud-GitHub-Repository.

.magento.app.yaml

Überprüfen Sie immer die in der Datei .magento.app.yaml enthaltenen Werte für Ihre installierte Version, da sie steuert, wie Ihre Anwendung die Cloud-Infrastruktur erstellt und bereitstellt. Das folgende Beispiel gilt für Version 2.4.7 und verwendet Composer 2.7.2. Die build: flavor:-Eigenschaft wird nicht für Composer 2.x verwendet; siehe Installieren und Verwenden von Composer 2.

So aktualisieren Sie die .magento.app.yaml-Datei:

  1. Wechseln Sie auf Ihrer lokalen Workstation in Ihr Projektverzeichnis.

  2. Öffnen und bearbeiten Sie die magento.app.yaml.

  3. Aktualisieren Sie die PHP-Optionen.

    code language-yaml
    type: php:8.3
    
    build:
        flavor: none
    dependencies:
        php:
            composer/composer: '2.7.2'
    
  4. Ändern Sie die hooks-build und 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. Fügen Sie die folgenden Umgebungsvariablen am Ende der Datei hinzu.

    Für Adobe Commerce 2.2.x bis 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. Speichern Sie die Datei. Übernehmen oder übertragen Sie noch keine Änderungen an die Remote-Umgebung.

  7. Fahren Sie mit dem Upgrade-Prozess fort.

composer.json

Überprüfen Sie vor einem Upgrade immer, ob die Abhängigkeiten in der composer.json mit der Adobe Commerce-Version kompatibel sind.

So aktualisieren Sie die composer.json für Adobe Commerce Version 2.4.4 und höher:

  1. Fügen Sie dem config Abschnitt die folgenden allow-plugins hinzu:

    code language-json
    "config": {
       "allow-plugins": {
          "dealerdirect/phpcodesniffer-composer-installer": true,
          "laminas/laminas-dependency-plugin": true,
          "magento/*": true
       }
    },
    
  2. Fügen Sie dem Abschnitt require das folgende Plug-in hinzu:

    code language-json
    "require": {
        "magento/composer-root-update-plugin": "^2.0.3"
    },
    
  3. Fügen Sie dem Abschnitt extra:component_paths die folgende Komponente hinzu:

    code language-json
    "extra": {
       "component_paths": {
          "tinymce/tinymce": "lib/web/tiny_mce_5"
       },
    },
    
  4. Speichern Sie die Datei. Übernehmen oder übertragen Sie noch keine Änderungen an Ihre Verzweigung.

  5. Fahren Sie mit dem Upgrade-Prozess fort.

Projekt-Backup

Es wird empfohlen, vor einem Upgrade eine Sicherungskopie des Projekts zu erstellen. Führen Sie die folgenden Schritte aus, um Ihre Integrations-, Staging- und Produktionsumgebungen zu sichern.

So sichern Sie die Datenbank und den Code Ihrer Integrationsumgebung:

  1. Erstellen Sie eine lokale Sicherung der Remote-Datenbank.

    code language-bash
    magento-cloud db:dump
    
    note note
    NOTE
    Der Befehl magento-cloud db:dump führt den Befehl mysqldump mit dem Flag --single-transaction aus, mit dem Sie Ihre Datenbank sichern können, ohne die Tabellen zu sperren.
  2. Sichern Sie Code und Medien.

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

    Optional können Sie [--media] auslassen, wenn sich bereits eine große Anzahl von statischen Dateien in der Versionsverwaltung befinden.

So sichern Sie die Datenbank Ihrer Staging- oder Produktionsumgebung vor der Bereitstellung:

  1. Verwenden Sie SSH, um sich bei der Remote-Umgebung anzumelden.

  2. Erstellen Sie einen Datenbank-Dump. Um einen Zielordner für den DB-Dump auszuwählen, verwenden Sie die Option --dump-directory .

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

    Der Dump-Vorgang erstellt eine dump-<timestamp>.sql.gz Archivdatei in Ihrem Remote-Projektverzeichnis. Siehe Datenbank sichern.

Anwendungs-Upgrade

Lesen Sie die Service-Versionen, um die neuesten Anforderungen an die Softwareversion zu erfüllen, bevor Sie Ihr Programm aktualisieren.

So aktualisieren Sie die Anwendungsversion:

  1. Wechseln Sie auf Ihrer lokalen Workstation in Ihr Projektverzeichnis.

  2. Legen Sie die Upgrade-Version mithilfe der Syntax der Versionsbeschränkung fest.

    code language-bash
    composer require "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update
    
    note note
    NOTE
    Sie müssen die Versionsbeschränkungssyntax verwenden, um das ece-tools Paket erfolgreich zu aktualisieren. Die Versionsbeschränkung finden Sie in der composer.json-Datei für die Version der Anwendungsvorlage die Sie für das Upgrade verwenden.
  3. Aktualisieren Sie das Projekt.

    code language-bash
    composer update
    
  4. Überprüfen Sie die aktuell angewendeten Patches:

    • Wenn im m2-hotfixes-Verzeichnis Patches installiert sind, Sie ein Adobe Commerce-Support-Ticket, und prüfen Sie gemeinsam mit dem Adobe Commerce-Support, welche Patches weiterhin auf die neue Version angewendet werden können. Entfernen Sie die nicht zutreffenden Patches aus dem m2-hotfixes.

    • Wenn [Quality Patches] in der .magento.env.yaml-Datei angewendet wurden, überprüfen Sie, ob diese weiterhin auf die neue Version angewendet werden können. Entfernen Sie die nicht zutreffenden Patches aus dem QUALITY_PATCHES Abschnitt der .magento.env.yaml.

    Methode 1: Überprüfen Sie die entsprechenden Versionen in den Versionshinweisen zu Qualitäts-Patches

    Methode 2: Anzeigen verfügbarer Patches und Status

    Methode 3: Suchen nach Patches

  5. Code-Änderungen hinzufügen, übertragen und per Push übertragen.

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

    git add -A ist erforderlich, um alle geänderten Dateien zur Versionsverwaltung hinzuzufügen, da Composer Basispakete marshallt. Sowohl composer install als auch composer update marshallen Dateien aus dem Basispaket (magento/magento2-base und magento/magento2-ee-base) in den Paketstamm.

    Die Dateien, die Composer marshallt, gehören zur neuen Version von Adobe Commerce, um die veraltete Version derselben Dateien zu überschreiben. Derzeit ist das Marshalling in Adobe Commerce deaktiviert, sodass Sie die marshallten Dateien zur Quellcodeverwaltung hinzufügen müssen.

  6. Warten Sie, bis die Bereitstellung abgeschlossen ist.

  7. Überprüfen Sie das Upgrade in Ihrer Integrations-, Staging- oder Produktionsumgebung, indem Sie sich mit SSH anmelden und die Version überprüfen.

    code language-bash
    php bin/magento --version
    

Erstellen einer Datei config.php

Wie unter Konfigurationsverwaltung erwähnt, müssen Sie nach dem Upgrade eine aktualisierte config.php erstellen. Schließen Sie alle zusätzlichen Konfigurationsänderungen über den Administrator in Ihrer Integrationsumgebung ab.

Erstellen einer systemspezifischen Konfigurationsdatei:

  1. Verwenden Sie am Terminal einen SSH-Befehl, um die /app/etc/config.php-Datei für die Umgebung zu generieren.

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

    So führen Sie beispielsweise für Pro die scd-dump auf der integration Verzweigung aus:

    code language-bash
    ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/ece-tools config:dump"
    
  2. Übertragen Sie die config.php-Datei mithilfe von rsync oder scp auf Ihre lokalen Workstations. Sie können diese Datei nur lokal zur Verzweigung hinzufügen.

    code language-bash
    rsync <SSH-URL>:app/etc/config.php ./app/etc/config.php
    
  3. Code-Änderungen hinzufügen, übertragen und per Push übertragen.

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

    Dadurch wird eine aktualisierte /app/etc/config.php-Datei mit einer Modulliste und Konfigurationseinstellungen generiert.

WARNING
Für ein Upgrade löschen Sie die config.php. Nachdem diese Datei zu Ihrem Code hinzugefügt wurde, sollten Sie nicht löschen. Wenn Sie Einstellungen entfernen oder bearbeiten müssen, bearbeiten Sie die Datei manuell.

Erweiterungen aktualisieren

Überprüfen Sie Ihre Erweiterungs- und Modulseiten von Drittanbietern auf Marketplace oder anderen Unternehmens-Sites und überprüfen Sie, ob Adobe Commerce und Adobe Commerce in der Cloud-Infrastruktur unterstützt werden. Wenn Sie Erweiterungen und Module von Drittanbietern aktualisieren müssen, empfiehlt Adobe, in einer neuen Integrationsverzweigung zu arbeiten, wobei Ihre Erweiterungen deaktiviert sind.

So überprüfen und aktualisieren Sie Ihre Erweiterungen:

  1. Erstellen Sie eine Verzweigung auf Ihrer lokalen Workstation.

  2. Deaktivieren Sie Ihre Erweiterungen nach Bedarf.

  3. Laden Sie, sofern verfügbar, Erweiterungs-Upgrades herunter.

  4. Installieren Sie das Upgrade, wie in der Dokumentation des Drittanbieters beschrieben.

  5. Aktivieren und Testen der Erweiterung.

  6. Fügen Sie die Code-Änderungen hinzu, übertragen Sie sie und übertragen Sie sie auf die Fernbedienung.

  7. Push-Benachrichtigung und Testen in der Integrationsumgebung.

  8. Pushen Sie in die Staging-Umgebung, um sie in einer Vorproduktionsumgebung zu testen.

Adobe empfiehlt dringend, die Produktionsumgebung () aktualisieren, einschließlich der aktualisierten Erweiterungen in Ihrem Site-Launch-Prozess.

NOTE
Wenn Sie Ihre Anwendungsversion aktualisieren, wird der Upgrade-Prozess automatisch auf die neueste Version des Fastly CDN-Moduls aktualisiert.

Fehlerbehebung bei Upgrades

Wenn das Upgrade fehlgeschlagen ist, erhalten Sie eine Fehlermeldung im Browser, die Sie darauf hinweist, dass Sie nicht auf Ihre Storefront oder das Admin-Panel zugreifen können:

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

So beheben Sie den Fehler:

  1. Wechseln Sie auf Ihrer lokalen Workstation in Ihr Projektverzeichnis.

  2. Verwenden Sie SSH, um sich bei der Remote-Umgebung anzumelden.

    code language-bash
    magento-cloud ssh
    
  3. Öffnen Sie die ./app/var/report/<error number>.

  4. Überprüfen Sie dieund ermitteln Sie die Ursache des Problems.

  5. Code-Änderungen hinzufügen, übertragen und per Push übertragen.

    code language-bash
    git add -A && git commit -m "Fixed deployment failure" && git push origin <branch-name>
    
recommendation-more-help