Authelia 4.39 介绍与选型指南

目标：说清 Authelia 是什么、解决什么问题、能力边界在哪，并给出与 Keycloak、Authentik 等同类方案的量化选型对比；本篇为认知篇，关键论断均实查自官方发布页与文档站，查询日期 2026-10-18，不做本地安装实测（部署实测见 《Authelia Docker Compose 部署指南》）。

一、环境信息

本篇是认知与选型篇，不涉及本地安装与实测，所有版本、活跃度数据均以官方渠道为准。为便于复查与后续更新，先把本篇的信息基准列清楚：

• 信息基准（查询日期）：2026-10-18
• 版本依据：GitHub Releases（authelia/authelia）最新稳定版 v4.39.28，发布于 2026-09-17，非预发布（prerelease: false）
• 本地复核依据：GitHub Releases 发布清单与官方文档确认本次介绍版本为 v4.39.28（复核入口：Releases 页面 tag 列表，prerelease 标记为 false）
• 官方来源清单：
  • 官网与文档站：https://www.authelia.com/
  • GitHub 仓库：https://github.com/authelia/authelia
  • 发布页：https://github.com/authelia/authelia/releases
  • 集成参考（Nginx auth_request）：https://www.authelia.com/integration/proxies/nginx/
  • 许可证：https://github.com/authelia/authelia/blob/master/LICENSE（Apache License 2.0）
• 对比对象版本依据（同为 2026-10-18 实查）：
  • Keycloak 最新稳定版 26.8.1（https://github.com/keycloak/keycloak/releases）
  • Authentik 最新稳定版 2026.8.4（https://github.com/goauthentik/authentik/releases）

💡 说明：Authelia 版本号形如 4.39.28，含义为「主版本.特性版本.补丁版本」。选型与部署时锁定到特性版本系列（如 4.39）即可，补丁版本按需跟进安全修复。

二、软件概述

Authelia 是一个开源的认证与授权服务器（Authentication & Authorization Server），可以理解为「给反向代理配套的统一登录门户 + 多因子认证网关」。它由澳大利亚开发者与社区团队维护，使用 Go 语言编写，编译产物是单个静态链接的二进制（官方同时提供多架构发布包与官方站点安装方式），资源占用低、无外部运行时依赖，这是它与 Java 系身份产品最直观的差异。

本篇介绍的版本为 v4.39.28（2026-09-17 发布），属于 4.39 特性系列。该系列是 2025 年下半年起的主线稳定系列，4.38/4.39 引入了多项重要变化：多域名会话配置（session.cookies 列表）、服务端监听地址新格式（server.address: tcp://...）、身份验证安全强化（elevated session 一次性码机制），以及 /api/verify 之外全新的 authz 端点体系。

核心事实速览（均实查自官方源）：

表格解读：Authelia 的关键差异点在「轻」——单二进制 + 可选 SQLite/文件后端即可跑起来，最小部署不依赖任何外部数据库；但它也不是「玩具」，Redis、MySQL、PostgreSQL、LDAP、OIDC 这些生产级扩展点全部具备。是否适合你，取决于第六、七节列出的能力边界。

三、核心架构

理解 Authelia 的架构，关键是理解它在整个 Web 体系中的位置：它不在应用进程内做认证，而是站在反向代理这一层，替所有后端应用把关。

3.1 组件构成

Authelia 本体是一个单体服务，内部包含四类可配置的子系统，每个子系统都有可替换的实现：

表格解读：四个子系统都是「最小可用 + 生产可扩展」的设计。最小部署可以用文件用户库 + 内存会话 + SQLite + 文件通知，零外部依赖；生产部署则逐项替换为 LDAP + Redis + PostgreSQL + SMTP，配置文件结构不变，只换键值。

💡 技术拓展：会话存储的「内存 vs Redis」不止是容量问题，涉及高可用语义——内存会话随进程重启全部失效，且无法多实例共享；Redis 会话可在 Authelia 重启后保持登录态，并支持多实例共享会话。常见选项对比：

会话存储	原理/特点	适用场景
内存	存进程内，重启即失，零依赖	单实例、测试环境
Redis 单机	外部缓存服务，重启 Authelia 会话不丢	单实例生产、小规模
Redis Cluster / Sentinel	分片或主从高可用的分布式会话	多实例 Authelia、高可用

