企业官网建设流程全解析

Authelia 与 Traefik 反向代理集成实战指南（Docker Compose 全流程部署）

【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia

本篇指南基于 Authelia 官方博客《Authelia + Traefik Setup Guide》，完整演示如何在单主机 Docker Compose 环境中，将Authelia作为独立认证服务接入Traefik反向代理，通过 ForwardAuth 中间件实现auth.example.com门户登录与受保护应用的访问控制（one_factor / two_factor 策略）。读完本文你将掌握：目录结构与 Compose 编排、Authelia 完整配置逐项解析、密钥安全生成、用户数据库初始化、启动验证与故障排查，并理解 ForwardAuth 端点底层如何通过转发请求头完成鉴权。

安全提示：官方将该指南定位为"临时解决方案"，用于在官方 Getting Started 文档完善期间提供参考，未来版本可能不再随新版本更新（届时会发布弃用通告）。它不是一键演示环境，如需开箱即用的整体演示，可参考 本地集成包。文中的配置遵循官方支持的方式，属于"有观点（opinionated）"的推荐部署形态。

前提假设与适配要点

本指南基于以下假设，高级复杂场景需要自行适配，无法覆盖所有进阶配置项：

• Docker 已正确安装并可用（Docker 安装文档）；
• 单主机（Single Host）部署；
• 默认变量（下文所有示例均使用这些默认值，请按需替换）：
  • 容器名：authelia；
  • Authelia 监听端口：9091；
  • 域名：example.com；
  • Authelia 门户子域：auth.example.com。

需要适配的情形：

• 使用不同容器名或代理部署在不同位置时，需修改 URL 中的authelia；
• 修改了配置中的默认端口时，需同步修改 URL 中的9091；
• Authelia 与代理不在同一主机时，需整体替换 URL；
• 所有服务均属于example.com域，除非仅用于测试或确实使用该域名，否则示例中所有域名与子域都必须替换为你自己的域名。

项目文件结构

建议按如下目录组织整个项目：

📁 project ┣ 📁 authelia ┃ ┣ 📁 config ┃ ┃ ┣ 📄 configuration.yml ┃ ┃ ┗ 📄 users.yml ┃ ┗ 📁 secrets ┣ 📄 compose.yml ┗ 📁 traefik ┣ 📁 config ┃ ┣ 📄 dynamic.yml ┃ ┗ 📄 traefik.yml ┣ 📁 data ┃ ┗ 📄 acme.json ┣ 📁 logs ┗ 📁 secrets

其中authelia/config/存放 Authelia 配置文件与用户数据库，authelia/secrets/存放密钥文件，traefik/存放 Traefik 静态/动态配置、ACME 证书存储与日志。

搭建 Traefik 与第一个测试服务

本指南只聚焦与 Authelia 协作所需的最小 Traefik 配置，进阶特性请参考 Traefik 官方文档。

Docker Compose 定义

services: traefik: image: 'traefik:latest' container_name: 'traefik' restart: 'unless-stopped' security_opt: - 'no-new-privileges=true' networks: proxy: aliases: - 'auth.example.com' authelia: {} ports: - '80:80' - '443:443' environment: TZ: 'America/Los_Angeles' ## 时区，见下方说明 volumes: - '/var/run/docker.sock:/var/run/docker.sock:ro' - './traefik/config/traefik.yml:/traefik.yml:ro' - './traefik/config/dynamic.yml:/dynamic.yml:ro' - './traefik/data/:/data' - './traefik/logs:/logs' labels: traefik.enable: 'true' traefik.http.routers.dashboard.rule: 'Host(`traefik.example.com`)' traefik.http.routers.dashboard.entrypoints: 'https' traefik.http.routers.dashboard.middlewares: 'authelia@docker' traefik.http.routers.dashboard.service: 'api@internal' whoami: image: 'traefik/whoami' restart: 'unless-stopped' container_name: 'whoami' labels: traefik.enable: 'true' traefik.http.routers.whoami.rule: 'Host(`whoami.example.com`)' traefik.http.routers.whoami.entrypoints: 'https' networks: proxy: {} ## 其他服务在这里添加 networks: proxy: external: true name: 'proxy' authelia: name: 'authelia'

几点说明：

