用法

valkey-cli [选项] [命令 [参数...]]

描述

Valkey 命令行界面用于管理、故障排除和试验 Valkey。

在交互模式下，valkey-cli 具有基本的行编辑功能，可提供熟悉的输入体验。

要以特殊模式启动程序，可以使用以下几个选项，包括

模拟一个副本，并打印它从主服务器接收到的复制流。
检查 Valkey 服务器的延迟并显示统计信息。
请求延迟样本和频率的 ASCII 艺术频谱图。

本主题涵盖了 valkey-cli 的不同方面，从最简单的功能开始，到更高级的功能结束。

选项

-h 主机名 : 服务器主机名 (默认: 127.0.0.1)。

-p 端口 : 服务器端口 (默认: 6379)。

-t 超时 : 服务器连接超时时间，单位为秒（允许小数）。默认超时时间为 0，表示没有限制，取决于操作系统。

-s 套接字 : 服务器套接字（覆盖主机名和端口）。

-a 密码 : 连接服务器时使用的密码。您也可以使用 VALKEYCLI_AUTH 环境变量更安全地传递此密码。（如果两者都使用，此参数优先。）

--user 用户名 : 用于发送 ACL 风格的 'AUTH 用户名密码'。需要 -a。

--pass 密码 : 作为 -a 的别名，与新的 --user 选项保持一致。

--askpass : 强制用户从 STDIN 输入密码并进行遮罩。如果使用此参数，-a 和 VALKEYCLI_AUTH 环境变量将被忽略。

-u URI : 服务器 URI 格式为 valkey://user:password@host:port/dbnum。用户、密码和数据库编号是可选的。如果无需用户名进行身份验证，请使用用户名 'default'。对于 TLS，请使用 'valkeys' 方案。

-r 重复次数 : 执行指定命令 N 次。

-i 间隔 : 当使用 -r 时，每条命令等待间隔秒。可以指定小于一秒的时间，例如 -i 0.1。此间隔也用于 --scan 和 --stat 的每个周期，以及 --bigkeys、--memkeys 和 --hotkeys 的每 100 个周期。

-n 数据库 : 数据库编号。

-2 : 以 RESP2 协议模式启动会话。

-3 : 以 RESP3 协议模式启动会话。

-x : 从 STDIN 读取最后一个参数（参见下面的示例）。

-X : 读取参数从 STDIN（参见下面的示例）。

-d 分隔符 : 原始格式中响应批次之间的分隔符（默认: \n）。

-D 分隔符 : 原始格式中响应之间的分隔符（默认: \n）。

-c : 启用集群模式（遵循 -ASK 和 -MOVED 重定向）。

-e : 命令执行失败时返回退出错误码。

-4 : 在 DNS 查找时优先使用 IPv4 而非 IPv6。

-6 : 在 DNS 查找时优先使用 IPv6 而非 IPv4。

--tls : 建立安全的 TLS 连接。

--sni 主机 : 用于 TLS 的服务器名称指示。

--cacert 文件 : 用于验证的 CA 证书文件。

--cacertdir 目录 : 存储受信任 CA 证书的目录。如果既未指定 cacert 也未指定 cacertdir，则将应用默认的全系统受信任根证书配置。

--insecure : 通过跳过证书验证来允许不安全的 TLS 连接。

--cert 文件 : 用于身份验证的客户端证书。

--key 文件 : 用于身份验证的私钥文件。

--tls-ciphers 列表 : 设置首选密码（TLSv1.2 及以下）列表，按优先级从高到低排列，以冒号（":"）分隔。有关此字符串语法的更多信息，请参阅 ciphers(1ssl) 手册页。

--tls-ciphersuites 列表 : 设置首选密码套件（TLSv1.3）列表，按优先级从高到低排列，以冒号（":"）分隔。有关此字符串语法的更多信息，特别是 TLSv1.3 密码套件，请参阅 ciphers(1ssl) 手册页。

--rdma : 建立 RDMA 连接。

--mptcp : 建立 MPTCP 连接。

--raw : 对回复使用原始格式（当 STDOUT 不是 tty 时的默认设置）。

--no-raw : 即使 STDOUT 不是 tty，也强制进行格式化输出。

--quoted-input : 强制将输入视为带引号的字符串处理。

--csv : 以 CSV 格式输出。

--json : 以 JSON 格式输出（默认 RESP3，如果想与 RESP2 一起使用，请使用 -2）。

--quoted-json : 与 --json 相同，但生成 ASCII 安全的带引号字符串，而不是 Unicode。

--show-pushes yes|no : 是否打印 RESP3 PUSH 消息。当 STDOUT 是 tty 时默认启用，但可以通过 --show-pushes no 覆盖。

--stat : 打印服务器的滚动统计信息：内存、客户端等...

