<p>Gin 不该直接监听 HTTPS 端口，因证书热更新需重启、缺乏 OCSP Stapling/HTTP/2 等优化、丢失 Nginx 的连接复用与 IP 透传能力，且运维职责错位；生产环境应由 Nginx 卸载 TLS，Gin 仅处理 HTTP，并通过可信 X-Forwarded-* 头（配合 SetTrustedProxies）还原原始 HTTPS 上下文。</p>
Gin 本身不处理 HTTPS 终止，也不内置 TLS 配置能力。要让 Gin 应用支持 HTTPS 反向代理，必须由前端反向代理（如 Nginx）完成 SSL 卸载，Gin 后端只需保持 HTTP 明文通信 —— 这是生产环境最常见、最安全的分工方式。
为什么 Gin 不该直接监听 HTTPS 端口
直接在 Gin 中调用 http.ListenAndServeTLS 虽然技术上可行，但会带来几个实际问题：
- 证书热更新困难：每次证书续期都要重启 Gin 进程，中断连接
- 无法复用成熟的 TLS 优化（如 OCSP Stapling、ALPN、HSTS 头自动注入）
- 失去连接复用、HTTP/2 升级、客户端 IP 透传等 Nginx 原生能力
- 运维边界模糊：本该由基础设施层承担的加密职责，落到应用代码里
除非是极简 demo 或离线测试场景，否则不建议 router.RunTLS。
Nginx 配置中必须透传的关键 Header
当 Nginx 作为 HTTPS 入口时，Gin 应用需要知道原始请求是加密的，否则 c.Request.TLS 始终为 nil，c.Request.URL.Scheme 默认是 http。必须在 proxy_set_header 中显式设置：
-
X-Forwarded-Proto: $scheme→ 让 Gin 知道客户端用的是https -
X-Forwarded-For: $proxy_add_x_forwarded_for→ 保留真实客户端 IP -
Host: $host→ 避免 Gin 生成的重定向 URL 错用后端地址
漏掉 X-Forwarded-Proto 是导致 Gin 中 c.Request.URL.Scheme == "http" 的最常见原因，会影响 OAuth 回调、Webhook 签名验证等依赖协议的逻辑。
Gin 内部如何安全使用 X-Forwarded-* 头
这些头可被客户端伪造，所以 Gin 必须只信任来自可信代理（即 Nginx）的值。需在初始化时启用信任：
r := gin.Default()
r.ForwardedByClientIP = true
r.SetTrustedProxies([]string{"127.0.0.1", "::1"}) // 仅信任本地 Nginx
同时，在路由中避免直接读 c.ClientIP() 或 c.Request.Header.Get("X-Forwarded-For")，而应使用 Gin 封装后的：
-
c.ClientIP()→ 已按SetTrustedProxies过滤 -
c.Request.URL.Scheme→ 若X-Forwarded-Proto存在且可信，Gin 会自动覆盖
没调用 SetTrustedProxies 就启用 ForwardedByClientIP，会导致任意请求都能伪造 IP。
WebSocket 在 HTTPS 反向代理下的特殊处理
如果 Gin 后端提供 WebSocket 接口（如 /ws），Nginx 配置需额外两行：
proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";
缺任一都会导致握手失败（返回 400 或直接关闭连接）。Gin 侧无需修改，但需确保 gorilla/websocket.Upgrader.CheckOrigin 不校验 Origin 或只校验可信域名 —— 因为 Nginx 会改写 Origin 头，原始值可能已不可见。
路径重写和 Header 透传的细节容易被忽略，尤其是 X-Forwarded-Proto 和 SetTrustedProxies 的配合，这两处出错会导致整个 HTTPS 语义链断裂，但错误表现往往很隐蔽（比如登录跳转回 http、签名验签失败）。
