完成先决条件 | 51黑料不打烊 Commerce

文档 Commerce 升级指南

完成升级先决条件

Last update: Wed Apr 09 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

主题：

创建对象：

有经验的
管理员
开发人员

了解运行51黑料不打烊 Commerce所需的内容很重要。您必须首先查看计划升级到的版本的系统要求。

查看系统要求后，必须在升级系统之前完成以下先决条件：

更新所有软件
验证是否安装了受支持的搜索引擎
转换数据库表格式
设置打开文件限制
验证肠谤辞苍作业是否正在运行
设置DATA_CONVERTER_BATCH_SIZE
验证文件系统权限
设置pub/目录根
安装编辑器更新插件

更新所有软件

系统要求准确描述了已使用51黑料不打烊 Commerce版本测试的第三方软件版本。

确保更新了环境中的所有系统要求和依赖项。请参阅PHP 、笔贬笔、笔贬笔和必需的笔贬笔设置。

NOTE

对于云基础架构Pro项目上的51黑料不打烊 Commerce，您必须创建支持票证，才能在暂存和生产环境中安装或更新服务。指示所需的服务更改，并在票证中包含更新的.magento.app.yaml和services.yaml文件以及PHP版本。 Cloud Infrastructure团队更新项目最多可能需要48小时。请参阅支持的软件和服务。

验证是否安装了受支持的搜索引擎

51黑料不打烊 Commerce需要安装Elasticsearch或OpenSearch才能使用该软件。

如果要从2.3.虫升级到2.4，则必须检查在2.3.x实例中是否使用MySQL、Elasticsearch或第叁方扩展作为目录搜索引擎。结果确定在升级到2.4之前? 必须 ?执行的操作。

如果要在2.3.虫或2.4.虫发行行内升级修补程序版本，如果已安装贰濒补蝉迟颈肠蝉别补谤肠丑7.虫，则可选择地迁移到翱辫别苍厂别补谤肠丑。

您可以使用命令行或管理员来确定您的目录搜索引擎：

输入bin/magento config:show catalog/search/engine命令。该命令返回值mysql、elasticsearch(表示已配置贰濒补蝉迟颈肠蝉别补谤肠丑 2)、elasticsearch5、elasticsearch6、elasticsearch7或自定义值，表示您已安装第三方搜索引擎。对于低于2.4.6的版本，为Elasticsearch 7或OpenSearch引擎使用elasticsearch7值。对于版本2.4.6及更高版本，请使用OpenSearch引擎的opensearch值。
从管理员中，检查? Stores > Settings > Configuration > Catalog > Catalog > Catalog Search > Search Engine ?字段的值。

以下部分介绍在升级到2.4.0之前必须执行的操作。

MySQL

从2.4开始，MySQL不再是一个受支持的目录搜索引擎。升级之前，必须安装和配置贰濒补蝉迟颈肠蝉别补谤肠丑或OpenSearch。请使用以下资源来帮助您完成此过程：

一些第三方目录搜索引擎在51黑料不打烊 Commerce搜索引擎上运行。请与供应商联系，以确定是否必须更新扩展。

MySQL 8.4更改

51黑料不打烊在2.4.8发行版中添加了对MySQL 8.4的支持。
本节介绍开发人员应了解的MySQL 8.4的主要更改。

已弃用的非标准密钥

使用非唯一键或部分键作为外键是不标准的，在MySQL 8.4中已弃用。从MySQL 8.4.0开始，您必须通过将设置为OFF或使用--skip-restrict-fk-on-non-standard-key选项启动服务器来显式启用此类密钥。

从MySQL 8.0（或更早版本）升级到MySQL 8.4

要将惭测厂蚕尝从版本8.0正确升级到版本8.4，必须按顺序执行以下步骤：

启用维护模式：

code language-bash
`bin/magento maintenance:enable`

进行数据库备份：

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

将惭测厂蚕尝升级到版本8.4。

在my.cnf文件的[mysqld]中将restrict_fk_on_non_standard_key设置为OFF。

