升级Commerce版本

您可以将Adobe Commerce代码库升级到较新版本。 在升级项目之前,请查看​ 安装 ​指南中的系统要求以了解最新的软件版本要求。

根据您的项目配置,升级任务可能包括以下内容:

  • 更新服务(例如MariaDB (MySQL)、OpenSearch、RabbitMQ和Redis)以便与新的Adobe Commerce版本兼容。
  • 转换旧版配置管理文件。
  • 使用挂接和环境变量的新设置更新.magento.app.yaml文件。
  • 将第三方扩展升级到支持的最新版本。
  • 更新.gitignore文件。
TIP
在开始升级或修补过程之前,请从集成环境创建一个活动分支,并将新分支签出到您的本地工作站。 将分支专用于升级或修补过程有助于避免干扰正在进行的工作。
TIP
对于Pro项目,您必须提交Adobe Commerce支持票证才能仅在StagingProduction环境中安装或更新服务
指示所需的服务更改,包括更新的.magento.app.yamlservices.yaml文件,并在票证中声明PHP版本。 有关对PHP版本、扩展或环境设置的自助更改,请参阅​_应用程序配置_​中的PHP设置
对于对​_实时_​生产环境的更改(仅限​ Pro),您必须提供至少48小时的通知,以便Cloud Infrastructure团队有足够的时间来调配资源并进行安全升级。

从旧版本升级

如果您开始从低于2.1的Commerce版本升级,Adobe Commerce代码库中的某些限制可能会影响您将​ 更新 ​到特定ECE-Tools版本或​ 升级 ​到下一个受支持的Commerce版本的能力。 使用下表确定最佳路径:

当前版本
升级路径
2.1.3及更早版本
在继续操作之前,请将Adobe Commerce升级到版本2.1.4或更高版本。 然后执行一次性升级以安装ECE-Tools
2.1.4 - 2.1.14
更新ECE-Tools包。
请参阅2002.0.9和更高版本2002.0.x的发行说明。
2.1.15 - 2.1.16
更新ECE-Tools包。
请参阅2002.0.9及更高版本的发行说明。
2.2.x及更高版本
更新ECE-Tools包。
请参阅2002.0.8及更高版本的发行说明。
NOTE
如果您在不包含ece-tools包的云基础架构上使用Adobe Commerce版本,则必须对云项目执行一次性升级以删除已弃用的包。 如果您当前使用的是ece-tools程序包,需要对其进行更新,请参阅更新ECE-Tools程序包

配置管理

较旧版本的Adobe Commerce(如2.1.4或更高版本到2.2.x或更高版本)使用config.local.php文件进行配置管理。 Adobe Commerce版本2.2.0及更高版本使用config.php文件,该文件与config.local.php文件完全相同,但其配置设置有所不同,其中包括已启用的模块的列表和其他配置选项。

从旧版本升级时,必须迁移config.local.php文件以使用较新的config.php文件。 使用以下步骤备份配置文件并创建一个。

要创建临时config.php文件

  1. 创建config.local.php文件的副本并将其命名为config.php

  2. 将此文件添加到您项目的app/etc文件夹中。

  3. 将文件添加并提交到分支。

  4. 将文件推送到集成分支。

  5. 继续升级过程。

WARNING
升级后,您可以删除config.php文件并生成新的完整文件。 您只能删除此文件以一次替换它。 生成新的、完整的config.php文件后,无法删除该文件以生成新的文件。 请参阅配置管理和管道部署

验证Zend框架编辑器依赖关系

从2.2.x 升级到 2.3.x或更高版本时,请验证Zend Framework依赖项是否已添加到composer.json文件的autoload属性中以支持Laminas。 此插件支持Zend框架的新要求,该框架已迁移到Laminas项目。 请参阅​ MagentoDevBlog ​上的将Zend Framework迁移到Laminas项目

检查auto-load:psr-4配置

  1. 在本地工作站上,转到您的项目目录。

  2. 请查看您的集成分支。

  3. 在文本编辑器中打开composer.json文件。

  4. 检查Zend插件管理器实施的autoload:psr-4部分以了解控制器依赖关系。

    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. 如果缺少Zend依赖项,请更新composer.json文件:

    • 将以下行添加到autoload:psr-4部分。

      code language-json
      "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"
      
    • 更新项目依赖关系。

      code language-bash
      composer update
      
    • 添加、提交和推送代码更改。

      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>
      
    • 先将更改合并到暂存环境,然后再合并到生产环境。

配置文件

在升级应用程序之前,必须更新项目配置文件,以便考虑对云基础架构或应用程序上Adobe Commerce的默认配置设置所做的更改。 可以在magento-cloud GitHub存储库中找到最新的默认值。

.magento.app.yaml

始终检查.magento.app.yaml文件中包含的值以确定您所安装的版本,因为它控制应用程序构建和部署到云基础架构的方式。 以下示例适用于版本2.4.7,并且使用编辑器2.7.2。build: flavor:属性不用于Composer 2.x;请参阅安装和使用Composer 2

要更新.magento.app.yaml文件

  1. 在本地工作站上,转到您的项目目录。

  2. 打开并编辑magento.app.yaml文件。

  3. 更新PHP选项。

    code language-yaml
    type: php:8.3
    
    build:
        flavor: none
    dependencies:
        php:
            composer/composer: '2.7.2'
    
  4. 修改hooks属性builddeploy命令

    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. 在文件末尾添加以下环境变量。

    对于Adobe Commerce 2.2.x到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'
    

    对于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. 保存文件。 不要将更改提交或推送到远程环境。

  7. 继续升级过程。

