Authelia Helm Chart 使用指南：在 Kubernetes 上快速集成 Authelia 单点登录-港品优选

Authelia Helm Chart 使用指南：在 Kubernetes 上快速集成 Authelia 单点登录

【免费下载链接】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 官方提供了 Helm Chart 为主线，完整讲解 Chart 仓库的添加方式、签名验证流程，并结合仓库中 Kubernetes 集成文档（introduction.md、secrets.md）补充部署前的关键注意事项，帮助你在集群中正确、安全地完成 Authelia 的 Helm 化部署。

Chart 概览：用 Helm 简化 Authelia 的 Kubernetes 集成

Authelia 官方 Helm Chart 的设计目标很明确：把 Authelia 在 Kubernetes 上的部署、配置注入、密钥管理等繁琐环节封装成声明式的 Helm 模板，让用户可以像安装其他云原生应用一样完成 Authelia 的交付。

需要特别留意的是，官方文档明确声明该 Chart目前仍处于 beta 状态，因此在后续演进过程中可能出现破坏性变更（breaking changes）。这意味着：

升级 Chart 时不能想当然地认为 API 兼容，需要关注发布说明；
生产环境使用前应结合版本策略评估风险；
当前仓库的路由图文档 kubernetes-documentation.md 也印证了这一状态：Helm Chart 功能虽已被标记为complete，但仍属于“pre-release（预发布）”，只有少数次要项尚待 v1 完成。

对于首次部署 Authelia 的用户，官方强烈建议先通读 Get started 指南。该指南覆盖了引导 Authelia 所需的一系列关键步骤，例如必须通过https协议提供服务、代理配置必须包含全部 Required Headers、以及 jwt_secret、authentication_backend、storage、session、notifier、access_control 等初始配置项——这些内容不因使用 Helm Chart 而省略，Chart 只负责交付载体，配置语义仍然遵循 Authelia 本身。

添加 Chart 仓库

Authelia Helm Chart 的官方仓库地址为https://charts.authelia.com。使用前需要先将其添加到本地 Helm 仓库列表并刷新索引：

helm repo add authelia https://charts.authelia.com helm repo update

其中：

helm repo add authelia <URL>将 Chart 仓库以别名authelia注册到本机（仓库名可自定义，但建议保持authelia以与后续文档一致）；
helm repo update从已注册的仓库拉取最新的 Chart 索引，确保你能检索到最新版本。

完成上述两步后，该仓库即可作为普通的 Helm Chart 源使用。官方 Chart 仓库同时具备以下特性：

签名发布：Chart 按照 Artifact Signing and Provenance 中描述的机制进行签名，验证密钥同样可以在该文档中找到；
静态网站：https://charts.authelia.com同时托管了一个展示基本 Chart 信息的网站，可用来快速浏览可用版本与元数据。

验证 Chart 的真实性与签名

供应链安全是 Authelia 一贯强调的重点。官方 Chart 的签名遵循 Artifact Signing and Provenance 中描述的整体制品签名体系。该文档给出了 Authelia 制品签名所用的专用 GPG 密钥信息，包括：

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

你可以在仓库的 docs/static/keys 目录下找到对应的密钥文件（authelia-security.gpg与authelia-security.asc），用于本地验证下载制品的完整性。以官方发布制品的校验为例，标准的验证流程是先下载 checksums 及其签名，再执行：

gpg --verify checksums.sha256.sig checksums.sha256 && sha256sum --ignore-missing -c checksums.sha256

验证通过后，输出中会显示Good signature from "Authelia Security <security@authelia.com>"以及主密钥指纹。需要注意的是，如果本地没有手动信任 Authelia 的 GPG 密钥，GPG 会提示The key's User ID is not certified with a trusted signature!，这是正常现象，不影响对制品真实性与完整性的验证结论。

此外，Authelia 还为其发布制品（.tar.gz、.deb等）生成并签名符合 SLSA Build Level 3 的 Provenance 元数据，可使用 slsa-verifier 进行校验；不过 SLSA Provenance 覆盖的是发布制品，不包含构建出的 Docker 镜像，这一点在使用 Chart 拉取镜像时需自行评估信任边界。

Chart 源码与贡献

Helm Chart 的源码托管在 GitHub 上的authelia/chartrepo仓库中。如果你在使用过程中发现问题，或者希望改进 Chart 本身，官方欢迎通过 contributing 指南参与贡献。在动手贡献前，建议先阅读仓库的贡献规范，确保提交符合项目的风格与流程要求。

部署前的关键 Kubernetes 注意事项

即使使用 Helm Chart，以下来自 Kubernetes 集成文档的注意事项仍然直接影响部署质量，尤其是“Authelia 配置管理系统与 Kubernetes 默认行为冲突”的两点：

关闭 enableServiceLinks

Authelia 的配置管理系统与 Pod 的enableServiceLinks选项存在冲突——当该选项为默认值true时，Kubernetes 会把集群内 Service 信息以环境变量形式注入容器，这些环境变量可能干扰 Authelia 基于环境变量的配置解析。因此必须将其设置为false。官方给出的 Pod 示例：

