Authelia Docker 部署：初始配置、密钥和权限边界

来源与维护方：Authelia 项目。本文将官方 Get started 与 Docker 两篇指南合并翻译整理；两页标注的最后更新日均为 2026-09-25，本文核对于 2026-10-05。原页未见可确认的个人作者署名。以下示例仅经静态审查，本次没有启动容器、改动主机、发送邮件或验证登录。

Authelia 的部署并没有一份适合所有架构的通用配置。官方入门指南按“先确定 HTTPS 和认证方式，再完成配置，最后部署并接入代理”的顺序组织内容。Docker 解决的是进程如何运行，认证后端、会话、存储、访问控制与代理信任关系仍然需要你自己配置。

Authelia 部署中需要分别配置的通信与数据边界。编者依据官方文档自绘，非部署截图。

先满足 HTTPS 与代理头要求

Authelia 对外提供的门户必须使用 https，测试环境也不例外。官方将这一点作为有意的安全设计：既让通信加密，也减少不安全模式带来的复杂性。为 Authelia 配置的反向代理必须提供官方要求的请求头；如果还使用代理授权接口，则要采用所选代理集成方式要求的全部头字段。

转发认证（Forwarded Authentication）是逐请求进行的授权检查：代理把请求元数据与会话 Cookie 交给认证流程，根据结果决定是否将用户转向认证门户。因为这种方式依赖 Cookie，受它保护的所有应用与域名也必须使用安全协议；普通 HTTP 对应 https，WebSocket 对应 wss。

如果使用 OpenID Connect 1.0，除 Authelia 自身的 HTTPS 要求外，还须遵守有关协议规范，但入门页没有额外要求把转发认证模式的全部条件强套到 OIDC 客户端。应先确定应用采用哪种集成方式，再阅读对应的代理或 OIDC 文档。代理接入时尤其需要看代理集成说明和 Forwarded Headers，确保不让不可信客户端伪造的头字段直接成为认证依据。

官方网页的“Documentation Variables”工具可以在浏览器里替换文档中的主机、端口、TLS、域名和 Authelia 子域名等示例值，并展示对应的公开 URL 与监听地址。其配置存储在浏览器本地，不随请求上传。它只方便阅读示例，不会替你修改服务器配置；本译稿是静态正文，不包含该网页脚本。

在启动前完成静态配置

Authelia 使用静态配置文件，而不是通过网页管理界面完成初始配置。可以从 GitHub 上的 config.template.yml起步；首次启动时 Authelia 也会写出与自身版本对应的模板。不要把动态的 master 分支模板直接当成任何旧镜像都接受的配置，优先使用锁定版本对应的模板。

初始配置至少涉及以下六个部分：

密码重置 JWT 密钥。启用重置密码流程时，jwt_secret 用于签署身份验证邮件。Docker 示例通过 AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE 指向相应密钥文件。
认证后端。authentication_backend 必须在 LDAP 与 YAML 用户文件之间选择一种适合环境的后端，用户依靠它完成认证。一个能打开的门户不代表它已经拥有可用用户来源。
SQL 存储。storage 要选择 SQL 存储提供方。官方建议测试和轻量部署使用 SQLite3，其他生产部署优先考虑 PostgreSQL。数据文件或外部数据库都需要持久化和备份。
会话。session.cookies 要列出需要保护的 SSO 域名；这些域名之间不能有互为后缀的配置。重点核对 domain 与 authelia_url。会话 secret 很重要，生产环境推荐 Redis。
通知。notifier 用于发送二次认证注册等邮件。可以选择本地文件投递或 SMTP，但只能配置其中一种；生产推荐 SMTP。
访问控制。access_control 在初次调通时可先用简单策略，之后必须按实际需求细化。

原文的最小访问策略如下：

access_control:
  default_policy: deny
  rules:
    - domain: '*.example.com'
      policy: one_factor

它表示默认拒绝，并为指定通配域名启用单因素策略。example.com 必须换成实际域名；这段规则既不是完整配置，也不是生产系统的默认安全答案。需要两步认证的应用应配置对应策略，公开应用的绕过范围也要明确。

选择镜像与容器身份

官方容器镜像提供以下名称：authelia/authelia、docker.io/authelia/authelia 和 ghcr.io/authelia/authelia。原文 Compose 示例使用 :latest，这是会随时间移动的标签。本文下方仍展示原文结构，同时要求实际部署前换成经过确认的版本标签或镜像摘要，以便升级、回滚和配置模板都对应同一个版本。

容器专用的环境变量与 Authelia 守护进程的配置变量不是同一回事：

变量	默认值	作用
`PUID`	0	容器以 UID 0 启动时，由入口程序降权到指定 UID。
`PGID`	0	容器以 UID 0 启动时，由入口程序切换到指定 GID。
`UMASK`	未设置	设置后，入口程序执行相应 `umask` 来控制新文件默认权限。

