Authelia：开源认证授权与单点登录服务部署与使用指南

一、项目官方信息

Authelia 是一个开源的认证与授权服务器，通过一个 Web 门户为你的应用提供双因素认证（2FA）与单点登录（SSO）。它本身不直接对外暴露业务，而是作为反向代理（reverse proxy）的“搭档”存在：由代理把未通过认证的请求放行、拒绝或重定向到 Authelia 的登录门户。官方 README 明确说明它与 nginx、Traefik、Caddy、Skipper、Envoy、HAProxy 等代理配合使用。

它的核心能力包括：OpenID Connect 1.0 / OAuth 2.0 身份提供（已通过 OpenID Certified™ 认证）、基于 FIDO2 / WebAuthn 的安全密钥（如 YubiKey）、TOTP 动态口令、Duo 移动推送、Passkey 无密码登录、基于邮件确认的密码找回、失败次数锁定，以及按子域名 / 用户 / 用户组 / 请求 URI / 请求方法 / 网络进行细粒度访问控制。高可用场景可使用远程数据库加 Redis 作为 KV 存储。

二、官方图片

下面是 Authelia 官方 README 与文档站提供的架构图与门户截图。

整体架构：反向代理在前，Authelia 作为认证决策点，对每个请求进行放行、拒绝或重定向。

Authelia 的登录门户（浅色主题），用户在此完成主密码登录与二次验证。

支持的二次验证方式：安全密钥（WebAuthn）、TOTP、移动推送等。

三、环境要求

根据官方 README，Authelia 支持多种安装形态，推荐使用容器方式部署：

• 操作系统：任意可运行 Docker 的 Linux 发行版（Debian / Ubuntu / Rocky / Arch 等）。
• Docker 引擎 20.10+ 与 Docker Compose v2（docker compose 插件）。
• 已安装并运行至少一个反向代理（nginx / Traefik / Caddy 等），Authelia 监听在内部网络，由代理反向代理到它。
• 端口规划：Authelia Web 服务默认监听 9091；对外门户通常是 https://auth.你的域名，由反代转发到容器的 9091。
• 资源建议：CPU 1 核、内存 512MB 以上即可起步；若启用 Redis / 数据库做高可用，再相应准备。
• 网络：对外部署时需通过 Let's Encrypt 等签发合法证书；官方提供的 Lite compose 示例即面向公网、用文件存储用户 + SQLite 配置存储，适合小规模；Local 示例面向内网自签名测试。

四、完整部署步骤

下面以官方推荐的 Docker Compose 方式为例，从零部署一个可对外访问的 Authelia 实例，并以 nginx 作为反向代理。

1. 创建工作目录

mkdir -p /opt/authelia/config /opt/authelia/data
cd /opt/authelia

目录用途：config/ 放配置文件与用户库，data/ 放运行时数据（SQLite 等）。

2. 编写配置文件 config/configuration.yml

Authelia 用一个 YAML 文件描述全部行为。最关键的是服务监听地址、会话密钥、认证后端与访问控制。下面是一份可直接启动的最小配置：

server:
  host: 0.0.0.0
  port: 9091

log:
  level: info

# 会话加密密钥，务必用随机长串替换；可用 authelia 容器生成：
# docker run --rm authelia/authelia:latest authelia generate encryption-key
jwt_secret: 请替换为一段足够长的随机字符串
session:
  secret: 请替换为另一段足够长的随机字符串
  # 对外域名示例，按你的实际主域名修改
  domain: 你的域名.example.com

# 认证后端：最小化方案用文件用户库
authentication_backend:
  file:
    path: /config/users_database.yml
    watch: true

# 初始主题与通信
totp:
  issuer: authelia

# 访问控制规则：默认两因子，登录门户本身放行
access_control:
  default_policy: two_factor
  rules:
    - domain: auth.你的域名.example.com
      policy: bypass

要点说明：

• server.port: 9091 是 Authelia 内置 Web 服务端口，与官方约定一致。
• jwt_secret 与 session.secret 必须是随机长串，泄露会导致会话可伪造，建议用 authelia generate encryption-key 生成。
• authentication_backend.file.path 指向用户库文件；这是官方 Lite 示例采用的文件存储方式。
• access_control.default_policy 可选 one_factor（仅密码）或 two_factor（密码 + 2FA）；登录门户所在域名设为 bypass 才能打开登录页。

3. 编写用户库 config/users_database.yml

文件用户库记录用户名、密码哈希与邮箱。密码需用 bcrypt 哈希，不要填明文。生成哈希的命令：

docker run --rm authelia/authelia:latest authelia crypto hash generate bcrypt --password '你的登录密码'

把输出的 $2a$... 哈希填进用户库：

