[僅限PaaS]{class="badge informative" title="僅適用於雲端專案(Adobe管理的PaaS基礎結構)和內部部署專案的Adobe Commerce 。"}

使用Valkey進行工作階段儲存

Last update: Tue Mar 31 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

主題：
設定
快取

建立對象：

經驗豐富
管理員
開發人員

IMPORTANT

您必須安裝Valkey，才能繼續。

Adobe Commerce提供命令列選項，用於設定Valkey工作階段存放區。

執行setup:config:set命令並指定Valkey特定引數。

bin/magento setup:config:set --session-save=valkey --session-save-valkey-<parameter_name>=<parameter_value>...

--session-save=valkey啟用Valkey工作階段存放區。如果已啟用此功能，請忽略此引數。
--session-save-valkey-<parameter_name>=<parameter_value>是設定工作階段存放區的引數/值配對清單：

NOTE

從 Adobe Commerce 2.4.9-alpha2 開始，Valkey已因授權變更正式取代CLI工具中的Redis。 Valkey是Redis的分支，可維護幾乎相同的功能。對於版本2.4.8和更早版本，用於設定Valkey的CLI命令與Redis的命令相同，可確保順暢的回溯相容性，並簡化移轉或雙環境支援。下列範例顯示Valkey特定命令。

bin/magento setup:config:set --session-save=redis --session-save-redis-<parameter_name>=<parameter_value>...

命令列引數

引數名稱

含義

預設值

session-save-valkey-host

主機

完整的主機名稱、IP位址或絕對路徑（若使用UNIX通訊端）。

localhost

session-save-valkey-port

連線埠

Valkey伺服器接聽連線埠。

6379

session-save-valkey-password

密碼

如果Valkey伺服器需要驗證，請指定密碼。

空白

session-save-valkey-timeout

逾時

連線逾時（秒）。

2.5

session-save-valkey-persistent-id

persistent_identifier

啟用持續連線的唯一字串（例如，sess-db0）。
phpredis和php-fpm的已知問題。

session-save-valkey-db

資料庫

唯一的Valkey資料庫編號，建議用來防止資料遺失。

重要：如果您將Valkey用於多種快取型別，則資料庫編號必須不同。建議您將預設快取資料庫編號指派給0，將分頁快取資料庫編號指派給1，並將工作階段儲存資料庫編號指派給2。

session-save-valkey-compression-threshold

compression_threshold

設定為0以停用壓縮（建議在suhosin.session.encrypt = On時使用）。

2048

session-save-valkey-compression-lib

compression_library

選項： gzip、lzf、lz4或snappy。

gzip

session-save-valkey-log-level

log_level

設為下列任一項，依從少到多的順序列出：

0 （緊急：只有最嚴重的錯誤）
1 （警示：需要立即動作）
2 （嚴重：應用程式元件無法使用）
3 （錯誤：執行階段錯誤，非嚴重，但必須監視）
4 （警告：其他資訊，建議）
5 （注意：正常但重要的情況）
6 （資訊：資訊訊息）
7 （除錯：僅供開發或測試使用的最多資訊）

session-save-valkey-max-concurrency

max_concurrency

可等候鎖定一個工作階段的最大處理序數目。對於大型生產叢集，請將此項設定為至少PHP流程數的10%。

session-save-valkey-break-after-frontend

break_after_frontend

嘗試解除前端（亦即storefront）工作階段鎖定之前等待的秒數。

session-save-valkey-break-after-adminhtml

break_after_adminhtml

嘗試中斷Admin HTML （即管理員）工作階段鎖定之前的等待秒數。

session-save-valkey-first-lifetime

first_lifetime

非機器人第一次寫入工作階段的期限（以秒為單位），或使用0加以停用。

600

session-save-valkey-bot-first-lifetime

bot_first_lifetime

機器人第一次寫入工作階段的存留期（以秒為單位），或使用0加以停用。

session-save-valkey-bot-lifetime

bot_lifetime

後續寫入的機器人工作階段存留期（以秒為單位），或使用0加以停用。

7200

session-save-valkey-disable-locking

disable_locking

完全停用工作階段鎖定。

0 (false)

session-save-valkey-min-lifetime

min_lifetime

工作階段存留期下限（以秒為單位）。

session-save-valkey-max-lifetime

max_lifetime

最長工作階段存留期（以秒為單位）。

2592000 （720小時）

session-save-valkey-sentinel-master

sentinel_master

Valkey Sentinel主名稱。

空白

session-save-valkey-sentinel-servers

sentinel_servers

Valkey Sentinel伺服器清單（以逗號分隔）。

空白

session-save-valkey-sentinel-verify-master