composer.json

升级之前,请始终检查composer.json文件中的依赖项是否与Adobe Commerce版本兼容。

要更新Adobe Commerce版本2.4.4及更高版本的composer.json文件

  1. 将以下allow-plugins添加到config部分:

    code language-json
    "config": {
       "allow-plugins": {
          "dealerdirect/phpcodesniffer-composer-installer": true,
          "laminas/laminas-dependency-plugin": true,
          "magento/*": true
       }
    },
    
  2. 将以下插件添加到require部分:

    code language-json
    "require": {
        "magento/composer-root-update-plugin": "^2.0.3"
    },
    
  3. 将以下组件添加到extra:component_paths部分:

    code language-json
    "extra": {
       "component_paths": {
          "tinymce/tinymce": "lib/web/tiny_mce_5"
       },
    },
    
  4. 保存文件。 尚未提交更改或将更改推送到分支。

  5. 继续升级过程。

项目备份

我们建议在升级之前创建项目的备份。 使用以下步骤可备份集成、暂存和生产环境。

要备份集成环境数据库和代码

  1. 创建远程数据库的本地备份。

    code language-bash
    magento-cloud db:dump
    
    note note
    NOTE
    magento-cloud db:dump命令运行带有--single-transaction标志的mysqldump命令,该标志允许您在不锁定表的情况下备份数据库。
  2. 备份代码和介质。

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

    或者,如果您有大量静态文件已在源代码管理中,则可以省略[--media]

要在部署 ​之前备份暂存或生产环境数据库,请执行以下操作:

  1. 使用SSH登录到远程环境。

  2. 创建数据库转储。 要为数据库转储选择目标目录,请使用--dump-directory选项。

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

    转储操作将在远程项目目录中创建dump-<timestamp>.sql.gz存档文件。 请参阅备份数据库

应用程序升级

在升级应用程序之前,请查看服务版本信息以了解最新的软件版本要求。

升级应用程序版本

  1. 在本地工作站上,转到您的项目目录。

  2. 使用版本约束语法设置升级版本。

    code language-bash
    composer require "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update
    
    note note
    NOTE
    您必须使用版本约束语法才能成功更新ece-tools包。 您可以在composer.json文件中找到用于升级的应用程序模板的版本限制。
  3. 更新项目。

    code language-bash
    composer update
    
  4. 添加、提交和推送代码更改。

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

    由于Composer封送基础包的方式,将所有更改的文件添加到源代码管理时需要git add -Acomposer installcomposer update将基包(magento/magento2-basemagento/magento2-ee-base)中的文件封送到包根中。

    Composer封送的文件属于新版本的Adobe Commerce,用于覆盖这些相同文件的过时版本。 目前,Adobe Commerce中已禁用封送处理,因此您必须将封送处理文件添加到源代码管理。

  5. 等待部署完成。

  6. 通过使用SSH登录并检查版本,在集成、暂存或生产环境中验证升级。

    code language-bash
    php bin/magento --version
    

创建config.php文件

配置管理中所述,升级后,您必须创建一个更新的config.php文件。 通过集成环境中的管理员完成任何其他配置更改。

要创建系统特定的配置文件

  1. 从终端,使用SSH命令为环境生成/app/etc/config.php文件。

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

    例如,对于Pro,要在integration分支上运行scd-dump,请执行以下操作:

    code language-bash
    ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/ece-tools config:dump"
    
  2. 使用rsyncscpconfig.php文件传输到本地工作站。 您只能将此文件添加到本地分支中。

    code language-bash
    rsync <SSH-URL>:app/etc/config.php ./app/etc/config.php
    
  3. 添加、提交和推送代码更改。

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

    这将生成一个包含模块列表和配置设置的更新/app/etc/config.php文件。

WARNING
对于升级,您删除了config.php文件。 将此文件添加到您的代码后,您应该​ ​删除它。 如果必须删除或编辑设置,请手动编辑该文件。

升级扩展

在Marketplace或其他公司站点中查看您的第三方扩展和模块页面,并验证在云基础架构上对Adobe Commerce和Adobe Commerce的支持。 如果必须升级任何第三方扩展和模块,Adobe建议在禁用扩展的情况下使用新的集成分支。

验证并升级扩展

  1. 在本地工作站上创建分支。

  2. 根据需要禁用扩展。

  3. 可用时,下载扩展升级。

  4. 按照第三方文档的说明安装升级。

  5. 启用并测试扩展。

  6. 添加、提交代码更改并将其推送到远程。

  7. 推送到并在您的集成环境中测试。

  8. 推送到暂存环境以在预生产环境中测试。

Adobe强烈建议在​ 之前升级您的生产环境,包括在您的站点启动过程中升级的扩展。

NOTE
当您升级应用程序版本时,升级过程将自动更新到Fastly CDN模块的最新版本。

升级疑难解答

如果升级失败,您会在浏览器中收到一条错误消息,指示您无法访问店面或管理面板:

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

要解决错误

  1. 在本地工作站上,转到您的项目目录。

  2. 使用SSH登录到远程环境。

    code language-bash
    magento-cloud ssh
    
  3. 打开./app/var/report/<error number>文件。

  4. 检查日志并确定问题的来源。

  5. 添加、提交和推送代码更改。

    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