• traefik容器同时加入proxy与authelia两个网络：proxy网络用于发现和路由各业务容器；authelia网络用于与 Authelia 单独通信（安全隔离，见下文网络章节）；
• Traefik 挂载 Docker socket 以动态发现容器，建议以:ro只读方式挂载；
• 时区字符串可参考 Go timezone 表，也可根据你的部署位置替换为Asia/Shanghai等；
• whoami是不受保护的测试服务，用于验证 Traefik 基础路由是否正常。

Traefik 基础配置（静态配置）

## Traefik 基础配置 api: dashboard: true debug: false insecure: false log: level: 'INFO' accessLog: filePath: '/logs/access.log' entryPoints: http: address: ':80' http: redirections: entryPoint: to: 'https' scheme: 'https' permanent: true https: address: ':443' http: tls: certResolver: 'myresolver' providers: docker: endpoint: 'unix:///var/run/docker.sock' exposedByDefault: false file: filename: '/dynamic.yml' certificatesResolvers: myresolver: acme: storage: '/data/acme.json' httpChallenge: entryPoint: 'http' tls: options: default: minVersion: 'VersionTLS12' cipherSuites: - 'TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256' - 'TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256' - 'TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384' - 'TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384' - 'TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305' - 'TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305'

要点解析：

• entryPoints.http将所有 80 端口请求永久 301 重定向到 HTTPS，entryPoints.https挂载 ACME 证书解析器myresolver；
• providers.docker启用 Docker Provider 且exposedByDefault: false——只有显式打了traefik.enable: 'true'标签的容器才会被路由，这是推荐的安全默认；
• providers.file加载/dynamic.yml（即挂载的traefik/config/dynamic.yml），用于放置动态路由/中间件配置；
• certificatesResolvers.myresolver.acme使用 HTTP-01 挑战，证书状态存于/data/acme.json，需提前创建（参见仓库 integration 文档中的 ACME 说明）；
• TLS 默认选项强制最低 TLS 1.2 并只启用现代 AEAD 密码套件（AES-GCM / ChaCha20-Poly1305）。

域名动态配置

## 此文件用于定义动态 routers/services/middlewares。

动态文件初始为空即可——Traefik 的路由、中间件主要由 Docker 标签提供。以上均为聚焦 Authelia 集成的最小配置，请结合 Traefik 官方文档按需调整。

接入 Authelia 容器与 ForwardAuth 中间件

以下服务定义应追加到前面创建的compose.yml中。它创建 Authelia 核心服务，并通过 Traefik 暴露门户（auth.example.com），同时新增一个受 Authelia 保护的whoami-secure容器。

authelia: image: 'authelia/authelia:4.38' container_name: 'authelia' volumes: - './authelia/secrets:/secrets:ro' - './authelia/config:/config' - './authelia/logs:/var/log/authelia/' networks: authelia: {} labels: ## 通过 Traefik 暴露 Authelia traefik.enable: 'true' traefik.docker.network: 'authelia' traefik.http.routers.authelia.rule: 'Host(`auth.example.com`)' traefik.http.routers.authelia.entrypoints: 'https' ## 配置 Authelia ForwardAuth 中间件 traefik.http.middlewares.authelia.forwardAuth.address: 'http://authelia:9091/api/authz/forward-auth' traefik.http.middlewares.authelia.forwardAuth.trustForwardHeader: 'true' traefik.http.middlewares.authelia.forwardAuth.maxResponseBodySize: '8192' traefik.http.middlewares.authelia.forwardAuth.authResponseHeaders: 'Remote-User,Remote-Groups,Remote-Name,Remote-Email' environment: TZ: 'America/Los_Angeles' X_AUTHELIA_CONFIG_FILTERS: 'template' whoami-secure: image: 'traefik/whoami' restart: 'unless-stopped' container_name: 'whoami-secure' labels: traefik.enable: 'true' traefik.http.routers.whoami-secure.rule: 'Host(`whoami-secure.example.com`)' traefik.http.routers.whoami-secure.entrypoints: 'https' traefik.http.routers.whoami-secure.middlewares: 'authelia@docker' networks: proxy: {}

核心标签逐一说明：