--latency : 进入持续采样延迟的特殊模式。如果在交互式会话中使用此模式，它将永远运行并显示实时统计信息。否则，如果指定了 --raw 或 --csv，或者将输出重定向到非 TTY，它将采样延迟 1 秒（您可以使用 -i 更改间隔），然后生成单个输出并退出。

--latency-history : 类似于 --latency，但跟踪延迟随时间的变化。默认时间间隔为 15 秒。使用 -i 更改它。

--latency-dist : 以频谱形式显示延迟，需要 xterm 256 色。默认时间间隔为 1 秒。使用 -i 更改它。

--lru-test 键 : 模拟具有 80-20 分布的缓存工作负载。

--replica : 模拟副本，显示从主服务器接收到的命令。

--rdb 文件名 : 将 RDB 转储从远程服务器传输到本地文件。使用文件名 "-" 写入 stdout。

--functions-rdb 文件名 : 类似于 --rdb，但在获取 RDB 转储文件时只获取函数（而不是键）。

--pipe : 将原始 RESP 协议从 stdin 传输到服务器。

--pipe-timeout n : 在 --pipe 模式下，如果在发送所有数据后 n 秒内未收到回复，则报错中止。默认超时时间：30。使用 0 表示永远等待。

--bigkeys : 采样键以查找具有许多元素（复杂性）的键。

--memkeys : 采样键以查找消耗大量内存的键。

--memkeys-samples n : 采样键以查找消耗大量内存的键。并定义要采样的键元素数量。

--hotkeys : 采样键以查找热点键。仅当 maxmemory-policy 为 *lfu 时有效。这等同于 --hotkeys-count 16。

--hotkeys-count n : 采样键以查找 n 个最热点键。仅当 maxmemory-policy 为 *lfu 时有效。

--scan : 使用 SCAN 命令列出所有键。

--pattern 模式 : 使用 --scan、--bigkeys 或 --hotkeys 选项时的键模式（默认: *）。

--count 计数 : 使用 --scan、--bigkeys 或 --hotkeys 时的计数选项（默认: 10）。

--quoted-pattern 模式 : 与 --pattern 相同，但指定的字符串可以加引号，以便传递一个否则非二进制安全的字符串。

--intrinsic-latency 秒 : 运行测试以测量系统固有延迟。测试将运行指定秒数。

--eval 文件 : 使用文件中的 Lua 脚本发送 EVAL 命令。

--ldb : 与 --eval 一起使用可启用服务器 Lua 调试器。

--ldb-sync-mode : 类似于 --ldb，但使用同步 Lua 调试器，在此模式下服务器将被阻塞，脚本更改不会从服务器内存中回滚。

--cluster 命令 [参数...] [选项...] : 集群管理器命令和参数（参见下文）。

--verbose : 详细模式。

--no-auth-warning : 在命令行界面使用密码时不显示警告消息。

--help : 输出帮助并退出。

--version : 输出版本并退出。

集群管理器命令

对于 Valkey 集群的管理，使用以下语法

valkey-cli --cluster 命令 [参数...] [选项...]

  Command        Args
  --------------------------------------------------------------------------------
  create         host1:port1 ... hostN:portN
                 --cluster-replicas <arg>
  check          <host:port> or <host> <port> - separated by either colon or space
                 --cluster-search-multiple-owners
  info           <host:port> or <host> <port> - separated by either colon or space
  fix            <host:port> or <host> <port> - separated by either colon or space
                 --cluster-search-multiple-owners
                 --cluster-fix-with-unreachable-masters
  reshard        <host:port> or <host> <port> - separated by either colon or space
                 --cluster-from <arg>
                 --cluster-to <arg>
                 --cluster-slots <arg>
                 --cluster-yes
                 --cluster-timeout <arg>
                 --cluster-pipeline <arg>
                 --cluster-replace
  rebalance      <host:port> or <host> <port> - separated by either colon or space
                 --cluster-weight <node1=w1...nodeN=wN>
                 --cluster-use-empty-masters
                 --cluster-timeout <arg>
                 --cluster-simulate
                 --cluster-pipeline <arg>
                 --cluster-threshold <arg>
                 --cluster-replace
  add-node       new_host:new_port existing_host:existing_port
                 --cluster-replica
                 --cluster-master-id <arg>
  del-node       host:port node_id
  call           host:port command arg arg .. arg
                 --cluster-only-masters
                 --cluster-only-replicas
  set-timeout    host:port milliseconds
  import         host:port
                 --cluster-from <arg>
                 --cluster-from-user <arg>
                 --cluster-from-pass <arg>
                 --cluster-from-askpass
                 --cluster-copy
                 --cluster-replace
  backup         host:port backup_directory
  help

命令行用法

要运行 Valkey 命令并在终端返回标准输出，请将要执行的命令作为 valkey-cli 的单独参数包含。

$ valkey-cli INCR mycounter
(integer) 7

命令的回复是 "7"。由于 Valkey 的回复是类型化的（字符串、数组、整数、nil、错误等），您会在括号之间看到回复的类型。当 valkey-cli 的输出必须用作另一个命令的输入或重定向到文件时，此附加信息可能不理想。

