Valkey 的 TLS 是需要在构建时启用的可选功能。它既能保护应用到服务端的连接，也能用于复制、集群总线和 Sentinel 通信。部署时最容易遗漏的地方，是只打开了客户端 TLS 端口，却保留了普通 TCP 端口，或让节点之间仍使用明文连接。
本文依据 Valkey 文档贡献者的 TLS 官方文档全文翻译整理，补充了明确标出的安全审查说明。核对日期为 2026 年 10 月 05 日；在线文档没有锁定版本，自动重载、证书到 ACL 用户的映射等选项必须与所安装版本的 valkey.conf 对照。以下命令和配置均未执行。
先准备构建与证书
确认使用的 Valkey 二进制包含 TLS 支持。自行构建时应遵照该版本的 构建说明；不要因为配置文件中有 TLS 参数，就假定当前安装包一定支持它。启用 TLS 需要 X.509 证书、对应私钥以及用于验证对端证书的可信 CA。
作为 TLS 服务端时，Valkey 使用 tls-cert-file 和 tls-key-file 指定服务端证书及私钥。原文的启动示例如下；路径只是示例，应替换成经过核验的实际文件。
./src/valkey-server \
--tls-port 6379 --port 0 \
--tls-cert-file /path/to/server.crt \
--tls-key-file /path/to/server.key \
--tls-ca-cert-file /path/to/ca.crt这里的 --tls-port 6379 打开 TLS 监听；--port 0 关闭普通 TCP 监听。两者互不替代：若只设置 TLS 端口而仍保留一个非零的 port，服务就可能同时接受加密和明文连接。只在默认 Valkey 端口提供 TLS 时，配置文件可以写为：
port 0
tls-port 6379审查补充：上述快速启动命令只展示 TLS 材料，未提供完整的监听范围、网络访问控制或 ACL 策略。应明确绑定业务所需地址，限制可到达端口的来源，不要关闭保护模式来解决连通性问题。私钥须限制文件访问权限，也不应进入版本库、日志或文章配图。
CA、服务端证书与客户端证书各有用途
Valkey 可使用 CA bundle 文件或 CA 证书目录建立信任。以下是配置入口；选择与证书管理方式相符的一项或组合，并确保其中只包含信任的签发机构。
tls-cert-file /path/to/valkey.crt
tls-key-file /path/to/valkey.key
tls-ca-cert-file /path/to/ca.crt
tls-ca-cert-dir /path/to/ca-certs/当 Valkey 作为客户端连接其他节点时，可以为出站连接配置单独的客户端证书和私钥：
tls-client-cert-file /path/to/client.crt
tls-client-key-file /path/to/client.key这对区分服务端用途与客户端用途的证书特别有用。原文配置说明将两者作为 TLS 身份材料来讨论；它们不是业务用户密码，也不自动决定能访问哪些键或命令。
连接前述 TLS 服务端的官方命令为：
./src/valkey-cli --tls \
--cert /path/to/client.crt \
--key /path/to/client.key \
--cacert /path/to/ca.crt审查补充：该命令省略主机和端口，依赖 CLI 默认连接目标。远程使用时要明确目标，并核对客户端库的证书链验证和服务器身份验证行为：连接名称应与证书身份匹配，发送 SNI 也不能单独证明主机名检查已经完成。不要以跳过证书验证作为排错措施。本文未建立 TLS 连接，不能据此宣称任何证书或客户端实现已通过验证。
双向 TLS 控制连接，ACL 控制权限
默认情况下，Valkey 使用双向 TLS，要求客户端提供能由所配置 CA 验证的有效证书。tls-auth-clients no 可以关闭客户端证书认证，但这会改变接入门槛，不能用作通用生产配置。
默认的证书验证只判断客户端能否建立连接，不会把客户端认证成某个 Valkey 用户。连接建立后，客户端仍可通过 AUTH 或 HELLO，以用户名和密码完成应用层认证。
在线文档还介绍了 tls-auth-clients-user。启用后，Valkey 从客户端证书中提取身份字段，查找匹配的 ACL 用户并自动完成用户认证。若找不到匹配用户，连接会停留在默认用户的状态，因此必须同时审查 default 用户的启用状态和权限，不能假定“没有匹配用户”一定等于拒绝访问。
为避免把开发分支功能当成所有已发布版本都支持的能力，先在本机版本附带配置中确认这个选项及其允许值。本次辅助核对的 unstable 分支配置列出了 CN、URI 和 off：其中 URI 取自证书 SAN 的 URI 项，存在多个 URI 时选择第一个匹配已启用用户的值。此信息用于解释当前在线文档，不能替代发布版本核验。
原文建议此模式下使用没有密码的 ACL 用户，使认证由 mTLS 证书完成，并给出：
ACL SETUSER client-user on allcommands allkeys安全审查：这条原文示例授予全部命令和全部键权限，仅用于解释身份映射。它不是最小权限配置，而且对已有用户执行 ACL SETUSER 并不等同于从零创建、清除所有旧权限。实际部署应使用明确、可审计的用户定义，按应用需要限制命令和键前缀，并规划管理用户、复制用户及证书撤销流程。本文没有直接给出可套用的 ACL 修改命令，避免在未知用户状态下扩大权限或锁死管理入口。
复制、Cluster 和 Sentinel 分别启用 TLS
主节点对应用客户端和副本的入站连接采用相同的 TLS 监听与客户端证书认证规则。但副本主动连接主节点时，还需要在副本侧指定：
tls-replication yes使用 Valkey Cluster 时，还应开启集群总线及跨节点连接的 TLS：
tls-cluster yes这说明“客户端已加密”不能推出“所有内部流量已加密”。应分别检查每个节点的服务端和客户端证书、信任 CA、地址以及复制与 Cluster 开关。
Sentinel 继承公共 Valkey 网络配置。它连接主节点时，通过 tls-replication 判断采用 TLS 还是普通连接；同一开关也决定 Sentinel 接受其他 Sentinel 连接的端口是否支持 TLS。官方文档的表述是：仅当启用了 tls-replication，Sentinel 才会以 tls-port 配置该监听行为。不要把 Sentinel 当作与节点 TLS 配置完全独立的例外。
材料重载、算法选择与性能
当前在线文档支持通过秒数设置自动重载间隔，默认值 0 表示关闭。每天检查一次的示例是：
tls-auto-reload-interval 86400重载在后台线程执行，不阻塞主服务线程。每次加载或重载 TLS 材料时，Valkey 会检查文件或目录是否为空、内容格式是否有效、证书是否与对应私钥匹配，以及证书是否处于有效期内；任一检查失败都会使该次加载失败。
审查补充：材料加载成功不等于整个部署的信任关系、主机名验证、证书用途和 ACL 映射均正确。轮换后仍应观察日志，并在受控验证环境分别检查正常证书、错误 CA、错误身份与未授权用户的行为。本文没有生成、读取或上传实际私钥，也没有进行这些连接测试。
TLS 协议版本、密码和 TLS 1.3 密码套件等参数可在对应发行版本自带的 valkey.conf 中查阅。不同版本及所链接的 TLS 库会影响可用参数，不能把在线开发配置整体覆盖到生产实例。
TLS 会增加读写、加解密和完整性校验开销，官方文档因此提示每个实例的可达吞吐量可能下降。幅度取决于硬件、连接复用、请求大小、并发和 TLS 配置；这里没有可推广的性能数字，也没有实测结论。
来源、修订与许可
原作者：Valkey documentation contributors；原文：Documentation: TLS。本文为中文翻译整理，安全边界和版本提示为编者补充；原文功能均已覆盖，未将原文示例称为执行测试。Valkey 文档仓库采用 CC BY-SA 4.0，本文翻译改编按同一许可提供；版权归 Valkey contributors。文档许可见 官方 LICENSE。Valkey 名称与标识的商标权不因该许可转移。
版权与许可全文
以下保留本页涉及的来源材料或示例代码的版权、许可条件与免责声明；各自适用范围依原声明。中文翻译及编辑标注：未完纪，2026-10-05。
Valkey-doc-LICENSE
Creative Commons Attribution-ShareAlike 4.0 International Public
License
By exercising the Licensed Rights (defined below), You accept and agree
to be bound by the terms and conditions of this Creative Commons
Attribution-ShareAlike 4.0 International Public License ("Public
License"). To the extent this Public License may be interpreted as a
contract, You are granted the Licensed Rights in consideration of Your
acceptance of these terms and conditions, and the Licensor grants You
such rights in consideration of benefits the Licensor receives from
making the Licensed Material available under these terms and
conditions.
Section 1 -- Definitions.
a. Adapted Material means material subject to Copyright and Similar
Rights that is derived from or based upon the Licensed Material
and in which the Licensed Material is translated, altered,
arranged, transformed, or otherwise modified in a manner requiring
permission under the Copyright and Similar Rights held by the
Licensor. For purposes of this Public License, where the Licensed
Material is a musical work, performance, or sound recording,
Adapted Material is always produced where the Licensed Material is
synched in timed relation with a moving image.
b. Adapter's License means the license You apply to Your Copyright
and Similar Rights in Your contributions to Adapted Material in
accordance with the terms and conditions of this Public License.
c. BY-SA Compatible License means a license listed at
creativecommons.org/compatiblelicenses, approved by Creative
Commons as essentially the equivalent of this Public License.
d. Copyright and Similar Rights means copyright and/or similar rights
closely related to copyright including, without limitation,
performance, broadcast, sound recording, and Sui Generis Database
Rights, without regard to how the rights are labeled or
categorized. For purposes of this Public License, the rights
specified in Section 2(b)(1)-(2) are not Copyright and Similar
Rights.
e. Effective Technological Measures means those measures that, in the
absence of proper authority, may not be circumvented under laws
fulfilling obligations under Article 11 of the WIPO Copyright
Treaty adopted on December 20, 1996, and/or similar international
agreements.
f. Exceptions and Limitations means fair use, fair dealing, and/or
any other exception or limitation to Copyright and Similar Rights
that applies to Your use of the Licensed Material.
g. License Elements means the license attributes listed in the name
of a Creative Commons Public License. The License Elements of this
Public License are Attribution and ShareAlike.
h. Licensed Material means the artistic or literary work, database,
or other material to which the Licensor applied this Public
License.
i. Licensed Rights means the rights granted to You subject to the
terms and conditions of this Public License, which are limited to
all Copyright and Similar Rights that apply to Your use of the
Licensed Material and that the Licensor has authority to license.
j. Licensor means the individual(s) or entity(ies) granting rights
under this Public License.
k. Share means to provide material to the public by any means or
process that requires permission under the Licensed Rights, such
as reproduction, public display, public performance, distribution,
dissemination, communication, or importation, and to make material
available to the public including in ways that members of the
public may access the material from a place and at a time
individually chosen by them.
l. Sui Generis Database Rights means rights other than copyright
resulting from Directive 96/9/EC of the European Parliament and of
the Council of 11 March 1996 on the legal protection of databases,
as amended and/or succeeded, as well as other essentially
equivalent rights anywhere in the world.
m. You means the individual or entity exercising the Licensed Rights
under this Public License. Your has a corresponding meaning.
Section 2 -- Scope.
a. License grant.
1. Subject to the terms and conditions of this Public License,
the Licensor hereby grants You a worldwide, royalty-free,
non-sublicensable, non-exclusive, irrevocable license to
exercise the Licensed Rights in the Licensed Material to:
a. reproduce and Share the Licensed Material, in whole or
in part; and
b. produce, reproduce, and Share Adapted Material.
2. Exceptions and Limitations. For the avoidance of doubt, where
Exceptions and Limitations apply to Your use, this Public
License does not apply, and You do not need to comply with
its terms and conditions.
3. Term. The term of this Public License is specified in Section
6(a).
4. Media and formats; technical modifications allowed. The
Licensor authorizes You to exercise the Licensed Rights in
all media and formats whether now known or hereafter created,
and to make technical modifications necessary to do so. The
Licensor waives and/or agrees not to assert any right or
authority to forbid You from making technical modifications
necessary to exercise the Licensed Rights, including
technical modifications necessary to circumvent Effective
Technological Measures. For purposes of this Public License,
simply making modifications authorized by this Section 2(a)
(4) never produces Adapted Material.
5. Downstream recipients.
a. Offer from the Licensor -- Licensed Material. Every
recipient of the Licensed Material automatically
receives an offer from the Licensor to exercise the
Licensed Rights under the terms and conditions of this
Public License.
b. Additional offer from the Licensor -- Adapted Material.
Every recipient of Adapted Material from You
automatically receives an offer from the Licensor to
exercise the Licensed Rights in the Adapted Material
under the conditions of the Adapter's License You apply.
c. No downstream restrictions. You may not offer or impose
any additional or different terms or conditions on, or
apply any Effective Technological Measures to, the
Licensed Material if doing so restricts exercise of the
Licensed Rights by any recipient of the Licensed
Material.
6. No endorsement. Nothing in this Public License constitutes or
may be construed as permission to assert or imply that You
are, or that Your use of the Licensed Material is, connected
with, or sponsored, endorsed, or granted official status by,
the Licensor or others designated to receive attribution as
provided in Section 3(a)(1)(A)(i).
b. Other rights.
1. Moral rights, such as the right of integrity, are not
licensed under this Public License, nor are publicity,
privacy, and/or other similar personality rights; however, to
the extent possible, the Licensor waives and/or agrees not to
assert any such rights held by the Licensor to the limited
extent necessary to allow You to exercise the Licensed
Rights, but not otherwise.
2. Patent and trademark rights are not licensed under this
Public License.
3. To the extent possible, the Licensor waives any right to
collect royalties from You for the exercise of the Licensed
Rights, whether directly or through a collecting society
under any voluntary or waivable statutory or compulsory
licensing scheme. In all other cases the Licensor expressly
reserves any right to collect such royalties.
Section 3 -- License Conditions.
Your exercise of the Licensed Rights is expressly made subject to the
following conditions.
a. Attribution.
1. If You Share the Licensed Material (including in modified
form), You must:
a. retain the following if it is supplied by the Licensor
with the Licensed Material:
i. identification of the creator(s) of the Licensed
Material and any others designated to receive
attribution, in any reasonable manner requested by
the Licensor (including by pseudonym if
designated);
ii. a copyright notice;
iii. a notice that refers to this Public License;
iv. a notice that refers to the disclaimer of
warranties;
v. a URI or hyperlink to the Licensed Material to the
extent reasonably practicable;
b. indicate if You modified the Licensed Material and
retain an indication of any previous modifications; and
c. indicate the Licensed Material is licensed under this
Public License, and include the text of, or the URI or
hyperlink to, this Public License.
2. You may satisfy the conditions in Section 3(a)(1) in any
reasonable manner based on the medium, means, and context in
which You Share the Licensed Material. For example, it may be
reasonable to satisfy the conditions by providing a URI or
hyperlink to a resource that includes the required
information.
3. If requested by the Licensor, You must remove any of the
information required by Section 3(a)(1)(A) to the extent
reasonably practicable.
b. ShareAlike.
In addition to the conditions in Section 3(a), if You Share
Adapted Material You produce, the following conditions also apply.
1. The Adapter's License You apply must be a Creative Commons
license with the same License Elements, this version or
later, or a BY-SA Compatible License.
2. You must include the text of, or the URI or hyperlink to, the
Adapter's License You apply. You may satisfy this condition
in any reasonable manner based on the medium, means, and
context in which You Share Adapted Material.
3. You may not offer or impose any additional or different terms
or conditions on, or apply any Effective Technological
Measures to, Adapted Material that restrict exercise of the
rights granted under the Adapter's License You apply.
Section 4 -- Sui Generis Database Rights.
Where the Licensed Rights include Sui Generis Database Rights that
apply to Your use of the Licensed Material:
a. for the avoidance of doubt, Section 2(a)(1) grants You the right
to extract, reuse, reproduce, and Share all or a substantial
portion of the contents of the database;
b. if You include all or a substantial portion of the database
contents in a database in which You have Sui Generis Database
Rights, then the database in which You have Sui Generis Database
Rights (but not its individual contents) is Adapted Material,
including for purposes of Section 3(b); and
c. You must comply with the conditions in Section 3(a) if You Share
all or a substantial portion of the contents of the database.
For the avoidance of doubt, this Section 4 supplements and does not
replace Your obligations under this Public License where the Licensed
Rights include other Copyright and Similar Rights.
Section 5 -- Disclaimer of Warranties and Limitation of Liability.
a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
c. The disclaimer of warranties and limitation of liability provided
above shall be interpreted in a manner that, to the extent
possible, most closely approximates an absolute disclaimer and
waiver of all liability.
Section 6 -- Term and Termination.
a. This Public License applies for the term of the Copyright and
Similar Rights licensed here. However, if You fail to comply with
this Public License, then Your rights under this Public License
terminate automatically.
b. Where Your right to use the Licensed Material has terminated under
Section 6(a), it reinstates:
1. automatically as of the date the violation is cured, provided
it is cured within 30 days of Your discovery of the
violation; or
2. upon express reinstatement by the Licensor.
For the avoidance of doubt, this Section 6(b) does not affect any
right the Licensor may have to seek remedies for Your violations
of this Public License.
c. For the avoidance of doubt, the Licensor may also offer the
Licensed Material under separate terms or conditions or stop
distributing the Licensed Material at any time; however, doing so
will not terminate this Public License.
d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
License.
Section 7 -- Other Terms and Conditions.
a. The Licensor shall not be bound by any additional or different
terms or conditions communicated by You unless expressly agreed.
b. Any arrangements, understandings, or agreements regarding the
Licensed Material not stated herein are separate from and
independent of the terms and conditions of this Public License.
Section 8 -- Interpretation.
a. For the avoidance of doubt, this Public License does not, and
shall not be interpreted to, reduce, limit, restrict, or impose
conditions on any use of the Licensed Material that could lawfully
be made without permission under this Public License.
b. To the extent possible, if any provision of this Public License is
deemed unenforceable, it shall be automatically reformed to the
minimum extent necessary to make it enforceable. If the provision
cannot be reformed, it shall be severed from this Public License
without affecting the enforceability of the remaining terms and
conditions.
c. No term or condition of this Public License will be waived and no
failure to comply consented to unless expressly agreed to by the
Licensor.
d. Nothing in this Public License constitutes or may be interpreted
as a limitation upon, or waiver of, any privileges and immunities
that apply to the Licensor or You, including from the legal
processes of any jurisdiction or authority.
© 版权声明
文章版权归作者所有，未经允许请勿转载。
THE END
暂无评论内容