Authelia 日常运维手册

Authelia v4.39.28 运维实操：日常巡检、日志与 401/403 分层排障、SQLite 备份恢复、版本升级演练、封禁解封与会话失效处置，全部附真实回显

AutheliaAuthelia身份认证Apache Kylin2026/10/18

Authelia 日常运维手册

目标：为已上线的 Authelia v4.39.28 提供一份可照着敲的运维手册，覆盖日常巡检、日志排障、数据备份与恢复、版本升级、会话与安全事件处置（封禁/失效/401/403）、常见故障定位。已在 Ubuntu 22.04 实测通过（运维动作均在《Authelia Docker Compose 部署指南》环境完成并附真实回显）。

一、环境信息

  • 操作系统：Ubuntu 22.04；部署形态：Docker Compose 三服务（Authelia + Nginx 反代 + 演示后端）
  • Authelia：v4.39.28；配置目录：/opt/authelia/authelia/data/（容器内 /config）
  • 编排目录：/opt/authelia/（compose.yml + .env 密钥文件）
  • 存储后端：SQLite（/config/db.sqlite3）；会话后端：内存（默认）；通知：filesystem
  • 演示账号：admin / q1w2e3r4；域名家族：authelia.example.com:9091、app.example.com:8098
  • 专用网络：authnet（10.89.23.0/24）
  • 环境基准与参数含义见《Authelia 4.39 配置参数详解》，本篇只讲「怎么运维」

二、前置条件

  • 熟悉部署篇的目录结构与端到端验证四步链路（本篇排障反复用到）；
  • 服务器上 sqlite3 命令可用（备份/封禁处置需要）；
  • 具备 docker compose 操作权限与配置文件编辑权限。

三、日常巡检

建议每天（或接入监控后自动化）执行的三条巡检：

cd /opt/authelia

# 1) 三服务状态与 healthy
docker compose ps

实测回显：

NAME                IMAGE                       COMMAND                  SERVICE    CREATED             STATUS                        PORTS
authelia-v4-app     authelia/authelia:4.39.28   "/app/entrypoint.sh"     authelia   About an hour ago   Up 30 minutes (healthy)       0.0.0.0:9091->9091/tcp, [::]:9091->9091/tcp
authelia-v4-demo    nginx:alpine                "/docker-entrypoint.…"   demo       About an hour ago   Up 30 minutes                 80/tcp
authelia-v4-nginx   nginx:1.27-alpine           "/docker-entrypoint.…"   nginx      About an hour ago   Up 28 minutes                 80/tcp, 0.0.0.0:8098->8098/tcp, [::]:8098->8098/tcp

# 2) 存活探针
curl -sk https://127.0.0.1:9091/api/health; echo

实测回显：

{"status":"OK"}

# 3) 认证错误趋势（近 24h 失败次数）
sqlite3 /opt/authelia/authelia/data/db.sqlite3 \
  "SELECT COUNT(*) FROM authentication_logs WHERE successful=0 AND time > datetime('now','-1 day');"

实测回显：

4

巡检解读：healthy + health OK 说明双探针（编排 healthcheck 与应用自检）都过；失败认证计数用于发现爆破企图——持续走高的失败数应结合第五章的封禁排查处置。三服务中 demo 仅是演示载体，生产环境替换为真实后端后，巡检对象相应调整。

四、日志与排障

4.1 日志级别与动态观察

日常用 info 排障临时切 debug（configuration.yml 的 log.level，改完重启生效）：

docker logs -f --tail 50 authelia-v4-app

debug 级别的实测输出（节选，含配置加载与认证尝试明细）：

time="2026-10-18T07:45:21Z" level=debug msg="Loaded Configuration Sources" files="[/config/configuration.yml]" filters="[]"
time="2026-10-18T07:45:21Z" level=debug msg="Process user information" gid=0 name=root uid=0 username=root
time="2026-10-18T07:45:29Z" level=debug msg="Mark 1FA authentication attempt made by user 'admin'" method=POST path=/api/firstfactor remote_ip=10.89.23.1

⚠️ 注意：debug 会输出更多上下文（含用户名、来源 IP），长期开启既费盘又有泄露风险，排障完毕记得改回 info 并重启（本篇实测即如此操作）。

4.2 认证日志的数据库视角

结构化认证流水在 SQLite 的 authentication_logs 表，比日志更适合统计：

sqlite3 /opt/authelia/authelia/data/db.sqlite3 \
  "SELECT datetime(time,'localtime') AS t,username,successful,remote_ip FROM authentication_logs ORDER BY time DESC LIMIT 5;"

实测回显：