valkey-cli 仅在检测到标准输出是 tty 或终端时才显示附加信息以供人类阅读。对于所有其他输出，它将自动启用 原始输出模式，如下例所示

$ valkey-cli INCR mycounter > /tmp/output.txt
$ cat /tmp/output.txt
8

请注意，输出中省略了 (integer)，因为 valkey-cli 检测到输出不再写入终端。您可以使用 --raw 选项强制在终端上进行原始输出

$ valkey-cli --raw INCR mycounter
9

当写入文件或通过管道传输到其他命令时，您可以使用 --no-raw 强制输出为人类可读的格式。

字符串引用和转义

当 valkey-cli 解析命令时，空白字符会自动分隔参数。在交互模式下，换行符将命令发送进行解析和执行。要输入包含空白字符或不可打印字符的字符串值，可以使用带引号和转义的字符串。

带引号的字符串值用双引号 (") 或单引号 (') 括起来。转义序列用于在字符和字符串字面量中放置不可打印的字符。

转义序列包含一个反斜杠 (\) 符号，后跟一个转义序列字符。

双引号字符串支持以下转义序列

\" - 双引号
\n - 换行
\r - 回车
\t - 水平制表符
\b - 退格
\a - 警报
\\ - 反斜杠
\xhh - 任何由十六进制数 (hh) 表示的 ASCII 字符

单引号假定字符串是字面量，并且只允许以下转义序列

\' - 单引号
\\ - 反斜杠

例如，要在两行显示 Hello World

127.0.0.1:6379> SET mykey "Hello\nWorld"
OK
127.0.0.1:6379> GET mykey
Hello
World

当您输入包含单引号或双引号的字符串时（例如在密码中），请转义字符串，如下所示

127.0.0.1:6379> AUTH some_admin_user ">^8T>6Na{u|jp>+v\"55\@_;OU(OR]7mbAYGqsfyu48(j'%hQH7;v*f1H${*gD(Se'"

主机、端口、密码和数据库

默认情况下，valkey-cli 连接到地址 127.0.0.1、端口 6379 的服务器。您可以使用多个命令行选项更改端口。要指定不同的主机名或 IP 地址，请使用 -h 选项。要设置不同的端口，请使用 -p。

$ valkey-cli -h valkey15.example.com -p 6390 PING
PONG

如果您的实例受密码保护，-a <密码> 选项将执行身份验证，从而无需显式使用 AUTH 命令

$ valkey-cli -a myUnguessablePazzzzzword123 PING
PONG

注意: 出于安全原因，请通过 VALKEYCLI_AUTH 环境变量自动向 valkey-cli 提供密码。

最后，可以使用 -n <数据库编号> 选项发送操作于非默认数据库编号（零）的命令

$ valkey-cli FLUSHALL
OK
$ valkey-cli -n 1 INCR a
(integer) 1
$ valkey-cli -n 1 INCR a
(integer) 2
$ valkey-cli -n 2 INCR a
(integer) 1

部分或全部此信息也可以通过使用 -u <URI> 选项和 URI 模式 valkey://user:password@host:port/dbnum 提供

$ valkey-cli -u valkey://LJenkins:p%40ssw0rd@valkey-16379.example.com:16379/0 PING
PONG

注意: 用户、密码和数据库编号是可选的。如果无需用户名进行身份验证，请使用用户名 default。对于 TLS，请使用 valkeys 方案。

SSL/TLS

默认情况下，valkey-cli 使用纯 TCP 连接到 Valkey。您可以使用 --tls 选项以及 --cacert 或 --cacertdir 来启用 SSL/TLS，以配置受信任的根证书包或目录。

如果目标服务器需要使用客户端证书进行身份验证，您可以使用 --cert 和 --key 指定证书和相应的私钥。

从其他程序获取输入

有两种方法可以使用 valkey-cli 从其他命令通过标准输入接收输入。一种是将目标有效负载作为来自 stdin 的最后一个参数。例如，要将 Valkey 键 net_services 设置为本地文件系统中的文件 /etc/services 的内容，请使用 -x 选项

$ valkey-cli -x SET net_services < /etc/services
OK
$ valkey-cli GETRANGE net_services 0 50
"#\n# Network services, Internet style\n#\n# Note that "

在上述会话的第一行中，valkey-cli 使用 -x 选项执行，并将一个文件重定向到 CLI 的标准输入，作为满足 SET net_services 命令短语的值。这对于脚本编写很有用。

另一种方法是向 valkey-cli 提供文本文件中写入的一系列命令

$ cat /tmp/commands.txt
SET item:3374 100
INCR item:3374
APPEND item:3374 xxx
GET item:3374
$ cat /tmp/commands.txt | valkey-cli
OK
(integer) 101
(integer) 6
"101xxx"

commands.txt 中的所有命令都由 valkey-cli 连续执行，就像用户在交互模式下键入的一样。如果需要，文件中的字符串可以加引号，这样就可以拥有包含空格、换行符或其他特殊字符的单个参数。

$ cat /tmp/commands.txt
SET arg_example "This is a single argument"
STRLEN arg_example
$ cat /tmp/commands.txt | valkey-cli
OK
(integer) 25

连续运行相同的命令

可以执行单个命令指定次数，并在每次执行之间进行用户选择的暂停。这在不同的上下文中很有用——例如，当我们想要持续监控某个键的内容或 INFO 字段输出时，或者当我们想要模拟一些重复写入事件时，例如每 5 秒将一个新项目推送到列表中。

此功能由两个选项控制：-r <计数> 和 -i <延迟>。-r 选项表示命令运行的次数，-i 设置不同命令调用之间的延迟时间，单位为秒（可以指定 0.1 等值来表示 100 毫秒）。

默认情况下，间隔（或延迟）设置为 0，因此命令会尽快执行

$ valkey-cli -r 5 INCR counter_value
(integer) 1
(integer) 2
(integer) 3
(integer) 4
(integer) 5

要无限期地运行相同的命令，请使用 -1 作为计数。要随时间监控 RSS 内存大小，可以使用以下命令

$ valkey-cli -r -1 -i 1 INFO | grep rss_human
used_memory_rss_human:2.71M
used_memory_rss_human:2.73M
used_memory_rss_human:2.73M
used_memory_rss_human:2.73M
... a new line will be printed each second ...

使用 `valkey-cli` 进行批量数据插入

使用 valkey-cli 进行批量插入在单独的页面中介绍，因为它本身就是一个有价值的主题。请参阅我们的批量插入指南。

CSV 输出

valkey-cli 中存在 CSV（逗号分隔值）输出功能，用于将数据从 Valkey 导出到外部程序。

$ valkey-cli LPUSH mylist a b c d
(integer) 4
$ valkey-cli --csv LRANGE mylist 0 -1
"d","c","b","a"

请注意，--csv 标志仅适用于单个命令，而不适用于整个数据库的导出。

运行 Lua 脚本

valkey-cli 对使用 Lua 脚本的调试功能提供了广泛支持，该功能从 Valkey 3.2 开始可用。有关此功能，请参阅 Valkey Lua 调试器文档。

即使不使用调试器，valkey-cli 也可以用作从文件运行脚本的参数

$ cat /tmp/script.lua
return server.call('SET',KEYS[1],ARGV[1])
$ valkey-cli --eval /tmp/script.lua location:hastings:temp , 23
OK

Valkey 的 EVAL 命令将脚本使用的键列表和非键参数作为不同的数组。调用 EVAL 时，您提供键的数量作为一个数字。

当使用上述 --eval 选项调用 valkey-cli 时，无需显式指定键的数量。相反，它使用逗号分隔键和参数的约定。这就是为什么在上面的调用中您会看到 location:hastings:temp , 23 作为参数。

因此 location:hastings:temp 将填充 KEYS 数组，而 23 将填充 ARGV 数组。

--eval 选项在编写简单脚本时很有用。对于更复杂的工作，建议使用 Lua 调试器。两种方法可以混合使用，因为调试器也可以从外部文件执行脚本。

交互模式

我们已经探讨了如何将 Valkey CLI 作为命令行程序使用。这对于脚本和某些类型的测试很有用，但大多数人将大部分时间花在 valkey-cli 的交互模式中。

在交互模式下，用户在提示符处键入 Valkey 命令。命令被发送到服务器，处理后，回复被解析并呈现为更简单的形式以便阅读。

在交互模式下运行 valkey-cli 不需要任何特殊操作——只需不带任何参数执行它即可

$ valkey-cli
127.0.0.1:6379> PING
PONG

字符串 127.0.0.1:6379> 是提示符。它显示连接的 Valkey 服务器实例的主机名和端口。

当连接的服务器发生变化或在非零数据库上操作时，提示符会更新

127.0.0.1:6379> SELECT 2
OK
127.0.0.1:6379[2]> DBSIZE
(integer) 1
127.0.0.1:6379[2]> SELECT 0
OK
127.0.0.1:6379> DBSIZE
(integer) 503

处理连接和重新连接

在交互模式下使用 CONNECT 命令可以连接到不同的实例，通过指定要连接的 主机名 和端口

127.0.0.1:6379> CONNECT metal 6379
metal:6379> PING
PONG

如您所见，连接到不同的服务器实例时，提示符会相应地改变。如果尝试连接到不可达的实例，valkey-cli 将进入断开连接模式，并在每个新命令时尝试重新连接

127.0.0.1:6379> CONNECT 127.0.0.1 9999
Could not connect to Valkey at 127.0.0.1:9999: Connection refused
not connected> PING
Could not connect to Valkey at 127.0.0.1:9999: Connection refused
not connected> PING
Could not connect to Valkey at 127.0.0.1:9999: Connection refused

通常，检测到断开连接后，valkey-cli 总是尝试透明地重新连接；如果尝试失败，它会显示错误并进入断开连接状态。以下是断开连接和重新连接的示例

127.0.0.1:6379> INFO SERVER
Could not connect to Valkey at 127.0.0.1:6379: Connection refused
not connected> PING
PONG
127.0.0.1:6379> 
(now we are connected again)

执行重新连接时，valkey-cli 会自动重新选择最后选择的数据库编号。但是，所有其他关于连接的状态都会丢失，例如在 MULTI/EXEC 事务中

$ valkey-cli
127.0.0.1:6379> MULTI
OK
127.0.0.1:6379> PING
QUEUED

( here the server is manually restarted )

127.0.0.1:6379> EXEC
(error) ERR EXEC without MULTI

在交互模式下使用 valkey-cli 进行测试时，这通常不是问题，但应了解此限制。

编辑、历史、补全和提示

因为 valkey-cli 使用 Valkey 附带的 "linenoise" 行编辑库，所以它具有行编辑功能，而不依赖于 libreadline 或其他可选库。

可以通按箭头键（上和下）访问命令执行历史记录，以避免重新输入命令。历史记录在 CLI 重启之间会保留，存储在用户主目录中名为 .valkeycli_history 的文件中，该目录由 HOME 环境变量指定。可以通过设置 REDISCLI_HISTFILE 环境变量来使用不同的历史文件名，并将其设置为 /dev/null 来禁用它。

valkey-cli 也能够通过按 TAB 键执行命令名称补全，如下例所示

127.0.0.1:6379> Z<TAB>
127.0.0.1:6379> ZADD<TAB>
127.0.0.1:6379> ZCARD<TAB>

一旦在提示符处输入 Valkey 命令名称，valkey-cli 将显示语法提示。与命令历史记录一样，此行为可以通过 valkey-cli 首选项打开或关闭。

首选项

有两种方法可以自定义 valkey-cli 的行为。CLI 在启动时会加载主目录中的 .valkeyclirc 文件。您可以通过将 REDISCLI_RCFILE 环境变量设置为替代路径来覆盖文件的默认位置。首选项也可以在 CLI 会话期间设置，在这种情况下它们只在会话期间有效。

要设置首选项，请使用特殊的 :set 命令。以下首选项可以通过在 CLI 中键入命令或将其添加到 .valkeyclirc 文件来设置

:set hints - 启用语法提示
:set nohints - 禁用语法提示

运行相同命令 N 次

在交互模式下，可以通过在命令名称前加上数字来多次运行相同的命令

127.0.0.1:6379> 5 INCR mycounter
(integer) 1
(integer) 2
(integer) 3
(integer) 4
(integer) 5

显示 Valkey 命令帮助

valkey-cli 使用 HELP 命令为大多数 Valkey 命令提供在线帮助。该命令有两种用法

HELP @<类别> 显示给定类别的所有命令。类别包括
- @generic
- @string
- @list
- @set
- @sorted_set
- @hash
- @pubsub
- @transactions
- @connection
- @server
- @scripting
- @hyperloglog
- @cluster
- @geo
- @stream
HELP <命令名称> 显示作为参数给出的命令的特定帮助。

例如，要显示 PFADD 命令的帮助，请使用

127.0.0.1:6379> HELP PFADD

PFADD key element [element ...]
summary: Adds the specified elements to the specified HyperLogLog.
since: 2.8.9

请注意，HELP 也支持 TAB 补全。

清除终端屏幕

在交互模式下使用 CLEAR 命令可以清除终端屏幕。

特殊操作模式

到目前为止，我们看到了 valkey-cli 的两种主要模式。

命令行执行 Valkey 命令。
交互式 "REPL" 用法。

CLI 执行其他与 Valkey 相关的辅助任务，这些任务将在以下部分中解释

用于显示 Valkey 服务器连续统计信息的监控工具。
扫描 Valkey 数据库以查找超大键。
具有模式匹配功能的键空间扫描器。
作为发布/订阅客户端订阅频道。
监控 Valkey 实例中执行的命令。
以不同方式检查 Valkey 服务器的延迟。
检查本地计算机的调度器延迟。
将 RDB 备份从远程 Valkey 服务器传输到本地。
作为 Valkey 副本，显示副本接收到的内容。
模拟 LRU 工作负载以显示键命中统计信息。
Lua 调试器的客户端。

连续统计模式

连续统计模式可能是 valkey-cli 中鲜为人知但非常有用的功能之一，用于实时监控 Valkey 实例。要启用此模式，请使用 --stat 选项。在这种模式下，CLI 的行为输出非常清晰

$ valkey-cli --stat
------- data ------ --------------------- load -------------------- - child -
keys       mem      clients blocked requests            connections
506        1015.00K 1       0       24 (+0)             7
506        1015.00K 1       0       25 (+1)             7
506        3.40M    51      0       60461 (+60436)      57
506        3.40M    51      0       146425 (+85964)     107
507        3.40M    51      0       233844 (+87419)     157
507        3.40M    51      0       321715 (+87871)     207
508        3.40M    51      0       408642 (+86927)     257
508        3.40M    51      0       497038 (+88396)     257

在此模式下，每秒都会打印一行新信息，其中包含有用的信息以及旧数据点之间请求值的差异。使用此辅助 valkey-cli 工具，可以轻松了解内存使用情况、客户端连接计数以及有关连接的 Valkey 数据库的各种其他统计信息。

在这种情况下，-i <间隔> 选项作为修饰符，用于更改新行发出的频率。默认值为一秒。

扫描大键

在这种特殊模式下，valkey-cli 作为键空间分析器工作。它扫描数据集以查找大键，还提供有关数据集组成的数据类型的信息。此模式通过 --bigkeys 选项启用，并产生详细输出

$ valkey-cli --bigkeys

# Scanning the entire keyspace to find biggest keys as well as
# average sizes per key type.  You can use -i 0.01 to sleep 0.01 sec
# per SCAN command (not usually needed).

[00.00%] Biggest string found so far 'key-419' with 3 bytes
[05.14%] Biggest list   found so far 'mylist' with 100004 items
[35.77%] Biggest string found so far 'counter:__rand_int__' with 6 bytes
[73.91%] Biggest hash   found so far 'myobject' with 3 fields

-------- summary -------

Sampled 506 keys in the keyspace!
Total key length in bytes is 3452 (avg len 6.82)

Biggest string found 'counter:__rand_int__' has 6 bytes
Biggest   list found 'mylist' has 100004 items
Biggest   hash found 'myobject' has 3 fields

504 strings with 1403 bytes (99.60% of keys, avg size 2.78)
1 lists with 100004 items (00.20% of keys, avg size 100004.00)
0 sets with 0 members (00.00% of keys, avg size 0.00)
1 hashs with 3 fields (00.20% of keys, avg size 3.00)
0 zsets with 0 members (00.00% of keys, avg size 0.00)

在输出的第一部分，会报告遇到的每个新键，如果它大于同类型的前一个最大键。摘要部分提供了 Valkey 实例中数据的总体统计信息。

程序使用 SCAN 命令，因此它可以在繁忙的服务器上执行而不会影响操作，但是 -i 选项可用于限制每个 SCAN 命令的扫描过程，使其在指定秒数的分数内完成。

例如，-i 0.01 将显著减慢程序执行速度，但也会将服务器负载降至可忽略的程度。

请注意，摘要还会以更清晰的形式报告每次找到的最大键。最初的输出只是为了在处理非常大的数据集时尽快提供一些有趣的信息。

获取键列表

还可以扫描键空间，同样以不阻塞 Valkey 服务器的方式（使用 KEYS * 命令时会发生阻塞），并打印所有键名，或根据特定模式进行筛选。此模式，像 --bigkeys 选项一样，使用 SCAN 命令，因此如果数据集正在改变，键可能会被报告多次，但如果该键自迭代开始以来就存在，则不会丢失任何键。由于它使用的命令，此选项称为 --scan。

$ valkey-cli --scan | head -10
key-419
key-71
key-236
key-50
key-38
key-458
key-453
key-499
key-446
key-371

请注意，这里使用 head -10 仅打印输出的前十行。

扫描能够使用 SCAN 命令的底层模式匹配功能，结合 --pattern 选项。

$ valkey-cli --scan --pattern '*-11*'
key-114
key-117
key-118
key-113
key-115
key-112
key-119
key-11
key-111
key-110
key-116

将输出通过 wc 命令管道传输可用于按键名计数特定类型的对象

$ valkey-cli --scan --pattern 'user:*' | wc -l
3829433

您可以使用 -i 0.01 在调用 SCAN 命令之间添加延迟。这将使命令变慢，但会显著减少服务器负载。

发布/订阅模式

CLI 能够使用 PUBLISH 命令在 Valkey 发布/订阅频道中发布消息。订阅频道以接收消息则不同——终端会被阻塞并等待消息，因此这在 valkey-cli 中以特殊模式实现。与其他特殊模式不同，此模式并非通过特殊选项启用，而是简单地通过使用 SUBSCRIBE 或 PSUBSCRIBE 命令启用，这些命令在交互模式或命令模式下都可用

$ valkey-cli PSUBSCRIBE '*'
Reading messages... (press Ctrl-C to quit)
1) "PSUBSCRIBE"
2) "*"
3) (integer) 1

