Garnet TLS 配置完全指南：证书生成、服务端启用与 RESP 客户端安全连接

Garnet TLS 配置完全指南：证书生成、服务端启用与 RESP 客户端安全连接

【免费下载链接】garnetGarnet is a remote cache-store from Microsoft Research that offers strong performance (throughput and latency), scalability, storage, recovery, cluster sharding, key migration, and replication features. Garnet can work with existing Redis clients.项目地址: https://gitcode.com/GitHub_Trending/garnet4/garnet

Garnet 是微软研究院推出的高性能远程缓存存储（remote cache-store），支持通过 TLS 对服务端与客户端之间的所有连接进行加密。本文以仓库中的 test/testcerts/README.md 为骨架，系统讲解 Garnet 的 TLS 配置：如何使用仓库自带的测试证书快速启动加密服务，如何通过--cert-file-name加载 PFX 或 PEM 格式证书，如何用 openssl 手工签发一套自签名证书，以及如何让兼容 RESP 的客户端（如 redis-cli）携带证书安全接入。读完本文，你将能够独立完成 Garnet 从证书准备、服务端 TLS 启动到客户端双向认证接入的完整链路。

1. TLS 支持概览：证书格式与自动检测

在 Garnet 中启用 TLS 的核心入口是GarnetServer的两个命令行参数：--cert-file-name与--cert-password。GarnetServer 既接受包含公私钥的 PFX 证书（Windows/Linux 均可），也接受 PEM 编码的证书与私钥对。证书格式是根据文件内容自动检测的，而非依赖文件扩展名，因此.pfx、.pem、.crt、.cer文件都可以通过--cert-file-name传入。

该自动检测逻辑实现在 libs/server/TLS/CertificateUtils.cs 的GetMachineCertificateByFile与IsPemFile方法中：

• IsPemFile读取文件开头的字节流，检查是否以-----BEGIN标记开头（容忍 UTF-8 BOM 与前面的空行/空白），据此区分 PEM 与 PKCS#12/PFX；
• 检测为 PEM 后调用GetCertificateFromPemFile，通过X509Certificate2.CreateFromPemFile加载证书与私钥，再经 PKCS#12 重新导入以获得 SslStream 各平台都支持的持久化密钥集；
• 检测为非 PEM 则走X509CertificateLoader.LoadPkcs12FromFile（.NET 9+）或new X509Certificate2(fileName, password)加载 PFX。

在 libs/host/Configuration/Options.cs 中，这两个参数的定义为：

--cert-file-name TLS 证书文件名。接受 PKCS#12/PFX 文件或 PEM 编码证书（.pem/.crt/.cer）， 格式根据文件内容自动检测（示例：testcert.pfx） --cert-password TLS 证书密码（示例：placeholder）。当 cert-file-name 为 PEM 编码证书时， 该参数被当作独立 PEM 私钥文件的路径（若私钥已包含在证书文件中则可不传）

从源码与测试均能印证"以内容而非扩展名判定格式"这一点：单元测试GetMachineCertificateByFileDetectsPemContentsRegardlessOfExtension（见 test/standalone/Garnet.test/CertificateUtilsTests.cs）将 PEM 证书复制为testcert.pfx文件名后仍能正确加载；GetMachineCertificateByFileLoadsPemCertificateWithEmbeddedKey则验证了单个 PEM 文件同时包含证书与私钥时无需再指定私钥文件。

2. 使用仓库自带的测试证书快速启动

仓库在test/testcerts目录下提供了现成的测试证书文件，便于开发与测试环境直接启用 TLS：

2.1 以 PFX 证书启动服务端

GarnetServer --cert-file-name /path/to/testcert.pfx --cert-password placeholder

2.2 以 PEM 证书 + 独立私钥启动服务端

GarnetServer --cert-file-name /path/to/testcert.pem --cert-password /path/to/testcert.key.pem

此时--cert-password的位置传入的是私钥文件路径。也可以直接把证书与私钥合并进同一个 PEM 文件（证书内容在前、私钥内容在后），则无需再指定私钥文件。

2.3 将 PEM 私钥/证书转换为 PFX

若你只有分离的.key/.crtPEM 文件，希望得到 PFX 格式，可以使用 openssl：

openssl pkcs12 -inkey <server-name>.key -in <server-name>.crt -export -out server-cert.pfx

2.4 使用测试证书的注意点