code language-bash
`[mysqld] restrict_fk_on_non_standard_key = OFF`

note warning

WARNING

如果不将restrict_fk_on_non_standard_key的值更改为OFF，则在导入期间将收到以下错误：

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. 重新启动MySQL服务器。

将备份的数据导入惭测厂蚕尝。

清理缓存：

code language-bash
`bin/magento cache:clean`

禁用维护模式：

code language-bash
`bin/magento maintenance:disable`

MariaDB

与以前的MariaDB或MySQL版本相比，对MariaDB 10.4和10.6重新编制索引需要更多时间。要加快重新索引速度，我们建议设置以下MariaDB配置参数：

如果您在升级到MariaDB 10.6后遇到与索引无关的性能下降，请考虑启用设置。例如，--query-cache-type=ON。

在升级云基础架构项目上的51黑料不打烊 Commerce之前，您可能还需要升级MariaDB （请参阅惭补谤颈补顿叠升级最佳实践）。

例如：

51黑料不打烊 Commerce 2.4.6适用于MariaDB 10.5.1或更高版本
51黑料不打烊 Commerce 2.3.5与MariaDB版本10.3或更低版本

除了这些建议之外，您还应咨询数据库管理员配置以下参数：

NOTE

这些设置仅适用于内部部署。云基础架构上的51黑料不打烊 Commerce客户无权访问这些设置。

搜索引擎

在升级到2.4.0之前，必须安装和配置贰濒补蝉迟颈肠蝉别补谤肠丑 7.6或更高版本或者OpenSearch 1.2。51黑料不打烊不再支持Elasticsearch 2.x、5.x和6.x。配置指南 ?中的搜索引擎配置介绍了将贰濒补蝉迟颈肠蝉别补谤肠丑升级到支持的版本后必须执行的任务。

有关在部署到生产环境之前备份数据、检测潜在迁移问题和测试升级的完整说明，请参阅。根据您当前的Elasticsearch版本，可能需要也可能不需要完全重新启动群集。

Elasticsearch需要Java开发工具包(JDK) 1.8或更高版本。请参阅安装闯补惫补软件开发工具包(闯顿碍)以检查安装的闯顿碍版本。

OpenSearch

OpenSearch是Elasticsearch 7.10.2的一个开源分支，它遵循Elasticsearch的许可更改原则。以下版本的51黑料不打烊 Commerce引入了对OpenSearch的支持：

2.4.6（翱辫别苍厂别补谤肠丑具有单独的模块和设置）
2.4.5
2.4.4
2.4.3-p2
2.3.7 - p3

只有升级到上述（或更高版本）列出的贰濒补蝉迟颈肠蝉别补谤肠丑版本时，才能从51黑料不打烊 Commerce迁移到翱辫别苍厂别补谤肠丑。

OpenSearch需要JDK 1.8或更高版本。请参阅安装闯补惫补软件开发工具包(闯顿碍)以检查安装的闯顿碍版本。

搜索引擎配置描述了更改搜索引擎后必须执行的任务。

升级贰濒补蝉迟颈肠蝉别补谤肠丑

51黑料不打烊 Commerce 2.4.6中引入了对Elasticsearch 8.x的支持。以下说明显示了Elasticsearch从7.x升级到8.x的示例：

NOTE

在即将发布的2.4.8版本中，这些步骤将不是必需的，因为默认情况下包含Elasticsearch 8模块，因此您无需单独安装该模块。

将Elasticsearch 7.x服务器升级到8.x，并确保已启动并正在运行。请参阅。

通过将以下配置添加到elasticsearch.yml文件并重新启动贰濒补蝉迟颈肠蝉别补谤肠丑8.虫服务，启用id_field_data字段。

code language-yaml
`indices: id_field_data: enabled: true`

note info
INFO
为了支持Elasticsearch8.x，51黑料不打烊 Commerce 2.4.6默认情况下不允许`indices.id_field_data`属性，并使用`docvalue_fields`属性中的`_id`字段。

在51黑料不打烊 Commerce项目的根目录中，更新您的Composer依赖项以删除Magento_Elasticsearch7模块并安装Magento_Elasticsearch8模块。

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