正在读取消息 的提示表示我们已进入发布/订阅模式。当另一个客户端在某个频道发布消息时，例如使用命令 valkey-cli PUBLISH mychannel mymessage，处于发布/订阅模式的 CLI 将显示类似以下内容

1) "pmessage"
2) "*"
3) "mychannel"
4) "mymessage"

这对于调试发布/订阅问题非常有用。要退出发布/订阅模式，只需按下 CTRL-C。

监控在 Valkey 中执行的命令

与发布/订阅模式类似，一旦您使用 MONITOR 命令，监控模式就会自动进入。活跃 Valkey 实例接收到的所有命令都将打印到标准输出

$ valkey-cli MONITOR
OK
1460100081.165665 [0 127.0.0.1:51706] "set" "shipment:8000736522714:status" "sorting"
1460100083.053365 [0 127.0.0.1:51707] "get" "shipment:8000736522714:status"

请注意，可以管道输出，因此您可以使用 grep 等工具监控特定模式。

监控 Valkey 实例的延迟

Valkey 通常用于延迟非常关键的场景。延迟涉及应用程序中的多个活动部分，从客户端库到网络堆栈，再到 Valkey 实例本身。

valkey-cli 具有多种工具，用于研究 Valkey 实例的延迟，并了解延迟的最大值、平均值和分布。