sentinel_verify_master

驗證Valkey Sentinel主要狀態旗標。

0 (false)

session-save-valkey-sentinel-connect-retries

sentinel_connect_retries

Sentinels的連線重試。

範例

下列範例將Valkey設為工作階段資料存放區，將主機設為127.0.0.1，將記錄層級設為4，並將資料庫編號設為2。所有其他引數都會設定為預設值。

bin/magento setup:config:set --session-save=valkey --session-save-valkey-host=127.0.0.1 --session-save-valkey-log-level=4 --session-save-valkey-db=2

NOTE

從 Adobe Commerce 2.4.9 開始，Valkey已因授權變更正式取代CLI工具中的Redis。 Valkey是Redis的分支，可維護幾乎相同的功能。對於版本2.4.8和更早版本，用於設定Valkey的CLI命令與Redis的命令相同，可確保順暢的回溯相容性，並簡化移轉或雙環境支援。下列範例顯示Valkey特定命令。

bin/magento setup:config:set --session-save=redis --session-save-redis-host=127.0.0.1 --session-save-redis-log-level=4 --session-save-redis-db=2

結果

Commerce將類似下列的行新增至<magento_root>app/etc/env.php：

'session' => [
    'save' => 'valkey',
    'redis' => [
        'host' => '127.0.0.1',
        'port' => '6379',
        'password' => '',
        'timeout' => '2.5',
        'persistent_identifier' => '',
        'database' => '2',
        'compression_threshold' => '2048',
        'compression_library' => 'gzip',
        'log_level' => '4',
        'max_concurrency' => '6',
        'break_after_frontend' => '5',
        'break_after_adminhtml' => '30',
        'first_lifetime' => '600',
        'bot_first_lifetime' => '60',
        'bot_lifetime' => '7200',
        'disable_locking' => '0',
        'min_lifetime' => '60',
        'max_lifetime' => '2592000',
    ],
],

INFO

工作階段記錄的TTL使用Cookie期限的值，此值是在管理員中設定。如果Cookie期限設定為0 （預設為3600），則Valkey工作階段會在min_lifetime中指定的秒數內到期（預設為60）。此差異是因為Valkey和工作階段Cookie解譯期限值0的方式有所差異。如果不希望出現這種行為，請增加min_lifetime的值。

驗證Valkey連線

若要確認Valkey和Commerce是否正常運作，請登入Valkey執行所在的伺服器、開啟終端機，然後使用valkey-cli monitor命令或redis-cli ping命令。

Valkey monitor命令

valkey-cli monitor

工作階段儲存輸出範例：

1476824834.187250 [0 127.0.0.1:52353] "select" "0"
1476824834.187587 [0 127.0.0.1:52353] "hmget" "sess_sgmeh2k3t7obl2tsot3h2ss0p1" "data" "writes"
1476824834.187939 [0 127.0.0.1:52353] "expire" "sess_sgmeh2k3t7obl2tsot3h2ss0p1" "1200"
1476824834.257226 [0 127.0.0.1:52353] "select" "0"
1476824834.257239 [0 127.0.0.1:52353] "hmset" "sess_sgmeh2k3t7obl2tsot3h2ss0p1" "data" "_session_validator_data|a:4:{s:11:\"remote_addr\";s:12:\"10.235.34.14\";s:8:\"http_via\";s:0:\"\";s:20:\"http_x_forwarded_for\";s:0:\"\";s:15:\"http_user_agent\";s:115:\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.143 Safari/537.36\";}_session_hosts|a:1:{s:12:\"10.235.32.10\";b:1;}admin|a:0:{}default|a:2:{s:9:\"_form_key\";s:16:\"e331ugBN7vRjGMgk\";s:12:\"visitor_data\";a:3:{s:13:\"last_visit_at\";s:19:\"2016-10-18 21:06:37\";s:10:\"session_id\";s:26:\"sgmeh2k3t7obl2tsot3h2ss0p1\";s:10:\"visitor_id\";s:1:\"9\";}}adminhtml|a:0:{}customer_base|a:1:{s:20:\"customer_segment_ids\";a:1:{i:1;a:0:{}}}checkout|a:0:{}" "lock" "0"
... more ...

Valkey ping命令

valkey-cli ping

預期的回應是： PONG。

如果兩個命令都成功，就會正確設定Valkey。

檢查壓縮資料

為了檢查壓縮的工作階段資料和頁面快取，RESP.app支援自動解壓縮Commerce 2工作階段和頁面快取，並以人類可讀的格式顯示PHP工作階段資料。

recommendation-more-help

386822bd-e32c-40a8-81c2-ed90ad1e198c