Authelia 裸机（Bare-Metal）部署指南：systemd 服务单元、APT 仓库与多发行版安装实战

Authelia 裸机（Bare-Metal）部署指南：systemd 服务单元、APT 仓库与多发行版安装实战

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

裸机（Bare-Metal）部署是 Authelia 的三种官方部署方式之一（其余为 Docker 与 Kubernetes）。本文以仓库中官方文档 bare-metal.md 为主体，逐条展开 systemd 服务单元、Debian/APT 仓库、Arch、Nix、FreeBSD 及二进制发布物的安装与校验细节，并结合仓库源码（authelia.service、authelia@.service、authelia-fb-rc.d、config.template.yml）讲透每个环节的底层原理，让读者能够在物理机或虚拟机（VM）上把 Authelia 作为系统守护进程稳定落地，并正确配置反向代理与初始化配置。

一、部署方式概览：为什么选择 Bare-Metal

在阅读正文前，先明确 Authelia 官方划分的三种主要部署路径（见 deployment/introduction.md）：

1. Docker：通过容器镜像交付，最省事，适合大多数场景；
2. Kubernetes：适合需要编排、自动伸缩的集群环境；
3. Bare-Metal：将 Authelia 作为系统守护进程（daemon）直接运行在宿主机上，适合已有传统运维体系、不便引入容器层的环境。

Authelia 本体就是一个编译好的单一二进制程序，因此它可以像其他守护进程一样被 systemd（Linux）或 rc.d（FreeBSD）托管。官方文档明确指出：除 systemd unit 文件外，官方不为其他服务管理方式提供具体示例——也就是说，systemd 是官方推荐的裸机服务托管方案，也是本文的核心章节。

二、部署前的硬性前提（不可跳过）

首次部署 Authelia 的用户，官方强烈建议先通读 Get started 指南。该指南给出了几条与裸机部署直接相关的强制性前提：

• Authelia 自身必须以https协议提供服务，这是有意为之的安全设计（加密通信 + 降低复杂度），即使测试环境也不允许例外；
• 前置反向代理的配置必须包含 Required Headers，即X-Forwarded-Proto、X-Forwarded-Host等转发头（默认来源分别为X-Forwarded-Proto与X-Forwarded-Host请求头），Authelia 依赖这些头判断原始请求的协议与主机名；
• 若采用转发认证（Forwarded Authentication）方式保护应用，则被保护的应用/域名同样必须使用安全协议（https/wss），因为该流程依赖会话 Cookie；
• OpenID Connect 1.0 场景除 Authelia 自身的https要求外，无额外特殊要求（其余以相关规范为准）。

这些前提决定了裸机架构的形态：用户 → 反向代理（Nginx/Caddy/Traefik 等）→ Authelia。Authelia 自身不直接对外暴露，而是被代理保护在内部端口（默认tcp://:9091/，见下文配置模板分析）。

三、systemd 服务单元：官方推荐的裸机托管方式

官方随仓库发布两个示例 systemd unit 文件：

• authelia.service：单实例服务单元；
• authelia@.service：模板服务单元，支持通过实例名启动多个互不干扰的 Authelia 实例。

3.1 单实例单元 authelia.service 逐段解读

仓库根目录下的 authelia.service 完整内容如下：

[Unit] Description=Authelia authentication and authorization server Documentation=https://www.authelia.com 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

关键点逐一说明：

• User=authelia/Group=authelia：以专用低权限账号运行，需要在安装时预先创建该系统用户与用户组；
• UMask=027：限制新建文件权限，防止配置文件、日志等被其他用户读取；
• Environment=AUTHELIA_SERVER_DISABLE_HEALTHCHECK=true：对应配置项server.disable_healthcheck。在 config.template.yml 中该选项的注释说明为"禁用向/app/.healthcheck.env写入健康检查变量，从而使 healthcheck.sh 返回退出码 0"，默认情况下若/app/.healthcheck.env或/app/healthcheck.sh不存在则自动禁用。裸机场景没有该文件，通过环境变量显式置 true 可避免无意义的健康检查逻辑；
• ExecStart=/usr/bin/authelia --config /etc/authelia/configuration.yml：启动命令指向/usr/bin/authelia（由 Debian 等发行版包安装），配置路径为/etc/authelia/configuration.yml。注意--config（-c）是 Authelia 主命令的核心参数，支持多次指定、逗号分隔列表或目录，详见 authelia CLI 参考：

  authelia --config /etc/authelia/config.yml --config /etc/authelia/access-control.yml authelia --config /etc/authelia/config.yml,/etc/authelia/access-control.yml authelia --config /etc/authelia/config/

  默认值为configuration.yml，即未显式指定时会在当前工作目录查找该文件；

