
Authelia CLI 根命令完全指南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 官方参考文档 authelia.md 为骨架深入剖析authelia命令本身的用法包括命令行语法、多配置文件/目录加载机制、配置过滤器filters、以及access-control、build-info、config、crypto、debug、storage六大子命令体系的整体结构。读完本文你将掌握如何正确启动 Authelia 服务、如何组织配置文件、如何利用内置帮助主题与子命令完成日常运维并能理解其命令行实现背后的源码逻辑。命令概述Synopsisauthelia是 Authelia 的守护进程入口命令负责为你的 Web 应用提供认证与授权能力。官方描述如下An open-source authentication and authorization server providing two-factor authentication and single sign-on (SSO) for your applications via a web portal.即这是一个开源的身份认证与授权服务器通过 Web 门户为你的应用提供双因素认证2FA与单点登录SSO。在命令帮助中版本信息会被动态填充例如文档中显示的authelia untagged-unknown-dirty (master, unknown)表示当前构建来自 master 分支、未打 tag 的开发版本。该字符串由 root.go 中的utils.Version()生成并注入到cobra.Command的Short、Long与Version字段中。命令语法极为简单authelia [flags]根命令不接受位置参数源码中通过Args: cobra.NoArgs强制约束见 root.go所有行为均由 flags 与子命令驱动。典型使用示例Examples参考文档给出了三种典型的启动方式分别对应多文件列表、逗号分隔列表与配置目录三种配置输入形态# 方式一重复使用 --config 指定多个配置文件 authelia --config /etc/authelia/config.yml --config /etc/authelia/access-control.yml # 方式二使用逗号分隔的单个 --config 参数 authelia --config /etc/authelia/config.yml,/etc/authelia/access-control.yml # 方式三直接加载整个配置目录 authelia --config /etc/authelia/config/这三种写法在语义上是等价的背后是同一个字符串切片StringSliceP标志。其中方式三加载目录时Authelia 会读取该目录下所有具有相关扩展名的文件非递归且目录中的文件按字典序加载多个文件之间遵循后者覆盖前者的合并语义——如果同一个配置项在多个文件中都出现后加载的文件中的值生效。命令行选项Options根命令仅暴露两个全局标志外加每个命令都有的--help选项简写类型默认值说明--config-cstrings[configuration.yml]要加载的配置文件或目录列表运行authelia -h authelia config可查看详细帮助--config.experimental.filters—strings空应用到所有配置文件上的过滤器列表运行authelia -h authelia filters可查看详细帮助--help-h——显示 authelia 帮助这两个标志是持久化标志PersistentFlags意味着它们会被所有子命令继承——这解释了为何每一个子命令的帮助输出中都会出现 Options inherited from parent commands 一节如 authelia storage 所示。从源码角度看这两个标志在 root.go 中定义cmd.PersistentFlags().StringSliceP(cmdFlagNameConfig, c, []string{configuration.yml}, ...)默认加载当前工作目录下的configuration.ymlcmd.PersistentFlags().StringSlice(cmdFlagNameConfigExpFilters, nil, ...)默认不启用任何过滤器。对应的环境变量分别为X_AUTHELIA_CONFIG与X_AUTHELIA_CONFIG_FILTERS见 const.go。配置加载的层级模型运行authelia -h authelia config或authelia --help config可以查看内建帮助主题helpTopicConfig定义于 const.go。它明确阐述了 Authelia 配置的分层加载模型各层按顺序加载后一层对前一层进行覆盖File/Directory Paths文件/目录路径通过--configCLI 参数或X_AUTHELIA_CONFIG环境变量指定两者均为逗号分隔列表。注意如果环境变量与 CLI 参数同时指定环境变量会被完全忽略。目录加载是非递归的目录中所有具有相关扩展名的文件都必须是语法合法的 Authelia 配置文件。Environment Variables环境变量大多数配置项都可以通过环境变量指定映射规则见项目文档。Secrets密钥文件所有以key、secret、password、token结尾的配置键都可以通过指向文件路径的环境变量方式加载实现敏感信息与配置文件的解耦。配置过滤器Filters--config.experimental.filters是一个用于模板化配置文件的实验性系统其完整说明位于帮助主题helpTopicConfigFilters见 const.go过滤器在文件数据从文件系统加载之后、被对应格式解析器解析之前应用过滤器按用户指定的顺序依次处理当日志级别设为 trace 时每个配置文件的内容会以 base64 原始字符串形式记录便于调试。当前提供两种过滤器template基于 Go 模板系统过滤文件除标准函数外还内置了若干自定义函数以简化配置编写expand-env已弃用DEPRECATED将配置中${DOMAIN_NAME}形式的占位符替换为同名环境变量的值不存在则为空字符串官方建议迁移到template过滤器。源码中在加载过滤器时会对此发出显式告警Experimental file filter expand-env is deprecated in favor of the template filter见 context.go。你可以使用authelia config template子命令配合过滤器对配置进行模板化渲染调试详见 authelia config template。启动流程的源码级拆解authelia入口极简main()调用commands.NewRootCmd().Execute()并针对ErrConfigCreated这一特殊错误返回退出码 0表示已自动生成默认配置其余错误返回退出码 1见 main.go。根命令的真正逻辑在于PreRunE中串联的一条初始化链root.go通过ctx.ChainRunE见 context.go依次执行ConfigEnsureExistsRunE确保配置文件存在若指定的默认配置路径不存在会自动生成一份默认配置并提示用户配置这正是ErrConfigCreated的来源见 context.goHelperConfigLoadRunE将文件、过滤器、环境变量、默认值等所有来源合并加载为最终配置见 context.goLogConfigure根据加载后的配置初始化日志级别、格式、文件路径LogProcessCurrentUserRunE记录进程运行时的用户信息UID/GID 等便于排查权限问题HelperConfigValidateKeysRunE/HelperConfigValidateRunE先后校验配置键的合法性含弃用键映射检查与配置结构的语义正确性ConfigValidateLogRunE将校验产生的警告与错误输出到日志若有错误则中止启动。随后RootRunEroot.go会加载所有 Provider认证后端、存储、通知器等执行启动自检Startup Checks最终通过service.RunAll(ctx)拉起全部服务HTTP 服务器、文件监视器等。整个根命令基于 Cobra 框架构建并禁用了自动生成标签DisableAutoGenTag: true保证了帮助输出的一致性。子命令体系SEE ALSOauthelia是一个典型的父命令 子命令聚合结构共有 6 个一级子命令覆盖运行、运维与调试三大场景。所有子命令都继承父级的--config与--config.experimental.filters标志。authelia access-control访问控制系统的辅助工具用于检查请求与访问控制规则的匹配情况。参考文档authelia access-control典型用法authelia access-control check-policy --config config.yml --url https://example.com --username john --groups admin,public --method GET --verbose输出会标明规则在配置中的位置#、首个完全匹配的规则*以及潜在匹配~等图例信息。authelia build-info显示 Authelia 二进制的构建信息对排障至关重要——尤其是当你使用的不是某个 tagged 正式版时官方建议在提交 issue 时附带该输出。参考文档authelia build-info典型用法authelia build-info支持-v/--verbose输出更详细的信息如 Go 版本、模块路径、可执行文件路径。底层信息由 CI 构建时注入二进制包含 Last Tag、State、Branch、Commit、Build Number、Build OS/Arch、Build Compiler、Build Date、Development 等字段格式定义见 const.go。authelia config配置相关的操作集合目前包含两个子命令详见 authelia configauthelia config template配合过滤器对配置文件进行模板化渲染参考文档注意需在与正常运行 Authelia 相同的环境变量与工作路径下执行才有意义authelia config validate在部署前用内部配置校验机制检查 YAML 与环境变量配置参考文档典型用法authelia config validate --config config.yml。authelia crypto执行密码学操作用于生成随机字符串、哈希摘要、证书与密钥对等详见 authelia crypto下设 4 个子命令authelia crypto rand生成加密安全随机字符串可用于加密密钥、HMAC 密钥等支持--charset指定字符集ascii、alphanumeric、alphabetic、numeric、numeric-hex、rfc3986authelia crypto hash哈希摘要的生成与校验支持argon2、sha2crypt、pbkdf2、bcrypt、scrypt五种算法其中authelia crypto hash generate取代了旧版authelia hash-password命令旧命令的说明见帮助主题helpTopicHashPasswordconst.goauthelia crypto certificate证书操作支持rsa、ecdsa、ed25519、mldsa后量子密码学算法四种算法每种又分generate与request生成 CSR两类authelia crypto pair密钥对操作同样覆盖上述四种算法。authelia debug调试辅助功能包括authelia debug tls检查远程服务器的 TLS 配置与证书有效性例如authelia debug tls tcp://smtp.example.com:465authelia debug expression针对特定用户检查用户属性表达式例如authelia debug expression username abc in groupsauthelia debug oidc/authelia debug oidc claims调试 OpenID Connect 1.0 场景与 claims 水合hydration过程。详见 authelia debug 及其子页面。authelia storage管理 Authelia 的 SQL 存储详见 authelia storage。这是运维最常用的命令组提供大量本需手工操作数据库才能完成的进阶功能官方描述为允许执行若干手工操作难度极高的高级操作。它支持三种数据库后端并允许通过 CLI 标志覆盖存储连接参数也可直接依赖配置文件标志默认值说明--sqlite.path—SQLite 数据库路径--mysql.addresstcp://127.0.0.1:3306MySQL 服务器地址--mysql.databaseautheliaMySQL 数据库名--mysql.username/--mysql.passwordauthelia/ 空MySQL 用户名与密码--postgres.addresstcp://127.0.0.1:5432PostgreSQL 服务器地址--postgres.database/--postgres.schemaauthelia/publicPostgreSQL 数据库名与 schema 名--postgres.username/--postgres.passwordauthelia/ 空PostgreSQL 用户名与密码--encryption-key—存储加密密钥其子命令涵盖bans用户/IP 封禁管理、cache mds3WebAuthn MDS3 元数据缓存管理、encryption存储加密密钥的检查、更换与 HMAC 密钥轮换、migrate数据库 schema 迁移up/down/history/list-up/list-down、schema-info存储 schema 诊断信息、user identifiersOIDC 不透明标识符的导入/导出/生成/添加、user totpTOTP 配置的生成、删除、导入导出支持 CSV/URI/PNG 二维码格式、user webauthnWebAuthn 凭据的增删查改与导入导出。使用这些命令前Authelia 会通过CheckSchema见 context.go校验数据库 schema 版本与加密密钥避免在不兼容的存储上执行操作。内置帮助主题Help Topics除子命令外根命令还注册了 5 个特殊的帮助主题通过authelia -h authelia topic或authelia --help authelia topic调用注册代码见 root.go帮助主题说明config配置文件/目录路径与分层加载模型的完整说明filters配置文件过滤器template、expand-env的使用说明time-layouts各命令接受的时间输入格式说明支持 Unix 秒/毫秒/微秒时间戳以及多种日期时间布局如 RFC3339、RFC1123、Ruby Date、ANSIC 等见 const.gohash-password说明旧版authelia hash-password命令已由authelia crypto hash generate取代及原因time-layouts之外的config与filters主题均已在上述配置章节详述—这些帮助主题使得不熟悉配置机制的用户无需翻阅外部文档即可在终端内获取关键信息是根命令体验设计的重要组成部分。总结authelia根命令虽然只暴露了--config与--config.experimental.filters两个全局标志却是整个 Authelia 控制面的枢纽它负责完成从配置加载、校验到 Provider 初始化、服务启动的完整生命周期同时通过六大子命令将访问控制检查、构建信息、配置管理、密码学操作、调试与存储运维全部纳入统一的 CLI 体系。无论你是首次部署 Authelia还是需要执行存储迁移、密钥轮换等高级运维操作理解本文梳理的命令结构、配置分层模型与内置帮助主题都能让你更高效、更安全地驾驭这套开源 SSO 门户。继续深入阅读authelia access-control · authelia build-info · authelia config · authelia crypto · authelia debug · authelia storage【免费下载链接】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),仅供参考