如何在编辑器中为 Authelia 的 YAML 配置启用 JSON Schema 校验

如何在编辑器中为 Authelia 的 YAML 配置启用 JSON Schema 校验

【免费下载链接】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 的官方配置载体是 YAML 文件：直接运行时加载configuration.yml，容器环境下默认位于/config/configuration.yml。官方文档明确指出，Authelia 虽然会在很多配置错误的场景下输出控制台错误，但覆盖并不完整，因此建议使用编辑器对配置文件做校验。本文说明如何用 VSCodium 或 VSCode 配合 RedHat 的 YAML 扩展，把 Authelia 发布的 JSON Schema 挂到 YAML 文件上，让编辑器按 Authelia 的字段定义来检查配置文件。

准备：编辑器与扩展

文件配置方法文档 中 "YAML Validation" 一节给出的推荐组合是：

• 编辑器：VSCodium 或 VSCode；
• 扩展：RedHat 出品的YAML扩展，文档原文称它可以完成对 YAML 文件“格式与 schema”的校验。

手上还没有配置文件时，可以从仓库根目录的 config.template.yml 出发，它是包含全部可选项的模板，复制成自己的configuration.yml再按需修改。

确定要挂的 Schema：版本与名称

Authelia 发布了一批 JSON Schema，URL 格式如下（Schemas 参考），该 URL 同时就是 schema ID：

https://www.authelia.com/schemas/<version>/json-schema/<name>.json

两个占位符按以下规则替换：

1. <version>采用v<major>.<minor>格式。例如 Authelia 版本为 4.38.1 时，<version>写作v4.38；
2. <name>填下表中对应的 schema 名称；
3. 文档定义了两个特殊元版本：
   • latest：指向 Authelia 的最新发布版本；
   • next：指向 master 分支的最新提交。

可用的 schema 名称及其对应的 YAML 文件类型：

同一批 schema 文件在仓库内也有一份，位于docs/static/schemas/<version>/json-schema/下，例如 docs/static/schemas/latest/json-schema/configuration.json 和 docs/static/schemas/latest/json-schema/user-database.json，可用于离线比对 schema 内容。

在配置文件顶部添加 $schema 指令

schema 的挂载方式是在 YAML 文件最上方写一行特殊注释。以主配置文件为例（下面的键值取自配置模板中的真实选项）：

# yaml-language-server: $schema=https://www.authelia.com/schemas/latest/json-schema/configuration.json theme: 'light'

希望 schema 与环境里部署的具体发布版本保持一致时，把latest换成对应版本的v<major>.<minor>。例如部署的是 4.38.1，则写成：

# yaml-language-server: $schema=https://www.authelia.com/schemas/v4.38/json-schema/configuration.json

yaml-language-server前缀表示这行注释是给 RedHat YAML 扩展背后的语言服务器读的指令，扩展会按注释中给出的 schema URL 对该文件做校验，而不是只做纯 YAML 语法检查。

其他 YAML 配置文件的校验方式

同样的指令适用于其他文件类型，只需把<name>换成对应 schema 名称。官方文档 passwords.md 中的用户数据库文件示例就是这样使用的：

# yaml-language-server: $schema=https://www.authelia.com/schemas/latest/json-schema/user-database.json

TOTP、WebAuthn、Identifiers 三类导出文件同理，分别使用exports.totp、exports.webauthn、exports.identifiers作为<name>。

校验生效后的判断方式

保存文件后，YAML 扩展按 YAML Validation 一节 的说明对该文件做两层检查：YAML 格式本身是否正确，以及文件内容是否符合 schema 的字段定义。不符合 schema 的部分会在编辑器诊断中标出并指向具体行；刚编辑且按 schema 合法的部分不会产生报告。

需要说明的边界：

• 这行指令只做 schema 挂载，不改变 Authelia 的加载行为。运行时控制台错误与编辑器校验是两条并行的防线，官方原文是 “While we produce console errors for users in many misconfiguration scenarios it's not perfect”，所以编辑器侧校验仍有独立价值；
• latest与next会随上游发布和 master 分支前进而变化，只有v<major>.<minor>形式才能把 schema 固定到某个发布版本；
• 每个文件只需要一行指令，多个文件（如拆分出的 ACL 配置）各自在文件顶部写自己对应的 schema。

如果之后要确认某个字段到底支持哪些取值，可以对照 config.template.yml 中的注释，以及 schema 文件本身（如 configuration.json）中对应的字段定义。

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