• 安全加固指令集：CapabilityBoundingSet=（清空 capability 边界）、NoNewPrivileges=yes、RestrictNamespaces=yes、ProtectHome=true、PrivateDevices=yes、PrivateUsers=yes、ProtectControlGroups/KernelModules/KernelTunables=yes、SystemCallArchitectures=native、SystemCallFilter=@system-service（配合SystemCallErrorNumber=EPERM拒绝集合外系统调用）。这套组合把 Authelia 进程的权限面压缩到最小，是值得在自己编写的服务单元中借鉴的加固模板；
• SyslogIdentifier=authelia：日志统一以authelia标识写入 journald；
• [Install] WantedBy=multi-user.target：systemctl enable时在multi-user.target下建立开机自启依赖。

3.2 模板单元 authelia@.service：多实例场景

authelia@.service 与单实例版本几乎一致，仅两处不同：

• ExecStart=/usr/bin/authelia --config /etc/authelia/configuration.%i.yml：%i是 systemd 的实例名占位符。启动authelia@tenant1时，实际加载/etc/authelia/configuration.tenant1.yml；
• SyslogIdentifier=authelia-%i：日志标识随实例名区分，便于按实例检索日志。

它适合在同一台裸机上为多个租户/域名分别运行独立实例的场景——每个实例拥有各自的配置、存储与会话密钥。

3.3 启用服务

安装好二进制与配置文件后，按常规 systemd 流程操作即可（仓库为只读，此处仅说明运行方式）：

# 创建专用用户（若安装包未自动创建） sudo useradd --system --home /var/lib/authelia --shell /usr/sbin/nologin authelia # 放置配置文件并设置权限 sudo install -d -o authelia -g authelia /etc/authelia sudo install -o authelia -g authelia -m 600 configuration.yml /etc/authelia/configuration.yml # 重载并启用、启动 sudo systemctl daemon-reload sudo systemctl enable --now authelia.service sudo systemctl status authelia.service

模板单元的多实例用法同理：sudo systemctl enable --now authelia@tenant1.service。

四、Arch Linux：AUR 包

除官方发布的二进制外，Arch Linux 用户还可以通过AUR（Arch User Repository）中的authelia包安装。AUR 属于社区维护的第三方打包渠道，安装前建议留意 PKGBUILD 的维护状态与更新频率，并优先考虑与官方 [releases] 二进制保持版本同步。使用 yay 等 AUR 辅助工具安装即可：

yay -S authelia

五、Debian：.deb 包与官方 APT 仓库

Debian 系发行版有两种官方途径获取 Authelia：随 [releases] 发布的.deb安装包，以及持续更新的 APT 软件源。两者均使用仓库 Artifact Signing and Provenance Overview 中描述的签名架构进行签名，安装来源可信度有保障。

5.1 签名架构背景

Debian 包与 APT 仓库均由 Authelia 专用 GPG 密钥签名，关键指纹信息（与文档一致）：

• 主密钥 ID：192085915BD608A458AC58DCE461FA1531286EEA
• 加密子密钥：7DBA42FED0069D5828A44079975E8FFC6876AFBB
• 签名子密钥：C387CC1B5FFC25E55F75F3E6A228F3BD04CC9652
• 密钥所有者：Authelia Security <security@authelia.com>/<team@authelia.com>

因此下文添加 APT 源时使用的 keyring 文件必须与上述指纹一致，可作为校验基准。

5.2 添加 APT 仓库的完整步骤

第一步：安装依赖并下载仓库密钥（Artifact Signing and Provenance Overview 对密钥获取有更详细的说明）：

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 <security@authelia.com> uid [ unknown] Authelia Security <team@authelia.com> 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，注意signed-by指向刚验证过的 keyring 文件，arch=$(dpkg --print-architecture)自动适配当前架构：

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

安装完成后，/usr/bin/authelia即与 authelia.service 中ExecStart的路径对应，可直接进入上文 systemd 章节的启用流程。

5.3 直接安装 .deb 包

若不想引入 APT 源，也可直接从 [releases] 下载对应发行版架构的authelia_*.deb包安装：

sudo apt install ./authelia_*.deb

Debian 包同样由上述 GPG 密钥签名，可参照 Artifact Signing and Provenance Overview 的校验流程验证完整性。

六、Nix：nixpkgs-unstable 通道

使用 Nix 包管理器时，Authelia 通过nixpkgs-unstable通道提供。官方文档特别提醒：该通道本身是 unstable（不稳定）的，且这是第三方打包的软件包，生产环境使用前需评估。

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

七、FreeBSD：rc.d 服务脚本

FreeBSD 场景下，除官方二进制外，FreshPorts 还提供第三方包。官方额外发布了一个 rc.d 服务脚本，即仓库根目录的 authelia-fb-rc.d，安装时应将其部署为/etc/rc.d/authelia（或/usr/local/etc/rc.d/下）。其核心逻辑如下：

# PROVIDE: authelia # REQUIRE: DAEMON NETWORKING # KEYWORD: shutdown . /etc/rc.subr name=authelia rcvar=authelia_enable load_rc_config "${name}" authelia_enable=${authelia_enable:-"NO"} logfile="/var/log/${name}.log" procname=/usr/local/bin/authelia command="/usr/sbin/daemon" command_args="-u root -o ${logfile} -t ${name} /usr/local/bin/authelia --config /usr/local/etc/authelia.yml" run_rc_command "$1"

