配置服务端证书热更新并避免重启监听

Go 服务端可以不重启监听就更新 TLS 证书：让 tls.Config.GetCertificate 在每次新握手时读取一个原子证书快照，轮换程序先把新证书完整加载并校验，全部通过后再用一次原子写入替换旧快照。这样 TCP 监听、HTTP Server 和已有连接保持不动；若新文件损坏或域名错误，旧证书继续服务。

Go TLS 官方文档：https://pkg.go.dev/crypto/tls

规模背景：证书轮换不应等同于进程重启

单实例低流量服务通过重启加载新证书通常能工作，但实例数量、长连接和发布链路增加后，问题会逐渐显现：

• 重启监听会中断尚未完成的请求，长轮询和 WebSocket 影响更明显；
• 证书轮换被迫绑定应用发布，证书到期风险与代码变更风险叠加；
• 大量实例同时滚动时，负载均衡容量和连接重建压力上升；
• 新证书文件有误时，重启后的进程可能直接失去 TLS 服务能力。

热更新的目标不是让旧连接中的证书“瞬间变化”。TLS 证书在握手时发送，已经建立的连接不会重新握手；热更新保证的是后续新握手使用新快照，同时监听器不中断。

原架构瓶颈：直接替换 Certificates 会引入并发风险

一个常见做法是把证书放入 tls.Config.Certificates，文件变化时直接修改切片。问题在于 tls.Config 正在被并发握手读取，原地修改共享对象容易产生数据竞争，也难以保证证书链、私钥和解析后的叶子证书在同一个版本。

另一个做法是每次握手都从磁盘调用 tls.LoadX509KeyPair。这会把磁盘 I/O、PEM 解析和密钥检查放进握手热路径；文件更新到一半时，还可能读到不完整内容。规模化后，更稳妥的边界是：

新架构：不可变证书快照加 GetCertificate

tls.Config.GetCertificate 在收到 ClientHello 后调用，可按客户端信息返回证书。对单域名或同一证书覆盖多个域名的服务，可以把当前证书保存在 atomic.Pointer[tls.Certificate] 中。加载器构造一个全新的对象；握手只做 Load，绝不修改已经发布的对象。

下面实现使用一个同时包含证书链与私钥的 server-bundle.pem。把两部分放进同一个受限权限文件，可以通过同文件系统内的原子重命名一次切换完整材料，避免证书文件已经更新而私钥文件仍是旧版本。

package main

import (
	"context"
	"crypto/tls"
	"crypto/x509"
	"errors"
	"fmt"
	"log"
	"net/http"
	"os"
	"os/signal"
	"sync/atomic"
	"syscall"
	"time"
)

type certReloader struct {
	bundlePath string
	serverName string
	current    atomic.Pointer[tls.Certificate]
}

func newCertReloader(bundlePath, serverName string) (*certReloader, error) {
	r := &certReloader{bundlePath: bundlePath, serverName: serverName}
	if err := r.Reload(); err != nil {
		// 启动时没有可用旧证书，必须失败退出
		return nil, err
	}
	return r, nil
}

func loadCertificate(bundlePath, serverName string) (*tls.Certificate, error) {
	pemData, err := os.ReadFile(bundlePath)
	if err != nil {
		return nil, fmt.Errorf("读取证书 bundle: %w", err)
	}

	// 同一 bundle 同时作为证书链和私钥输入，LoadX509KeyPair 会检查配对
	pair, err := tls.X509KeyPair(pemData, pemData)
	if err != nil {
		return nil, fmt.Errorf("解析证书与私钥: %w", err)
	}
	if len(pair.Certificate) == 0 {
		return nil, errors.New("证书链为空")
	}

	leaf, err := x509.ParseCertificate(pair.Certificate[0])
	if err != nil {
		return nil, fmt.Errorf("解析叶子证书: %w", err)
	}
	pair.Leaf = leaf

	now := time.Now()
	if now.Before(leaf.NotBefore) || !now.Before(leaf.NotAfter) {
		return nil, fmt.Errorf("证书不在有效期内: %s ~ %s", leaf.NotBefore, leaf.NotAfter)
	}
	if err := leaf.VerifyHostname(serverName); err != nil {
		return nil, fmt.Errorf("证书不覆盖 %s: %w", serverName, err)
	}
	return &pair, nil
}

func (r *certReloader) Reload() error {
	next, err := loadCertificate(r.bundlePath, r.serverName)
	if err != nil {
		// 任何校验失败都不覆盖当前快照
		return err
	}
	r.current.Store(next)
	return nil
}

func (r *certReloader) GetCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error) {
	cert := r.current.Load()
	if cert == nil {
		return nil, errors.New("当前没有可用服务端证书")
	}
	// 检查客户端协议版本和签名算法是否支持当前证书
	if err := hello.SupportsCertificate(cert); err != nil {
		return nil, fmt.Errorf("客户端不支持当前证书: %w", err)
	}
	return cert, nil
}