--- apiVersion: v1 kind: Pod metadata: name: authelia spec: enableServiceLinks: false ...

好消息是：官方 Helm Chart已经自动处理了这一点。正如配置迁移文档 migration.md 中的提示所述，只有在 Kubernetes 上部署 Authelia 但不使用官方 Helm Chart（例如手写清单或使用 Kustomize）时，才需要你手动配置enableServiceLinks。这正体现了 Chart 封装的价值。

配置 externalTrafficPolicy 为 local

如果处理流量进入 Kubernetes Ingress 的 Service 没有将externalTrafficPolicy配置为local，Authelia 以及其他所有应用都可能拿到无效的远端 IP（remote IP）。这对于依赖客户端 IP 进行访问控制、速率限制等功能的场景至关重要，请参照 Kubernetes 官方文档中关于保留客户端源 IP（preserving the client source IP）的说明进行配置。

预留足够内存：argon2id 的 1GB 默认开销

使用文件（YAML）认证后端时，argon2id 密码哈希算法默认情况下会为密码生成过程使用1GB 内存。这意味着：

你的 Deployment/DaemonSet 资源规格中应至少预留这么多内存；
所在节点也必须有足够的内存可用；
否则登录过程中 Authelia 可能因内存不足（OOM）而被杀死。

可以通过调整文件认证后端的 memory 配置来降低该开销。例如将authentication_backend.file.password.argon2.memory调低，使其与你的集群资源匹配。

Chart 自动生成并注入 Secrets

使用 Helm Chart 的另一个直接收益体现在密钥管理上：正如 secrets.md 所述，Helm Chart 会自动生成并注入 Authelia 部署所需的 Secrets，无需手工创建 Secret 对象。

作为对比，不使用 Chart 的手动清单部署方式则需要显式创建 Secret，其中包含的密钥项（对应 Secrets 配置方法中以key、secret、password、token、certificate_chain结尾的配置键）包括但不限于：

Secret 键	对应 Authelia 配置键（环境变量形式）
`JWT_SECRET`	`AUTHELIA_JWT_SECRET_FILE`
`SESSION_SECRET`	`AUTHELIA_SESSION_SECRET_FILE`
`REDIS_PASSWORD`	`AUTHELIA_SESSION_REDIS_PASSWORD_FILE`
`REDIS_SENTINEL_PASSWORD`	`AUTHELIA_REDIS_HIGH_AVAILABILITY_SENTINEL_PASSWORD_FILE`
`LDAP_PASSWORD`	`AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD_FILE`
`STORAGE_PASSWORD`	`AUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE`等
`STORAGE_ENCRYPTION_KEY`	`AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE`
`SMTP_PASSWORD`	`AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE`
`DUO_SECRET_KEY`	`AUTHELIA_DUO_API_SECRET_KEY_FILE`
`OIDC_HMAC_SECRET`	`AUTHELIA_IDENTITY_PROVIDERS_OIDC_HMAC_SECRET_FILE`
`OIDC_ISSUER_PRIVATE_KEY`	`AUTHELIA_IDENTITY_PROVIDERS_OIDC_ISSUER_PRIVATE_KEY_FILE`

手动部署时，Secret 的值通过以_FILE结尾的环境变量以文件路径方式注入容器（这是 Authelia 推荐的 Secrets 配置方法，避免在环境变量中以明文暴露密钥）。另外需要特别注意：不能为未使用的 Provider 定义 Secret——例如使用 filesystem notifier 时，就不应再设置AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE，否则 Authelia 将拒绝启动。这一约束同样适用于 storage、authentication backend 等 Provider，具体可参见 Secrets 配置方法中关于“配置层”的说明。

版本策略与升级注意

由于 Chart 目前处于 beta 阶段，升级时需要额外谨慎：

关注 Chart 发布说明中的 breaking changes 提示；
结合仓库的版本策略文档理解 Authelia 的版本化承诺范围；
若从手动清单/Kustomize 方式迁移到 Chart，可对照 migration.md 中的配置键变更表（如 4.30.0 中host→server.host、port→server.port等）核对你的配置是否仍然有效。

从仓库路由图看，Kustomize 方案已被标记为abandoned，官方明确将精力聚焦在 Helm Chart 上，因此Helm 是当前 Authelia 在 Kubernetes 上受官方推荐的交付方式，这本身也是对 Chart 路线的一种背书。

小结

通过官方 Helm Chart，你可以用两条命令完成 Chart 仓库接入，借助签名验证机制保障供应链安全，并让 Chart 自动处理enableServiceLinks、Secret 生成与注入等易错细节。部署之前，请务必核对externalTrafficPolicy、内存配额（argon2id 默认 1GB）等 Kubernetes 侧的前置条件，并留意 Chart 的 beta 状态带来的破坏性变更风险。相关完整资料可在 Kubernetes 集成文档、Secrets 指南与 Artifact Signing and Provenance 中继续深入。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析