寻求HAProxy整合SSO（Keycloak、Authelia等）的新手指南及配置解决方案

阿华AIGC实验室

2026-4-21

兄弟我太懂你这种感受了！用HAProxy好几年，basic auth天天弹框烦死人，还跟某些服务兼容性拉胯，试Authelia卡壳的滋味我也经历过。下面给你一步步捋清楚怎么搞，先解决你最疑惑的点，再给你完整的配置指南，顺便拆解清楚整个认证流程的逻辑。

先解决你的核心疑问：Authelia需要auth.$DOMAIN的DNS和HAProxy后端吗？

答案是必须要！Authelia本身是一个独立的Web服务，它需要HAProxy反向代理才能被外网访问，所以你得做两件事：

给auth.yourdomain.com做DNS解析，指向你的HAProxy服务器公网IP
在HAProxy配置里给Authelia单独加一个backend，把请求转发到Authelia的容器/服务端口

分步配置HAProxy + Authelia（适配Docker微服务场景）

步骤1：先把Authelia跑起来（用Docker Compose为例）

先写个极简的docker-compose.yml，把Authelia部署好：

version: '3.8'
services:
  authelia:
    image: authelia/authelia:latest
    volumes:
      - ./authelia/config:/config  # 挂载配置目录，方便修改
    ports:
      - 9091:9091  # 暴露端口给HAProxy调用
    environment:
      - TZ=Asia/Shanghai
    restart: unless-stopped

然后在./authelia/config目录下创建configuration.yml，配置最基础的认证规则和信任IP（关键是要把HAProxy的IP加入信任列表）：

server:
  host: 0.0.0.0
  port: 9091
log:
  level: info
authentication_backend:
  file:
    path: /config/users_database.yml  # 可以用本地用户文件，也能换LDAP/OAuth
session:
  name: authelia_session
  secret: 你的随机加密密钥（自己生成一个长字符串）
  expiration: 3600  # 会话有效期1小时
  inactivity: 300   # 5分钟无操作登出
  domain: yourdomain.com  # 主域名，这样Cookie能在子域名间共享
proxy:
  trusted_proxies:
    - 127.0.0.1/32  # HAProxy的本地IP，要是Docker网络就加对应的子网（比如172.17.0.0/16）
  endpoints:
    - domain: docs.yourdomain.com  # 你要保护的Hedgedoc域名
      policy: single_factor  # 可选single_factor（单密码）或two_factor（两步验证）

再创建users_database.yml添加测试用户：

users:
  yourname:
    displayname: "Your Name"
    password: "$argon2id$v=19$m=65536,t=3,p=4$xxx$xxx"  # 用Authelia生成的argon2哈希密码
    email: your@email.com
    groups:
      - admins

（密码可以用docker run --rm authelia/authelia hash-password 你的密码生成）

步骤2：HAProxy里配置Authelia的反向代理

先给Authelia加backend：

backend authelia_backend
    server authelia 127.0.0.1:9091 check  # 要是Authelia在Docker容器里，换成容器IP

然后在你的HTTPS frontend里加规则，处理auth域名的请求：

frontend https_frontend
    bind *:443 ssl crt /etc/haproxy/certs/  # 你的SSL证书目录
    # 匹配auth域名
    acl host_auth hdr(host) -i auth.yourdomain.com
    # 转发到Authelia后端
    use_backend authelia_backend if host_auth

步骤3：给Hedgedoc等微服务加认证保护

先给Hedgedoc加backend：

backend hedgedoc_backend
    server hedgedoc 172.17.0.2:3000 check  # 换成你的Hedgedoc容器IP和端口

然后回到HTTPS frontend，加认证规则：

# 匹配Hedgedoc的域名
acl host_hedgedoc hdr(host) -i docs.yourdomain.com
# 检查是否有Authelia的有效会话Cookie
acl authelia_authenticated req.cook(authelia_session) -m found
# 如果未认证，重定向到Authelia登录，登录后跳回原地址
redirect location https://auth.yourdomain.com/api/verify?rd=https://%[req.hdr(host)]%[req.url] if host_hedgedoc !authelia_authenticated
# 认证通过后，转发到Hedgedoc后端
use_backend hedgedoc_backend if host_hedgedoc authelia_authenticated

整个认证流程的逻辑拆解（不用图也能懂）

用户访问https://docs.yourdomain.com，请求打到HAProxy
HAProxy检查请求里有没有authelia_session的有效Cookie：
- 有Cookie且有效：直接把请求转发到Hedgedoc后端，用户正常使用服务
- 没有Cookie/ Cookie失效：自动重定向到https://auth.yourdomain.com/api/verify?rd=原请求地址
用户被带到Authelia的登录页面，输入账号密码（开了两步验证的话还要输验证码）
登录成功后，Authelia给浏览器设置authelia_sessionCookie，然后自动跳回用户原来要访问的docs.yourdomain.com
再次访问时，HAProxy检测到有效Cookie，直接放行到后端服务，不会再跳登录