中文

应用程序

使用 Authelia 和 Caddy 保护您的服务

使用 Docker 和 Caddy 在 Debian 或 Ubuntu 上部署 Authelia:认证门户、双重验证、独立保存的密钥、访问规则、更新与备份。

阅读约 9 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

本指南介绍如何将 Authelia 部署在您的 Web 应用前面。反向代理 Caddy 会针对每个请求询问 Authelia 该访客是否可以通过。如果访客尚未通过身份识别,就会被送往登录门户,门户要求输入密码和第二重验证。

完成本指南后,https://app.您的域名.com 只有在 https://auth.您的域名.com 上完成双重验证之后才能访问。密钥与配置相互分离,您也将掌握如何更新和备份这套安装。

订购服务器

本指南适用于由您自行管理的服务器:

前提条件

  • 运行 Debian 12 或 13,或 Ubuntu 22.04 或 24.04 的服务器
  • 使用具有 sudo 权限的用户进行 SSH 访问
  • Docker Engine 和 Docker Compose,已按照指南安装 Docker Engine 和 Docker Compose安装
  • Caddy,已按照指南使用 Caddy 反向代理并自动启用 HTTPS安装
  • 一个由您管理 DNS 区域的域名,其中 auth.您的域名.com 和 app.您的域名.com 都指向 您的服务器IP
  • 一个需要保护的应用,仅在本地监听,此处为 127.0.0.1:3000
  • 一个 SMTP 账户,用于发送验证码和重置密码邮件

使用的端口

端口 方向 作用 是否需要开放
80/tcp 入站 证书验证以及重定向到 HTTPS 是
443/tcp 入站 Authelia 门户和受保护的应用 是
443/udp 入站 HTTP/3 建议开放
9091/tcp 本地 Authelia,仅限 127.0.0.1 否
3000/tcp 本地 示例应用 否

Authelia 还会信任代理传给它的 X-Forwarded-* 请求头。因此,它的端口绝不能从互联网访问。

步骤 1:创建文件夹和密钥

Authelia 需要三个密钥:重置链接的签名、会话密钥以及数据库加密密钥。每个密钥都单独放在各自的文件中,与配置分开。

终端
sudo mkdir -p /opt/authelia/config /opt/authelia/secrets
for name in JWT_SECRET SESSION_SECRET STORAGE_ENCRYPTION_KEY; do
  openssl rand -hex 64 | sudo tee "/opt/authelia/secrets/$name" > /dev/null
done
sudo nano /opt/authelia/secrets/SMTP_PASSWORD

在最后一个文件中填入您的 SMTP 账户密码,单独占据第一行。

步骤 2:创建第一个用户

计算您密码的指纹。该命令会要求您输入两次密码:

终端
sudo docker run --rm -it authelia/authelia:4.39.28 authelia crypto hash generate argon2

它会显示一行以 Digest: 开头的内容。创建用户文件:

终端
sudo nano /opt/authelia/config/users.yml

只复制以 $argon2id$ 开头的值,并用单引号括起来:

YAML
users:
  您的用户名:
    disabled: false
    displayname: 'Admin'
    password: '$argon2id$v=19$m=65536,t=3,p=4$...'
    email: 'admin@您的域名.com'
    groups:
      - 'admins'

该邮箱地址将接收验证码:它必须有效。

步骤 3:编写配置

终端
sudo nano /opt/authelia/config/configuration.yml
YAML
server:
  address: 'tcp://:9091/'

log:
  level: 'info'

totp:
  issuer: 'auth.您的域名.com'

authentication_backend:
  file:
    path: '/config/users.yml'
    password:
      algorithm: 'argon2'

session:
  cookies:
    - domain: '您的域名.com'
      authelia_url: 'https://auth.您的域名.com'
      default_redirection_url: 'https://app.您的域名.com'

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

regulation:
  modes:
    - 'user'
    - 'ip'
  max_retries: 3
  find_time: '2 minutes'
  ban_time: '10 minutes'

notifier:
  smtp:
    address: 'submission://smtp.您的域名.com:587'
    username: 'authelia@您的域名.com'
    sender: 'Authelia <authelia@您的域名.com>'

access_control:
  default_policy: 'deny'
  rules:
    - domain: 'app.您的域名.com'
      policy: 'two_factor'
配置段 作用
authentication_backend 从 users.yml 读取账户,密码使用 Argon2id
session.cookies 受保护的域名和门户地址,必须使用 HTTPS
storage SQLite 数据库,适用于仅有一个 Authelia 实例的情况
regulation 两分钟内失败三次后临时封锁
notifier 发送电子邮件。submission:// 使用 STARTTLS,submissions:// 使用直接 TLS
access_control 除非有规则允许,否则一律拒绝