基本的延迟检查工具是 --latency 选项。使用此选项，CLI 会运行一个循环，向 Valkey 实例发送 PING 命令并测量接收回复所需的时间。这每秒发生 100 次，并且统计信息会在控制台中实时更新

$ valkey-cli --latency
min: 0, max: 1, avg: 0.19 (427 samples)

统计数据以毫秒为单位提供。通常，由于运行 valkey-cli 本身的系统的内核调度器引起的延迟，非常快速的实例的平均延迟往往会略微高估，因此上面显示的 0.19 平均延迟很容易是 0.01 或更少。然而，这通常不是一个大问题，因为大多数开发人员更关心几毫秒或更长时间的事件。

有时，研究最大延迟和平均延迟如何随时间演变会很有用。--latency-history 选项用于此目的：它的工作方式与 --latency 完全相同，但每 15 秒（默认）会从头开始一个新的采样会话

$ valkey-cli --latency-history
min: 0, max: 1, avg: 0.14 (1314 samples) -- 15.01 seconds range
min: 0, max: 1, avg: 0.18 (1299 samples) -- 15.00 seconds range
min: 0, max: 1, avg: 0.20 (113 samples)^C

采样会话的长度可以通过 -i <间隔> 选项更改。

最先进的延迟研究工具，但对于非经验用户来说也是最难解释的，是使用彩色终端显示延迟频谱的能力。您将看到彩色输出，指示不同的样本百分比，以及指示不同延迟数字的不同 ASCII 字符。此模式通过使用 --latency-dist 选项启用