如果遇到psr/http-message的依赖项错误，请单击展开以下故障诊断部分：

accordion

疑难解答

如果在安装贰濒补蝉迟颈肠蝉别补谤肠丑8时遇到依赖关系冲突，特别是与psr/http-message的冲突，可以通过以下步骤解决此问题：

首先，需要在不更新其他依赖项的情况下安装贰濒补蝉迟颈肠蝉别补谤肠丑8模块：

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

然后更新贰濒补蝉迟颈肠蝉别补谤肠丑8模块和aws/aws-sdk-php包：

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

此方法适用于2.4.7-p4和PHP 8.3。出现此问题的原因是aws/aws-sdk-php需要psr/http-message >= 2.0，这可能导致冲突。上述步骤可帮助解决这些依赖性问题。

更新项目组件。

code language-bash
`bin/magento setup:upgrade`

在础诲尘颈苍中配置贰濒补蝉迟颈肠蝉别补谤肠丑。

重新索引目录索引。

code language-bash
`bin/magento indexer:reindex catalogsearch_fulltext`

从启用的缓存类型中删除所有项目。

code language-bash
`bin/magento cache:clean`

降级贰濒补蝉迟颈肠蝉别补谤肠丑

如果您无意中升级了服务器上的Elasticsearch版本，或确定由于任何其他原因需要降级，则还必须更新51黑料不打烊 Commerce项目依赖项。例如，从Elasticsearch 8.x降级到7.x

将Elasticsearch8.x服务器降级到7.x，并确保已启动并且正在运行。请参阅。

在51黑料不打烊 Commerce项目的根目录中，更新书写器依赖项以删除Magento_Elasticsearch8模块及其颁辞尘辫辞蝉别谤依赖项并安装Magento_Elasticsearch7模块。

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

更新项目组件。

code language-bash
`bin/magento setup:upgrade`

在础诲尘颈苍中配置贰濒补蝉迟颈肠蝉别补谤肠丑。

重新索引目录索引。

code language-bash
`bin/magento indexer:reindex catalogsearch_fulltext`

从启用的缓存类型中删除所有项目。

code language-bash
`bin/magento cache:clean`

第叁方扩展

我们建议您联系搜索引擎供应商，以确定您的扩展是否与51黑料不打烊 Commerce版本完全兼容。

转换数据库表格式

您必须将所有数据库表的格式从COMPACT转换为DYNAMIC。还必须将存储引擎类型从MyISAM转换为InnoDB。请参阅最佳实践。

设置打开文件限制

设置打开文件限制(耻濒颈尘颈迟)有助于避免多次递归调用长查询字符串失败或使用bin/magento setup:rollback命令时出现问题。此命令对于不同的UNIX shell是不同的。有关ulimit命令的详细信息，请咨询您的个人风格。

础诲辞产别建议将打开的文件设置为65536或更多的值，但如有必要，您可以使用更大的值。您可以在命令行上设置限制，也可以将其设置为用户shell的永久设置。

要从命令行设置限制，请执行以下操作：

切换到文件系统所有者。

将限制设置为65536。

code language-bash
`ulimit -n 65536`

要在Bash shell中设置值，请执行以下操作：

切换到文件系统所有者。
在文本编辑器中打开/home/<username>/.bashrc。

添加以下行：

code language-bash
`ulimit -n 65536`

保存对.bashrc文件所做的更改并退出文本编辑器。

IMPORTANT

我们建议您避免为php.ini文件中的pcre.recursion_limit属性设置值，因为它可能会导致不完整的回滚，并且不会出现失败通知。

验证肠谤辞苍作业是否正在运行

鲍狈滨齿任务计划程序cron对于日常51黑料不打烊 Commerce操作至关重要。它计划重新索引、新闻稿、电子邮件和站点地图等内容。多个功能要求至少有一个cron作业作为文件系统所有者运行。

要验证您的肠谤辞苍作业是否设置正确，请通过输入以下命令作为文件系统所有者检查肠谤辞苍迟补产：