test/testcerts/README.md明确提示：

• 这些证书是自签名的，默认不被系统信任；
• 它们可能使用了过时的哈希与加密套件，强度有限；
• 生产环境应购买由知名证书颁发机构（CA）签发的证书；
• 仅供开发/测试环境使用。

对应地，测试代码中硬编码的证书口令即为placeholder（见 test/standalone/Garnet.test/TestUtils.cs），与 README 的说明一致。

3. Garnet 的 TLS 配置参数全景

除--cert-file-name/--cert-password之外，libs/host/Configuration/Options.cs 还定义了以下 TLS 相关参数，它们共同构成完整的 TLS 配置面：

这些参数在 libs/server/TLS/GarnetTlsOptions.cs 中被组织进SslServerAuthenticationOptions与SslClientAuthenticationOptions。值得注意的实现细节：

• 服务端证书选择通过ServerCertificateSelector完成：首次同步加载证书，若配置了--cert-refresh-freq则启动一个 Timer 周期刷新证书（失败时按 5 秒重试），实现证书热更新（见 libs/server/TLS/ServerCertificateSelector.cs）；
• cert-file-name与cert-subject-name同时设置会抛出GarnetException，二者只能提供其一；
• cert-subject-name仅在 Windows 平台可用；
• 当client-certificate-required开启但未提供issuer-certificate-path时，代码会记录警告：远端证书链将不做签发者校验（ValidateCertificateIssuer中authority == null时仅构建信任链，不比对根证书指纹）。

4. 让 RESP 兼容客户端通过 TLS 接入

要使用 RESP 兼容客户端（例如 redis-cli）通过 TLS 连接 Garnet，客户端需要三样东西：服务端证书、私钥、CA 根证书。以仓库导出的测试证书为例，启动客户端时提供：

--cacert garnet-ca.crt --cert garnet-cert.crt --key garnet.key

即：

redis-cli --tls \ --cacert /path/to/garnet-ca.crt \ --cert /path/to/garnet-cert.crt \ --key /path/to/garnet.key \ -h <garnet-host> -p <garnet-port>

服务端侧对应需要开启--client-certificate-required并（推荐）指定--issuer-certificate-path指向 CA 根证书，形成双向 TLS 认证。

测试工程中的用法可作参考：在 test/standalone/Garnet.test/TestUtils.cs 中，测试客户端通过CertificateUtils.GetMachineCertificateByFile(certFile, certPassword)加载testcert.pfx并放入ClientCertificates集合发起 TLS 连接，服务端同时配置了证书文件与ClientCertificateRequired = true。

5. 生成你自己的自签名证书（openssl 全流程）

若不想使用仓库测试证书，可按以下步骤用 openssl 构建一套"根 CA → 服务器证书"的完整证书链。整个过程会产生四个关键文件：<issuer-name>.crt/.key（CA 根）与<server-name>.crt/.key（服务器证书）。

5.1 安装 openssl

Linux 发行版：

sudo apt install openssl

Windows 系统可从 OpenSSL 官方 Wiki 的 Binaries 页面选取合适的发行版安装（说明详见 test/testcerts/README.md）。

5.2 创建根密钥（CA 私钥）

openssl ecparam -out <issuer-name>.key -name prime256v1 -genkey

这里使用prime256v1椭圆曲线生成根 CA 的私钥。

5.3 生成根证书 CSR 并自签名

首先生成证书签名请求（CSR）：

openssl req -new -sha256 -key <issuer-name>.key -out <issuer-name>.csr

按提示输入根密钥密码，以及自定义 CA 的组织信息：Country/Region（国家/地区）、State（省/州）、Org（组织）、OU（部门）和签发者名称。

然后用根密钥自签名生成根证书：

openssl x509 -req -sha256 -days 365 -in <issuer-name>.csr -signkey <issuer-name>.key -out <issuer-name>.crt

生成的<issuer-name>.crt将用于签署后续的服务器证书。

5.4 创建服务器证书密钥

注意：服务器名称（subject）必须与签发者名称不同。

openssl ecparam -out <server-name>.key -name prime256v1 -genkey

5.5 生成服务器证书 CSR

openssl req -new -sha256 -key <server-name>.key -out <server-name>.csr

按提示输入密码与组织信息，其中通用名（fully qualified domain name）必须填写服务器的域名，且与签发者不同——这个名称将与后续连接时的服务端主机名匹配，是 TLS 校验的关键。