func main() {
	const bundlePath = "/etc/example-service/tls/server-bundle.pem"
	const serverName = "api.example.internal"

	reloader, err := newCertReloader(bundlePath, serverName)
	if err != nil {
		log.Fatal("初始证书不可用: ", err)
	}

	mux := http.NewServeMux()
	mux.HandleFunc("/health", func(w http.ResponseWriter, _ *http.Request) {
		// 健康检查只表示进程与 HTTP 处理器可用
		w.WriteHeader(http.StatusNoContent)
	})

	server := &http.Server{
		Addr:    ":8443",
		Handler: mux,
		TLSConfig: &tls.Config{
			MinVersion:    tls.VersionTLS12,
			GetCertificate: reloader.GetCertificate,
		},
		ReadHeaderTimeout: 5 * time.Second,
		IdleTimeout:       60 * time.Second,
	}

	reloadSignals := make(chan os.Signal, 1)
	signal.Notify(reloadSignals, syscall.SIGHUP)
	go func() {
		for range reloadSignals {
			if err := reloader.Reload(); err != nil {
				// 失败时继续服务旧证书，并让监控采集这条错误
				log.Printf("证书重载失败，保留旧证书: %v", err)
				continue
			}
			log.Print("证书重载成功")
		}
	}()

	serveErrors := make(chan error, 1)
	go func() {
		// 已配置 GetCertificate，因此无需传入静态证书文件名
		serveErrors 

这里有三个关键点。第一，Reload 只在全部校验通过后调用 Store；第二，GetCertificate 返回后不再修改证书对象；第三，ListenAndServeTLS("", "") 之所以可用，是因为 TLSConfig 已提供 GetCertificate。

关键取舍一：重载触发器与文件原子性

SIGHUP 的优点是行为清晰：证书管理器先写好文件，再显式通知进程。相比每隔几秒轮询，它不会持续访问磁盘，也不会因为文件时间戳差异重复加载。代价是部署系统必须可靠地发送信号。

单个 bundle 可以在同一文件系统内先写临时文件，再原子重命名到正式路径。临时文件和目标文件必须处于同一挂载点，否则移动可能退化为复制，失去原子切换语义。

#!/usr/bin/env bash
set -euo pipefail

# 先把完整证书链与私钥 bundle 安装为受限权限的临时文件
install -m 0600 ./server-bundle.pem /etc/example-service/tls/server-bundle.pem.next

# 同一文件系统内重命名，避免服务读到半写入文件
mv /etc/example-service/tls/server-bundle.pem.next \
   /etc/example-service/tls/server-bundle.pem

# 文件完全就绪后再通知服务；PID 文件由服务管理器维护
kill -HUP "$(cat /run/example-service.pid)"

如果组织要求证书与私钥分开保存，可以把它们写入一个新的版本目录，再原子切换单一 current 符号链接。加载器应先解析链接得到同一版本目录，再读取其中的两份文件，不能分别跟随可能在中途变化的链接。

关键取舍二：旧连接不会自动换证书

证书只在 TLS 握手时发送。HTTP keep-alive、HTTP/2 长连接或 WebSocket 在轮换后仍沿用原会话，不会再次调用 GetCertificate。测试热更新时，如果客户端复用了连接，很容易误判“新证书没有生效”。

验证时应显式建立一条新 TLS 连接，检查新连接看到的叶子证书序列号、指纹或到期时间；不要只刷新一个持续复用连接的 HTTP 客户端。生产侧也应接受短时间内新旧证书同时被观察到，这通常是连接生命周期造成的正常现象。

关键取舍三：单证书与多租户 SNI

示例适合一个证书覆盖一个或多个固定域名。若同一监听端口托管多个租户，可把原子快照从单个 *tls.Certificate 扩展为不可变映射：

• 键使用规范化后的 SNI 域名；
• 值包含候选证书链，并在发布前完成解析；
• GetCertificate 根据 ClientHelloInfo.ServerName 选择候选；
• 通过 SupportsCertificate 选择客户端兼容的签名算法；
• 整张映射一次 Store，避免某些域名已更新、另一些域名仍处于半状态。

若除了证书还要按租户切换 ALPN、客户端证书策略或其他 TLS 参数，可以考虑 GetConfigForClient。官方文档要求，回调返回的 Config 不得在之后继续修改；因此仍应构造不可变新配置，而不是修改正在使用的父 Config。

上线结果：用可验证信号定义成功

不要用“进程没重启”作为唯一成功标准。一次完整轮换至少应满足以下结果：

日志只记录证书序列号、SHA-256 指纹、NotAfter、SAN 摘要和错误类型，不输出私钥或完整 PEM。指标建议包含 certificate_reload_success_total、certificate_reload_failure_total、certificate_not_after_seconds 与当前证书信息标签。

后续改进：让轮换从可用走向可运营

• 增加提前量告警：按剩余有效期分级告警，不把 SIGHUP 当作唯一健康信号。
• 保留最后成功版本：重载失败时继续用旧证书，并保留可回滚的版本目录。
• 限制证书来源：检查文件权限、属主与路径，避免低权限进程替换私钥。
• 测试客户端兼容性：使用 SupportsCertificate 覆盖 RSA、ECDSA 与协议版本差异。
• 为多实例错峰：证书统一生成，但信号触发可小批量推进，便于观察失败。
• 分离服务健康与证书健康：HTTP 健康端点正常不代表证书即将到期问题已经解决。

常见问题

为什么不直接替换 tls.Config.Certificates？

正在并发使用的配置不应原地修改。不可变证书对象加原子指针更容易保证线程安全和版本一致性。

GetCertificate 每次都会读取文件吗？

本文实现不会。它只原子读取内存快照；磁盘读取与 PEM 解析发生在控制面的 Reload 中。

证书热更新后，已有 HTTP/2 连接何时使用新证书？

已有连接不会换证书。客户端关闭旧连接并建立新 TLS 握手时才会看到新证书。

重载失败是否应该退出进程？

启动时没有旧证书，应失败退出；运行期间重载失败，应保留最后一个有效快照并报警，除非组织的安全策略明确要求停止服务。

为什么还要检查 VerifyHostname？

密钥与证书配对只说明材料一致，不能说明证书覆盖当前服务域名。发布前验证主机名可以阻止把其他服务的证书切进当前监听器。

证书热更新的本质是把“监听器生命周期”“握手读取路径”和“证书加载路径”拆开：数据面只读，控制面完整校验后一次发布。这样既避免重启监听，也把错误证书的影响限制在切换之前。