官方首推由 Docker 直接指定容器用户。这样入口程序与服务进程从开始就没有容器内 root 身份；代价是你要预先把配置、密钥和需要写入的位置的文件权限设好。Compose 中可以通过 user: '1000:1000' 表达这类选择，但数字必须匹配自己的主机权限设计，不能机械照抄。

第二种方式是设置 PUID／PGID。它的优点是入口程序可以自动处理有关目录的所有权和权限，缺点是入口程序仍会先以 root 运行。把 PUID 改成非零值，不等于容器的整个生命周期都没有 root 阶段。第三种方式是 Docker user namespace；官方将这种架构的具体配置列为本文档和支持范围之外。

独立 Compose 示例的前提

独立示例只运行 Authelia，不附带数据库、代理或被保护应用。采用它之前，应准备好 data/authelia/config/configuration.yml、PostgreSQL 服务，以及一个名为 net 的外部 bridge 网络。示例写了 external: true，意味着 Compose 不会负责创建该网络。

密钥目录 data/authelia/secrets/ 中需放入四个文件：JWT_SECRET、SESSION_SECRET、STORAGE_PASSWORD 和 STORAGE_ENCRYPTION_KEY。它们分别对应重置密码 JWT、会话秘密、PostgreSQL 密码和存储加密密钥。秘密文件的内容应是实际密钥值，不能填入示例字符串或把四个用途混用同一秘密。数据库备份与存储加密密钥应一并规划；只有数据库副本、却丢失解密密钥，不能视为完整恢复方案。

通过 Compose secrets 提供秘密

下面保留官方的 secrets 映射和变量名，并作了三项明确修改：把可变的 latest 改为要求调用者显式设置的 AUTHELIA_IMAGE，加入显式 UID／GID 占位配置，路径用 Compose 文件相对路径替代依赖 Shell 的 ${PWD}。这仍然是需要配套配置文件、数据库和网络的模板。

secrets:
  JWT_SECRET:
    file: './data/authelia/secrets/JWT_SECRET'
  SESSION_SECRET:
    file: './data/authelia/secrets/SESSION_SECRET'
  STORAGE_PASSWORD:
    file: './data/authelia/secrets/STORAGE_PASSWORD'
  STORAGE_ENCRYPTION_KEY:
    file: './data/authelia/secrets/STORAGE_ENCRYPTION_KEY'

services:
  authelia:
    container_name: 'authelia'
    image: '${AUTHELIA_IMAGE:?set a pinned Authelia image}'
    user: '${AUTHELIA_UID:?set UID}:${AUTHELIA_GID:?set GID}'
    restart: 'unless-stopped'
    networks:
      net:
        aliases: []
    secrets:
      - JWT_SECRET
      - SESSION_SECRET
      - STORAGE_PASSWORD
      - STORAGE_ENCRYPTION_KEY
    environment:
      AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE: '/run/secrets/JWT_SECRET'
      AUTHELIA_SESSION_SECRET_FILE: '/run/secrets/SESSION_SECRET'
      AUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE: '/run/secrets/STORAGE_PASSWORD'
      AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE: '/run/secrets/STORAGE_ENCRYPTION_KEY'
    volumes:
      - './data/authelia/config:/config'

networks:
  net:
    external: true
    name: 'net'

_FILE 变量保存的是容器内文件路径，而非秘密本身。Compose secrets 也不意味着主机上的源文件自动获得加密保护；主机文件权限、备份权限与 Docker 管理权限仍需控制。以非 root 用户运行时，必须确认该用户能读取挂载后的文件。

/config 在原文中是可写目录，本文保持这一点，因为模板首次生成、本地数据库或文件通知等使用方式可能需要写入。若已将所有可写数据分离、配置不会在运行时生成，可以再按自己的配置设计只读挂载；不能未经分析就把整目录设为只读并承诺可运行。

通过目录或卷挂载秘密

如果不用 Compose secrets，可将秘密目录挂到 /secrets。配置结构仍与前面的独立示例相同，只需移除 services 下的 secrets 列表和顶层 secrets 定义，改用以下环境变量与卷。本文给秘密目录增加了 :ro，这是对原文可写绑定挂载的收紧：

environment:
  AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE: '/secrets/JWT_SECRET'
  AUTHELIA_SESSION_SECRET_FILE: '/secrets/SESSION_SECRET'
  AUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE: '/secrets/STORAGE_PASSWORD'
  AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE: '/secrets/STORAGE_ENCRYPTION_KEY'
volumes:
  - './data/authelia/config:/config'
  - './data/authelia/secrets:/secrets:ro'

普通命名卷也能承载秘密，但其初始化和权限仍需自行处理。不要在工单、日志或文章里输出真实秘密来证明“配置正确”。本文没有提供实际生产密钥。

用演示包理解认证流程