5.6 用 CA 根证书签署服务器证书

openssl x509 -req -in <server-name>.csr -CA <issuer-name>.crt -CAkey <issuer-name>.key -CAcreateserial -out <server-name>.crt -days 365 -sha256

-CAcreateserial会生成序列号文件（<issuer-name>.srl），-days 365设置证书有效期一年。

5.7 验证新证书

openssl x509 -in <server-name>.crt -text -noout

输出会展示证书的全部信息，包括你录入的组织信息、Issuer（签发者）与Subject（证书主体/服务器名）数据，可据此确认证书链正确。

5.8 确认最终文件清单

完成上述步骤后，你的目录下应包含四个文件：

• <issuer-name>.crt—— CA 根证书
• <issuer-name>.key—— CA 根私钥
• <server-name>.crt—— 服务器证书
• <server-name>.key—— 服务器私钥

随后即可用第 2 节的方式将<server-name>.crt+<server-name>.key作为 PEM 对传入GarnetServer，或以 2.3 节的 openssl 命令转换为 PFX 使用。

6. 从 PFX 导出分离的证书/私钥/CA 文件

当手头只有 PFX 格式证书（例如仓库的testcert.pfx），而客户端需要分离的证书、私钥与 CA 文件时，可用 openssl 分别导出：

导出私钥（-nocerts表示不含证书，-nodes表示不加密私钥）：

openssl pkcs12 -in testcert.pfx -nocerts -nodes -out garnet.key

导出客户端证书（-clcerts仅导出客户端证书，-nokeys不含私钥）：

openssl pkcs12 -in testcert.pfx -clcerts -nokeys -out garnet-cert.crt

导出 CA 根证书（-cacerts仅导出 CA 证书，-chain包含证书链）：

openssl pkcs12 -in testcert.pfx -cacerts -nokeys -chain -out garnet-ca.crt

执行后即得到第 4 节客户端连接所需的garnet.key、garnet-cert.crt、garnet-ca.crt三件套。

7. 常见问题与排障要点

• 证书加载失败：检查--cert-file-name路径与--cert-password是否正确。源码中ServerCertificateSelector在同步加载失败时会记录 "Unable to fetch certificate using the provided filename and password" 日志；若配置了--cert-refresh-freq，则会按 5 秒间隔自动重试（见 libs/server/TLS/ServerCertificateSelector.cs）。
• PEM 文件无法解析：确认文件确实以-----BEGIN开头且未被编辑器写入额外内容；CertificateUtils.IsPemFile已对 UTF-8 BOM 与前置空行做了容错（对应测试GetMachineCertificateByFileDetectsPemWithLeadingBomAndBlankLines，见 test/standalone/Garnet.test/CertificateUtilsTests.cs）。
• 主机名校验失败：服务器证书 Subject 中的通用名（FQDN）必须与客户端连接使用的目标主机名一致，客户端校验逻辑优先取 DNS 名称，缺省时回退到 SimpleName 进行不区分大小写的比对（见 libs/server/TLS/GarnetTlsOptions.cs）。
• 同时指定了 cert-file-name 与 cert-subject-name：二者互斥，运行时会抛出GarnetException；cert-subject-name还仅支持 Windows 平台。
• 双向认证未生效：确认服务端设置了--client-certificate-required true，并通过--issuer-certificate-path指定 CA 根证书，否则校验回调会直接放行（源码中ClientCertificateRequired == false时记录警告并恒返回 true）。

8. 总结

Garnet 的 TLS 配置链路清晰完整：服务端通过--cert-file-name/--cert-password加载 PFX 或 PEM 证书（格式按内容自动识别），配合--tls、双向认证与证书热更新等参数可覆盖从单机加密到集群复制的安全需求；仓库test/testcerts目录提供了开箱即用的测试证书（PFX 口令placeholder），openssl 全流程则可满足自定义证书链的生成与导出。将上述命令与配置组合起来，即可快速搭建一套 TLS 加密的 Garnet 开发/测试环境，并为生产环境的证书规划提供完整参考。

【免费下载链接】garnetGarnet is a remote cache-store from Microsoft Research that offers strong performance (throughput and latency), scalability, storage, recovery, cluster sharding, key migration, and replication features. Garnet can work with existing Redis clients.项目地址: https://gitcode.com/GitHub_Trending/garnet4/garnet