Authelia 配置通用语法与数据结构完全指南Duration、Address、TLS 与 Server Buffers 深度解析【免费下载链接】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 作为面向 Web 应用的单点登录与多因素认证门户其配置系统横跨认证、授权、会话、存储、通知、OIDC 等多个模块。为了让这些模块共享一致的配置体验Authelia 定义了一套贯穿全配置体系的通用语法Common Syntax与通用数据结构Common Structures。本篇指南以 docs/content/configuration/prologue/common.md 为骨架系统讲解 Duration 时长语法、Address 监听/连接地址语法、正则表达式书写规范、Network 网段表示、TLS 配置结构、Server Buffers 与 Server Timeouts 结构并结合仓库源码如 internal/utils/time.go、internal/configuration/schema/types_address.go揭示底层解析原理。读完本文你将能够准确读懂 Authelia 任意配置文件中出现的时长、地址、TLS 段落并避免因 YAML 转义、IPv6 括号、单位缩写等细节而踩坑。说明本文所描述的通用语法与结构是跨模块复用的公共约定而非针对某个具体实例的配置指南各模块的专属参数请查阅对应模块文档如 server 等。文中引用的链接均已转换为以仓库根目录为起点的相对路径。语法Syntax以下通用语法在多个配置区域中被反复使用且对书写格式有明确要求。理解这些语法是正确配置 Authelia 的前提。字典引用语法Dictionary Reference字典引用语法适用于键名可由管理员任意指定且该键名可在其他位置被引用的场景。例如如果文档中标注policies是一个字典Dictionary那么其中的arbitrary_name键就是管理员自定义的任意名称它可以被其他地方引用——如下面示例中usage_example列表里的policy字段就通过arbitrary_name引用了上面定义的策略policies: arbitrary_name: enable: true usage_example: - name: example policy: arbitrary_name这种先定义、后引用的模式在 Authelia 的访问控制规则、OIDC 客户端、2FA 方法策略等场景中大量出现理解它能帮助你读懂名称从哪里来、被谁消费的配置关系。时长语法DurationDuration 是 Authelia 配置中最常见的通用语法之一其基础类型是字符串同时也接受整数但不推荐使用整数。整数被视为秒数。例如5400表示 5400 秒。字符串按数量 单位字母的块block解析例如5h表示 5 个h单位5 小时。解析时以下内容会被忽略或剔除所有空格前导零单词and。虽然支持将多个数量单位块组合使用如1h30m但官方建议保持简单、尽量使用单一值。同时需要提醒该格式虽具一定可读性仍需严格遵循预期的格式规范。单位对照表Unit Legend下表为时长语法支持的单位。长格式单位Long Unit如hours自 v4.38.0 起才可用单位短格式人类可读长格式年yyear,years月Mmonth,months周wweek,weeks天dday,days小时hhour,hours分钟mminute,minutes秒ssecond,seconds毫秒msmillisecond,milliseconds注意月M使用大写字母以避免与分钟m混淆。配置示例Examples期望值短格式配置示例长格式配置示例1 小时 30 分钟90m或1h30m或5400或5400s1 hour and 30 minutes1 天1d或24h或86400或86400s1 day10 小时10h或600m或9h60m或3600010 hours源码级解析原理从源码结构看时长的标准化与解析位于 internal/utils/time.goStandardizeDurationString 先将输入中的空格与and剔除再用正则reDurationStandard (?PDuration[1-9]\d*?)(?PUnit[^\d\s])定义于 internal/utils/const.go将输入切分为数量单位块逐块调用standardizeQuantityAndUnits转换。该正则以[1-9]开头、不允许前导零恰好印证了文档中忽略前导零的行为。对于 Go 标准库time.ParseDuration不认识的单位如天、周、月、年standardizeQuantityAndUnitsinternal/utils/time.go会将其换算为小时1 天 24h、1 周 168h、1 月 730h、1 年 8760h。ParseDurationString 会先判断输入是否为纯数字^\d$若是则按秒处理time.Second * duration否则走标准化流程后交给time.ParseDuration。在配置反序列化阶段internal/configuration/decode_hooks.go 中的 DecodeTimeDuration 负责将配置值转换为time.Duration其中字符串分支调用utils.ParseDurationString整数分支同样按秒计算并通过durationMax time.Duration(math.MaxInt64)见 internal/configuration/const.go做最大值校验。因此你在配置里写6s、30s、1h30m或纯整数5400最终都会被统一归一化到纳秒级的time.Duration。地址语法Address地址类型的基础类型也是字符串。它用于描述两类对象监听器Listener即服务监听连接的一端例如 HTTP 服务器监听的地址连接器Connector即发起远程连接的一端例如 LDAP、SMTP 客户端连接的远端地址。查询参数Query Parameters部分 scheme 支持查询参数参数以?附加在地址之后多个参数用连接参数监听器连接器用途umask是否在创建 socket 前设置 umask创建完成后恢复原值。取值必须是 3 或 4 位八进制数字。path是否设置子路径变量主要用于 unix socket但对 TCP 也技术性生效。注意只需填写字母数字部分不要以正斜杠/前缀。格式Format地址格式使用传统的 POSIX 记法表示可选与必填部分方括号[]包裹可选部分尖括号包裹必填部分。必填部分也可能出现在可选部分之内此时通常伴随其他格式说明文字指示若该文字存在则该部分实际必填否则整体可选。另外需要说明某部分可选仅指解析层面配置校验层面可能仍要求必须提供其中一项。Hostname 格式同时适用于监听器与连接器大多数场景。scheme 与 port 可选未提供时的默认值因选项而异[scheme://]hostname[:port][/path]Port 格式大多数场景下仅适用于监听器。scheme 与 hostname 可选scheme 未提供时默认值因选项而异hostname 未提供时默认为所有可用地址[scheme://][hostname]:port[/path]文件描述符格式File Descriptors仅适用于监听器且无可选部分。该格式接受查询字符串由上文查询参数控制其行为fd://file descriptor numberfd://file descriptor number?umask0022fd://file descriptor number?pathauthfd://file descriptor number?umask0022pathauthUnix 域套接字格式Unix Domain Socket适用于监听器与连接器大多数场景无可选部分。同样接受查询字符串unix://pathunix://path?umask0022unix://path?pathauthunix://path?umask0022pathauth示例Examples0.0.0.0 tcp://0.0.0.0 tcp://0.0.0.0/subpath tcp://0.0.0.0:9091 tcp://0.0.0.0:9091/subpath tcp://:9091 tcp://:9091/subpath 0.0.0.0:9091 udp://0.0.0.0:123 udp://:123 unix:///var/lib/authelia.sock示例中的端口9091为 Authelia 默认 HTTP 端口文档站点使用 sitevar 变量按版本注入实际值以当前版本为准。scheme整个 scheme 是可选的但一旦字符串中出现 scheme 与 host 的分隔符://则 scheme 必须存在。scheme 必须是下列之一监听器/连接器列表示该 scheme 在对应地址类型上的支持情况scheme监听器连接器默认端口说明tcp是是N/A标准 TCP socket允许 IPv4 和/或 IPv6 地址tcp4是是N/A标准 TCP socket仅允许 IPv4 地址tcp6是是N/A标准 TCP socket仅允许 IPv6 地址udp是是N/A标准 UDP socket允许 IPv4 和/或 IPv6 地址udp4是是N/A标准 UDP socket仅允许 IPv4 地址udp6是是N/A标准 UDP socket仅允许 IPv6 地址unix是是N/A标准 Unix 域套接字仅允许绝对路径ldap否是389通过 TCP socket 的远端 LDAP 连接可用时使用 StartTLSldaps否是636通过 TLS socket 的远端 LDAP 连接ldapi否是N/A通过 Unix 域套接字的 LDAP 连接smtp否是25通过 TCP socket 的远端 SMTP 连接可用时使用 StartTLSsubmission否是587通过 TCP socket 的远端 SMTP Submission 连接可用时使用 StartTLSsubmissions否是465通过 TLS socket 的远端 SMTP Submission 连接scheme 缺失时的默认推断规则若地址以/前缀开头则推断为unix否则推断为tcp若 scheme 为unix则必须以绝对路径作为后缀例如/var/run/authelia.sock应写作unix:///var/run/authelia.sock注意unix://之后是三斜杠因为路径本身以/开头。hostname当 scheme 为tcp或udp且未指定 port 时hostname 为必填。它可以是任意本机可寻址的 IP或解析到本机可寻址 IP 的主机名。指定 IPv6 时必须用方括号包裹。例如 IPv6 地址::1搭配tcpscheme 与端口80的正确写法是tcp://[::1]:80port当 scheme 为tcp或udp且未指定 hostname 时port 为必填。源码级解析原理地址解析的核心实现在 internal/configuration/schema/types_address.goNewAddressDefault 是解析入口先用正则判断字符串是否携带 schemeregexpHasScheme有则直接交给url.Parse否则若以/开头就自动补unix://前缀其余情况补tcp://前缀——这正是文档中以/前缀推断为 unix、否则推断为 tcp规则的代码实现。NewAddressFromURL 等函数负责将url.URL校验并转换为内部Address结构定义于同文件 L190。空字符串会被解析为tcp://:0形式见 NewAddressDefault 的边界处理。对于 SMTP 类地址NewSMTPAddress 演示了默认端口的回退逻辑port 为 0 时按 scheme 回退到 465/587/25scheme 为空时按端口反推 scheme。在反序列化链路中StringToAddressHookFunc 注册于 internal/configuration/decode_hooks.go 的 decode hooks 列表负责把字符串自动转换为地址类型。也就是说你在配置文件中写下的每一个地址字符串最终都会经过上述解析流程变成结构化的网络地址对象。正则表达式Regular ExpressionsAuthelia 多处配置使用正则表达式采用Google RE2 正则引擎即 Go 标准库正则语法引擎。它与 PCRE、Perl、Python 等引擎非常相似主要区别是不支持回溯backtracking。官方建议手动验证正则可使用 Regex 101 之类的工具并务必选择Golang选项或用其他手段验证。反斜杠转义陷阱使用反斜杠时必须格外小心YAML 解析器很可能把反斜杠当作 YAML 转义语法而非正则转义语法。为了避免这一问题请使用单引号而不是无引号或双引号。正确示例domain_regex: ^(admin|secure)\.example\.com$错误示例domain_regex: ^(admin|secure)\.example\.com$上面的错误示例中双引号内的\.会被 YAML 当作转义序列处理导致最终传给 RE2 的模式与预期不符。网络NetworkAuthelia 支持将字符串反序列化为网段network range的网络语法。字符串使用标准CIDR 记法若省略 CIDR 后缀则默认视为单个主机IPv4 适配为 /32IPv6 适配为 /128。示例CIDR范围192.168.0.1192.168.0.1/32192.168.0.1192.168.1.0/24192.168.1.0/24192.168.1.0 - 192.168.1.255192.168.2.1/24192.168.2.0/24192.168.2.0 - 192.168.2.2552001:db8:3333:4444:5555:6666:7777:88882001:db8:3333:4444:5555:6666:7777:8888/1282001:db8:3333:4444:5555:6666:7777:88882001:db8:3333:4400::/562001:db8:3333:4400::/562001:0db8:3333:4400:0000:0000:0000:0000 - 2001:0db8:3333:44ff:ffff:ffff:ffff:ffff2001:db8:3333:4444:5555:6666:7777:8888/562001:db8:3333:4400::/562001:0db8:3333:4400:0000:0000:0000:0000 - 2001:0db8:3333:44ff:ffff:ffff:ffff:ffff注意上表中两个值得留意的归一化行为192.168.2.1/24会被归一化为网络地址192.168.2.0/24覆盖192.168.2.0 - 192.168.2.255整个子网带前缀长度的 IPv6 地址同样会被归一化到该前缀的网络边界如2001:db8:3333:4444:5555:6666:7777:8888/56等价于2001:db8:3333:4400::/56。数据结构Structures以下通用数据结构在多个配置区域被复用各自具有明确的字段要求。TLS配置中多个区域使用统一的tls配置结构用于配置 TLS socket 与 TLS 校验参数。默认情况下Authelia 使用系统证书信任库进行 TLS 证书校验你可以通过全局的 certificates_directory 选项扩充信任库也可以通过下面的 skip_verify 完全关闭 TLS 证书校验。tls: server_name: example.com skip_verify: false minimum_version: TLS1.2 maximum_version: TLS1.3 certificate_chain: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- private_key: | -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----server_name类型string非必填。server_name会覆盖证书校验过程中用于比对证书的名称。当后端服务的主机地址需要使用 IP 时这一选项尤为有用——你可以连接 IP但校验特定的证书服务器名称。skip_verify类型boolean默认false非必填。skip_verify会完全跳过对后端服务证书的校验。不推荐使用。更合理的做法是调整server_name选项以及全局的 certificates directory。minimum_version类型string默认TLS1.2非必填。控制 Authelia 执行 TLS 握手时使用的最低 TLS 版本。可选值为TLS1.3、TLS1.2、TLS1.1、TLS1.0、SSL3.0。除TLS1.3与TLS1.2之外的值都非常古老且已废弃应避免使用——正确做法是升级后端服务而不是降低此值。截至撰写本文时SSL3.0在任何情况下都会产生错误。从源码看schema 层的默认值被定义为MinimumVersion: TLSVersion{tls.VersionTLS12}见 internal/configuration/schema/authentication.go 等多处与文档默认值一致。maximum_version类型string默认TLS1.3非必填。控制 Authelia 执行 TLS 握手时使用的最高 TLS 版本。可选值同上TLS1.3、TLS1.2、TLS1.1、TLS1.0、SSL3.0同样不建议使用除TLS1.3与TLS1.2以外的值。certificate_chain类型string非必填secret 类型参见下文 private_key 说明。与 private_key 配合使用用于与服务器进行双向 TLSmTLS认证的证书链/证书包。取值必须是一个或多个以DER base64RFC4648编码的 PEM 格式证书。若提供多个证书按自上而下的顺序每个证书必须由下一个证书若提供签名。private_key类型string非必填secret敏感值。与 certificate_chain 配合用于双向 TLS 认证的私钥。该私钥的公钥材料必须与 certificate_chain 中第一个证书的私钥匹配。取值必须是一份以 DER base64RFC4648编码的 PEM 格式私钥并必须符合 PKCS#8、PKCS#1 或 SECG1 规范之一。引用规范PKCS#8 见 RFC 5208PKCS#1 见 RFC 8017SECG1 见 RFC 5915RFC4648 见 RFC 4648此处仅给出规范名称不展开外部链接。Server Buffers配置中多个区域使用统一的buffers结构来配置 HTTP 服务器缓冲区典型使用者包括 server 与 metrics telemetry 两个配置段。buffers: read: 4096 write: 4096read类型integer默认4096非必填。配置最大请求大小单位为字节。默认值 4096 对大多数场景已足够。write类型integer默认4096非必填。配置最大响应大小单位为字节。默认值 4096 对大多数场景已足够。Server Timeouts配置中多个区域使用统一的timeouts结构来配置 HTTP 服务器超时典型使用者包括 server 与 metrics telemetry 两个配置段。timeouts: read: 6s write: 6s idle: 30sread类型string,integer语法duration默认 6 秒非必填。配置服务器读取超时。注意其值必须遵循上文时长语法书写。write类型string,integer语法duration默认 6 秒非必填。配置服务器写入超时。idle类型string,integer语法duration默认 30 秒非必填。配置服务器空闲超时。这三个字段的默认值6s、6s、30s是时长语法在真实配置中的典型应用——它们会被 DecodeTimeDuration 反序列化为 Go 的time.Duration并作用于底层 HTTP 服务器。历史锚点Historical References原文档末尾保留了对历史锚点的引用其中 Duration Notation Format 一节即指向本文的时长语法小节用于维持旧版文档链接的兼容性。结语把这些通用要素串起来掌握 Authelia 的通用语法与数据结构后你会发现整个配置体系的公共词汇表已经打通任何时长类参数超时、刷新间隔、会话有效期都遵循 Duration 语法底层由 internal/utils/time.go 与 internal/configuration/decode_hooks.go 负责归一化任何地址类参数监听端口、LDAP/SMTP 连接、unix socket都遵循 Address 语法底层由 internal/configuration/schema/types_address.go 负责解析其中tcp4/tcp6、ldap/ldaps/ldapi、smtp/submission/submissions等 scheme 直接决定了连接的协议与默认端口正则类参数必须使用 RE2 语法并以单引号书写避免 YAML 转义破坏模式TLS、buffers、timeouts 三个结构作为公共零件被 server、metrics、LDAP、SMTP、存储等模块反复装配配置一次即可理解多处。当你需要为 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Authelia 配置通用语法与数据结构完全指南：Duration、Address、TLS 与 Server Buffers 深度解析
Authelia 配置通用语法与数据结构完全指南Duration、Address、TLS 与 Server Buffers 深度解析【免费下载链接】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 作为面向 Web 应用的单点登录与多因素认证门户其配置系统横跨认证、授权、会话、存储、通知、OIDC 等多个模块。为了让这些模块共享一致的配置体验Authelia 定义了一套贯穿全配置体系的通用语法Common Syntax与通用数据结构Common Structures。本篇指南以 docs/content/configuration/prologue/common.md 为骨架系统讲解 Duration 时长语法、Address 监听/连接地址语法、正则表达式书写规范、Network 网段表示、TLS 配置结构、Server Buffers 与 Server Timeouts 结构并结合仓库源码如 internal/utils/time.go、internal/configuration/schema/types_address.go揭示底层解析原理。读完本文你将能够准确读懂 Authelia 任意配置文件中出现的时长、地址、TLS 段落并避免因 YAML 转义、IPv6 括号、单位缩写等细节而踩坑。说明本文所描述的通用语法与结构是跨模块复用的公共约定而非针对某个具体实例的配置指南各模块的专属参数请查阅对应模块文档如 server 等。文中引用的链接均已转换为以仓库根目录为起点的相对路径。语法Syntax以下通用语法在多个配置区域中被反复使用且对书写格式有明确要求。理解这些语法是正确配置 Authelia 的前提。字典引用语法Dictionary Reference字典引用语法适用于键名可由管理员任意指定且该键名可在其他位置被引用的场景。例如如果文档中标注policies是一个字典Dictionary那么其中的arbitrary_name键就是管理员自定义的任意名称它可以被其他地方引用——如下面示例中usage_example列表里的policy字段就通过arbitrary_name引用了上面定义的策略policies: arbitrary_name: enable: true usage_example: - name: example policy: arbitrary_name这种先定义、后引用的模式在 Authelia 的访问控制规则、OIDC 客户端、2FA 方法策略等场景中大量出现理解它能帮助你读懂名称从哪里来、被谁消费的配置关系。时长语法DurationDuration 是 Authelia 配置中最常见的通用语法之一其基础类型是字符串同时也接受整数但不推荐使用整数。整数被视为秒数。例如5400表示 5400 秒。字符串按数量 单位字母的块block解析例如5h表示 5 个h单位5 小时。解析时以下内容会被忽略或剔除所有空格前导零单词and。虽然支持将多个数量单位块组合使用如1h30m但官方建议保持简单、尽量使用单一值。同时需要提醒该格式虽具一定可读性仍需严格遵循预期的格式规范。单位对照表Unit Legend下表为时长语法支持的单位。长格式单位Long Unit如hours自 v4.38.0 起才可用单位短格式人类可读长格式年yyear,years月Mmonth,months周wweek,weeks天dday,days小时hhour,hours分钟mminute,minutes秒ssecond,seconds毫秒msmillisecond,milliseconds注意月M使用大写字母以避免与分钟m混淆。配置示例Examples期望值短格式配置示例长格式配置示例1 小时 30 分钟90m或1h30m或5400或5400s1 hour and 30 minutes1 天1d或24h或86400或86400s1 day10 小时10h或600m或9h60m或3600010 hours源码级解析原理从源码结构看时长的标准化与解析位于 internal/utils/time.goStandardizeDurationString 先将输入中的空格与and剔除再用正则reDurationStandard (?PDuration[1-9]\d*?)(?PUnit[^\d\s])定义于 internal/utils/const.go将输入切分为数量单位块逐块调用standardizeQuantityAndUnits转换。该正则以[1-9]开头、不允许前导零恰好印证了文档中忽略前导零的行为。对于 Go 标准库time.ParseDuration不认识的单位如天、周、月、年standardizeQuantityAndUnitsinternal/utils/time.go会将其换算为小时1 天 24h、1 周 168h、1 月 730h、1 年 8760h。ParseDurationString 会先判断输入是否为纯数字^\d$若是则按秒处理time.Second * duration否则走标准化流程后交给time.ParseDuration。在配置反序列化阶段internal/configuration/decode_hooks.go 中的 DecodeTimeDuration 负责将配置值转换为time.Duration其中字符串分支调用utils.ParseDurationString整数分支同样按秒计算并通过durationMax time.Duration(math.MaxInt64)见 internal/configuration/const.go做最大值校验。因此你在配置里写6s、30s、1h30m或纯整数5400最终都会被统一归一化到纳秒级的time.Duration。地址语法Address地址类型的基础类型也是字符串。它用于描述两类对象监听器Listener即服务监听连接的一端例如 HTTP 服务器监听的地址连接器Connector即发起远程连接的一端例如 LDAP、SMTP 客户端连接的远端地址。查询参数Query Parameters部分 scheme 支持查询参数参数以?附加在地址之后多个参数用连接参数监听器连接器用途umask是否在创建 socket 前设置 umask创建完成后恢复原值。取值必须是 3 或 4 位八进制数字。path是否设置子路径变量主要用于 unix socket但对 TCP 也技术性生效。注意只需填写字母数字部分不要以正斜杠/前缀。格式Format地址格式使用传统的 POSIX 记法表示可选与必填部分方括号[]包裹可选部分尖括号包裹必填部分。必填部分也可能出现在可选部分之内此时通常伴随其他格式说明文字指示若该文字存在则该部分实际必填否则整体可选。另外需要说明某部分可选仅指解析层面配置校验层面可能仍要求必须提供其中一项。Hostname 格式同时适用于监听器与连接器大多数场景。scheme 与 port 可选未提供时的默认值因选项而异[scheme://]hostname[:port][/path]Port 格式大多数场景下仅适用于监听器。scheme 与 hostname 可选scheme 未提供时默认值因选项而异hostname 未提供时默认为所有可用地址[scheme://][hostname]:port[/path]文件描述符格式File Descriptors仅适用于监听器且无可选部分。该格式接受查询字符串由上文查询参数控制其行为fd://file descriptor numberfd://file descriptor number?umask0022fd://file descriptor number?pathauthfd://file descriptor number?umask0022pathauthUnix 域套接字格式Unix Domain Socket适用于监听器与连接器大多数场景无可选部分。同样接受查询字符串unix://pathunix://path?umask0022unix://path?pathauthunix://path?umask0022pathauth示例Examples0.0.0.0 tcp://0.0.0.0 tcp://0.0.0.0/subpath tcp://0.0.0.0:9091 tcp://0.0.0.0:9091/subpath tcp://:9091 tcp://:9091/subpath 0.0.0.0:9091 udp://0.0.0.0:123 udp://:123 unix:///var/lib/authelia.sock示例中的端口9091为 Authelia 默认 HTTP 端口文档站点使用 sitevar 变量按版本注入实际值以当前版本为准。scheme整个 scheme 是可选的但一旦字符串中出现 scheme 与 host 的分隔符://则 scheme 必须存在。scheme 必须是下列之一监听器/连接器列表示该 scheme 在对应地址类型上的支持情况scheme监听器连接器默认端口说明tcp是是N/A标准 TCP socket允许 IPv4 和/或 IPv6 地址tcp4是是N/A标准 TCP socket仅允许 IPv4 地址tcp6是是N/A标准 TCP socket仅允许 IPv6 地址udp是是N/A标准 UDP socket允许 IPv4 和/或 IPv6 地址udp4是是N/A标准 UDP socket仅允许 IPv4 地址udp6是是N/A标准 UDP socket仅允许 IPv6 地址unix是是N/A标准 Unix 域套接字仅允许绝对路径ldap否是389通过 TCP socket 的远端 LDAP 连接可用时使用 StartTLSldaps否是636通过 TLS socket 的远端 LDAP 连接ldapi否是N/A通过 Unix 域套接字的 LDAP 连接smtp否是25通过 TCP socket 的远端 SMTP 连接可用时使用 StartTLSsubmission否是587通过 TCP socket 的远端 SMTP Submission 连接可用时使用 StartTLSsubmissions否是465通过 TLS socket 的远端 SMTP Submission 连接scheme 缺失时的默认推断规则若地址以/前缀开头则推断为unix否则推断为tcp若 scheme 为unix则必须以绝对路径作为后缀例如/var/run/authelia.sock应写作unix:///var/run/authelia.sock注意unix://之后是三斜杠因为路径本身以/开头。hostname当 scheme 为tcp或udp且未指定 port 时hostname 为必填。它可以是任意本机可寻址的 IP或解析到本机可寻址 IP 的主机名。指定 IPv6 时必须用方括号包裹。例如 IPv6 地址::1搭配tcpscheme 与端口80的正确写法是tcp://[::1]:80port当 scheme 为tcp或udp且未指定 hostname 时port 为必填。源码级解析原理地址解析的核心实现在 internal/configuration/schema/types_address.goNewAddressDefault 是解析入口先用正则判断字符串是否携带 schemeregexpHasScheme有则直接交给url.Parse否则若以/开头就自动补unix://前缀其余情况补tcp://前缀——这正是文档中以/前缀推断为 unix、否则推断为 tcp规则的代码实现。NewAddressFromURL 等函数负责将url.URL校验并转换为内部Address结构定义于同文件 L190。空字符串会被解析为tcp://:0形式见 NewAddressDefault 的边界处理。对于 SMTP 类地址NewSMTPAddress 演示了默认端口的回退逻辑port 为 0 时按 scheme 回退到 465/587/25scheme 为空时按端口反推 scheme。在反序列化链路中StringToAddressHookFunc 注册于 internal/configuration/decode_hooks.go 的 decode hooks 列表负责把字符串自动转换为地址类型。也就是说你在配置文件中写下的每一个地址字符串最终都会经过上述解析流程变成结构化的网络地址对象。正则表达式Regular ExpressionsAuthelia 多处配置使用正则表达式采用Google RE2 正则引擎即 Go 标准库正则语法引擎。它与 PCRE、Perl、Python 等引擎非常相似主要区别是不支持回溯backtracking。官方建议手动验证正则可使用 Regex 101 之类的工具并务必选择Golang选项或用其他手段验证。反斜杠转义陷阱使用反斜杠时必须格外小心YAML 解析器很可能把反斜杠当作 YAML 转义语法而非正则转义语法。为了避免这一问题请使用单引号而不是无引号或双引号。正确示例domain_regex: ^(admin|secure)\.example\.com$错误示例domain_regex: ^(admin|secure)\.example\.com$上面的错误示例中双引号内的\.会被 YAML 当作转义序列处理导致最终传给 RE2 的模式与预期不符。网络NetworkAuthelia 支持将字符串反序列化为网段network range的网络语法。字符串使用标准CIDR 记法若省略 CIDR 后缀则默认视为单个主机IPv4 适配为 /32IPv6 适配为 /128。示例CIDR范围192.168.0.1192.168.0.1/32192.168.0.1192.168.1.0/24192.168.1.0/24192.168.1.0 - 192.168.1.255192.168.2.1/24192.168.2.0/24192.168.2.0 - 192.168.2.2552001:db8:3333:4444:5555:6666:7777:88882001:db8:3333:4444:5555:6666:7777:8888/1282001:db8:3333:4444:5555:6666:7777:88882001:db8:3333:4400::/562001:db8:3333:4400::/562001:0db8:3333:4400:0000:0000:0000:0000 - 2001:0db8:3333:44ff:ffff:ffff:ffff:ffff2001:db8:3333:4444:5555:6666:7777:8888/562001:db8:3333:4400::/562001:0db8:3333:4400:0000:0000:0000:0000 - 2001:0db8:3333:44ff:ffff:ffff:ffff:ffff注意上表中两个值得留意的归一化行为192.168.2.1/24会被归一化为网络地址192.168.2.0/24覆盖192.168.2.0 - 192.168.2.255整个子网带前缀长度的 IPv6 地址同样会被归一化到该前缀的网络边界如2001:db8:3333:4444:5555:6666:7777:8888/56等价于2001:db8:3333:4400::/56。数据结构Structures以下通用数据结构在多个配置区域被复用各自具有明确的字段要求。TLS配置中多个区域使用统一的tls配置结构用于配置 TLS socket 与 TLS 校验参数。默认情况下Authelia 使用系统证书信任库进行 TLS 证书校验你可以通过全局的 certificates_directory 选项扩充信任库也可以通过下面的 skip_verify 完全关闭 TLS 证书校验。tls: server_name: example.com skip_verify: false minimum_version: TLS1.2 maximum_version: TLS1.3 certificate_chain: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- private_key: | -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----server_name类型string非必填。server_name会覆盖证书校验过程中用于比对证书的名称。当后端服务的主机地址需要使用 IP 时这一选项尤为有用——你可以连接 IP但校验特定的证书服务器名称。skip_verify类型boolean默认false非必填。skip_verify会完全跳过对后端服务证书的校验。不推荐使用。更合理的做法是调整server_name选项以及全局的 certificates directory。minimum_version类型string默认TLS1.2非必填。控制 Authelia 执行 TLS 握手时使用的最低 TLS 版本。可选值为TLS1.3、TLS1.2、TLS1.1、TLS1.0、SSL3.0。除TLS1.3与TLS1.2之外的值都非常古老且已废弃应避免使用——正确做法是升级后端服务而不是降低此值。截至撰写本文时SSL3.0在任何情况下都会产生错误。从源码看schema 层的默认值被定义为MinimumVersion: TLSVersion{tls.VersionTLS12}见 internal/configuration/schema/authentication.go 等多处与文档默认值一致。maximum_version类型string默认TLS1.3非必填。控制 Authelia 执行 TLS 握手时使用的最高 TLS 版本。可选值同上TLS1.3、TLS1.2、TLS1.1、TLS1.0、SSL3.0同样不建议使用除TLS1.3与TLS1.2以外的值。certificate_chain类型string非必填secret 类型参见下文 private_key 说明。与 private_key 配合使用用于与服务器进行双向 TLSmTLS认证的证书链/证书包。取值必须是一个或多个以DER base64RFC4648编码的 PEM 格式证书。若提供多个证书按自上而下的顺序每个证书必须由下一个证书若提供签名。private_key类型string非必填secret敏感值。与 certificate_chain 配合用于双向 TLS 认证的私钥。该私钥的公钥材料必须与 certificate_chain 中第一个证书的私钥匹配。取值必须是一份以 DER base64RFC4648编码的 PEM 格式私钥并必须符合 PKCS#8、PKCS#1 或 SECG1 规范之一。引用规范PKCS#8 见 RFC 5208PKCS#1 见 RFC 8017SECG1 见 RFC 5915RFC4648 见 RFC 4648此处仅给出规范名称不展开外部链接。Server Buffers配置中多个区域使用统一的buffers结构来配置 HTTP 服务器缓冲区典型使用者包括 server 与 metrics telemetry 两个配置段。buffers: read: 4096 write: 4096read类型integer默认4096非必填。配置最大请求大小单位为字节。默认值 4096 对大多数场景已足够。write类型integer默认4096非必填。配置最大响应大小单位为字节。默认值 4096 对大多数场景已足够。Server Timeouts配置中多个区域使用统一的timeouts结构来配置 HTTP 服务器超时典型使用者包括 server 与 metrics telemetry 两个配置段。timeouts: read: 6s write: 6s idle: 30sread类型string,integer语法duration默认 6 秒非必填。配置服务器读取超时。注意其值必须遵循上文时长语法书写。write类型string,integer语法duration默认 6 秒非必填。配置服务器写入超时。idle类型string,integer语法duration默认 30 秒非必填。配置服务器空闲超时。这三个字段的默认值6s、6s、30s是时长语法在真实配置中的典型应用——它们会被 DecodeTimeDuration 反序列化为 Go 的time.Duration并作用于底层 HTTP 服务器。历史锚点Historical References原文档末尾保留了对历史锚点的引用其中 Duration Notation Format 一节即指向本文的时长语法小节用于维持旧版文档链接的兼容性。结语把这些通用要素串起来掌握 Authelia 的通用语法与数据结构后你会发现整个配置体系的公共词汇表已经打通任何时长类参数超时、刷新间隔、会话有效期都遵循 Duration 语法底层由 internal/utils/time.go 与 internal/configuration/decode_hooks.go 负责归一化任何地址类参数监听端口、LDAP/SMTP 连接、unix socket都遵循 Address 语法底层由 internal/configuration/schema/types_address.go 负责解析其中tcp4/tcp6、ldap/ldaps/ldapi、smtp/submission/submissions等 scheme 直接决定了连接的协议与默认端口正则类参数必须使用 RE2 语法并以单引号书写避免 YAML 转义破坏模式TLS、buffers、timeouts 三个结构作为公共零件被 server、metrics、LDAP、SMTP、存储等模块反复装配配置一次即可理解多处。当你需要为 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考