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.mdDocker通过容器镜像交付最省事适合大多数场景Kubernetes适合需要编排、自动伸缩的集群环境Bare-Metal将 Authelia 作为系统守护进程daemon直接运行在宿主机上适合已有传统运维体系、不便引入容器层的环境。Authelia 本体就是一个编译好的单一二进制程序因此它可以像其他守护进程一样被 systemdLinux或 rc.dFreeBSD托管。官方文档明确指出除 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因为该流程依赖会话 CookieOpenID 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] DescriptionAuthelia authentication and authorization server Documentationhttps://www.authelia.com Aftermulti-user.target [Service] Userauthelia Groupauthelia UMask027 EnvironmentAUTHELIA_SERVER_DISABLE_HEALTHCHECKtrue ExecStart/usr/bin/authelia --config /etc/authelia/configuration.yml SyslogIdentifierauthelia CapabilityBoundingSet NoNewPrivilegesyes RestrictNamespacesyes ProtectHometrue PrivateDevicesyes PrivateUsersyes ProtectControlGroupsyes ProtectKernelModulesyes ProtectKernelTunablesyes SystemCallArchitecturesnative SystemCallFiltersystem-service SystemCallErrorNumberEPERM [Install] WantedBymulti-user.target关键点逐一说明Userauthelia/Groupauthelia以专用低权限账号运行需要在安装时预先创建该系统用户与用户组UMask027限制新建文件权限防止配置文件、日志等被其他用户读取EnvironmentAUTHELIA_SERVER_DISABLE_HEALTHCHECKtrue对应配置项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 边界、NoNewPrivilegesyes、RestrictNamespacesyes、ProtectHometrue、PrivateDevicesyes、PrivateUsersyes、ProtectControlGroups/KernelModules/KernelTunablesyes、SystemCallArchitecturesnative、SystemCallFiltersystem-service配合SystemCallErrorNumberEPERM拒绝集合外系统调用。这套组合把 Authelia 进程的权限面压缩到最小是值得在自己编写的服务单元中借鉴的加固模板SyslogIdentifierauthelia日志统一以authelia标识写入 journald[Install] WantedBymulti-user.targetsystemctl enable时在multi-user.target下建立开机自启依赖。3.2 模板单元 authelia.service多实例场景authelia.service 与单实例版本几乎一致仅两处不同ExecStart/usr/bin/authelia --config /etc/authelia/configuration.%i.yml%i是 systemd 的实例名占位符。启动autheliatenant1时实际加载/etc/authelia/configuration.tenant1.ymlSyslogIdentifierauthelia-%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 autheliatenant1.service。四、Arch LinuxAUR 包除官方发布的二进制外Arch Linux 用户还可以通过AURArch 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 密钥签名关键指纹信息与文档一致主密钥 ID192085915BD608A458AC58DCE461FA1531286EEA加密子密钥7DBA42FED0069D5828A44079975E8FFC6876AFBB签名子密钥C387CC1B5FFC25E55F75F3E6A228F3BD04CC9652密钥所有者Authelia Security securityauthelia.com/teamauthelia.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 securityauthelia.com uid [ unknown] Authelia Security teamauthelia.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_*.debDebian 包同样由上述 GPG 密钥签名可参照 Artifact Signing and Provenance Overview 的校验流程验证完整性。六、Nixnixpkgs-unstable 通道使用 Nix 包管理器时Authelia 通过nixpkgs-unstable通道提供。官方文档特别提醒该通道本身是 unstable不稳定的且这是第三方打包的软件包生产环境使用前需评估。nix-channel --add https://nixos.org/channels/nixpkgs-unstable nix-channel --update nix-env -iA nixpkgs.authelia七、FreeBSDrc.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 nameauthelia rcvarauthelia_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 框架托管rcvarauthelia_enable意味着需要在/etc/rc.conf中设置authelia_enableYES才能开机启动默认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生产推荐 PostgreSQLsession配置会话 Cookie 的domain、authelia_url与secret生产环境推荐 Redis 存储notifier发送 2FA 注册邮件的通知器SMTP 为生产推荐仅可配置其一access_control初始可用最简策略起步例如access_control: default_policy: deny rules: - domain: *.example.com policy: one_factor9.3 从裸机走向生产环境的检查清单Get started 指南给出了明确的迁移建议裸机部署同样适用将所有机密值从配置文件迁移到环境变量/密钥文件见 配置方法 - secrets花时间理解并精细化配置 access control阅读 Security Measures 与 Threat Model 文档检查前置代理的 Forwarded Headers 配置避免不安全请求头被透传通读其余 配置项总览。十、总结裸机部署 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考