Authelia 部署指南：Docker、Kubernetes 与裸机（Bare-Metal）三种部署方式详解

本文以 Authelia 官方部署文档（docs/content/integration/deployment/introduction.md）为骨架，系统讲解 Authelia 的三种主流部署方式：Docker（含 Docker Compose 独立示例与 lite/local 全家桶）、Kubernetes（含 Pod 示例与 RAM 注意事项）、Bare-Metal（systemd 服务单元、APT 仓库、Nix、FreeBSD rc.d）。读完本文，你将掌握 Authelia 各部署方式的适用场景、配置文件挂载、密钥注入（Secrets）、权限上下文、systemd 加固配置等实战要点，并能结合仓库内的真实示例与源码快速完成一套可运行的部署。

部署方式总览

Authelia 以守护进程（daemon）形态运行，官方提供三种主要部署方式：

1. Docker —— 官方推荐的主要交付与部署路径，适合大多数用户；
2. Kubernetes —— 面向容器编排场景的部署方式；
3. Bare-Metal —— 直接在操作系统上运行二进制，需自行托管服务（官方提供 systemd 单元与 FreeBSD rc.d 脚本）。

在正式动手前，官方强烈建议首次部署的用户先阅读 Get started 指南，它涵盖了引导 Authelia 所必需的若干步骤（HTTPS 前提、必需请求头、初始配置项等）。

部署前必须理解的前提

无论选择哪种部署方式，Get started 指南都强调了几条不可妥协的前提，它们直接影响部署架构：

• Authelia 必须通过 https 协议对外服务，这不是可选项，即便是测试环境也一样。这是 Authelia 刻意为之的设计决策，既通过加密通信直接提升安全性，也通过减少复杂度间接降低出错面。
• 代理（Proxy）配置必须携带全部必需请求头，具体清单见 代理集成文档的 Required Headers。
• 若启用 Proxy Authorization，代理还必须包含该实现方式所要求的全部请求头。
• 使用 Forwarded Authentication（按请求授权的简单流程，通过检查请求元数据与会话 Cookie 决定是否转发到认证门户）时，所有被保护的应用程序/域名的通信必须使用安全协议（https 与 wss），因为该流程依赖 Cookie。
• 使用 OpenID Connect 1.0 时，除 Authelia 自身须走 https 外，没有额外要求（以相关规范为准）。

此外，Get started 指南给出了初始配置必须考虑的六个核心配置区（详见 配置文件章节）：

1. jwt_secret —— 用于对重置密码流程的身份验证邮件进行签名（如果启用）；
2. authentication_backend —— 在 LDAP 与 YAML 文件 之间二选一，是用户认证的核心；
3. storage —— 在 SQL 存储提供者中选择：测试与轻量部署推荐 SQLite3，生产环境推荐 PostgreSQL；
4. session —— 会话 Cookie 配置（每个受保护的 SSO 域名都要列出，且不能互为后缀；最关键的是 domain 与 authelia_url），以及最重要的 secret，生产环境推荐使用 Redis；
5. notifier —— 用于发送 2FA 注册邮件等，生产推荐 SMTP，只能配置一种；
6. access_control —— 初始阶段配置一个非常基础策略即可，例如：

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

配置是静态的、不通过 Web GUI 修改。仓库根目录的 config.template.yml 可作为配置基础模板；另一种方式是首次启动 Authelia 时让它自动写出与你版本匹配的模板文件。

方式一：Docker 部署

Docker 是官方主要交付路径，镜像名如下：

• authelia/authelia（Docker Hub）
• docker.io/authelia/authelia
• ghcr.io/authelia/authelia（GitHub Container Registry）

容器专属环境变量

官方容器有一组仅对容器本身生效的环境变量（不影响 Authelia 守护进程本身，本节也不涵盖守护进程的环境变量）：

变量名	默认值	用途
PUID	0	若容器以 UID 0 运行，entrypoint 会通过它降权到该 UID
PGID	0	若容器以 UID 0 运行，entrypoint 会通过它降权到该 GID
UMASK	N/A	若设置，容器通过执行 umask ${UMASK} 以该 UMASK 运行

这些变量的行为可以在仓库根目录的 entrypoint.sh 源码中看到实现：脚本先执行 [ -n "${UMASK}" ] && umask "${UMASK}"；当以非 root 运行时直接 exec authelia "${@}"；当以 root 运行时，会先 chown -R "${PUID}:${PGID}" /config 修正文件系统属主，再通过 su-exec "${PUID}:${PGID}" authelia "${@}" 降权启动进程。

权限上下文（Permission Context）

容器默认以 Docker 守护进程所配置的用户运行，用户可通过三种方式控制：

