使用 Authelia 和 Caddy 保护您的服务
使用 Docker 和 Caddy 在 Debian 或 Ubuntu 上部署 Authelia:认证门户、双重验证、独立保存的密钥、访问规则、更新与备份。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
本指南介绍如何将 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$ 开头的值,并用单引号括起来:
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.ymlserver:
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.yamlservices:
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/ 中的某个文件:
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:注册第二重验证
- 在隐私浏览窗口中打开
https://app.您的域名.com。您会进入门户。 - 使用
您的用户名以及步骤 2 中选择的密码登录。 - 点击注册设备。
- 输入通过电子邮件收到的一次性验证码,以确认您的身份。
- 使用您的 TOTP 应用添加一个一次性密码,或添加一个 WebAuthn 安全密钥。
- 确认第二重验证:您将被重定向到应用。
之后,您可以在门户的设置中添加更多设备。如有可能,请至少注册两种方式,以免依赖单一设备。
验证结果
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 规则。规则按顺序读取,第一条匹配的规则生效。
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 autheliasecrets: 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 statusTarget 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