在 Redis 的世界裡，redis-cli (Redis Command Line Interface) 不僅僅是一個工具，更是開發者和系統管理員與 the redis server 直接互動的最重要橋樑。無論是進行快速的資料操作、執行日常維護、偵錯複雜問題，還是進行 performance 診斷，redis-cli 都扮演著不可或缺的角色。它是一個輕量級但功能極其強大的終端程式，允許使用者將 commands 傳送到任何 Redis instance，並即時讀取伺服器的回應。
許多開發者初次接觸 Redis 時，可能僅止於使用 PING、SET、GET 等基本指令來驗證服務是否正常運作。然而，redis-cli 的能力遠不止於此。它提供了豐富的命令列選項、多種互動模式，以及一系列專為效能分析和問題排查而設計的進階功能。
本文旨在成為一份關於 the redis command line tool (redis-cli) 的終極指南。我們將從最基礎的安裝步驟開始，系統性地介紹 how to 在不同作業系統（Windows、Linux、macOS）下安裝，並特別比較新舊版本在 Windows 上的差異。接著，我們將深入探討連線到本地及雲端 Redis 執行個體的完整流程與必要 options，包括針對 security 至關重要的 TLS 加密 connections。
在不同作業系統下安裝 redis-cli
redis-cli 通常作為 Redis 完整套件的一部分提供。因此，安裝 redis-cli 最直接的方式就是安裝 Redis。
在 Linux 上安裝
在大多數 Linux 發行版中，可以透過其內建的套件管理器輕鬆安裝 Redis。
- 基於 Debian/Ubuntu 的系統： bash sudo apt-get update sudo apt-get install redis-tools 註：redis-tools package 專門提供 redis-cli 等客戶端工具，若您不需要在該主機上運行 Redis 伺服器，這是一個更輕量的選擇。若需完整功能，可安裝 redis-server。
- 基於 RHEL/CentOS/Fedora 的系統：
sudo yum install redis
或在新版 Fedora/CentOS 8+ 上使用 dnf
sudo dnf install redis
- 從原始碼編譯安裝（獲取最新版本或啟用特定功能）：
有時官方套件庫的版本較舊，或您需要啟用像 TLS 這樣的特定編譯選項。從原始碼安裝是最佳選擇，這也是 best practices 之一。安裝編譯所需的依賴
sudo yum install gcc make openssl-devel
下載最新的穩定版 Redis
wget https://download.redis.io/releases/redis-stable.tar.gz
tar xzf redis-stable.tar.gz
cd redis-stable進行編譯，特別注意：若要讓 redis-cli 支援 TLS，必須加上 BUILD_TLS=yes
make BUILD_TLS=yes
將編譯好的 redis-cli 複製到系統路徑下，方便隨時呼叫
sudo cp src/redis-cli /usr/local/bin/
驗證版本
redis-cli –version
在 Windows 上安裝
在 Windows 上安裝 redis-cli 的方式較為多元，主要有以下三種途徑，各有其適用情境。
現代推薦方案：適用於 Linux 的 Windows 子系統 (WSL)
這是目前 Microsoft 官方與 Redis 社羣最推薦的方式。WSL 讓您可以在 Windows 內運行一個完整的 Linux 發行版，從而能夠原生、無縫地使用 redis-cli 等 Linux 工具。
- 步驟一：安裝 WSL
以系統管理員身分開啟 PowerShell 或 Windows 命令提示字元，然後輸入： powershell wsl –install 此命令會自動啟用所需功能、下載最新的 Linux 核心、並預設安裝 Ubuntu。 - 步驟二：在 WSL 中安裝 Redis 工具
安裝完成後，開啟 Ubuntu (或您選擇的 Linux 發行版)，然後執行與 Linux 上相同的安裝指令： bash sudo apt-get update sudo apt-get install redis-tools
這樣您就可以在 WSL 環境中，如同在原生 Linux 上一樣使用 redis-cli 的所有功能，包含完整的 TLS 支援。
原生 Windows 版本（社羣維護）
雖然 Redis 官方並未正式支援 Windows，但社羣提供了穩定的原生 Windows 版本。其中 tporadowski/redis 這個 GitHub 專案是目前最活躍且推薦的選擇，它提供了比舊版更完整的 Redis 5.0.10 等版本。
- You can 前往 https://github.com/tporadowski/redis/releases。
- 下載最新的 .zip 或 .msi 安裝檔。
- 如果您只需要 redis-cli，可以下載 .zip 檔並解壓縮，直接執行 redis-cli.exe。
舊版官方封存（已停止更新）
過去 Microsoft 曾維護一個 Redis 的 Windows 移植版 (MicrosoftArchive/redis)。許多舊的教學文章（如本文參考資料中的 m@rcus 學習筆記）皆以此版本為基礎。但請注意，此版本已停止更新，其最新版本僅為 3.2.100，與目前 Redis 主流版本（6.x、7.x）差異巨大，缺少許多新功能與資料結構，不建議用於新的專案。
在 macOS 上安裝
在 macOS 上，使用 Homebrew 是最簡單方便的方式。
brew install redis
安裝完成後，redis-cli 將會自動加入到您的系統路徑中。
連線到 Redis 執行個體
成功安裝後，下一步就是使用 redis-cli 連線到您的 Redis 伺服器。連線過程可以拆解為以下幾個關鍵步驟。
步驟一：準備連線資訊
無論您的 Redis database 在哪裡，都至少需要 the following 資訊：
- 主機名稱 (Hostname): 伺服器的 IP 位址或網域名稱。本機通常是 127.0.0.1 或 localhost。雲端服務商（如 Azure, AWS, 阿里雲）會提供一個專屬的連線端點，格式通常類似 <cachename>.redis.cache.windows.net 或 r-bp1zxszhcgatnx.redis.rds.aliyuncs.com。
- 通訊埠 (Port): Redis 伺服器監聽的埠號。預設為 6379。部分雲端服務或啟用 TLS 的執行個體可能會使用不同的埠，例如 Azure Cache for Redis 的 TLS 埠為 6380，企業級則為 10000。
- 密碼 (Password / Access Key): 如果 Redis 伺服器設定了密碼保護（requirepass 指令），則 connect 時必須提供。此 authentication 對於 security 至關重要。在雲端環境中，這通常被稱為「存取金鑰 (Access Key)」。
步驟二：網路與防火牆設定
當您 connect to 一個遠端的 instance 時，請務必確認 the network path 是通暢的：
- IP 白名單： 大多數雲端 Redis 服務都要求將客戶端的公用 IP 位址加入到執行個體的「白名單」或「防火牆規則」中。只有在白名單內的 IP 才能成功連線。若出現 (error) ERR illegal address 或 client ip is not in whitelist 的錯誤，這通常是首要檢查項目。
- VPC/專用網路： 如果您的應用程式和 Redis 執行個體位於同一個雲端專用網路 (VPC) 中，應使用其私有 IP 或內部端點進行連線，這樣更安全且效能更佳。
步驟三：執行連線指令與參數詳解
redis-cli 提供了豐富的命令列參數來滿足不同的連線需求。
| 參數 (Parameter) | 說明 (Description) | 範例 (Example) |
|---|---|---|
| -h <hostname> | 指定要連線的 Redis 伺服器主機名稱或 IP 位址。預設為 127.0.0.1。 | -h my-redis.example.com |
| -p <port> | 指定 Redis 伺服器的通訊埠。預設為 6379。 | -p 6380 |
| -a <password> | 指定連線密碼。如果 Redis 設定了 requirepass，則必須提供。 | -a “MyStrongPassword123” |
| –user <username> | 搭配 -a 或 –pass 使用，用於 Redis 6 ACL (Access Control List) 的使用者名稱驗證。 | –user myapp -a “Password” |
| –pass <password> | -a 的別名，功能完全相同。 | –pass “AnotherPassword” |
| -c | 啟用叢集模式 (Cluster Mode)。當您連線到 Redis Cluster 時，此 option 會讓 redis-cli 自動處理 MOVED 和 ASK 重新導向，讓您能無縫地對整個叢集操作。 | -c |
| –tls | 建立一個安全的 TLS/SSL 加密連線。連線到所有現代雲端 Redis 服務時，這幾乎是必要選項。 | –tls |
| –raw | 顯示原始輸出。當 Redis 回應中包含非 ASCII 字元（如中文）時，在某些終端環境下可能會顯示為亂碼。使用此參數可以確保正確顯示。 | –raw |
| –latency | 進入一個持續取樣延遲的特殊模式，即時顯示延遲統計數據。 | redis-cli –latency |
| –latency-history | 類似 –latency，但會追蹤延遲隨時間的變化。預設每 15 秒更新一次。 | redis-cli –latency-history -i 5 (每 5 秒更新) |
| –bigkeys | 對鍵空間進行取樣，尋找包含大量元素的「大鍵」(Big Keys)。這對於發現潛在的記憶體問題非常有用。 | redis-cli –bigkeys |
| –hotkeys | 尋找被頻繁存取的「熱鍵」(Hot Keys)。此功能要求 Redis 的 maxmemory-policy 設定為 *lfu (Least Frequently Used) 之一。 | redis-cli –hotkeys |
連線範例：
- 連線到本機、無密碼的 Redis： bash redis-cli
- 連線到遠端、有密碼的 Redis 實例： bash redis-cli -h 192.168.1.100 -p 6379 -a “YourPassword”
- 連線到 Azure Cache for Redis (啟用 TLS)： bash redis-cli -h mycache.redis.cache.windows.net -p 6380 -a <YourAccessKey> –tls
- 連線到啟用 TLS 的 Redis Cluster： bash redis-cli -h my-cluster-endpoint.com -p 6379 -a <YourPassword> –tls -c
基礎與進階指令操作
連線成功後，您會看到一個提示符，如 127.0.0.1:6379>，表示 redis-cli 已進入互動模式，可以開始輸入 Redis 指令。
基礎指令
以下是在日常開發與測試中最常用的一些基礎指令：
- PING: 測試伺服器連線是否正常。如果一切順利，伺服器會回應 PONG。 127.0.0.1:6379> PING PONG
- SET key value: 設定一個字串類型的值。例如，一個簡單的 hello world 實例： 127.0.0.1:6379> SET msg “hello world” OK
- GET key: 取得一個字串類型的值。 127.0.0.1:6379> GET msg “hello world”
- DEL key [key …]: 刪除一個或多個鍵。 127.0.0.1:6379> DEL msg (integer) 1
- EXISTS key: 檢查指定的鍵是否存在。 127.0.0.1:6379> EXISTS msg (integer) 0
- KEYS pattern: 尋找符合指定模式的鍵。警告：KEYS 是一個阻塞操作，在正式環境的龐大資料庫中使用 KEYS 會掃描所有鍵，可能導致服務長時間停頓，應極力避免。請改用 SCAN 指令。 127.0.0.1:6379> KEYS user: 1) “user:2:name” 2) “user:1:profile”
- SCAN cursor [MATCH pattern] [COUNT count]: 安全地迭代鍵空間。它是一個非阻塞的指令，非常適合在正式環境中 to use。
進階監控與診斷指令
redis-cli 不僅能操作資料，更是強大的診斷工具。
- MONITOR: 這是一個偵錯指令，能夠即時串流顯示 Redis 伺服器正在處理的每一條指令。這對於理解應用程式與 the redis 的實際互動非常有幫助。You can 也將此輸出管道傳送到另一個分析 tool。 127.0.0.1:6379> MONITOR OK 1669275823.385788 [0 127.0.0.1:58960] “SET” “mykey” “hello” 1669275825.834958 [0 127.0.0.1:58960] “GET” “mykey” 注意：
- MONITOR 會帶來效能開銷，因為它會將所有指令推送到所有監聽的客戶端。只應在偵錯期間短暫使用。
- 出於安全考量，AUTH 等管理指令不會被 MONITOR 記錄。
- 在極端高併發下，MONITOR 可能導致客戶端輸出緩衝區 (client output buffer) 快速增長，耗盡伺服器記憶體。
- CLIENT LIST: 列出所有目前連線到伺服器的客戶端資訊，包括 IP 位址、連線時長、閒置時間、正在執行的指令等。這對於排查惡意連線或發現有問題的客戶端非常有價值。 127.0.0.1:6379> CLIENT LIST id=5 addr=127.0.0.1:58960 … age=18 idle=0 flags=N … cmd=client
- INFO [section]: 提供關於 Redis 伺服器狀態的詳盡資訊。可以不帶參數以獲取所有資訊，也可以指定區塊（如 server, memory, stats, replication）來獲取特定部分的資訊。您也可以 from the 官方 INFO command 文件中獲取更多資訊。 “`
127.0.0.1:6379> INFO memoryMemory
used_memory:1056896
used_memory_human:1.01M
… - SLOWLOG GET [count]: 獲取 Redis 的慢查詢日誌。Redis 會記錄執行時間超過指定閾值（透過 slowlog-log-slower-than 設定）的指令。這是效能調校的關鍵工具。
常見問題 (FAQ)
Q1: 我嘗試連線到雲端 Redis，但收到 (error) ERR illegal address 或 client ip is not in whitelist 的錯誤，該如何解決？
A: 這個錯誤明確表示您的客戶端 IP 位址未被 Redis 伺服器的防火牆或安全規則所允許。您需要登入您的雲端服務供應商（如 Azure、AWS、阿里雲）的管理 console，找到您的 Redis 執行個體的網路設定或防火牆規則，並將您執行 redis-cli 的機器的公用 IP 位址新增到允許存取的白名單中。
Q2: 我確定密碼是正確的，但連線時一直提示 (error) WRONGPASS invalid username-password pair，這是為什麼？
A: 這個錯誤通常有兩種可能。第一，密碼確實輸入錯誤，請仔細檢查是否有複製貼上多餘的空格或特殊字元。第二，如果您的 Redis 伺服器版本為 6.0 或以上，並且啟用了 ACL (Access Control List)，那麼驗證可能不僅需要密碼，還需要使用者名稱。在這種情況下，正確的 AUTH 指令格式是 AUTH <username> <password>。如果使用 redis-cli 的 -a 參數，您需要同時提供 –user 參數，例如：redis-cli –user myuser -a “mypassword”。
Q3: 我在 Windows 的命令提示字元 (cmd) 中使用 redis-cli 存取包含中文的資料時，顯示的是亂碼，怎麼辦？
A: 這是 Windows 終端對 UTF-8 字元編碼支援不佳的典型問題。redis-cli 提供了一個專門解決此問題的參數：–raw。當您使用此參數啟動 redis-cli 時，它會將伺服器返回的原始位元組流直接輸出到終端，從而避免被轉碼而導致亂碼。
範例：redis-cli –raw
Q4: 我無法連線到啟用了 TLS 的 Redis 執行個體，明明主機、埠和密碼都正確。
A: 連線到啟用 TLS/SSL 的 Redis 伺服器時，必須在 redis-cli 指令中明確加上 –tls 旗標。如果加上後仍然失敗，請確認您的 redis-cli 版本是否支援 TLS。較舊的版本或未經特定編譯的版本可能不包含此功能。您可以透過從原始碼編譯並加上 BUILD_TLS=yes 參數來確保您的 redis-cli 具備完整的 TLS 支援能力。
Q5: 為什麼大家都不推薦在正式環境中使用 KEYS * 指令？我應該用什麼來替代？
A: KEYS 指令是一個阻塞式操作。當它執行時，Redis 伺服器會暫停處理其他所有指令，直到遍歷完整個鍵空間並返回結果。在一個擁有數百萬甚至數億個鍵的資料庫中，這個過程可能會持續數秒甚至更久，導致服務中斷，引發嚴重的效能問題。
正確的替代方案是使用 SCAN 指令。SCAN 是一個基於遊標的非阻塞迭代器，它每次只返回一小部分鍵，並給出一個新的遊標供下次迭代使用，直到遊標返回 0 為止。這樣可以在不阻塞伺服器的情況下安全地遍歷所有鍵。
總結與心得
redis-cli 是每一位 Redis 使用者都應熟練掌握的瑞士軍刀。它遠非一個簡單的指令執行器，而是一個集資料操作、系統管理、效能監控與問題診斷於一身的綜合性工具。
本文從多個維度對 redis-cli 進行了深入剖析：
- 安裝： 我們強調了在 Windows 上使用 WSL 的現代化作法，同時也回顧了舊版和社羣維護版的原生安裝方式，讓使用者能根據需求做出最佳選擇。
- 連線： 詳細拆解了連線所需的資訊、網路配置以及 redis-cli 強大的命令列參數，特別是針對雲端服務和叢集環境中至關重要的 –tls 和 -c 選項。
- 操作與診斷： 除了基礎的 CRUD 指令，我們更著重介紹了 MONITOR、CLIENT LIST、INFO 等進階指令，以及 –latency、–bigkeys 等診斷參數的應用，這些都是揭開 Redis 效能面紗的利器。
精通 redis-cli，意味著您將能更自信、更精準地管理您的 Redis 執行個體，快速定位並解決問題，從而確保應用程式的高效能與穩定性。希望這份詳盡的指南，能夠成為您在 Redis 探索之路上的一份可靠參考。
總結這次的學習心得，我們可以看到 redis-cli 的設計哲學是提供一個直接且高效的介面。對於開發者來說，熟悉這個 tool 的各種 options 和 best practices 是提升 development 效率和保障系統 performance 的不二法門。