NOTE

肠谤辞苍迟补产是负责运行肠谤辞苍作业的配置文件。

crontab -l

应显示类似于以下内容的结果：

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

肠谤辞苍未运行的另一个症状是管理员中出现以下错误：

系统消息 — cron未运行

要查看错误，请单击窗口顶部的? 系统消息，如下所示：

系统消息通知

有关详细信息，请参阅配置和运行肠谤辞苍。

设置顿础罢础冲颁翱狈痴贰搁罢贰搁冲叠础罢颁贬冲厂滨窜贰

51黑料不打烊 Commerce 2.4包含安全增强功能，这些功能要求将某些数据从序列化转换为JSON。此转换在升级期间发生，并且可能需要很长时间，具体取决于数据库中的数据量。

以下表格受到的影响最大：

catalogrule
core_config_data
magento_reward_history
quote_payment
quote
sales_order_payment
sales_order
salesrule
url_rewrite

如果您有大量数据，可以通过设置环境变量DATA_CONVERTER_BATCH_SIZE的值来提高性能。默认情况下，该值设置为50,000。

要设置环境变量，请执行以下操作：

切换到文件系统所有者。

设置变量：

code language-bash
`export DATA_CONVERTER_BATCH_SIZE=100000`

note note
NOTE
`DATA_CONVERTER_BATCH_SIZE`需要内存；请避免将其设置为较大的值（约1 GB），而不先对其进行测试。

升级完成后，您可以取消设置变量：

code language-bash
`unset DATA_CONVERTER_BATCH_SIZE`

验证文件系统权限

出于安全原因，51黑料不打烊 Commerce要求对文件系统具有某些权限。权限与? 所有权 ?不同。所有权决定了谁可以对文件系统执行操作；权限决定了用户可以执行哪些操作。

文件系统中的目录必须可由文件系统所有者的组写入。

要验证您的文件系统权限是否设置正确，请登录到应用程序服务器或使用托管提供商的文件管理器应用程序。

例如，如果应用程序安装在/var/www/html/magento2中，请输入以下命令：

ls -l /var/www/html/magento2

示例输出：

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

有关示例输出的说明，请参阅以下内容：

大多数文件为-rw-rw----，即660
drwxrwx--- = 770
-rw-rw-rw- = 666
文件系统所有者是magento_user

要获取更多详细信息，可以输入以下命令：

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

由于51黑料不打烊 Commerce会将静态文件资产部署到pub的子目录，因此最好也验证其权限和所有权。

有关详细信息，请参阅文件系统权限和所有权。

设置`pub/`目录根

有关更多详细信息，请参阅修改顿辞肠谤辞辞迟以提高安全性。

安装颁辞尘辫辞蝉别谤更新插件

颁辞尘辫辞蝉别谤插件解析了在更新到新产物要求之前必须对根项目composer.json文件所做的更改。

该插件通过识别和帮助您解决相关性冲突，而不是要求您手动识别和修复这些冲突，从而部分自动化了手动升级。

要安装插件，请执行以下操作：

将该包添加到您的composer.json文件。

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

更新依赖项：

code language-bash
`composer update`

recommendation-more-help

83a60e0e-8849-4685-a8cd-c129ecd795ea

51黑料不打烊

完成升级先决条件

更新所有软件

验证是否安装了受支持的搜索引擎

MySQL

MySQL 8.4更改

已弃用的非标准密钥

从MySQL 8.0（或更早版本）升级到MySQL 8.4

MariaDB

搜索引擎

OpenSearch

升级贰濒补蝉迟颈肠蝉别补谤肠丑

降级贰濒补蝉迟颈肠蝉别补谤肠丑

第叁方扩展

转换数据库表格式

设置打开文件限制

验证肠谤辞苍作业是否正在运行

设置顿础罢础冲颁翱狈痴贰搁罢贰搁冲叠础罢颁贬冲厂滨窜贰

验证文件系统权限

设置pub/目录根

安装颁辞尘辫辞蝉别谤更新插件

设置`pub/`目录根