1. 推荐方式：让 Docker 守护进程以另一个用户运行 Authelia 容器。参见 docker run 或 Docker Compose 文件参考文档。优点是进程永远不会拥有特权访问；缺点是需要手动配置好文件系统权限。
2. 使用上述环境变量。缺点是 entrypoint 本身会以 UID 0（root）运行；优点是容器会自动修正文件系统的属主与权限。
3. 使用 Docker 的 user namespace 重映射。这超出了官方文档与支持范围。

Docker Compose 独立示例（Standalone Example）

官方提供两套可测试或可改造的 Docker Compose 示例：

• 独立示例（仅 Authelia，无捆绑应用/代理）
• Bundle: lite
• Bundle: local

独立示例的前提条件：

• 存在配置文件 data/authelia/config/configuration.yml；
• 目录 data/authelia/secrets/ 存在且包含相关的 secret 文件：
  • JWT_SECRET —— 对应 jwt_secret（见 reset-password 文档）；
  • SESSION_SECRET —— 对应 session secret；
  • STORAGE_PASSWORD —— 对应 PostgreSQL 密码 secret；
  • STORAGE_ENCRYPTION_KEY —— 对应 storage encryption_key secret；
• 使用 PostgreSQL；
• 存在一个名为 net 的外部桥接网络。

方式 A：使用 Docker Secrets

适用于 Swarm 模式的 docker secrets：

---
secrets:
  JWT_SECRET:
    file: '${PWD}/data/authelia/secrets/JWT_SECRET'
  SESSION_SECRET:
    file: '${PWD}/data/authelia/secrets/SESSION_SECRET'
  STORAGE_PASSWORD:
    file: '${PWD}/data/authelia/secrets/STORAGE_PASSWORD'
  STORAGE_ENCRYPTION_KEY:
    file: '${PWD}/data/authelia/secrets/STORAGE_ENCRYPTION_KEY'
services:
  authelia:
    container_name: 'authelia'
    image: 'docker.io/authelia/authelia:latest'
    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:
      - '${PWD}/data/authelia/config:/config'
networks:
  net:
    external: true
    name: 'net'
...

方式 B：使用 Secrets 卷（Volume / Bind Mount）

适用于普通 Docker volume 或 bind mount：

---
services:
  authelia:
    container_name: 'authelia'
    image: 'docker.io/authelia/authelia:latest'
    restart: 'unless-stopped'
    networks:
      net:
        aliases: []
    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:
      - '${PWD}/data/authelia/config:/config'
      - '${PWD}/data/authelia/secrets:/secrets'
networks:
  net:
    external: true
    name: 'net'
...

可以看到两种方式的共同点：所有敏感值均通过 *_FILE 环境变量指向密钥文件，而不是把明文写进配置或环境变量本身。这与 Get started 中“生产环境要把 secret 全部移出配置、移入 secrets”的建议一致。

Bundles 全家桶示例

使用全家桶示例前，建议先在 Linux 桌面克隆仓库并切到最新 release 标签：

git clone https://github.com/authelia/authelia.git
cd authelia
git checkout $(git describe --tags `git rev-list --tags --max-count=1`)

lite 轻量全家桶示例

仓库内的 examples/compose/lite 目录即此示例。按以下步骤使用：

1. 先完成上面 Bundles 小节的克隆操作；
2. 执行 cd examples/compose/lite；
3. 编辑 users_database.yml，修改 authelia 用户的用户名，或按 passwords 指南 生成新密码，或两者都改。默认密码是 authelia；
4. 编辑 configuration.yml 与 compose.yml，填入你自己的域名与密钥；
5. 编辑 configuration.yml 配置 SMTP 服务器；
6. 运行 docker compose up -d。

lite 示例是一个完整的 Traefik + Redis + Authelia + whoami 组合。从其 compose.yml 可以看到完整链路：Traefik 通过 traefik.http.middlewares.authelia.forwardAuth.address: 'http://authelia:9091/api/authz/forward-auth' 将请求转发给 Authelia 做 forward-auth 鉴权，并通过 authResponseHeaders 透传 Remote-User、Remote-Groups、Remote-Name、Remote-Email 等认证结果头；secure.example.com 使用 two_factor 策略、traefik.example.com 使用 one_factor 策略、public.example.com 使用 bypass 策略（见 configuration.yml 的 access_control 段）。

local 本地全家桶示例

仓库内的 examples/compose/local 目录即此示例，包含 Traefik 证书配置与一键初始化脚本。克隆仓库（按 Bundles 小节操作）后在 Linux 桌面运行：

cd examples/compose/local
./setup.sh

该脚本会通过 sudo 修改 /etc/hosts。成功后访问以下 URL 即可看到 Authelia 实际效果（example.com 会替换为你指定的域名）：

