Kratos框架不内置mTLS完整实现,但提供可插拔扩展点;gRPC需设tls.Config.ClientAuth为tls.RequireAndVerifyClientCert并配置ClientCAs,HTTP需手动注入TLSConfig并调用ListenAndServeTLS,证书校验逻辑须自行实现。

Kratos 框架本身不内置 TLS 双向认证(mTLS)的完整实现,但提供了清晰、可插拔的扩展点,让你能基于 Go 标准库 crypto/tls 和 gRPC 的 TransportCredentials 完整控制双向认证流程。关键不是“框架帮你做”,而是“框架留出正确位置让你做”。
gRPC Server 端启用 mTLS 需显式配置 tls.Config
Kratos 的 gRPC Server 通过 TLSConfig(c *tls.Config) ServerOption 接收自定义 TLS 配置。要启用双向认证,必须设置 ClientAuth 字段为 tls.RequireAndVerifyClientCert,并提供可信 CA 证书池(ClientCAs)。
常见错误现象:服务启动无报错,但客户端证书被忽略,或连接直接被拒绝且日志只显示 tls: failed to verify client's certificate。
- 必须调用
tls.X509KeyPair(serverCert, serverKey)加载服务端证书和私钥,不能只传入 PEM 内容字符串 -
ClientCAs必须是*x509.CertPool,不能是空值或 nil;可用certPool.AppendCertsFromPEM(caPEM)加载 CA 证书 - 若使用自签名 CA,客户端证书必须由该 CA 签发,且服务端加载的
ClientCAs必须包含该 CA 公钥
HTTP Server 同样依赖 http.Server.TLSConfig
Kratos 的 HTTP Server 不像 gRPC 那样暴露 TLSConfig 选项,需在构建 http.Server 实例前手动注入。典型做法是在 internal/server/http.go 中修改 NewHTTPServer 函数:
srv := &http.Server{
Addr: addr,
Handler: handler,
TLSConfig: &tls.Config{
ClientAuth: tls.RequireAndVerifyClientCert,
ClientCAs: caPool,
MinVersion: tls.VersionTLS12,
},
}
注意:Kratos 默认不会自动调用 srv.ListenAndServeTLS,你必须显式调用它(而非 ListenAndServe),否则 TLS 不生效。
- 如果只配置了
TLSConfig但没调用ListenAndServeTLS,服务会退化为明文 HTTP,且无任何警告 -
MinVersion建议设为tls.VersionTLS12或更高,避免 TLS 1.0/1.1 引发握手失败或安全审计不通过 - HTTP mTLS 下,客户端证书信息可通过
r.TLS.PeerCertificates获取,需自行解析并注入 context
客户端证书校验逻辑必须自己实现
Kratos 不提供开箱即用的证书白名单、SPIFFE 支持或证书 DN 匹配中间件。所有业务级校验(比如只允许 O=internal,CN=payment-service 的证书访问支付接口)都得手写。
典型使用场景:在 gRPC UnaryInterceptor 或 HTTP middleware 中提取证书信息并判断。
- gRPC 场景下,从
peer.FromContext(ctx).AuthInfo解出credentials.TLSInfo,再取State.VerifiedChains - HTTP 场景下,从
http.Request.TLS.PeerCertificates[0]获取客户端证书,调用cert.Verify(&opts)可复用服务端已加载的caPool - 不要仅比对
CN字段——现代证书常禁用 CN,应优先检查SANs(Subject Alternative Names)中的 DNS 名或 URI
Wire 依赖注入里容易漏掉证书文件路径管理
Kratos 推荐用 Wire 管理依赖,但证书路径(如 server.crt、server.key、ca.crt)若硬编码在 New 函数里,会导致测试难 mock、环境切换麻烦。
性能与兼容性影响:证书读取不应在每次请求时发生;必须在初始化阶段一次性读取并解析,否则 TLS 握手延迟会飙升。
- 把证书路径作为
Config结构体字段注入,配合 Kratosconfig模块从 YAML/etcd/Nacos 加载 - 证书解析(
ioutil.ReadFile+x509.ParseCertificate)务必放在Initialize阶段,不要放在 handler 内 - 若证书更新,Kratos 的 config watch 不会自动 reload
tls.Config—— 需监听变更后重建 Server 实例或热替换tls.Config.GetConfigForClient
最易被忽略的一点:mTLS 要求整个调用链路(client → gateway → service)每跳都开启双向认证,而 Kratos 的网关层(如集成 Nginx 或 Hertz)通常不参与证书校验,此时必须确保服务间直连通信走 mTLS,且网关只做透传,不终止 TLS。


