本组件文档体系的部署篇实际采用「SQLite + 内存会话」的最小形态起步（便于从 0 到 1 复现），并在运维篇说明升级到 Redis 的路径。

3.2 认证数据流（auth_request / ForwardAuth 模式）

这是 Authelia 最主流的工作模式，以 Nginx 为例（Traefik/Caddy 的 ForwardAuth 同理）：

1. 用户请求 https://app.example.com/，先到达反向代理；
2. 反向代理发起一个内部子请求到 Authelia 的校验端点（Nginx 用 auth_request 指令调 /api/verify），把原始 URL、方法、Cookie 等信息经请求头透传；
3. Authelia 校验会话 cookie 与访问控制规则：
   • 未认证 → 返回 401，反向代理将其转换为 302 跳转到 Authelia 登录页（带 ?rd= 回跳地址）；
   • 已认证且策略允许 → 返回 200，并附带 Remote-User、Remote-Groups、Remote-Email 等身份头；
4. 反向代理把请求转发给真正的后端应用，同时把身份头注入上游请求，后端应用直接信任这些头即可拿到「当前用户是谁」。

这套模式的直接收益是：存量应用零改造接入 SSO——无论后端是静态站点、自研服务还是第三方面板，只要前面有反向代理，就统一被 Authelia 保护。上述数据流在本组件文档体系的部署篇中已用真实命令逐环节实测（未登录 302 → 登录接口返回会话 cookie → 带 cookie 请求返回 200），完整命令与回显见《Authelia Docker Compose 部署指南》。

3.3 OIDC 提供方模式（可选角色）

除反向代理模式外，Authelia 还可以作为一个 OIDC 1.0 Provider（IdP）：支持标准授权码流程、PKCE、客户端凭据等，配置在 identity_providers.oidc 段。适合「应用不支持头注入、只认 OIDC」的场景。需要注意它与 Keycloak 这类「全功能 IdP」的差异：Authelia 的 OIDC 客户端在配置文件中静态声明，没有独立的管理控制台，客户端规模大时运维成本上升——这是选型时的重要权衡点（见第七节）。

3.4 访问控制模型

认证（你是谁）之后是授权（你能访问什么）。Authelia 的授权由 access_control 规则引擎承担，规则要素包括：

• 匹配维度：域名、路径（支持正则）、用户、用户组、请求方法、来源网段（IP/CIDR）、时间段；
• 策略取值：bypass（完全放行）、one_factor（登录一次即可）、two_factor（必须完成二因子）、deny（拒绝）；
• 生效顺序：按规则声明顺序自上而下匹配，未命中任何规则时落到 default_policy。

这套规则语言的完整语法与逐项实测（含 two_factor 策略下仅完成一因子时被拒绝的行为验证）见《Authelia 4.39 配置参数详解》。

四、功能特性

本节逐项列出 4.39 系列的功能面，均以官方文档（查询日期 2026-10-18）为依据。

4.1 认证能力

• 一因子认证（1FA）：用户名 + 密码；密码哈希支持 argon2、scrypt、pbkdf2、bcrypt、sha2crypt 等（官方 authelia crypto hash generate 子命令可生成全部主流格式的哈希）；
• 二因子认证（2FA）：
  • TOTP：时间型一次性码，兼容主流验证器应用（Google Authenticator、Aegis 等）；
  • WebAuthn / Passkey：支持安全密钥与平台认证器（指纹/Face ID），4.39 已支持 passkey 登录；
  • Duo Push：对接 Duo 安全服务的推送认证；
• 会话安全：单次登录签发的 cookie 默认 HttpOnly + Secure + SameSite=Lax，支持可配置的不活跃超时（inactivity）与绝对有效期（expiration）；
• 身份验证强化（4.38+）：修改安全设置（如注册 2FA 设备）前需要通过一次性验证码完成会话提权（elevated session），验证码经 SMTP 或文件系统通知送达。

4.2 授权与防护

• 细粒度访问控制：域名/路径/用户/组/方法/网段/时间的规则组合（见 3.4）；
• 防暴力破解（regulation）：在限定时间窗内失败次数达到阈值即封禁来源，封禁记录持久化到存储后端；
• 密码策略：可配置长度、字符类、_entropy（信息熵）门槛，并可启用内置弱口令字典校验（对 zxcvbn 类启发式评分的支持见官方 password policy 文档）；
• NTP 时钟校验：启动时校验本机与 NTP 源的偏移，防止 TOTP 因时钟漂移失效。