• https://public.example.com —— 绕过 Authelia（bypass）
• https://traefik.example.com —— 受 Authelia 单因素认证保护
• https://secure.example.com —— 受 Authelia 双因素认证保护（见下方说明）

访问每个域名时都需要信任自签名证书。访问 https://secure.example.com 时，你需要先注册一个用于第二因素认证的设备，并通过邮件中的链接确认。由于这是演示环境、使用的是假邮箱，邮件内容会存放在 ./authelia/notification.txt，注册后可用如下命令直接抓取确认链接：

grep -Eo '"https://.*" ' ./authelia/notification.txt

FAQ：代理运行在宿主机而非容器内

如果你希望代理以 systemd 服务或其他守护进程方式运行在宿主机，需要调整配置。下面示例在独立示例基础上增加了 ports 选项，使 Docker 宿主上的守护进程能与 Authelia 通信——该示例允许通过 localhost IP 127.0.0.1 的 9091 端口访问 Authelia，请按需调整：

---
services:
  authelia:
    container_name: 'authelia'
    image: 'docker.io/authelia/authelia:latest'
    restart: 'unless-stopped'
    networks:
      net:
        aliases: []
    ports:
      - '127.0.0.1:9091:9091'
...

需要说明的是，该配置主要是 Docker 概念而非 Authelia 特有，官方无法为每一种架构选择提供文档与支持，出现问题时需要自行调研。

FAQ：容器启动问题日志无提示时如何调试

多数情况下日志足以定位问题，但存在少数无法给出有用提示的情况。假设容器名为 authelia、使用的 compose 文件为 compose.yml，先叠加调试用 compose.debug.yml 启动：

docker compose -f compose.yml -f compose.debug.yml up -d

再在容器内以交互方式运行 Authelia：

docker exec -it authelia sh
authelia

配套的 compose.debug.yml 如下（禁用健康检查、开启 trace 级日志、以 sleep 3300 占位防止容器退出，便于进入容器手动调试）：

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

方式二：Kubernetes 部署

在容器编排场景中，Authelia 以 Kubernetes 工作负载方式运行，详见 Kubernetes 介绍文档。该方式同样要求先阅读 Get started 指南。

重要注意事项

External Traffic Policy（外部流量策略）：如果负责把流量送入 Kubernetes Ingress 的 Service 没有把 externalTrafficPolicy 设置为 local（参见 Kubernetes 官方“preserving the client source ip”文档），Authelia（以及所有其他应用）可能收到无效的远端 IP。这会影响基于 IP 的访问控制与审计。

Enable Service Links（服务链接）：Authelia 的配置管理系统与默认开启的 enableServiceLinks 选项冲突，应将其改为 false（详见 PodSpec v1 core 文档）。Pod 示例如下：

---
apiVersion: v1
kind: Pod
metadata:
  name: authelia
spec:
  enableServiceLinks: false
...

FAQ：内存占用

如果使用基于文件的认证后端，argon2id 提供者默认在密码生成/校验时占用 1GB RAM。因此部署/StatefulSet 规格中应至少为该进程预留这么多内存，节点上也需要有足够的可用内存；否则登录时 Authelia 可能 OOM（内存不足被杀）。如无法满足，可调整 file 认证提供者的 memory 参数。

补充说明：该内存占用源自 argon2id 的默认成本参数设计，属于“以空间换时间”的抗暴力破解策略；调整 memory 参数即调整 argon2id 的内存成本，需在安全性允许的范围内权衡。

方式三：Bare-Metal 裸机部署

Authelia 以守护进程运行，因此裸机部署有多种方式。官方除提供 systemd 单元 外，不提供其他具体的服务化示例，用户可以自行选择进程管理器。

systemd 服务单元

仓库根目录提供两个示例 systemd 单元文件：

• authelia.service —— 单实例服务
• authelia@.service —— 模板化服务（支持多实例，实例名通过 %i 注入）

单实例单元的关键配置如下（来自 authelia.service）：

[Unit]
Description=Authelia authentication and authorization server
After=multi-user.target

[Service]
User=authelia
Group=authelia
UMask=027
Environment=AUTHELIA_SERVER_DISABLE_HEALTHCHECK=true
ExecStart=/usr/bin/authelia --config /etc/authelia/configuration.yml
SyslogIdentifier=authelia
CapabilityBoundingSet=
NoNewPrivileges=yes
RestrictNamespaces=yes
ProtectHome=true
PrivateDevices=yes
PrivateUsers=yes
ProtectControlGroups=yes
ProtectKernelModules=yes
ProtectKernelTunables=yes
SystemCallArchitectures=native
SystemCallFilter=@system-service
SystemCallErrorNumber=EPERM

