設定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。

使用下列指示在Pro整合環境與入門環境（包括master分支）上進行服務設定。

NOTE

若要變更Pro生產和中繼環境上的服務組態，請提交Adobe Commerce支援票證。如需排程需求與客戶可用性指引，請參閱_設定服務_中的專業服務支援。

設定Valkey

若要使用Valkey取代Redis，請更新下列檔案：

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

設定服務

在.magento/services.yaml中，以Valkey服務定義取代Redis服務定義。以您的Adobe Commerce版本和目前的雲端範本支援的Valkey版本取代<version>。

cache:
  type: valkey:<version>

範例

cache:
  type: valkey:8.0

範例版本並非通用。實際的預設和支援服務版本取決於您的Adobe Commerce版本和目前的雲端範本。使用目前專案範本指定的版本。如需詳細資訊，請參閱設定服務。

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。

即使在環境已移轉至Valkey後，預計New Relic仍會繼續將快取服務稱為Redis。

Valkey是Redis的開放原始碼復本，而且有些工具和整合專案會繼續使用Redis命名來識別服務，而非不同的Valkey標籤。此行為並不一定表示仍安裝Redis。

自訂Valkey設定

如需快取、工作階段、L2和復本連線建議，請參閱 實作Playbook最佳作法指南 中的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>`

版本和組建詳細資料會因環境而異。請勿將顯示的範例版本視為必要或通用服務版本。

Pro測試和生產

在Pro測試和生產環境中，執行：

code language-terminal
`valkey-server -v`

範例回應

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

版本和組建詳細資料會因環境而異。請勿將顯示的範例版本視為必要或通用服務版本。

疑難排解Valkey

快取清除錯誤參考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中的服務識別碼不符。請參閱驗證服務關係。

recommendation-more-help

commerce-on-cloud-help-cloud-guide