官方还提供 lite 与 local 两组 Compose 示例，适合在 Linux 桌面环境体验。先克隆官方仓库并切换到已确认的发布标签。原文自动查找“最新标签”的 Shell 嵌套命令会随仓库状态变化；这里改成显式标签占位，便于复核和重现：

git clone https://github.com/authelia/authelia.git
cd authelia
# 把下列占位内容换成已确认的发布标签，再执行。
# git checkout <release-tag>

克隆会下载文件，checkout 会改变工作树；应使用专门的演示目录。上面注释行是说明，不是可直接运行的标签。

lite：配置自己的域名和 SMTP

进入 examples/compose/lite。
编辑 users_database.yml。原始用户为 authelia，默认密码也是 authelia。应生成新密码哈希，并按需要改变用户名；默认凭据仅用于演示，不能发布到可被他人访问的环境。
修改 configuration.yml 与 compose.yml 中的域名和全部秘密。
在 configuration.yml 中配置 SMTP 服务。
核对完成后，原文用 docker compose up -d 启动。

启动会拉取镜像、创建容器及相关资源，是实际部署操作。本次只审查了文档，没有执行它。

local：理解绕过、单因素和双因素差异

原文进入 examples/compose/local 后运行 ./setup.sh。该脚本会用 sudo 修改 /etc/hosts。读者应先审查脚本和要写入的域名映射，备份相关配置，并清楚演示结束后的恢复方式；不能把它当成纯只读检查。

完成设置后，example.com 会被替换为所选域名，三个示例地址展示不同策略：

https://public.example.com：绕过 Authelia。
https://traefik.example.com：由 Authelia 的单因素认证保护。
https://secure.example.com：由双因素认证保护。

演示使用自签名证书，访问每个域名时需要按演示说明信任它。此做法仅是本地体验的一部分，不能用于教读者忽略未知站点的证书错误。进入双因素示例时，还需注册第二因素设备，再通过邮件中的链接确认。由于演示使用虚构邮箱，邮件会落在 ./authelia/notification.txt。

原文提供的 grep 命令把路径写成了 notification.txt.，末尾多出一个句点，且匹配表达式依赖引号与空格。本文不原样推荐执行；更直接的只读检查方式是打开实际文件：

cat ./authelia/notification.txt

这是对原文提取链接命令的替换。通知里可能含身份验证链接，应仅在本人演示环境查看，勿复制到公开日志。

代理在主机上运行时，只开放需要的端口

如果反向代理是主机上的 systemd 服务而不是同一 Docker 网络中的容器，可在 Authelia 服务下增加：

ports:
  - '127.0.0.1:9091:9091'

这样主机代理可以通过回环地址的 9091 端口访问容器。该映射只是主机到容器的通信入口，不能代替对外 HTTPS 代理配置。若把 127.0.0.1 去掉，监听范围可能扩大；应按实际网络边界调整，不要为了“连得上”而无条件发布到所有接口。原文也说明，这类组合架构属于 Docker 网络设计的一部分，项目无法替每一种部署方式给出完整支持。

日志不足时，临时改成交互式排障

官方排障方案假定容器名为 authelia，基本 Compose 文件名为 compose.yml。新增 compose.debug.yml：

services:
  authelia:
    healthcheck:
      disable: true
    environment:
      AUTHELIA_LOG_LEVEL: 'trace'
    command: 'sleep 3300'

先用两份文件启动合成配置，然后进入容器手动启动 Authelia：

docker compose -f compose.yml -f compose.debug.yml up -d
docker exec -it authelia sh
authelia

sleep 3300 让容器暂时保持运行，方便交互排查；它没有在正常提供认证服务。覆盖配置关闭了健康检查并启用 trace 日志，可能增加请求上下文的暴露，也可能中断正常认证。应在维护窗口或隔离环境使用，并在排障后恢复正常命令、健康检查与日志级别。不能把这份 debug 文件长期当作生产部署参数。

从能登录走向可维护的部署

Get started 最后强调五件事：把秘密从普通配置中移出并交给秘密机制；理解访问控制并按需求细化；阅读安全措施与威胁模型；复核转发头的可信边界；再检查其他配置选项。本文另外把版本锁定、持久化与恢复纳入同一部署脉络：镜像、配置模板和代理集成应匹配，数据库、加密密钥与必要配置都要能恢复，通知渠道也必须可靠。

默认接入方式仍是反向代理集成，应查阅所用代理的专门文档；若部署到 Kubernetes，原文建议先看专门的 Kubernetes 文档。其他问题可从官方 FAQ 继续查找。这两篇指南给出的是初始路径，不包含每一种代理、LDAP、SMTP 或数据库的完整配置。本文没有把“容器启动”写成“认证和授权已验证”，也没有在未运行的情况下声称生产可用。

文章版权归作者所有，未经允许请勿转载。

THE END