users:
  用户名:
    displayname: 管理员
    password: $2a$12$把上面命令输出的bcrypt哈希贴到这里
    email: you@example.com
    groups:
      - admins
      - dev

4. 编写 docker-compose.yml

services:
  authelia:
    image: authelia/authelia:latest
    container_name: authelia
    restart: unless-stopped
    volumes:
      - ./config:/config
      - ./data:/data
    ports:
      - "9091:9091"
    environment:
      - TZ=Asia/Shanghai

说明：官方 README 建议固定版本标签而非使用 latest，因为项目仍在活跃开发中、可能出现破坏性变更，升级前应阅读 Releases 说明。生产环境请把 :latest 替换为具体版本号。

5. 启动并查看日志

docker compose up -d
docker compose logs -f authelia

启动后，日志中应看到服务监听在 0.0.0.0:9091，没有配置校验错误。

6. 配置反向代理（以 nginx 为例）

Authelia 不直接面向公网，需要由 nginx 反代。Authelia 门户站点 auth.你的域名.example.com 的最小 nginx 配置：

server {
    listen 443 ssl;
    server_name auth.你的域名.example.com;

    ssl_certificate     /etc/nginx/ssl/你的域名.crt;
    ssl_certificate_key /etc/nginx/ssl/你的域名.key;

    location / {
        proxy_pass http://127.0.0.1:9091;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

重启 nginx 使配置生效：

nginx -t && systemctl reload nginx

7. 验证部署

• 浏览器访问 https://auth.你的域名.example.com，应出现 Authelia 登录门户。
• 用第 3 步创建的用户名密码登录。
• 首次登录会引导你绑定 TOTP（扫码到 Authenticator App），绑定后进入主界面。
• 若配置了某个受保护站点的 auth_request / forward_auth，访问该站点时会被重定向到 Authelia 完成认证，认证通过后再跳回业务站点。

五、使用方法

• 登录门户：所有认证都收敛到 auth.你的域名 这个 Web 门户，支持密码 + 2FA 两步登录。
• 绑定二次验证：首次登录按引导扫码绑定 TOTP；在设置里可后续添加安全密钥（FIDO2/WebAuthn，如 YubiKey）或 Duo 推送。
• 保护业务站点：在 nginx 中通过 auth_request 指向 Authelia 的 /api/verify，即可把未登录请求重定向到门户；Traefik 用 forwardAuth 中间件，Caddy 用 forward_auth 指令，均为官方开箱支持。
• 访问策略：在 access_control.rules 中按域名 / 用户组设定 bypass / one_factor / two_factor，例如对后台管理要求两因子、对公开文档站放行。
• 密码找回：配置 SMTP 后，用户可通过邮件确认身份重置密码（README 功能列表中明确支持）。
• 高可用扩展：官方说明可用远程数据库 + Redis 作为高可用 KV 存储，多实例横向扩展；小规模场景先用文件 + SQLite 的 Lite 形态即可。

六、常见问题 FAQ

1. 访问登录门户直接 401 / 一直跳回登录页？ 多半是 access_control 没有把门户自身域名设为 bypass，或者 session.domain 配置的主域名与实际域名不一致，导致 Cookie 无法写入。检查 configuration.yml 中的域名与规则。

2. 启动即退出，日志报配置校验失败？ Authelia 启动时会严格校验配置。常见原因是 jwt_secret / session.secret 太短或为空、用户库里密码不是 bcrypt 哈希、YAML 缩进错误。按 docker compose logs 里的行号修正。

3. 密码填了明文也能登录吗？ 不能。users_database.yml 里的 password 必须是 bcrypt 哈希。请用 authelia crypto hash generate bcrypt 生成，不要手写明文。

4. 为什么建议固定版本而不是用 latest？ README 明确说明 Authelia 仍在活跃开发，会出现破坏性变更。使用 latest 自动升级可能在某次重启后配置不再兼容。生产请固定版本号，升级前阅读 Release Notes。

5. TOTP 扫码后时间对不上？ TOTP 基于时间同步，容器与宿主机器时间偏差过大会导致动态口令校验失败。执行 timedatectl 检查时区与 NTP，确保容器与宿主机时间准确（本教程 compose 中已设 TZ=Asia/Shanghai）。

6. Authelia 能不能直接暴露到公网？ README 强调 Authelia 本身不应直接暴露，真正面向公网的是反向代理；Authelia 是内部安全控制面，应放在代理之后的内网，只通过代理访问。

七、跳转链接

• GitHub 仓库：https://github.com/authelia/authelia
• 官方文档：https://www.authelia.com/
• Release 说明（升级前必读）：https://github.com/authelia/authelia/releases