• traefik.http.routers.authelia.rule：将auth.example.com路由到 Authelia 门户；traefik.docker.network: 'authelia'明确指定 Traefik 通过authelia网络访问 Authelia 容器；
• traefik.http.middlewares.authelia.forwardAuth.address：整个集成的核心——Traefik 将受保护请求转发给 Authelia 的http://authelia:9091/api/authz/forward-auth端点做鉴权。若你修改了容器名或端口，此 URL 必须同步修改；
• trustForwardHeader: 'true'：信任 Traefik 注入的X-Forwarded-*头（ForwardAuth 实现依赖这些头获取请求元数据，见下文原理章节）；
• maxResponseBodySize: '8192'：限制 Auth 响应体大小，防止响应过大；
• authResponseHeaders：鉴权通过后，Authelia 返回的用户身份信息（用户名、组、显示名、邮箱）由 Traefik 以Remote-User、Remote-Groups、Remote-Name、Remote-Email请求头转发给后端应用——这正是从源码 handleAuthzAuthorizedStandard 中可以看到的实际响应头实现；
• X_AUTHELIA_CONFIG_FILTERS: 'template'：启用 Authelia 配置文件的模板渲染（详见 Templating 参考指南），使configuration.yml中的{{ secret ... }}等模板指令生效。官方参考指南中同样提到：配置模板可以通过 authelia config template 命令或trace日志级别（以 base64 输出渲染结果）进行验证调试。

whoami-secure通过traefik.http.routers.whoami-secure.middlewares: 'authelia@docker'挂载认证中间件，成为受保护的演示应用。

Docker 网络规划

需要（或会自动创建）两个网络，它们承担不同的信任边界：

proxy 网络

包含 Traefik，用于把任意附加容器接入 Traefik 代理。该网络为外部网络，需手动创建：

docker network create proxy \ --opt "com.docker.network.bridge.name"="br-docker-proxy"

authelia 网络

包含 Authelia 运行所需的容器，并把 Authelia 与 Traefik 通过独立网络相连。本指南未涉及，但该网络中通常会包含存储提供者（PostgreSQL 或 MySQL）、会话提供者（Redis）以及 LDAP 认证后端。该网络无需手动创建，容器启动时会自动创建。

注意：whoami-secure虽然受 Authelia 中间件保护，却不在authelia网络中——这是为了避免任何 HTTP 流量被截获的风险。受保护业务应位于proxy网络或与 Traefik 共享的网络，而 Authelia 专用服务使用独立的authelia网络，以获得更强的安全隔离。

Authelia 核心配置逐项解析

server: address: 'tcp4://:9091' log: level: debug file_path: '/var/log/authelia/authelia.log' keep_stdout: true identity_validation: elevated_session: require_second_factor: true reset_password: jwt_lifespan: '5 minutes' jwt_secret: {{ secret "/secrets/jwt_secret.txt" | mindent 0 "|" | msquote }} totp: disable: false issuer: 'example.com' period: 30 skew: 1 password_policy: zxcvbn: enabled: true min_score: 4 authentication_backend: file: path: '/config/users.yml' password: algorithm: 'argon2' argon2: variant: 'argon2id' iterations: 3 memory: 65535 parallelism: 4 key_length: 32 salt_length: 16 access_control: default_policy: 'deny' rules: - domain: 'traefik.example.com' policy: 'one_factor' - domain: 'whoami-secure.example.com' policy: 'two_factor' session: name: 'authelia_session' secret: {{ secret "/secrets/session_secret.txt" | mindent 0 "|" | msquote }} cookies: - domain: 'example.com' authelia_url: 'https://auth.example.com' regulation: max_retries: 4 find_time: 120 ban_time: 300 storage: encryption_key: {{ secret "/secrets/storage_encryption_key.txt" | mindent 0 "|" | msquote }} local: path: '/config/db.sqlite3' notifier: disable_startup_check: false filesystem: filename: '/config/notification.txt'

各配置段说明（本指南未涉及的选项请查阅官方配置文档）：