步骤 4:启动 Authelia

终端
sudo nano /opt/authelia/compose.yaml
YAML
services:
  authelia:
    image: authelia/authelia:4.39.28
    restart: unless-stopped
    user: "8091:8091"
    environment:
      TZ: "Europe/Paris"
      AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE: /secrets/JWT_SECRET
      AUTHELIA_SESSION_SECRET_FILE: /secrets/SESSION_SECRET
      AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE: /secrets/STORAGE_ENCRYPTION_KEY
      AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE: /secrets/SMTP_PASSWORD
    volumes:
      - ./config:/config
      - ./secrets:/secrets:ro
    ports:
      - "127.0.0.1:9091:9091"

容器以无特权用户运行。请只授予该用户访问其文件的权限,其他人一律不可访问:

终端
sudo chown -R 8091:8091 /opt/authelia/config /opt/authelia/secrets
sudo chmod 700 /opt/authelia/config /opt/authelia/secrets
sudo find /opt/authelia/config /opt/authelia/secrets -type f -exec chmod 600 {} +

验证配置,然后启动服务:

终端
cd /opt/authelia
sudo docker compose run --rm authelia authelia config validate --config /config/configuration.yml
sudo docker compose up -d
sudo docker compose logs --tail=30 authelia
curl -fsS http://127.0.0.1:9091/api/health

验证应显示 Configuration parsed and loaded successfully without errors. 日志中应包含 Listening for non-TLS connections,最后一条命令应返回 {"status":"OK"}。

Caddy 与 Authelia 之间的流量始终停留在服务器的本地回环上。而访客只能通过 HTTPS 访问门户。

步骤 5:配置 Caddy

如果您使用 UFW,请允许 Web 端口:

终端
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp

将这两个站点添加到 /etc/caddy/Caddyfile,或添加到 /etc/caddy/sites/ 中的某个文件:

caddyfile
auth.您的域名.com {
	reverse_proxy 127.0.0.1:9091
}

app.您的域名.com {
	forward_auth 127.0.0.1:9091 {
		uri /api/authz/forward-auth
		copy_headers Remote-User Remote-Groups Remote-Email Remote-Name
	}

	reverse_proxy 127.0.0.1:3000
}

forward_auth 会在每个请求之前询问 Authelia。如果允许访问,Caddy 会将用户身份复制到 Remote-* 请求头中,再把请求转发给应用。否则,它会返回 Authelia 的响应,通常是重定向到门户。

验证并应用:

终端
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

步骤 6:注册第二重验证

  1. 在隐私浏览窗口中打开 https://app.您的域名.com。您会进入门户。
  2. 使用 您的用户名 以及步骤 2 中选择的密码登录。
  3. 点击注册设备。
  4. 输入通过电子邮件收到的一次性验证码,以确认您的身份。
  5. 使用您的 TOTP 应用添加一个一次性密码,或添加一个 WebAuthn 安全密钥。
  6. 确认第二重验证:您将被重定向到应用。

之后,您可以在门户的设置中添加更多设备。如有可能,请至少注册两种方式,以免依赖单一设备。

验证结果

终端
curl -si https://app.您的域名.com | grep -iE '^(HTTP|location)'
sudo ss -ltnp | grep -E ':(3000|9091) '

第一条命令应返回状态码 302,以及带有 rd 参数的 https://auth.您的域名.com/ 地址。第二条应仅显示 127.0.0.1。

从您的电脑访问 http://您的服务器IP:3000 和 http://您的服务器IP:9091 应当没有响应。最后,请在隐私窗口中进行以下检查:

  • 仅有密码不能访问应用;
  • 错误的 TOTP 验证码会被拒绝;
  • 从门户退出登录后,应用会再次要求身份验证。

每次修改代理或访问规则之后,请重复这些测试。

添加服务并细化规则

要保护另一个服务,请添加一个带有相同 forward_auth 块的 Caddy 站点,再添加一条 Authelia 规则。规则按顺序读取,第一条匹配的规则生效。

YAML
access_control:
  default_policy: 'deny'
  rules:
    - domain: 'status.您的域名.com'
      resources:
        - '^/api/health$'
      policy: 'bypass'
    - domain: 'admin.您的域名.com'
      subject:
        - 'group:admins'
      policy: 'two_factor'
    - domain: 'app.您的域名.com'
      policy: 'two_factor'
策略 效果
deny 拒绝访问
bypass 无需身份验证:仅用于真正公开的路径
one_factor 要求输入密码
two_factor 要求输入密码和第二重验证