2026-10-18 15:45:29|admin|1|10.89.23.1
2026-10-18 15:40:05|admin|1|10.89.23.1
2026-10-18 15:39:53|admin|1|10.89.23.1
2026-10-18 15:17:40|admin|0|10.89.23.1
2026-10-18 15:17:40|admin|0|10.89.23.1

回显解读：successful=1 成功、0 失败；remote_ip 是请求来源（经反代后为代理侧地址，本环境为 docker 网关 10.89.23.1——生产应配置反代传递真实 IP 并按官方文档让 Authelia 信任代理头，否则封禁与审计都指向代理而非真实客户端）。

4.3 典型故障：401 的分层定位

用户报「登录不上/一直跳登录页」时，按链路逐层复现（四步命令与预期回显见部署篇 4.11）：

层检查点命令正常表现
1. 服务层Authelia 活着/api/health{"status":"OK"}
2. 校验层verify 对有效 cookie/api/verify + Cookie + X-Original-URL200 + Remote-User
3. 策略层access_control 规则同上改 X-Original-URL 为目标域one_factor 会话访问 one_factor 规则域应为 200
4. 反代层auth_request 转发未登录 curl 目标应用302 且 Location 带 ?rd=

实测案例（每层真实回显）：

  • 层 2 失败——会话真的失效了（见 4.4）：
HTTP/1.1 401 Unauthorized
  • 层 3 失败——会话级别低于规则要求（如 one_factor 会话撞上 two_factor 规则，配置篇 5.7 实测）：
401（verify）/ 302（跳补二因子）
  • 层 4 失败——反代没把认证子请求转发出去，浏览器直接看到 502 或 Authelia 的 403：
（nginx error log）connect() failed (111: Connection refused) while connecting to upstream

处理：docker compose exec nginx nginx -t 校验反代语法后 docker compose restart nginx；确认 proxy_pass https://authelia:9091 与服务名一致（服务间用服务名解析，不是 127.0.0.1）。

4.4 会话失效与时钟问题

内存会话随重启失效（本方案会话后端为内存，实测对照组）：

# 重启前有效会话
curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1:9091/api/verify \
  -H 'Cookie: authelia_session=IOgngIb^q4GpY…' -H 'X-Original-URL: https://app.example.com:8098/'

200

docker compose restart authelia && sleep 8
# 重启后同一 cookie
curl -sk -i https://127.0.0.1:9091/api/verify \
  -H 'Cookie: authelia_session=IOgngIb^q4GpY…' -H 'X-Original-URL: https://app.example.com:8098/' | head -1

HTTP/1.1 401 Unauthorized

结论：每次重启 Authelia，所有登录用户都要重新登录（内存会话的固有代价）。运维窗口应选低峰；不希望失效就按配置篇 5.5 迁移 session.redis。

篡改/无效 cookie 被签名校验拒绝（实测把 cookie 首字符改掉）：

HTTP/1.1 401 Unauthorized

出现大量此类 401 时，通常是 SESSION_SECRET 被更换或负载均衡各实例密钥不一致——排查 .env 与所有实例的环境变量。

时钟漂移与 NTP 警告：本环境启动日志持续出现（实测原文）：

time="2026-10-18T07:15:18Z" level=warning msg="Could not determine the clock offset due to an error" error="error occurred reading ntp packet response to the connection: read udp 10.89.23.4:44577->162.159.200.1:123: i/o timeout"

影响与处置：该警告表示无法校验时钟偏移；时钟漂移会直接破坏 TOTP（±30s 窗口）与 token 时效判断。内网环境把 ntp.address 指向内部 NTP 源，或由宿主机 chrony 保证时间同步后关闭 Authelia 内建校验（ntp.disable_startup_check: true）。验证宿主机时间同步状态用 timedatectl status（观察 System clock synchronized: yes）。

五、安全事件处置

5.1 登录封禁（regulation）的确认与解封

配置篇 5.8 已完整实测封禁行为（3 次失败即封 5 分钟、封禁期正确密码也 401、记录持久化）。运维侧的处置流程：

# 1) 确认封禁记录（谁被封、何时解封）
sqlite3 /opt/authelia/authelia/data/db.sqlite3 'SELECT * FROM banned_user;'

实测回显：

1|2026-10-18 07:17:40|2026-10-18 07:22:40.353693774+00:00||0|admin|regulation|Exceeding Maximum Retries

# 2) 误封（如办公出口 IP 被同事连累）→ 立即解封
sqlite3 /opt/authelia/authelia/data/db.sqlite3 'DELETE FROM banned_user;'
# 3) 验证解封后可正常登录（实测 HTTP 200 + {"status":"OK"...}）

