Authelia 必须作为独立反向代理网关运行，不能嵌入 Go 服务；Go 微服务仅信任其注入的 X-Forwarded-User 等请求头，不自行鉴权，且需代理正确透传 X-Real-IP、X-Forwarded-Proto 等关键头。
Authelia 不能直接“嵌入”Golang 微服务代码里当库用；它必须作为独立网关进程运行，通过反向代理方式拦截并认证请求。强行在 Go 服务里调用 Authelia API 做鉴权，会绕过它的会话管理、MFA 流程和统一策略引擎，等于白配。
Authelia 必须以反向代理模式部署，而非 SDK 集成
Authelia 是一个独立的认证网关服务，不是 Go 的 authelia-go 客户端库（官方不提供、也不存在成熟 SDK）。它靠 HTTP 反向代理（如 Nginx、Traefik、Caddy）前置，截获请求、弹出登录页、验证凭证、注入身份头，再把干净请求透传给后端 Go 服务。
- Authelia 自身监听一个端口（如
:9091），不处理业务逻辑，只管认证和授权 - 你的 Go 微服务仍跑在自己的端口（如
:8080），但**不对外暴露**，只允许来自 Authelia 的请求 - 所有外部流量必须先经过 Authelia —— 这是强制前提，不是可选项
- 若跳过代理、改用 Go 服务主动调
/api/verify，则无法触发 TOTP/WebAuthn 页面、无法维持会话 Cookie、无法执行访问控制规则（如policy: two_factor）
Go 微服务只需信任 Authelia 注入的请求头
Authelia 认证成功后，默认会在转发请求时添加 X-Forwarded-User 和 X-Forwarded-Groups 头。你的 Go 服务只需检查这些头，无需自己解析 JWT 或校验签名。
- 确保反向代理配置里启用了
forward_headers（Traefik）或proxy_set_header（Nginx），否则 Go 收不到这些头 - Go 代码中直接读取：
r.Header.Get("X-Forwarded-User")，值就是已认证用户名 - 不要自行验证
Authorization头 —— Authelia 已做完全部 MFA，此时再验 token 属于重复劳动且易出错 - 若需更高权限上下文（如角色、MFA 类型），可开启 Authelia 的
headers配置项，注入X-Forwarded-Auth-Method等自定义头
常见代理配置漏项：Nginx/Traefik 必设参数
Nginx 或 Traefik 若没正确透传关键信息，Go 服务会收不到用户身份，或 Authelia 无法维持会话。
立即学习“go语言免费学习笔记（深入）”；
-
X-Real-IP和X-Forwarded-Proto必须透传，否则 Authelia 会因协议不匹配拒绝 HTTPS 登录 - Authelia 的
session.cookie.secure设为true时，Nginx 必须加proxy_cookie_flags ~Secure，否则浏览器不存 Cookie - Traefik 用户需在中间件中启用
passHostHeader: true，否则 Authelia 日志显示源 IP 全是 127.0.0.1 - Go 服务收到的
RemoteAddr是代理 IP（如 172.18.0.1），不是真实客户端 IP —— 要取真实 IP，必须解析X-Real-IP，而非r.RemoteAddr
调试时最常卡住的三个点
本地跑通但上线失败，问题几乎全集中在网络链路和头字段传递上，和 Go 代码本身关系极小。
- Authelia 日志出现
unable to determine remote IP address→ 检查代理是否透传X-Real-IP，以及 Authelia 的networks配置是否包含代理网段 - 登录后重定向回 Go 服务报 401 → Go 服务没读
X-Forwarded-User，而是错误地要求客户端带Authorization: Bearer ... - WebAuthn 设备注册失败，浏览器提示 “Invalid origin” → Authelia 的
server.host配成0.0.0.0，必须改为实际域名（如auth.example.com），且该域名需与前端页面 URL 完全一致
真正难的不是写 Go 代码，而是让 Authelia、反向代理、Go 服务三者之间的 HTTP 头和 Cookie 严丝合缝地串起来。少一个 proxy_set_header，整个 MFA 就断在第一步。