$ valkey-cli --latency-dist
(output not displayed, requires a color terminal, try it!)

valkey-cli 内部还实现了一个相当不寻常的延迟工具。它不检查 Valkey 实例的延迟，而是检查运行 valkey-cli 的计算机的延迟。此延迟是内核调度器固有的，如果是虚拟化实例，则是虚拟机管理程序固有的，依此类推。

Valkey 将其称为 固有延迟，因为它对程序员来说大部分是透明的。如果 Valkey 实例具有高延迟，而无论所有明显的潜在原因，都值得通过直接在运行 Valkey 服务器的系统上以这种特殊模式运行 valkey-cli 来检查您的系统能做到什么程度。

通过测量固有延迟，您知道这是基线，Valkey 无法超越您的系统。要在此模式下运行 CLI，请使用 --intrinsic-latency <测试时间>。请注意，测试时间以秒为单位，并决定测试应运行多长时间。

$ ./valkey-cli --intrinsic-latency 5
Max latency so far: 1 microseconds.
Max latency so far: 7 microseconds.
Max latency so far: 9 microseconds.
Max latency so far: 11 microseconds.
Max latency so far: 13 microseconds.
Max latency so far: 15 microseconds.
Max latency so far: 34 microseconds.
Max latency so far: 82 microseconds.
Max latency so far: 586 microseconds.
Max latency so far: 739 microseconds.

