Iris必须用app.ListenTLS()直接绑定证书启动HTTPS服务，否则ctx.Request().TLS为nil、ctx.IsSSL()返回false，导致HSTS、Secure Cookie等逻辑失效；子域名需各自调用ListenTLS并传入对应证书路径，不继承主实例配置。
app.ListenTLS() 是唯一生效的 HTTPS 启动方式
Iris 不支持通过反向代理（如 Nginx）后置 TLS 的“伪 HTTPS”配置来启用内部安全校验——ctx.Request().TLS 为 nil、ctx.IsSSL() 返回 false，所有依赖 HTTPS 的逻辑（如 HSTS 头、Secure Cookie、OAuth2 重定向校验）都会失效。必须用 app.ListenTLS() 直接绑定证书启动服务。
常见错误现象：本地配了 Nginx 转发 https://api.example.com → http://127.0.0.1:8080，但 Iris 中 ctx.Request().URL.Scheme 仍是 "http"，导致 JWT 重定向跳转到 http:// 被浏览器拦截。
-
app.ListenTLS(":443", "cert.pem", "key.pem")是标准写法；端口不能省略，":https"这类别名不被识别 - 证书路径必须是绝对路径或相对于当前工作目录的可读路径；相对路径在 systemd 或 Docker 中容易因 cwd 变化而失败
- 若需同时监听 HTTP 和 HTTPS，必须启动两个独立实例（或用
app.Run(iris.TLS(...))+app.Run(iris.Raw(...))），Iris 不支持单实例双协议
子域名 HTTPS 必须各自调用 ListenTLS，不共享证书路径
用 app.Subdomain("api") 创建的子域实例，**不会自动继承主实例的 TLS 配置**。即使你已对主应用调用过 app.ListenTLS()，api.example.com 的请求仍会以 HTTP 形式落到主路由，或直接 404（取决于 Host 匹配逻辑）。
正确做法是为每个子域实例单独绑定证书：
apiApp := app.Subdomain("api")
apiApp.ListenTLS(":443", "./certs/api.crt", "./certs/api.key")
adminApp := app.Subdomain("admin")
adminApp.ListenTLS(":443", "./certs/admin.crt", "./certs/admin.key")
- 泛子域（如
{service}.example.com）无法用单组证书覆盖所有可能子域，除非使用通配符证书（*.example.com）并统一传入各子域实例 - 不要尝试复用同一文件句柄或内存中加载的证书字节——
ListenTLS内部会重新打开文件，传入路径最稳定 - 本地开发时，自签名证书需手动导入系统钥匙串（macOS）或信任根证书（Windows），否则浏览器报
NET::ERR_CERT_AUTHORITY_INVALID
HTTPS 中间件里别依赖 ctx.Request().Host 做路由判断
当客户端通过代理（包括 Cloudflare、ALB、甚至某些企业防火墙）访问时，ctx.Request().Host 可能被篡改或固定为主域名（如 example.com），而真实子域信息实际藏在 X-Forwarded-Host 或 Host 的原始值里。直接用它做鉴权或跳转，会导致 API 在生产环境路由错乱。
- 优先使用
ctx.Subdomain()提取子域值——它基于iris.SubdomainExtractor，已内置对X-Forwarded-Host和标准Host的兼容解析 - 若需校验请求是否来自可信 HTTPS 源，检查
ctx.Request().TLS != nil，而非比对Host字符串 - 设置 Secure Cookie 时，务必显式传
iris.CookieSecure(true)，不要靠框架自动推断；Iris 不会因为监听了 TLS 端口就默认开启 Cookie 安全标记
Let’s Encrypt 自动续期要绕过 Iris 的静态文件拦截
acme-http-01 挑战要求 /.well-known/acme-challenge/xxx 路径返回纯文本，但如果你注册了通配路由 /{path:path} 并放在最后兜底，它会抢先匹配该路径并返回 404 或 HTML，导致验证失败。
- 必须在所有路由注册前，**显式注册 ACME 路由**：
app.Get("/.well-known/acme-challenge/{token}", acmeHandler) -
acmeHandler不能走模板渲染或重定向，必须用ctx.Text("text/plain", content)直接输出 challenge 值 - 若用 Caddy/Nginx 做反代并托管 ACME，Iris 本体无需处理该路径，但此时
app.ListenTLS()就不该启用——让反代层负责 TLS 终止，Iris 回归纯 HTTP
真正容易被忽略的是证书私钥权限和容器内时区：Linux 上私钥文件权限必须是 600，否则 ListenTLS 启动时静默失败；Docker 镜像若未同步主机时区（/etc/localtime），证书有效期校验可能误判为过期。