• server（Server 配置）：设置监听地址为tcp4://:9091，端口与 ForwardAuth 中间件中的地址必须一致；
• log（Logging 配置）：级别设为debug便于排查，同时写文件并保留标准输出（容器日志）；
• identity_validation（Identity Validation 配置）：启用提升会话需二次验证；重置密码的 JWT 有效期 5 分钟，其jwt_secret通过模板指令从密钥文件读取；
• totp（TOTP 配置）：启用 TOTP 二次验证，issuer 为example.com，30 秒周期、允许 1 个时间窗口偏差；
• password_policy（Password Policy 配置）：启用 zxcvbn 密码强度评估并要求最低得分 4（满分 4，即要求强密码）；
• authentication_backend：使用文件认证后端（/config/users.yml），密码哈希算法为argon2id（迭代 3 次、内存 64 MiB、并行度 4、密钥长 32 字节、盐长 16 字节）；
• access_control（Access Control 配置）：default_policy: 'deny'为安全默认——未命中任何规则的请求一律拒绝；规则按顺序匹配（rule 的匹配条件同时满足才命中）：traefik.example.com只需一次因子（one_factor），whoami-secure.example.com需要二次因子（two_factor）。该配置段不适用于 OpenID Connect 1.0 场景（详见官方 FAQ）；
• session（Session 配置）：会话 Cookie 名authelia_session，secret从密钥文件读取；现代配置将domain与authelia_url作为session.cookies列表项的子键，authelia_url: https://auth.example.com用于门户跳转（旧版配置为顶层default_redirection_url+session.domain，官方 Traefik 集成文档 提供了两种形态对比）；
• regulation（Regulation 配置）：暴力破解防护——120 秒内最多 4 次失败，超限封禁 300 秒；
• storage（Storage 配置）：encryption_key从密钥文件读取，本地存储使用 SQLite（/config/db.sqlite3）。生产环境可替换为 MySQL / PostgreSQL，会话可改用 Redis（见文末"下一步"）；
• notifier（Notifier 配置）：文件通知器，把邮件内容写入/config/notification.txt——适合测试环境（例如注册 TOTP/WebAuthn 时接收验证链接），生产应改用 SMTP。

密钥文件与模板指令

配置中{{ }}包裹的是 Go 模板，启动时会被指定文件的内容替换（需配合环境变量X_AUTHELIA_CONFIG_FILTERS: 'template'开启，详见 Templating 参考指南）。其中secret函数用于读取文件内容并去除尾部换行，mindent 0 "|"与msquote用于保证多行内容以正确的 YAML 块标量（|）呈现、单行内容以单引号包裹，避免密钥中含特殊字符时破坏 YAML 结构。

需要在authelia/secrets/目录创建 3 个必需密钥文件：

• jwt_secret.txt（重置密码 JWT 签名密钥）
• storage_encryption_key.txt（存储加密密钥）
• session_secret.txt（会话加密密钥）

在项目根目录project/下依次执行以下命令完成权限设置与自动生成：

chown 8000:8000 ./authelia/secrets && chmod 0700 ./authelia/secrets

docker run --rm -u 8000:8000 -v ./authelia/secrets:/secrets docker.io/authelia/authelia sh -c "cd /secrets && authelia crypto rand --length 64 session_secret.txt storage_encryption_key.txt jwt_secret.txt"

说明：

• 容器默认以 UID/GID 8000（authelia用户）运行，因此密钥目录需归属8000:8000并设为0700，否则容器内无法读取；
• 第二条命令以 UID 8000 启动一次性容器，在/secrets目录内调用authelia crypto rand --length 64生成 3 个 64 字符随机字符串文件（参见 Generating Secure Values 参考指南）；
• 如果自行生成，强烈建议这 3 个值使用 64 字符及以上的随机字母数字字符串（authelia crypto rand --length 64 --charset alphanumeric是官方推荐的生成方式）。

关于容器权限：官方 Docker 部署文档 还记录了PUID/PGID/UMASK三个容器环境变量——当容器以 UID 0 启动时，entrypoint 会降权到PUID/PGID并自动修正文件属主；而本指南采用-u 8000:8000的方式直接以非特权用户运行，需要手动保证文件系统权限正确，两种方式可任选其一。

用户数据库

users: authelia: ## 用户名 displayname: 'Authelia User' ## 警告：以下为仅供测试的默认密码！ ## 重要：生产部署前必须修改该密码！ ## 使用以下指引生成新的密码哈希： ## https://www.authelia.com/reference/guides/passwords/#passwords ## 当前密码是 'authelia' password: '$6$rounds=50000$BpLnfgDsc2WD8F2q$Zis.ixdg9s/UOJYrs56b5QEZFiZECu0qZVNsIYxBaNJ7ucIL.nlxVCT5tqh8KHG8X4tlwCFm5r6NTOZZ5qRFN/' email: 'authelia@authelia.com' groups: - 'admin' - 'dev'

• 当前示例密码为authelia，仅用于测试，正式部署前必须按 Passwords 参考指南 重新生成哈希；
• 推荐使用 Authelia 自带命令生成随机密码及哈希（参考 Generating Secure Values）：