要点解读：

• 通过 rc.subr 框架托管，rcvar=authelia_enable意味着需要在/etc/rc.conf中设置authelia_enable="YES"才能开机启动（默认NO）；
• 使用daemon命令包装守护进程：-u root以 root 身份运行（Authelia 自身会完成必要的降权或依赖系统权限管理），-o ${logfile}将日志重定向到/var/log/authelia.log，-t ${name}设置进程标签便于管理；
• 配置路径为/usr/local/etc/authelia.yml（对应--config参数），与 Linux 场景的/etc/authelia/configuration.yml不同，迁移时需注意。

八、二进制发布物：通用安装与完整性校验

所有受支持的操作系统都可以直接使用 [releases] 中发布的预编译二进制（官方文档称之为 "Binaries"）。以 Linux x86_64 为例，典型安装流程为：

# 下载并解压（以 musl 静态链接变体为例） curl -fsSLO https://<release-url>/authelia-<version>-linux-amd64-musl.tar.gz tar -xzf authelia-<version>-linux-amd64-musl.tar.gz sudo install -m 755 authelia-<version>-linux-amd64-musl/authelia /usr/bin/authelia

发布物带有 glibc 与 musl 两种 Linux 变体，并覆盖 amd64/arm/arm64 等架构，可按目标系统选择。建议同时使用官方提供的checksums.sha256与签名文件进行完整性校验，具体做法见 Artifact Signing and Provenance Overview：

# 下载 checksums 及其 GPG 签名后执行 gpg --verify checksums.sha256.sig checksums.sha256 && sha256sum --ignore-missing -c checksums.sha256

校验输出中若出现 "Good signature from Authelia Security" 即说明签名有效；GPG 关于 "User ID is not certified" 的警告是正常的——只要没有手动信任该密钥就会出现，不影响完整性验证结论。此外，Authelia 的.tar.gz与.deb发布物还附带符合 SLSA Build Level 3 的 Provenance 元数据（authelia.intoto.jsonl），可用slsa-verifier进一步验证构建来源的可信与可复现性。

九、裸机部署后的初始化与生产化

安装只是第一步。Authelia 的配置是静态的、通过配置文件而非 Web 界面管理的，因此部署前必须完成配置定制。

9.1 获取配置模板

仓库根目录的 config.template.yml 即官方配置模板。除了手工复制该文件外，Authelia 还有一个便利行为：首次启动时若未找到配置，会写出适配当前版本的模板文件。这与主程序入口的实现相印证——cmd/authelia/main.go 中，当命令返回commands.ErrConfigCreated错误时进程以退出码 0 正常结束，即"只生成配置模板、不继续启动"的路径。初次部署时也可以直接运行authelia --config /etc/authelia/configuration.yml，让其自动生成模板再逐项修改。

9.2 配置中的关键段落

结合 config.template.yml 与 Get started 指南，首次部署必须重点核对以下部分：

• server：监听地址采用 Authelia 的 address 通用语法，默认tcp://:9091/（裸机部署通常保持本地监听，由前置代理转发），disable_healthcheck默认为 false、且在容器特定文件不存在时自动禁用，systemd 单元中通过环境变量显式置为 true 正是与之对应；
• jwt_secret：用于签发重置密码等身份验证邮件的 JWT 签名密钥；
• authentication_backend：在 LDAP 与 YAML 文件两种方式中选择其一；
• storage：在 SQL 存储提供商中选择，测试/轻量场景推荐 SQLite3，生产推荐 PostgreSQL；
• session：配置会话 Cookie 的domain、authelia_url与secret，生产环境推荐 Redis 存储；
• notifier：发送 2FA 注册邮件的通知器，SMTP 为生产推荐，仅可配置其一；
• access_control：初始可用最简策略起步，例如：

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

9.3 从裸机走向生产环境的检查清单

Get started 指南给出了明确的迁移建议，裸机部署同样适用：

1. 将所有机密值从配置文件迁移到环境变量/密钥文件（见 配置方法 - secrets）；
2. 花时间理解并精细化配置 access control；
3. 阅读 Security Measures 与 Threat Model 文档；
4. 检查前置代理的 Forwarded Headers 配置，避免不安全请求头被透传；
5. 通读其余 配置项总览。

十、总结

裸机部署 Authelia 的完整链路可以概括为：选择发行版安装途径（APT/.deb、AUR、Nix、FreeBSD 包或官方二进制）→ 使用官方 systemd/rc.d 服务单元托管守护进程 → 通过--config指定并初始化静态配置 → 置于 HTTPS 反向代理之后并正确设置转发头 → 按生产清单加固密钥与访问控制。仓库中的 authelia.service、authelia@.service、authelia-fb-rc.d 三份服务文件既是可直接使用的托管方案，也是理解 Authelia 运行方式（配置路径、健康检查环境变量、最小权限加固）的最佳源码级参考；配合 Get started 指南 与 制品签名文档，即可在裸机上构建一套来源可信、权限收敛、可长期维护的 SSO 门户。

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