真实攻击场景不要急着解封：先看 remote_ip 是否为外网扫描源，调大 ban_time、必要时在反代/防火墙层直接封 IP。IP 维度封禁在 banned_ip 表，处置方式相同。

5.2 密码重置

文件用户后端没有自助改密入口，运维改密的标准动作：

# 生成新哈希（以重置 admin 密码为例）
docker run --rm authelia/authelia:4.39.28 authelia crypto hash generate argon2 --password 'new-password-here'

实测回显（重置回 q1w2e3r4 的哈希，节选）：

Digest: $argon2id$v=19$m=65536,t=3,p=4$COvCyJXZxaXzM4RRCMyEJQ$/CtM5BKqBlXD6Txbey1wQwPiz+CwbcSYjRxh811kG10

把 users.yml 中该用户的 password 替换为新哈希，docker compose restart authelia 生效；完成后按部署篇 4.11 第二步实测验证新密码可登录。门户的「忘记密码」流程（邮件重置链接）依赖 notifier 与 identity_validation.reset_password.jwt_secret，生产配置 SMTP 后即可启用。

六、备份与恢复

6.1 备份什么

对象路径说明
SQLite 数据库/opt/authelia/authelia/data/db.sqlite3唯一的运行时状态（认证流水、2FA 绑定、封禁、OIDC 会话）
存储加密密钥.env 的 STORAGE_ENCRYPTION_KEY与数据库绑定，分开存放即白备份
配置与用户库configuration.yml、users.yml建议进 Git/配置管理
TLS 证书certs/、authelia/data/certs/可重新签发，建议仍纳入备份

6.2 冷备份实操

SQLite 在 Authelia 写入时直接 cp 有截断风险，标准做法是先停服再拷（窗口期秒级）：

cd /opt/authelia
docker compose stop authelia
cp authelia/data/db.sqlite3 backup/db-backup-$(date +%Y%m%d).sqlite3
docker compose start authelia
ls -lh backup/

实测回显：

total 304K
-rw-r--r-- 1 root root 304K 10月 18 15:44 db-backup-20261018.sqlite3

备份后校验完整性（对原库执行）：

sqlite3 /opt/authelia/authelia/data/db.sqlite3 'PRAGMA integrity_check;'

实测回显：

ok

6.3 恢复实操（实测）

cd /opt/authelia
docker compose stop authelia
rm authelia/data/db.sqlite3            # 只删库文件，配置/用户库/证书不动
cp backup/db-backup-20261018.sqlite3 authelia/data/db.sqlite3
docker compose start authelia
sleep 8 && docker compose ps --format '{{.Name}} {{.Status}}'

实测回显：

authelia-v4-app Up 9 seconds (healthy)

数据完整性验证（备份时刻的认证流水应完整回来）：

sqlite3 /opt/authelia/authelia/data/db.sqlite3 'SELECT COUNT(*) FROM authentication_logs;'
curl -sk https://127.0.0.1:9091/api/health; echo

实测回显：

11
{"status":"OK"}

💡 说明：恢复演练做到「库文件可替换、启动 healthy、行数对得上」即为有效；若备份来自更换过 STORAGE_ENCRYPTION_KEY 的环境，恢复时必须用备份当时的密钥，否则 2FA 设备等加密列解不开。

七、版本升级

7.1 升级原则与检查项

  • 先看 Release Notes：https://github.com/authelia/authelia/releases 逐条读目标版本的 breaking changes（4.38/4.39 就有多处键名破坏性变化，清单见配置篇 Q2）；
  • 先备份：按第六章完成备份再动手；
  • 补丁版本（4.39.x）间升级：schema 兼容，直接换版本号；特性版本（4.38→4.39）升级：先在测试环境过一遍；
  • 配置先校验：用 authelia validate-config（配置篇 3.1，有实测回显）确认新版本兼容现有配置。

7.2 升级实操（实测：4.39.27 → 4.39.28 演练）

cd /opt/authelia

# 1) 备份（见第六章）
docker compose stop authelia && cp authelia/data/db.sqlite3 backup/db-pre-upgrade.sqlite3 && docker compose start authelia

# 2) 拉取新镜像
docker pull authelia/authelia:4.39.28

实测回显：

Status: Downloaded newer image for authelia/authelia:4.39.28

# 3) 修改 compose.yml 中的镜像 tag 后重建
sed -i 's/authelia\/authelia:4.39.27/authelia\/authelia:4.39.28/' compose.yml
docker compose up -d authelia

实测回显：

 Container authelia-v4-app Started

# 4) 版本确认与状态检查
docker exec authelia-v4-app authelia --version
docker compose ps --format '{{.Name}} {{.Status}}'
docker logs authelia-v4-app 2>&1 | grep -E 'schema|complete|error|fatal' | tail -3