4.3 集成能力

• 反向代理集成：官方提供 Nginx（auth_request）、Traefik（ForwardAuth）、Caddy（forward_auth）、HAProxy、Envoy、Skipper 等一整套现成配置（https://www.authelia.com/integration/proxies/）；
• OIDC 1.0 Provider：标准授权码 + PKCE，可对接 Grafana、GitLab、Nextcloud 等 OIDC 客户端；
• 可观测性：结构化日志（可调级别）、Prometheus 指标端点（telemetry.metrics）。

4.4 运维能力

• 配置校验：authelia validate-config 子命令可在启动前验证配置文件；
• 密码哈希工具：authelia crypto hash generate <算法> 直接产出可写入用户文件的哈希串；
• 存储迁移：内置 schema 版本迁移（首次启动自动建表，如 SQLite 从版本 0 迁移到 29 的实测日志见部署篇）；
• 单二进制/多架构：除 x86_64 外官方发布 ARM 架构，可在低功耗设备上运行。

五、快速上手（引自官方文档的最小示例）

本节示例引自官方文档 Get Started 页（来源：https://www.authelia.com/configuration/prologue/get-started/ ，查询日期 2026-10-18），仅展示「让 Authelia 跑起来」所需的最小配置骨架，帮助建立直观认知；完整可落地的部署过程（含 TLS、自签证书、端到端验证与真实回显）见《Authelia Docker Compose 部署指南》。

官方最小配置涉及三个文件骨架：

其一，主配置 configuration.yml（节选官方示例结构）：

server:
  address: 'tcp://:9091/'

session:
  cookies:
    - domain: 'example.com'
      authelia_url: 'https://auth.example.com'

storage:
  local:
    path: '/config/db.sqlite3'

access_control:
  default_policy: 'two_factor'
  rules:
    - domain: 'public.example.com'
      policy: 'bypass'

identity_validation:
  reset_password:
    jwt_secret: 'a_staging_secret_of_at_least_20_chars'

其二，用户文件 users.yml（官方示例结构）：

users:
  authelia:
    displayname: 'Authelia Admin'
    password: '$argon2id$v=19$m=65536,t=3,p=4$...'  # 由 authelia crypto hash generate argon2 生成
    email: 'authelia@example.com'
    groups:
      - 'admins'
      - 'dev'

其三，反向代理侧注入认证（以 Nginx 为例的官方集成要点）：在受保护站点的 server 块中声明一个 internal 的子请求位置指向 /api/verify，并在主 location 中启用 auth_request，未认证时用 error_page 401 =302 跳转登录页。

💡 说明：users.yml 中的密码哈希必须用官方工具生成，不要手写。官方命令形态为 authelia crypto hash generate argon2 --password '你的密码'，输出形如 $argon2id$v=19$m=65536,t=3,p=4$... 的完整哈希串（本组件部署篇有该命令的真实执行回显）。官方示例中的 jwt_secret 仅为演示占位，生产环境应使用高强度随机值并通过环境变量注入，切勿把密钥明文写进配置文件入库。

快速上手要点：Authelia 的上手路径是「三个文件 + 一个反代」，真正需要花时间理解的是 configuration.yml（参数极多，建议配合《Authelia 4.39 配置参数详解》逐段消化）与反向代理的集成姿势。

六、适用场景与限制

6.1 典型适用场景

1. 自托管服务群的统一登录：内网/公网自建了十几个 Web 服务（Grafana、代码托管、下载站、路由器面板……），希望「一次登录，处处通行」，且不想在每个应用里各配一套用户体系——这是 Authelia 最经典的场景；
2. 给无认证能力的应用补 2FA：老应用或第三方发布的软件包不支持双因子，在反代层加 Authelia 后整站强制 2FA；
3. HTTP API 的轻量门禁：对内部 API 网关加一层会话/Basic 校验，用 access_control 网段规则做白名单；
4. 小团队的轻量 IdP：需要 OIDC 但不想为几个客户端部署一套 Keycloak 的小规模场景。

6.2 能力边界与限制