[Install]
WantedBy=multi-user.target

这是一个相当典型的加固型 systemd 单元：以专属用户 authelia 运行、UMask=027 收紧文件权限、CapabilityBoundingSet= 清空能力集、NoNewPrivileges=yes 禁止提权、ProtectHome/PrivateDevices/PrivateUsers/ProtectControlGroups/ProtectKernelModules/ProtectKernelTunables 全面隔离命名空间与内核接口、SystemCallFilter=@system-service 限制系统调用并统一返回 EPERM。模板化单元 authelia@.service 与之唯一的关键差异是 ExecStart=/usr/bin/authelia --config /etc/authelia/configuration.%i.yml，即以实例名区分配置文件，便于运行多个隔离实例。

Arch Linux

除官方发布的可执行二进制外，还发布了 AUR 包 authelia。

Debian（.deb 与 APT 仓库）

官方随 releases 描述的签名架构进行签名。

添加 APT 仓库

先安装所需软件包并下载仓库密钥：

sudo apt install ca-certificates curl gnupg
sudo curl -fsSL https://www.authelia.com/keys/authelia-security.gpg -o /usr/share/keyrings/authelia-security.gpg

验证下载的密钥（gpg --no-default-keyring --keyring /usr/share/keyrings/authelia-security.gpg --list-keys --with-subkey-fingerprint），正确输出应包含以下 Key ID：

/usr/share/keyrings/authelia-security.gpg
-----------------------------------------
pub   rsa4096 2025-06-27 [SC]
      192085915BD608A458AC58DCE461FA1531286EEA
uid           [ unknown] Authelia Security <[e-mail]>
uid           [ unknown] Authelia Security <[e-mail]>
sub   rsa2048 2025-06-27 [E] [expires: 2033-06-25]
      7DBA42FED0069D5828A44079975E8FFC6876AFBB
sub   rsa2048 2025-06-27 [SA] [expires: 2033-06-25]
      C387CC1B5FFC25E55F75F3E6A228F3BD04CC9652

将仓库加入 sources.list.d：

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/authelia-security.gpg] https://apt.authelia.com stable main" | \
  sudo tee /etc/apt/sources.list.d/authelia.list > /dev/null

更新缓存并安装：

sudo apt update && sudo apt install authelia

Nix

通过 Nix 包管理器可从 https://nixos.org/channels/nixpkgs-unstable 频道安装 Authelia。注意该频道本身不稳定，且这是第三方打包：

nix-channel --add https://nixos.org/channels/nixpkgs-unstable
nix-channel --update
nix-env -iA nixpkgs.authelia

FreeBSD

除官方发布的二进制外，FreshPorts。该脚本基于 FreeBSD rc.subr 框架，启用方式是在 /etc/rc.conf 中设置 authelia_enable="YES"；脚本内部通过 /usr/sbin/daemon 以 -u root -o /var/log/authelia.log 方式后台运行 /usr/local/bin/authelia --config /usr/local/etc/authelia.yml。

二进制（Binaries）

官方随 releases 发布可在多种操作系统上安装的二进制文件。

部署到生产环境的检查清单

Get started 指南在“Moving to Production”一节给出了进入生产环境前必须完成的几件事，可作为三种部署方式通用的收尾清单：

1. 将所有 secret 值从配置中移出，放入 secrets（Docker 场景即上文示例中的 *_FILE 环境变量 + 密钥文件/卷）；
2. 花时间理解 access control，并按需进行细粒度配置；
3. 阅读 Security Measures 与 Threat Model 文档；
4. 阅读 Forwarded Headers 文档，确保代理不会向 Authelia 透传不安全头；
5. 审阅其余 Configuration Options。

总结与选型建议

部署方式	适用场景	关键注意点
Docker / Docker Compose	大多数用户的首选，官方推荐路径	用 *_FILE 环境变量注入密钥；利用 PUID/PGID/UMASK 控制权限上下文；代理与 Authelia 同网络
Kubernetes	容器编排、多副本、云原生环境	externalTrafficPolicy: local 保真实客户端 IP；enableServiceLinks: false；文件认证时预留 1GB 内存（可调 argon2id memory 参数）
Bare-Metal	已有系统化运维体系、需要 systemd/APT/Nix/FreeBSD 集成	必须置于代理之后（官方文档明确 Bare-Metal 部署的前提是位于代理之后）；使用加固型 systemd 单元；密钥优先走环境变量/文件注入

三种方式都以“守护进程 + 前置代理 + HTTPS + 必需请求头”为核心架构，官方推荐路径是 Docker。部署后如需接入代理鉴权，请继续阅读 代理集成文档；若部署在 Kubernetes 上，则应先阅读 Kubernetes 文档 再对接代理集成。