所有服务都必须位于 session.cookies 中声明的域名之下。要添加用户,请补充 users.yml。每次修改配置或用户之后,请重启 Authelia:

终端
cd /opt/authelia
sudo docker compose restart authelia

会话保存在内存中:此次重启会使所有人退出登录。

更新 Authelia

请查阅发行说明,先备份,然后修改 compose.yaml 中的版本号:

终端
cd /opt/authelia
sudo nano compose.yaml
sudo docker compose pull
sudo docker compose run --rm authelia authelia config validate --config /config/configuration.yml
sudo docker compose up -d
sudo docker compose logs --tail=30 authelia

启动时,Authelia 会自动将其数据库迁移到新版本的结构。因此,事先备份就是您的回退手段。之后请重新执行验证部分的各项检查。

备份与恢复

/opt/authelia 文件夹包含这套安装的全部状态:配置、用户、SQLite 数据库和密钥。请短暂停止服务,以获得一致的副本:

终端
cd /opt/authelia
sudo docker compose stop authelia
sudo tar -czpf "/root/authelia-$(date +%F).tar.gz" -C /opt authelia
sudo docker compose start authelia
sudo chmod 600 "/root/authelia-$(date +%F).tar.gz"

该归档包含您的密钥和密码指纹。请将其复制到服务器之外的加密位置。

若要在不影响正在运行的实例的情况下验证它是否可用,请替换归档名称,然后在副本上检查加密密钥:

终端
sudo install -d -m 700 /root/authelia-test
sudo tar -xzpf /root/authelia-2026-11-18.tar.gz -C /root/authelia-test
cd /root/authelia-test/authelia
sudo docker compose -p authelia-test run --rm authelia authelia storage encryption check --verbose --config /config/configuration.yml
sudo docker compose -p authelia-test down
cd /
sudo rm -rf /root/authelia-test

预期结果为 Storage Encryption Key Validation: SUCCESS。

要在已装好 Docker 和 Caddy 的服务器上恢复:

终端
cd /opt/authelia
sudo docker compose down
cd /
sudo mv /opt/authelia "/opt/authelia.old-$(date +%F)"
sudo tar -xzpf /root/authelia-2026-11-18.tar.gz -C /opt
cd /opt/authelia
sudo docker compose up -d

故障排除

请始终先查看日志:

终端
cd /opt/authelia
sudo docker compose logs --tail=100 authelia

secrets: error loading secret path /secrets/...

指定的文件不存在或无法读取。请检查其名称,然后重新执行步骤 4 中的 chown 和 chmod 命令。

notifier: please ensure only one of the 'smtp' or 'filesystem' notifier is configured

您使用了 filesystem,但 compose.yaml 中仍然存在 AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE。请删除这一行,然后重新执行 sudo docker compose up -d。

One or more providers had fatal failures performing startup checks

某个必需的服务在启动时失败。多数情况下是 Authelia 无法连接或使用 SMTP 服务器。前面的错误行会给出原因:地址、端口、凭据,或出站端口被阻止。

the configured encryption key does not appear to be valid for this database

STORAGE_ENCRYPTION_KEY 与创建数据库时使用的密钥不一致。请从您的备份中放回正确的密钥。如需有意更改,请使用命令 authelia storage encryption change-key。

the system clock is not synchronized accurately enough with the configured NTP server

服务器时钟出现偏差,这会使 TOTP 验证码失效。请检查同步状态:

终端
timedatectl status

Target URL does not appear to have a relevant session cookies configuration

应用的域名未被 session.cookies 覆盖。请检查 configuration.yml 中的 domain 以及 Caddyfile 中使用的名称。

Target URL ... has an insecure scheme

请求是通过 HTTP 到达的。所有受保护的应用都必须通过 HTTPS 提供服务。请确认 Caddy 站点使用的是公开域名,且没有 http:// 前缀。

Access to '...' is forbidden to user '...'

用户已登录,但没有任何规则允许其访问。请检查规则的顺序、域名以及 users.yml 中的用户组。

密码正确却被拒绝

多次失败之后,账户或 IP 地址会在 ban_time 期间被封锁。请等待该时间结束,或解除账户的封锁:

终端
cd /opt/authelia
sudo docker compose exec authelia authelia storage bans user revoke 您的用户名 --config /config/configuration.yml

对于 IP 地址,请使用 authelia storage bans ip revoke 您的IP。

浏览器中出现 502 错误

Caddy 无法连接到 Authelia 或应用。请在本地测试这两者:

终端
curl -fsS http://127.0.0.1:9091/api/health
curl -I http://127.0.0.1:3000

参考资料