• 不是完整 IAM：没有用户自助注册、组织架构、用户生命周期管理（入职/离职流程）、审批工作流；用户来源只有「YAML 文件」或「外部 LDAP」两种——没有 LDAP 就得手编 YAML，用户多时维护成本高；
• 管理界面缺失：用户、OIDC 客户端、访问规则全部通过配置文件管理，改配置需重载服务；对「想要点鼠标管用户」的团队不友好；
• 依赖反向代理：主流用法必须与 Nginx/Traefik/Caddy 等配合，没有反代的单体应用接入需要额外搭建；
• 多实例部署有前提：横向扩容必须把会话迁到 Redis、存储迁到 MySQL/PostgreSQL，且 OIDC 部分（4.39）对会话后端有额外要求，不能拿最小配置直接扩。

一句话定位：Authelia 是「反向代理时代的认证门神」，不是「企业级 IAM 平台」。前者它做得极轻极好，后者的需求请看第七节的重型方案。

七、同类选型对比

本节从定位、资源形态、功能矩阵、社区活跃度四个维度做横向对比。所有版本号与 Stars 数据于 2026-10-18 实查自各项目 GitHub 仓库与 Releases 页。

7.1 主流方案对比表

表格解读：第一行「定位」决定了后面的所有差异。Keycloak/Authentik 是「先把用户、应用、策略都管起来」的平台，自带管理控制台与用户目录，代价是 Java/Python 技术栈带来的资源占用与运维复杂度；Authelia/oauth2-proxy 是「站在反代门口的哨兵」，不管理用户生命周期，换来的是单二进制的极简运维。Authelia 与 oauth2-proxy 的关键分野在于前者自带本地用户库 + 2FA + 访问控制规则引擎，而后者必须依赖外部 IdP。

💡 技术拓展：「轻量级身份网关」这一赛道除本表所列外，还有 TinyAuth、Authz 之类的小型项目，它们多数只做 Basic/会话门禁、无 2FA 或 OIDC，社区规模与维护稳定性普遍不及 Authelia，本文不逐一展开；若你的全部需求只是「给一个站点加个密码门」，这类更小的方案也可考虑。

7.2 版本节奏与维护活跃度（量化）

• Authelia：4.39 系列在 2026-04-12（4.39.19）至 2026-09-17（4.39.28）期间连发 9 个补丁版本（GitHub Releases 逐条实查），补丁节奏约每月 1–2 个，主线活跃；
• Keycloak：26.x 系列当前最新 26.8.1，由 Red Hat 主导，发布节奏稳定（约每季度一个特性版本 + 补丁）；
• Authentik：采用日历版本（YYYY.M.P），当前 2026.8.4，由公司（Authentik Security GmbH）主导，节奏快。

7.3 选型建议（如果…则…）

• 如果你的场景是「给一批反代后面的自建服务加统一登录 + 2FA」，且用户量在几十到几百级 → 选 Authelia：零管理界面的运维成本反而最低，资源占用最小，官方反代集成文档覆盖面最全；
• 如果你需要完整的用户生命周期管理（自助注册、找回密码流程、组织架构）、SAML 协议、或者对接大量 OIDC 客户端并希望有管理台 → 选 Keycloak（企业级、协议最全、社区最大）或 Authentik（现代化界面、上手更快）；
• 如果你已经有 IdP，只是想给内网应用加一层 OAuth2 门禁 → oauth2-proxy 足矣，不必引入本地用户库；
• 如果你只想保护单个静态站点 → 甚至反代自带的 Basic Auth 就够了，任何身份网关都是过度设计；
• 资源极度受限的边缘设备（如 ARM 小盒子） → Authelia 的 Go 单二进制在内存与体积上有明显优势。

八、参考链接

• Authelia 官网：https://www.authelia.com/
• GitHub 仓库：https://github.com/authelia/authelia
• 发布页（版本依据）：https://github.com/authelia/authelia/releases
• 配置总览文档：https://www.authelia.com/configuration/prologue/introduction/
• Get Started（第五节示例来源）：https://www.authelia.com/configuration/prologue/get-started/
• Nginx 集成文档（auth_request 模式）：https://www.authelia.com/integration/proxies/nginx/
• 访问控制文档：https://www.authelia.com/configuration/security/access-control/
• 密码策略与哈希算法文档：https://www.authelia.com/configuration/first-factor/file/
• Keycloak Releases（对比版本依据）：https://github.com/keycloak/keycloak/releases
• Authentik Releases（对比版本依据）：https://github.com/goauthentik/authentik/releases

⚠️ 以上全部外部链接与版本数据的查询/核验日期为 2026-10-18，后续版本可能变化，选型前请以官方页面当日数据为准。