app.ListenTLS() 是最简 HTTPS 启动方式,但要求 cert.pem 为完整证书链(如 Let’s Encrypt 的 fullchain.pem)、key.pem 为未加密且权限 ≤0600 的私钥、换行符为 LF;必须用 ConfigureHost() 预设 TLSConfig(如 MinVersion: tls.VersionTLS12),且顺序不可颠倒;本地调试需 SAN 字段覆盖访问 IP/域名,生产环境应弃用 ListenTLS() 改用手动 srv.ListenAndServeTLS() 以支持超时与优雅关闭。

app.ListenTLS() 是最简 HTTPS 启动方式,但参数顺序和文件内容必须严格匹配
直接调用 app.ListenTLS(":443", "cert.pem", "key.pem") 就能跑 HTTPS,但失败时往往没明确报错,只卡住或静默退出。根本原因不是端口权限,而是两个 PEM 文件不合规:
-
cert.pem必须是完整证书链(domain cert + intermediate CA),Let’s Encrypt 用户必须用fullchain.pem,不能只放cert.pem;否则客户端握手失败,报x509: certificate signed by unknown authority -
key.pem必须是未加密私钥(不含DEK-Info行),若用openssl genrsa -aes256生成,得先解密:openssl rsa -in key.pem.enc -out key.pem - Linux/macOS 下私钥权限必须 ≤
0600,0644会被 Go 的crypto/tls拒绝加载,但错误日志常误导为private key does not match public key - 文件换行符必须是 LF(Unix 风格),Windows 的 CRLF 会导致
tls: failed to find any PEM data in certificate input;可用dos2unix cert.pem key.pem修复
ConfigureHost() 才能设置 TLS 安全策略,比如最低版本和密码套件
app.ListenTLS() 内部仍走标准库的 http.Server,但默认允许 TLS 1.0/1.1,现代浏览器会警告甚至拦截。必须用 app.ConfigureHost() 注入自定义 *http.Server 配置:
- 显式设
MinVersion: tls.VersionTLS12,Go 1.26 默认仍兼容旧协议,不设就等于开后门 - 禁用弱 CipherSuites:Go 1.19+ 默认已优先 AEAD 套件,一般无需手动裁剪;若需兼容极老设备,只保留如
tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 -
TLSConfig必须在app.ListenTLS()调用前完成赋值,之后改无效 —— 因为ListenTLS()内部会新建http.Server实例
示例写法:
app.ConfigureHost(func(s *http.Server) {
s.TLSConfig = &tls.Config{
MinVersion: tls.VersionTLS12,
// 其他配置...
}
})
注意:别把 ConfigureHost() 放在 ListenTLS() 之后,顺序错了配置就丢弃了。
本地调试自签名证书,浏览器报错不是服务端问题,而是证书缺 SAN 字段
用 openssl req -x509 生成自签名证书时,如果漏掉 -addext "subjectAltName = DNS:localhost,IP:127.0.0.1",Chrome 90+ 和 Edge 会直接拒绝连接,报 ERR_CERT_COMMON_NAME_INVALID 或 NET::ERR_CERT_AUTHORITY_INVALID —— 这跟 Iris 无关,是浏览器强制要求。
- 生成命令必须带
-addext参数,且 SAN 要覆盖所有访问域名/IP,比如开发时还用192.168.x.x,就得一并写进去 - 证书生成后,双击导入系统根证书存储(macOS 拖进“钥匙串访问”→ 设为“始终信任”;Windows 导入“受信任的根证书颁发机构”)
- Iris 服务端完全不用改代码,它只管 TLS 握手;信任关系纯属客户端行为
生产环境别依赖 ListenTLS(),超时、优雅关闭、信号处理都得自己控
app.ListenTLS() 看似方便,但它不暴露 http.Server 实例,无法设 ReadTimeout、WriteTimeout、IdleTimeout,也做不到优雅关机。线上出问题就是连接堆积、goroutine 泄漏、重启断连。
- 真正可控的做法:用
app.Server()拿到*http.Server,手动设Addr、TLSConfig、超时字段,再调srv.ListenAndServeTLS() - 优雅关闭必须监听
os.Interrupt或syscall.SIGTERM,调srv.Shutdown();ListenTLS()不提供这个入口 - 若需 ACME 自动续签(如 Certbot 或 lego),得用
app.TLSConfig(&tls.Config{GetCertificate: myFunc})动态提供证书,而不是固定路径
最容易被忽略的是 IdleTimeout:不设的话,空闲连接永远不释放,Nginx 反向代理后容易触发 upstream timeout,而日志里只显示客户端断连,查不出根源。


