实测回显（本次实测经 4.39.27↔4.39.28 双向演练，结果一致）：

authelia version v4.39.28
authelia-v4-app Up 8 seconds (healthy)
time="2026-10-18T07:44:49Z" level=info msg="Storage schema is being checked for updates"
time="2026-10-18T07:44:49Z" level=info msg="Storage schema is already up to date"
time="2026-10-18T07:45:54Z" level=info msg="Startup complete"

Storage schema is already up to date 说明 schema 无变化（4.39 补丁版本间兼容）；若出现 Storage schema migration from X to Y is being attempted，务必等日志出现 migration is complete 再做业务验证，中途强行回滚会留下半迁移状态。

# 5) 业务回归：四步链路（部署篇 4.11）+ health
curl -sk https://127.0.0.1:9091/api/health; echo

{"status":"OK"}

回滚：sed 把镜像 tag 改回旧版本 → docker compose up -d → 恢复升级前备份的数据库（若 schema 发生了向上迁移则不能直接回滚旧版本，需按官方降级指引处理）。本篇实测 4.39.28→4.39.27 回退、4.39.27→4.39.28 再升级均正常（healthy + schema up to date）。

八、常用命令速查

cd /opt/authelia

# —— 状态 ——
docker compose ps                                  # 三服务与健康值
curl -sk https://127.0.0.1:9091/api/health         # 应用存活
docker logs -f --tail 50 authelia-v4-app           # 跟日志

# —— 配置变更 ——
vim authelia/data/configuration.yml                # 或 users.yml
docker compose restart authelia                    # 全部配置改动都需要重启生效

# —— 备份恢复 ——
docker compose stop authelia && cp authelia/data/db.sqlite3 backup/db-$(date +%Y%m%d).sqlite3 && docker compose start authelia
sqlite3 authelia/data/db.sqlite3 'PRAGMA integrity_check;'

# —— 安全事件 ——
sqlite3 authelia/data/db.sqlite3 'SELECT * FROM banned_user;'   # 查封禁
sqlite3 authelia/data/db.sqlite3 'DELETE FROM banned_user;'     # 解封

# —— 升级 ——
docker pull authelia/authelia:<新版本>
# 改 compose.yml 的 image tag 后：
docker compose up -d authelia

# —— 反代 ——
docker compose exec nginx nginx -t                 # 反代配置语法校验
docker compose restart nginx

九、常见问题

Q1：每次重启 Authelia 用户都要重新登录，正常吗？ 内存会话后端的固有行为（4.4 有实测对照组：同一 cookie 重启前 200、重启后 401）。两种改善路径：① 迁移 session.redis（配置篇 5.5），重启后登录态保留；② 升降级窗口选低峰期并在公告里预告。迁移 Redis 前注意 OIDC 等功能对会话后端的要求（见选型篇架构章节）。

Q2：日志里 read udp ...:123: i/o timeout 一直在刷。 Authelia 启动时向默认 NTP 源（time.cloudflare.com）校验时钟，出不了网 UDP 123 的环境就会持续告警（4.4 有实测原文）。处置：ntp.address 改内网 NTP，或宿主机已由 chrony 同步后设 ntp.disable_startup_check: true。不要放着不管——时钟漂移会让 TOTP 用户集体「验证码错误」。

Q3：/api/state 返回 403，但用户登录功能正常。 域名校验问题：/api/state 要求 Host 与 session.cookies[].domain 匹配，用 IP 直连就会 403（部署篇 Q5/Q6 有实测与解法，--resolve 用配置域名访问即可）。登录走门户域名正常说明服务本身没问题。

Q4：用户被封禁了，怎么快速处理？ 第五章 5.1 的三步：查 banned_user → 确认是否误封 → 删记录解封（实测删除后立即恢复登录）。若反复触发，把失败来源 IP 与 4.2 的认证流水对齐，判断是爆破攻击还是规则太严（regulation 三参数调整见配置篇 5.8）。

Q5：升级后起不来，日志报 configuration key not expected。 新版本删了你还在用的旧配置键（4.38→4.39 的清单见配置篇 Q2）。先用 authelia validate-config 列出全部问题，逐项改成新键名再启动。这也是 7.1 要求「先校验再升级」的原因。

Q6：备份恢复后部分功能异常（如 2FA 报错）。 典型原因是「备份的数据库」与「现用的加密密钥」不配套——db.sqlite3 里的敏感列是用备份当时的 STORAGE_ENCRYPTION_KEY 加密的。恢复时成对还原（6.1 的绑定关系），或接受 2FA 设备需重新注册。

十、参考链接