65433042 total runs (avg latency: 0.0764 microseconds / 764.14 nanoseconds per run).
Worst run took 9671x longer than the average latency.

重要：此命令必须在运行 Valkey 服务器实例的计算机上执行，而不是在其他主机上。它不连接到 Valkey 实例，而是在本地执行测试。

在上述情况下，系统最坏情况下的延迟不能优于 739 微秒，因此可以预期某些查询偶尔会以低于 1 毫秒的速度运行。

RDB 文件的远程备份

在 Valkey 复制的首次同步期间，主服务器和副本会以 RDB 文件的形式交换整个数据集。valkey-cli 利用此功能提供远程备份功能，允许将 RDB 文件从任何 Valkey 实例传输到运行 valkey-cli 的本地计算机。要使用此模式，请使用 --rdb <目标文件名> 选项调用 CLI

$ valkey-cli --rdb /tmp/dump.rdb
SYNC sent to master, writing 13256 bytes to '/tmp/dump.rdb'
Transfer finished with success.

这是一种简单而有效的方法，可以确保您的 Valkey 实例存在灾难恢复 RDB 备份。在脚本或 cron 作业中使用此选项时，请务必检查命令的返回值。如果非零，则表示发生错误，如下例所示

$ valkey-cli --rdb /tmp/dump.rdb
SYNC with master failed: -ERR Can't SYNC while not connected with my master
$ echo $?
1

副本模式

CLI 的副本模式是一项高级功能，对 Valkey 开发人员和调试操作很有用。它允许检查主服务器在复制流中发送给其副本的内容，以将写入传播到其副本。选项名称很简单，就是 --replica。以下是一个工作示例

$ valkey-cli --replica
SYNC with master, discarding 13256 bytes of bulk transfer...
SYNC done. Logging commands from master.
"PING"
"SELECT","0"
"SET","last_name","Enigk"
"PING"
"INCR","mycounter"

该命令首先丢弃第一次同步的 RDB 文件，然后以 CSV 格式记录收到的每个命令。

如果您认为某些命令在您的副本中没有正确复制，这是一个很好的检查方式，也是改进错误报告的有用信息。

执行 LRU 模拟

Valkey 通常用作具有 LRU 淘汰的缓存。根据键的数量和为缓存分配的内存量（通过 maxmemory 指令指定），缓存命中和未命中的数量将发生变化。有时，模拟命中率对于正确配置缓存非常有用。

valkey-cli 有一个特殊模式，它使用请求模式中的 80-20% 幂律分布来执行 GET 和 SET 操作的模拟。这意味着 20% 的键将被请求 80% 的时间，这在缓存场景中是一种常见的分布。

理论上，给定请求的分布和 Valkey 的内存开销，应该可以用数学公式分析计算命中率。然而，Valkey 可以配置不同的 LRU 设置（采样数量），并且 Valkey 中近似实现的 LRU 在不同版本之间变化很大。同样，每个键的内存量也可能在不同版本之间变化。这就是为什么构建此工具的原因：其主要动机是为了测试 Valkey LRU 实现的质量，但现在也用于测试给定版本在最初部署设置下的行为。

要使用此模式，请指定测试中键的数量，并首次尝试配置一个合理的 maxmemory 设置。

重要提示：在 Valkey 配置中配置 maxmemory 设置至关重要：如果对最大内存使用量没有上限，则命中率最终将达到 100%，因为所有键都可以存储在内存中。如果为最大内存指定了太多键，最终将使用所有计算机 RAM。还需要配置适当的 maxmemory 策略；大多数情况下会选择 allkeys-lru。

在以下示例中，配置了 100MB 的内存限制，并使用 1000 万个键进行 LRU 模拟。

警告：此测试使用管道，会给服务器带来压力，请勿在生产实例上使用。

$ ./valkey-cli --lru-test 10000000
156000 Gets/sec | Hits: 4552 (2.92%) | Misses: 151448 (97.08%)
153750 Gets/sec | Hits: 12906 (8.39%) | Misses: 140844 (91.61%)
159250 Gets/sec | Hits: 21811 (13.70%) | Misses: 137439 (86.30%)
151000 Gets/sec | Hits: 27615 (18.29%) | Misses: 123385 (81.71%)
145000 Gets/sec | Hits: 32791 (22.61%) | Misses: 112209 (77.39%)
157750 Gets/sec | Hits: 42178 (26.74%) | Misses: 115572 (73.26%)
154500 Gets/sec | Hits: 47418 (30.69%) | Misses: 107082 (69.31%)
151250 Gets/sec | Hits: 51636 (34.14%) | Misses: 99614 (65.86%)

程序每秒显示统计信息。在最初的几秒钟内，缓存开始填充。未命中率随后稳定在预期的实际数值

120750 Gets/sec | Hits: 48774 (40.39%) | Misses: 71976 (59.61%)
122500 Gets/sec | Hits: 49052 (40.04%) | Misses: 73448 (59.96%)
127000 Gets/sec | Hits: 50870 (40.06%) | Misses: 76130 (59.94%)
124250 Gets/sec | Hits: 50147 (40.36%) | Misses: 74103 (59.64%)

59% 的未命中率对于某些用例可能不可接受，因此 100MB 内存是不够的。观察一个使用半千兆字节内存的示例。几分钟后，输出稳定到以下数字

140000 Gets/sec | Hits: 135376 (96.70%) | Misses: 4624 (3.30%)
141250 Gets/sec | Hits: 136523 (96.65%) | Misses: 4727 (3.35%)
140250 Gets/sec | Hits: 135457 (96.58%) | Misses: 4793 (3.42%)
140500 Gets/sec | Hits: 135947 (96.76%) | Misses: 4553 (3.24%)

使用 500MB，足以容纳键的数量（1000 万）和分布（80-20 样式）。