docker run --rm authelia/authelia:latest authelia crypto hash generate argon2 --random --random.length 64 --random.charset alphanumeric

• 文件认证后端完整选项（argon2id 参数、密码哈希算法等）参见 First Factor 配置。

启动、验证与排错

启动整个栈

所有 Traefik、Authelia 及业务容器配置完成后，在project/目录执行：

docker compose up -d

Compose 会拉取镜像并启动全部容器（authelia网络会自动创建）。

验证安装

1. 查看容器状态：docker compose ps；
2. 访问 Traefik 仪表盘：https://traefik.example.com（需先通过一次因子认证）；
3. 测试认证流程：访问https://whoami-secure.example.com，未登录时应被重定向到https://auth.example.com门户，完成 two_factor 认证（用户名/密码 + TOTP）后可访问。

常见问题排查

• 查看容器日志：docker logs authelia；
• 确认 3 个密钥文件均存在且权限正确（目录0700、属主8000:8000）；
• 若 Traefik 报middleware authelia@docker not found：当 Traefik 与 Authelia 分属不同 Compose 栈时可能出现该错误，可通过depends_on确保 Authelia 先于 Traefik 启动，或在 Traefik 容器上直接定义 ForwardAuth 中间件标签解决（参见 Traefik 集成文档 FAQ）。

ForwardAuth 鉴权原理（源码视角）

了解 Traefik 集成背后的机制，有助于排查"为什么某个请求被放行/拒绝"。Authelia 的 ForwardAuth 实现在internal/handlers/handler_authz_impl_forwardauth.go中：它从请求头中读取元数据并构造鉴权对象——

• 请求方法取自X-Forwarded-Method；
• 协议、主机、路径分别取自X-Forwarded-Proto、X-Forwarded-Host、X-Forwarded-URI；

这些正是 Proxy Authorization 参考指南 中 ForwardAuth 实现所要求的元数据（方法/协议/主机/路径/IP/门户 URL），也是 Traefik 中间件必须设置trustForwardHeader: 'true'的原因。而"门户 URL"默认取自会话 Cookie 配置中的authelia_url，也可通过查询参数覆盖。

鉴权完成后（参见 handler_authz_common.go）：

• 授权成功：返回 200，并写入Remote-User、Remote-Groups、Remote-Name、Remote-Email响应头（对应中间件中的authResponseHeaders）；
• 未授权：对普通浏览器请求返回 302/303 重定向到门户（handleAuthzRedirectStatusCode会根据请求方法选择 302 或 303；HEAD 请求重定向不带响应体），对 XHR 或非 HTML 请求返回 401——这正是"页面访问跳转门户、API 请求直接 401"行为的源码出处。

从源码结构还可以推断：受保护请求会按顺序执行多种认证策略（会话 Cookie、Authorization 头等），最终由访问控制规则决定是否放行，这也解释了为何 Traefik 仪表盘（traefik.example.com）配置 one_factor 而业务站点（whoami-secure.example.com）配置 two_factor 即可实现差异化保护。

下一步扩展方向

本指南未覆盖 Authelia 的全部能力，以下官方文档可作为后续深入的方向：

• OpenID Connect 1.0（Provider 配置）：让支持 OIDC 的应用直接对接 Authelia 完成认证，无需反向代理参与；
• 外部数据库（Storage 配置）：除 SQLite 外支持 MySQL、PostgreSQL，适合多副本/高可用部署；
• 非内存会话存储（Session 配置）：默认内存会话在 Authelia 重启后会全部失效、用户需重新认证；接入 Redis 后会话可跨重启持久化，并使 Authelia 完全无状态化；
• 指标监控（Metrics 参考指南 与 Telemetry 配置）：导出安装实例的各项统计指标，便于接入 Prometheus/Grafana；
• 生产化改造：将文件通知器替换为 SMTP、收紧log.level、为 Authelia 自身启用 TLS 客户端证书双向认证（Traefik YAML 集成示例见 Traefik 集成文档，其中展示了通过serversTransports+ 客户端证书确保只有受信代理能访问 Authelia 的加固方案），并定期按 Validating Forwarded Authentication 指南 校验转发认证的安全性。

至此，你已经拥有了一套由 Traefik 统一入口、Authelia 集中鉴权的单点登录多因子认证架构：一条 ForwardAuth 中间件标签即可让任意新服务获得统一的登录与访问控制能力。

【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia