Go 服务中正确配置 Let’s Encrypt TLS 的完整实践指南-Golang-PHP中文网

Go 服务中正确配置 Let’s Encrypt TLS 的完整实践指南

本文详解 go 应用集成 let’s encrypt 的常见握手错误成因与解决方案，涵盖 autocert 自动签发和手动证书加载两种模式，重点纠正 servername、hostpolicy、http-01 挑战路径及 tls 配置误区，并提供可直接运行的健壮示例代码。

本文详解 go 应用集成 let’s encrypt 的常见握手错误成因与解决方案，涵盖 autocert 自动签发和手动证书加载两种模式，重点纠正 servername、hostpolicy、http-01 挑战路径及 tls 配置误区，并提供可直接运行的健壮示例代码。

在 Go 中通过 golang.org/x/crypto/acme/autocert 或原生 http.ListenAndServeTLS 集成 Let’s Encrypt 是常见做法，但大量开发者遭遇看似“随机”的 TLS 握手错误（如 acme/autocert: missing server name、host not configured、EOF、connection reset by peer），导致服务无法稳定提供 HTTPS。这些错误极少源于证书本身问题（正如 SSL Labs 测试报告无误所印证），而几乎全部根植于 Go HTTP 服务器配置逻辑与 ACME 协议交互机制的误解。

? 核心问题诊断与修正

✅ 1. `autocert` 模式下最常被忽略的三大配置陷阱

ServerName 在 tls.Config 中必须为空
错误写法：

TLSConfig: &tls.Config{
    ServerName: app.Cfg.S_HOST, // ❌ 禁止显式设置！autocert 会根据 SNI 自动匹配
    GetCertificate: certManager.GetCertificate,
}

正确写法（完全移除 ServerName）：

TLSConfig: &tls.Config{
    GetCertificate: certManager.GetCertificate,
    // ServerName 必须留空，否则 autocert 无法动态路由证书
}

HostWhitelist 必须严格匹配客户端请求的 Host 头（含端口？否！）
若你的域名是 example.com，但用户通过 https://example.com:443 访问，ACME 不会校验端口 —— HostWhitelist("example.com") 完全合法。但若 app.Cfg.S_HOST 被误设为 "example.com:443" 或 "www.example.com"（而 DNS 未同时解析），则触发 host not configured。务必确保：
```
HostPolicy: autocert.HostWhitelist(strings.TrimSuffix(app.Cfg.S_HOST, ":443")), // 建议标准化处理
```

HTTP-01 挑战端口必须为 80，且不可被重定向拦截
autocert 在首次申请时需响应 /.well-known/acme-challenge/xxx，该请求必须由 :80 服务直接处理，而非重定向到 :443。你当前的 :80 服务中：

http.HandleFunc("/*", ...) { http.Redirect(...https://...) } // ❌ 会中断 ACME 挑战！

✅ 正确方案：为 :80 添加挑战专用路由，其他路径才重定向：

go func() {
    http.HandleFunc("/.well-known/acme-challenge/", certManager.HTTPHandler(nil))
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        http.Redirect(w, r, "https://"+app.Cfg.S_HOST+r.RequestURI, http.StatusMovedPermanently)
    })
    log.Println("HTTP redirect server starting on :80")
    if err := http.ListenAndServe(":80", nil); err != nil && !errors.Is(err, http.ErrServerClosed) {
        log.Fatal("HTTP server error:", err)
    }
}()

✅ 2. 手动证书模式的典型错误：协议层不兼容

你遇到的 http2: server: error reading preface... bogus greeting "POST / HTTP/1.1" 表明客户端（如 curl、浏览器）正尝试用 HTTP/1.1 明文请求连接到 TLS 端口 :443 —— 这是典型的端口复用误配。http.ListenAndServeTLS 仅接受 TLS 握手后的加密流量，任何直连 :443 的 HTTP/1.1 请求都会失败。

✅ 解决方案：确保所有外部流量均通过 HTTPS 发起；若需调试，使用：

curl -v https://example.com/hello   # ✅ 正确：走 TLS
curl -v http://example.com/hello    # ❌ 错误：应被 :80 重定向，而非直连 :443

同时，检查证书路径权限：ssl["cert"] 和 ssl["key"] 文件需被 Go 进程可读，且私钥不可加密（即无密码保护）：

openssl rsa -in privkey.pem -check -noout  # 应输出 "RSA key ok"

? 完整可运行示例（autocert + 生产就绪）

package main

import (
    "log"
    "net/http"
    "strings"
    "time"

    "golang.org/x/crypto/acme/autocert"
)

func main() {
    domain := "example.com" // 替换为你的域名

    // ✅ 步骤1：配置 autocert Manager（关键：Cache 目录需存在且可写）
    m := autocert.Manager{
        Prompt:     autocert.AcceptTOS,
        HostPolicy: autocert.HostWhitelist(domain),
        Cache:      autocert.DirCache("./certs"), // mkdir -p ./certs
        Email:      "admin@example.com",          // 可选，用于到期提醒
    }

    // ✅ 步骤2：启动 HTTP 重定向服务（:80），专供 ACME 挑战
    go func() {
        http.HandleFunc("/.well-known/acme-challenge/", m.HTTPHandler(nil))
        http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
            target := "https://" + domain + r.RequestURI
            http.Redirect(w, r, target, http.StatusMovedPermanently)
        })
        log.Println("HTTP redirect server listening on :80")
        log.Fatal(http.ListenAndServe(":80", nil))
    }()

    // ✅ 步骤3：HTTPS 服务（:443），TLSConfig 中绝不设 ServerName
    mux := http.NewServeMux()
    mux.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "text/plain")
        w.Write([]byte("Hello from Go + Let's Encrypt!\n"))
    })

    server := &http.Server{
        Addr: ":443",
        Handler: mux,
        TLSConfig: &tls.Config{
            GetCertificate: m.GetCertificate,
            // ✅ 关键：不要设置 ServerName！
            MinVersion: tls.VersionTLS12,
        },
        ReadTimeout:  5 * time.Second,
        WriteTimeout: 10 * time.Second,
    }

    log.Println("HTTPS server starting on :443")
    log.Fatal(server.ListenAndServeTLS("", "")) // 空字符串表示由 autocert 提供
}

⚠ 注意事项与最佳实践

证书缓存目录安全：DirCache("./certs") 目录应设为 0700 权限，避免私钥泄露。
Let’s Encrypt 速率限制：首次部署建议先用 autocert.Cache 实现本地持久化，避免重复申请触发限制。
64 天证书生命周期：自 2027 年 2 月起，Let’s Encrypt 默认签发 64 天证书（非 90 天），autocert 会自动处理续期，无需人工干预。
生产环境加固：启用 HTTP/2（Go 1.8+ 默认支持）、HSTS 头、OCSP Stapling（需 tls.Config 中配置 NextProtos 和 GetConfigForClient）。

日志监控：autocert 的 Manager 支持 Prompt 和 HostPolicy 返回错误，建议包装 HostPolicy 添加日志：

HostPolicy: func(ctx context.Context, host string) error {
    log.Printf("ACME host check: %s", host)
    if host == domain || strings.HasSuffix(host, "."+domain) {
        return nil
    }
    return fmt.Errorf("host %s not allowed", host)
},

通过以上配置，99% 的 TLS 握手错误将被根除。记住：Go 的 http 包对 TLS 是“声明式”的——你只需正确声明意图（谁来提供证书、哪些域名有效、挑战如何响应），其余均由底层自动完成。过度干预（如硬编码 ServerName、在 :443 上处理非 TLS 流量）才是问题之源。