valkey-io/valkey

[](https://codecov.io/gh/valkey-io/valkey) [](https://securityscorecards.dev/viewer/?uri=github.com/valkey-io/valkey) 本项目是在开源 Redis 项目过渡到其新的源代码可用许可证之前，从该项目分叉而来的。 本 README 仅是一份快速*入门*文档。更多详情请见 [valkey.io](https://valkey.io/) # 什么是 Valkey？ Valkey 是一个高性能的数据结构服务器，主要服务于键/值（key/value）工作负载。 它支持多种原生结构，并提供可扩展的插件系统，用于添加新的数据结构和访问模式。 # 使用 `Makefile` 构建 Valkey Valkey 可以在 Linux、macOS、OpenBSD、NetBSD、FreeBSD 上编译和使用。 我们支持大端序和小端序架构，同时支持 32 位和 64 位系统。 它可能可以在 Solaris 衍生系统（例如 SmartOS）上编译，但我们对该平台的支持仅是*尽力而为*，不保证 Valkey 能像在 Linux、macOS 和 *BSD 上那样正常运行。 操作非常简单： ``` % make ``` 要构建支持 TLS 的版本，你需要 OpenSSL 开发库（例如 Debian/Ubuntu 上的 libssl-dev）。 要将 TLS 支持构建为 Valkey 内置功能： ``` % make BUILD_TLS=yes ``` 要将 TLS 构建为 Valkey 模块： ``` % make BUILD_TLS=module ``` 请注意，sentinel 模式不支持 TLS 模块。 要构建带有实验性 RDMA 支持的版本，你需要 RDMA 开发库（例如 Debian/Ubuntu 上的 librdmacm-dev 和 libibverbs-dev）。 要将 RDMA 支持构建为 Valkey 内置功能： ``` % make BUILD_RDMA=yes ``` 要将 RDMA 构建为 Valkey 模块： ``` % make BUILD_RDMA=module ``` 要构建支持 systemd 的版本，你需要 systemd 开发库（例如 Debian/Ubuntu 上的 libsystemd-dev 或 CentOS 上的 systemd-devel）并运行： ``` % make USE_SYSTEMD=yes ``` 自 Valkey 8.1 版本起，引入了 `fast_float` 作为可选依赖项，它可以加速有序集合（sorted sets）以及其他使用 double 数据类型的命令。要构建支持 `fast_float` 的版本，你需要一个 C++ 编译器并运行： ``` % make USE_FAST_FLOAT=yes ``` 要构建包含文件名和行号（针对所有函数，包括静态函数）的增强堆栈跟踪信息，请使用 libbacktrace： ``` % make USE_LIBBACKTRACE=yes ``` 要构建不带 Lua 引擎的 Valkey： ``` % make BUILD_LUA=no ``` 要为 Valkey 程序名称添加后缀，请使用： ``` % make PROG_SUFFIX="-alt" ``` 你可以使用以下命令构建 32 位的 Valkey 二进制文件： ``` % make 32bit ``` 构建 Valkey 后，建议使用以下命令进行测试： ``` % make test ``` 上述命令运行主要的集成测试。附加测试可以通过以下方式启动： ``` % make test-unit # Unit tests % make test-modules # Tests of the module API % make test-sentinel # Valkey Sentinel integration tests % make test-cluster # Valkey Cluster integration tests ``` 关于运行集成测试的更多信息可以在 [tests/README.md](tests/README.md) 中找到；关于单元测试，请参见 [src/unit/README.md](src/unit/README.md)。 ## 性能监控 Valkey 性能仪表板提供了跨版本吞吐量趋势的综合视图，帮助贡献者快速验证改进并识别回归。 - [性能概览](https://valkey.io/performance/) - 比较不同 Valkey 版本的吞吐量 - [Unstable 分支仪表板](https://perf-dashboard.valkey.io/public-dashboards/3e45bf8ded3043edaa941331cd1a94e2) - 追踪 unstable 分支中所有提交的性能 ## 解决依赖项或缓存构建选项导致的构建问题 Valkey 包含一些依赖项，它们位于 `deps` 目录中。 即使依赖项的源代码发生变化，`make` 也不会自动重新构建依赖项。 当你使用 `git pull` 更新源代码，或者依赖项树中的代码以其他方式被修改时，请确保使用以下命令来彻底清理所有内容并从头开始重新构建： ``` % make distclean ``` 这将清理：jemalloc、lua、libvalkey、linenoise 及其他依赖项。 此外，如果你强制指定了某些构建选项，如 32 位目标、禁用 C 编译器优化（用于调试目的）以及其他类似的构建时选项，这些选项将被无限期缓存，直到你执行 `make distclean` 命令。 ## 解决构建 32 位二进制文件的问题 如果你在构建了 32 位目标的 Valkey 之后需要重新构建 64 位目标，或者反之，你需要在 Valkey 发行版的根目录下执行 `make distclean`。 如果在尝试构建 32 位 Valkey 二进制文件时遇到构建错误，请尝试以下步骤： * 安装 libc6-dev-i386 包（也可以尝试 g++-multilib）。 * 尝试使用以下命令行代替 `make 32bit`： `make CFLAGS="-m32 -march=native" LDFLAGS="-m32"` ## 内存分配器 在构建 Valkey 时选择非默认的内存分配器可以通过设置 `MALLOC` 环境变量来完成。默认情况下，Valkey 使用 libc malloc 进行编译和链接，但在 Linux 系统上例外，jemalloc 是默认选项。选择此默认值是因为事实证明 jemalloc 的内存碎片问题比 libc malloc 更少。 要强制使用 libc malloc 进行编译，请使用： ``` % make MALLOC=libc ``` 要在 Mac OS X 系统上针对 jemalloc 进行编译，请使用： ``` % make MALLOC=jemalloc ``` ## 单调时钟 默认情况下，Valkey 使用处理器的内部指令时钟（x86 上的 TSC，ARM 上的 CNTVCT）进行单调时间跟踪，这比 POSIX clock_gettime 提供的时间访问速度快约 3 倍（约 10-30ns 对比约 100ns）。 这在支持的架构（x86_64 Linux 和 aarch64）上默认启用，并在不支持的系统上自动回退到 POSIX clock_gettime。 有关处理器时钟用法的更多信息，请参见： http://oliveryang.net/2015/09/pitfalls-of-TSC-usage/ 要禁用处理器时钟并强制使用 POSIX clock_gettime，请使用： ``` % make CFLAGS="-DNO_PROCESSOR_CLOCK" ``` ## 详细构建 默认情况下，Valkey 构建时会显示用户友好的彩色输出。 如果你想查看更详细的输出，请使用以下命令： ``` % make V=1 ``` # 运行 Valkey 要使用默认配置运行 Valkey，只需输入： ``` % cd src % ./valkey-server ``` 如果你想提供自定义的 valkey.conf，你需要使用额外的参数（配置文件的路径）来运行它： ``` % cd src % ./valkey-server /path/to/valkey.conf ``` 可以通过在命令行中直接传递参数作为选项来更改 Valkey 配置。示例： ``` % ./valkey-server --port 9999 --replicaof 127.0.0.1 6379 % ./valkey-server /etc/valkey/6379.conf --loglevel debug ``` valkey.conf 中的所有选项也支持作为命令行选项使用，名称完全相同。 # 使用 TLS 运行 Valkey： ## 手动运行 要手动运行处于 TLS 模式的 Valkey 服务器（假设已调用 `./utils/gen-test-certs.sh`，因此有示例证书/密钥可用）： * TLS 内置模式： ./src/valkey-server --tls-port 6379 --port 0 \ --tls-cert-file ./tests/tls/valkey.crt \ --tls-key-file ./tests/tls/valkey.key \ --tls-ca-cert-file ./tests/tls/ca.crt * TLS 模块模式： ./src/valkey-server --tls-port 6379 --port 0 \ --tls-cert-file ./tests/tls/valkey.crt \ --tls-key-file ./tests/tls/valkey.key \ --tls-ca-cert-file ./tests/tls/ca.crt \ --loadmodule src/valkey-tls.so 请注意，你可以通过显式指定 `--port 0` 来禁用 TCP。 同时启用 TCP 和 TLS 也是可能的，但你必须分配不同的端口。 使用 `valkey-cli` 连接到 Valkey 服务器： ``` ./src/valkey-cli --tls \ --cert ./tests/tls/valkey.crt \ --key ./tests/tls/valkey.key \ --cacert ./tests/tls/ca.crt ``` 指定 `--tls-replication yes` 可使副本（replica）连接到主节点（primary）。 使用 `--tls-cluster yes` 可使 Valkey Cluster 在节点间使用 TLS。 # 使用 RDMA 运行 Valkey： 请注意，Valkey Over RDMA 是一项实验性功能。 它可能会在任何次要或主要版本中被更改或移除。 目前，它仅在 Linux 上受支持。 * RDMA 内置模式： ./src/valkey-server --protected-mode no \ --rdma-bind 192.168.122.100 --rdma-port 6379 * RDMA 模块模式： ./src/valkey-server --protected-mode no \ --loadmodule src/valkey-rdma.so --rdma-bind 192.168.122.100 --rdma-port 6379 可以通过运行时命令更改 RDMA 的绑定地址/端口： ``` 192.168.122.100:6379> CONFIG SET rdma-port 6380 ``` RDMA 和 TCP 也可以同时可用，TCP(6379) 和 RDMA(6379) 之间没有冲突，例如： ``` % ./src/valkey-server --protected-mode no \ --loadmodule src/valkey-rdma.so --rdma-bind 192.168.122.100 --rdma-port 6379 \ --port 6379 ``` 请注意，网卡（本例中的 192.168.122.100）应支持 RDMA。要测试服务器是否支持 RDMA： ``` % rdma res show (a new version iproute2 package) ``` 或者： ``` % ibv_devices ``` # 体验 Valkey 你可以使用 valkey-cli 来体验 Valkey。启动一个 valkey-server 实例，然后在另一个终端中尝试以下操作： ``` % cd src % ./valkey-cli valkey> ping PONG valkey> set foo bar OK valkey> get foo "bar" valkey> incr mycounter (integer) 1 valkey> incr mycounter (integer) 2 valkey> ``` # 安装 Valkey 要将 Valkey 二进制文件安装到 /usr/local/bin，只需使用： ``` % make install ``` 如果你想使用不同的目标路径，可以使用 `make PREFIX=/some/other/directory install`。 *注意*：为了与 Redis 兼容，我们会创建从 Redis 名称（`redis-server`、`redis-cli` 等）到 `make install` 安装的 Valkey 二进制文件的符号链接。 这些符号链接创建在 Valkey 二进制文件所在的同一目录中。 使用 `make uninstall` 时会删除这些符号链接。 可以通过设置 makefile 变量 `USE_REDIS_SYMLINKS=no` 来跳过创建符号链接。 `make install` 只会在你的系统中安装二进制文件，但不会在适当的位置配置 init 脚本和配置文件。如果你只是想稍微试用一下 Valkey，这不需要，但如果你要在生产系统上正确安装它，我们提供了一个脚本，可以为 Ubuntu 和 Debian 系统完成此操作： ``` % cd utils % ./install_server.sh ``` *注意*：`install_server.sh` 无法在 macOS 上运行；它专为 Linux 设计。 该脚本会问你几个问题，并设置好运行 Valkey 所需的一切，使其作为后台守护进程运行，并在系统重启时再次启动。 你将能够使用名为 `/etc/init.d/valkey_<端口号>` 的脚本停止和启动 Valkey，例如 `/etc/init.d/valkey_6379`。 # 使用 `CMake` 构建 除了传统的 `Makefile` 构建外，Valkey 还支持使用 `CMake` 的替代**实验性**构建系统。 要在 `Release` 模式（优化构建）下构建并安装 `Valkey`，请在终端中输入： ``` mkdir build-release cd $_ cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/opt/valkey sudo make install # Valkey 现已安装在 /opt/valkey 下 ``` Valkey 的 `CMake` 构建系统支持的其他选项： ## 特殊构建标志 - `-DBUILD_TLS=` 为 Valkey 启用 TLS 构建。默认值：`no` - `-DBUILD_RDMA=` 启用 RDMA 模块构建（仅支持模块模式）。默认值：`no` - `-DBUILD_MALLOC=` 选择要使用的分配器。Linux 上默认值：`jemalloc`，其他操作系统：`libc` - `-DBUILD_SANITIZER=` 在启用地址消毒剂的情况下构建。默认值：禁用（无消毒剂） - `-DBUILD_UNIT_GTESTS=[yes|no]` 设置后，构建将生成单元测试可执行文件 `valkey-unit-gtests`。默认值：`no` - `-DBUILD_TEST_MODULES=[yes|no]` 设置后，构建将包含位于 `tests/modules` 文件夹下的模块。默认值：`no` - `-DBUILD_EXAMPLE_MODULES=[yes|no]` 设置后，构建将包含位于 `src/modules` 文件夹下的示例模块。默认值：`no` ## 通用标志 - `-DCMAKE_BUILD_TYPE=` 定义构建类型，更多详情请参见 CMake 手册 - `-DCMAKE_INSTALL_PREFIX=/installation/path` 覆盖此值以定义自定义安装前缀。默认值：`/usr/local` - `-G""` 为 "Generator Name" 生成构建文件。默认情况下，CMake 将生成 `Makefile`。 ## 详细构建 `CMake` 默认生成用户友好的彩色输出。 如果你想查看更详细的输出，请使用以下命令： ``` make VERBOSE=1 ``` ## 故障排除 在 `CMake` 阶段，`CMake` 会将变量缓存在名为 `CMakeCache.txt` 的本地文件中。Valkey 生成的所有变量在使用后都会从缓存中移除（这是通过调用 `unset(VAR-NAME CACHE)` 完成的）。然而，有些变量（如编译器路径）会保留在缓存中。要开始全新的构建，可以从构建文件夹中删除缓存文件 `CMakeCache.txt`，或者完全删除构建文件夹。 **在添加新源文件时重新运行 `CMake` 非常重要。** ## IDE 集成 在构建的 `CMake` 阶段，`CMake` 会生成一个名为 `compile_commands.json` 的 JSON 文件，并将其放置在构建文件夹下。文件被许多 IDE 和文本编辑器用于提供代码补全（通过 `clangd`）。 一个小问题是，这些工具会在 Valkey 的顶层文件夹下查找 `compile_commands.json`。 一个常见的解决方法是创建一个指向它的符号链接： ``` cd /path/to/valkey/ # 我们在此假设您的构建文件夹是 `build-release` ln -sf $(pwd)/build-release/compile_commands.json $(pwd)/compile_commands.json ``` 重启你的 IDE 即可。 # 代码贡献 请参阅 [CONTRIBUTING.md][2]。关于安全漏洞和弱点，请参阅 [SECURITY.md][3]。 # Valkey 是 LF Projects 下的开放社区项目 Valkey a Series of LF Projects, LLC 2810 N Church St, PMB 57274 Wilmington, Delaware 19802-4447

标签：Bash脚本, BSD, HTTP工具, RDMA支持, Redis替代, rizin, Sentinel, Systemd, TLS加密, Valkey, 中间件, 主从复制, 内存数据库, 分布式键值数据库, 后端开发, 大数据, 实时数据处理, 客户端加密, 底层编程, 开源, 数据挖掘, 数据结构服务器, 服务端, 目录扫描, 缓存, 网络安全审计, 键值存储