设置Valkey服务

最近更新： 2026年9月2日

主题：
配置

创建对象：

管理员
开发人员

Valkey是云基础架构上Adobe Commerce的可选后端缓存解决方案。当您覆盖Adobe Commerce 2.4.9及更高版本上的默认缓存配置，或在2.4.5-p16、2.4.6-p14、2.4.7-p9和2.4.8-p4之前的修补程序版本上的默认缓存配置时，需要Valkey。

请按照以下说明在专业集成环境和入门环境（包括master分支）上进行服务设置。

NOTE

要更改Pro生产和暂存环境中的服务配置，请提交Adobe Commerce支持票证。有关计划要求和客户可用性指导，请参阅_配置服务_中的专业服务支持。

配置Valkey

要使用Valkey替换Redis，请更新以下文件：

.magento/services.yaml
.magento.app.yaml

配置服务

在.magento/services.yaml中，将Redis服务定义替换为Valkey服务定义。将<version>替换为您的Adobe Commerce版本和当前云模板支持的Valkey版本。

cache:
  type: valkey:<version>

示例

cache:
  type: valkey:8.0

示例版本不是通用的。实际的默认服务版本和支持的服务版本取决于您的Adobe Commerce版本和当前的Cloud模板。使用当前项目模板指定的版本。有关详细信息，请参阅配置服务。

WARNING

如果更改服务ID，则会删除现有服务并创建新服务。永久删除已删除服务中的现有数据。在重命名服务之前备份环境。

将type值从redis:<version>更改为valkey:<version>时，即使您保留了相同的服务ID，也不要假定缓存和会话数据会保留。将迁移视为创建新的缓存：无法保证保留现有缓存和会话数据，并且在迁移完成后用户将注销。

配置服务关系

在.magento.app.yaml中，配置应用程序与Valkey服务之间的关系：

relationships:
  valkey: "cache:valkey"

关系键valkey是应用程序用于访问服务的名称。值cache:valkey引用了.magento/services.yaml中定义的服务ID和服务类型。

TIP

Adobe Commerce通过credis客户端库与Valkey进行通信，默认情况下，该库通过普通PHP套接字工作。若要提高性能，请在.magento.app.yaml中启用redis PHP扩展。 credis在编译后的扩展可用时自动使用该扩展。

code language-yaml
`runtime: extensions: - redis`

提交并部署更改

添加、提交和推送配置更改：

git add .magento/services.yaml .magento.app.yaml
git commit -m "Enable Valkey service"
git push origin <branch-name>

部署完成后，验证Valkey服务关系是否可用。

TIP

在初始服务设置之后，您可以通过更新services.yaml和.magento.app.yaml配置文件来更改已安装服务的软件版本。有关升级或降级服务的指导，请参阅更改服务版本。此自助方法不适用于Pro暂存或生产环境 — 请参阅_配置服务_中的Pro服务支持。

NOTE

即使在迁移到Valkey后，New Relic仍可能会显示Redis。

预计New Relic将继续将缓存服务称为Redis，即使环境已迁移到Valkey也是如此。

Valkey是Redis的开源分支，一些工具和集成继续使用Redis命名而不是不同的Valkey标签来标识服务。此行为并不一定表明仍安装了Redis。

自定义Valkey配置

有关缓存、会话、L2和副本连接建议，请参阅 实施行动手册最佳实践指南 中的Valkey和Redis服务配置的最佳实践。

验证服务关系

要显示已解码的MAGENTO_CLOUD_RELATIONSHIPS对象，请在部署配置后从应用程序容器中运行以下命令：

使用SSH连接到远程云环境，然后运行：

echo "$MAGENTO_CLOUD_RELATIONSHIPS" | base64 -d | json_pp

该命令显示所有已配置的服务关系。要识别Valkey连接详细信息，请找到valkey关系。

示例输出

以下缩写示例显示了valkey关系。它不是一个通用的架构。

{
   "database" : [
      {
         "host" : "database.internal",
         "port" : 3306,
         "path" : "main",
         "scheme" : "mysql"
      }
   ],
   "opensearch" : [
      {
         "host" : "opensearch.internal",
         "port" : 9200,
         "path" : null,
         "scheme" : "http"
      }
   ],
   "valkey" : [
      {
         "host" : "valkey.internal",
         "port" : 6379,
         "path" : null,
         "scheme" : "valkey"
      }
   ]
}

输出因环境和服务配置而异。请勿对此示例中的主机名、端口、IP地址、群集名称、服务版本、用户名或密码进行硬编码。在目标环境中使用MAGENTO_CLOUD_RELATIONSHIPS返回的值。

如果jq可用，则仅显示Valkey关系：

printf '%s' "$MAGENTO_CLOUD_RELATIONSHIPS" \
  | base64 -d \
  | jq '{valkey: .valkey}'

有关服务关系的详细信息，请参阅配置服务。

使用Valkey CLI

假定您的Valkey关系名为valkey，请使用MAGENTO_CLOUD_RELATIONSHIPS返回的主机和端口连接到Valkey：

valkey-cli -h <host> -p <port>

示例

valkey-cli -h valkey.internal -p 6379

获取已安装的Valkey版本

集成环境

在集成环境中，使用valkey关系返回的主机和端口运行：

code language-terminal
`valkey-cli -h <host> -p <port> info \| grep version`

示例响应

code language-text
`valkey_version:<installed-version> gcc_version:<gcc-version>`

版本和内部版本详细信息因环境而异。请勿将显示的示例版本视为必需或通用服务版本。

专业暂存和生产

在专业暂存和生产环境中，运行：

code language-terminal
`valkey-server -v`

示例响应

code language-text
`Valkey server v=<installed-version> ...`

版本和内部版本详细信息因环境而异。请勿将显示的示例版本视为必需或通用服务版本。

Valkey疑难解答

Cache-clean错误引用Valkey配置的缓存上的Redis

预部署缓存清理失败可能会显示错误代码[107] (clean-redis-cache)和Connection to Redis消息，即使cache服务配置为Valkey也是如此。无论后备缓存服务是Redis还是Valkey，ece-tools都会将此错误代码和消息用于缓存清理步骤。

如果基础错误是DNS故障（如关系主机的Name or service not known），则部署步骤在服务关系可用之前运行，或者.magento.app.yaml中的关系名称与.magento/services.yaml中的服务ID不匹配。请参阅验证服务关系。

recommendation-more-help

commerce-on-cloud-help-cloud-guide