Authelia CLI 深度解析使用 storage cache mds3 dump 导出 WebAuthn MDS3 缓存【免费下载链接】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 官方 CLI 参考文档authelia storage cache mds3 dump展开说明该命令如何把 Authelia 数据库中缓存的 WebAuthn MDS3FIDO Metadata Service 3.0数据完整导出为本地文件并结合 命令定义源码 与 元数据缓存实现剖析其执行链路、前提配置与错误处理机制帮助你在审计、备份或离线迁移 WebAuthn 认证器元数据时准确使用并验证该命令。一、背景MDS3 缓存是 WebAuthn 认证器校验的数据基础Authelia 支持 WebAuthnPasskey作为登录与注册方式。当配置启用了 WebAuthn 元数据功能即 配置模板 中webauthn.metadata.enabled开启时Authelia 会从 FIDO 官方的 MDS3 服务拉取一份描述认证器Authenticator状态与认证能力的元数据并将其缓存到存储后端供validate_entry、validate_status、validate_trust_anchor等校验逻辑使用参见 配置模板中的 webauthn.metadata 段 与 WebAuthn 配置结构体。这份 MDS3 缓存就是一个加密存储的二进制数据块blob。在实际运维中经常需要把它“原样”取出来用于备份 MDS3 数据块避免重新拉取MDS3 服务可能限流或不可达将同一份缓存迁移/恢复到另一套环境配合authelia storage cache mds3 update的--path参数从文件而非网络更新缓存审计当前缓存的元数据版本号与内容。authelia storage cache mds3 dump正是完成“从数据库缓存到本地文件”这一步的官方命令。二、命令语法与参数与官方文档一致官方参考文档 authelia_storage_cache_mds3_dump.md 对该命令的定义如下Dump WebAuthn MDS3 cache storage —— 将 WebAuthn MDS3 缓存存储转储dump到文件中。基本调用形式authelia storage cache mds3 dump [flags]文档给出的示例authelia storage cache mds3 dump命令自身参数参数说明默认值-h, --help显示 dump 子命令的帮助信息—--path string转储的 MDS3 数据块保存路径data.mds3该默认值在源码中可以直接印证newStorageCacheMDSDumpCmd 中注册了cmd.Flags().String(cmdFlagNamePath, data.mds3, the path to save the dumped mds3 data blob)因此不带--path时命令会把当前缓存的 MDS3 数据块写入工作目录下的data.mds3文件。继承自父命令的参数由于命令树中storage一级命令注册了持久化标志PersistentFlagsmds3 dump同样支持以下参数来自 官方文档 与 storage 命令定义参数说明默认值-c, --config strings要加载的配置文件或目录详见authelia -h authelia configconfiguration.yml--config.experimental.filters strings应用到所有配置文件的过滤条件列表—--encryption-key string要使用的存储加密密钥—--sqlite.path stringSQLite 数据库路径—--mysql.address stringMySQL 服务器地址tcp://127.0.0.1:3306--mysql.database stringMySQL 数据库名authelia--mysql.username stringMySQL 用户名authelia--mysql.password stringMySQL 密码—--postgres.address stringPostgreSQL 服务器地址tcp://127.0.0.1:5432--postgres.database stringPostgreSQL 数据库名authelia--postgres.schema stringPostgreSQL schema 名public--postgres.username stringPostgreSQL 用户名authelia--postgres.password stringPostgreSQL 密码—这些命令行参数通过ConfigStorageCommandLineConfigRunE映射为配置键例如--sqlite.path映射到storage.local.path--encryption-key映射到storage.encryption_key映射表见 storage_run.go。三、运行前提配置与存储的硬性条件从 StorageCacheMDS3DumpRunE 的实现看执行 dump 前必须满足以下条件否则会直接报错命令链前置校验。storage命令的PersistentPreRunE依次执行标志映射、配置加载、存储配置校验、存储 Provider 加载newStorageCmd。若数据库不可连或加密密钥错误命令在这些阶段就会失败不会进入 dump 逻辑。Schema 校验。执行体首先调用ctx.CheckSchema()确保数据库 schema 可用。必须启用 WebAuthn 元数据。源码中有明确的硬性检查if !ctx.config.WebAuthn.Metadata.Enabled { return fmt.Errorf(webauthn metadata is disabled) }即若配置中webauthn.metadata.enabled为false默认未启用命令会直接返回 “webauthn metadata is disabled” 错误。缓存中必须已有数据。dump走的是LoadCache只读缓存不会触发从网络拉取。若缓存为空命令返回 “error dumping metadata: no metadata is in the cache”。因此典型操作顺序是先authelia storage cache mds3 update刷新缓存再status确认版本与时效最后dump导出。输出路径必须非空白。--path若传空字符串会报 “error dumping metadata: path must not be blank”。相关配置项webauthn.metadata 段dump本身不直接消费这些参数但它们决定了缓存中数据的内容与行为来自 配置模板 与 webauthn.goenabled启用元数据拉取行为本命令的前提cache_policy缓存策略取值strict/relaxed默认strictvalidate_trust_anchor、validate_entry、validate_entry_permit_zero_aaguid、validate_status、validate_status_permitted、validate_status_prohibited控制导出内容在实际认证流程中的校验强度。四、源码级执行流程一行 dump 背后发生了什么核心实现位于 runStorageCacheMDS3Dump完整调用链如下构造元数据 Provider。webauthn.NewMetaDataProvider(config, store)基于配置创建一个StoreCachedMetadataProvider见 metadata.go。从源码结构看该 Provider 内嵌go-webauthn/webauthn库的cachedProvider并用metadata.NewDecoder(metadata.WithIgnoreEntryParsingErrors())构造解码器同时携带cachePolicy配置与生产环境 MDS3 拉取器productionMDS3Provider。只读加载缓存。provider.LoadCache(ctx)调用底层getCache通过存储后端的LoadCachedData读取名为mds3的缓存条目缓存名常量cacheMDS3 mds3定义在 webauthn/const.go随后用解码器解析出*metadata.Metadata。关键点dump全程只读绝不会访问 MDS3 网络端点——网络拉取只发生在update路径中Load/LoadForce/LoadFile。以 0600 权限写文件。拿到原始字节data即数据库中存储的 MDS3 blob 本体而非重新序列化后f, err os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)以O_WRONLY|O_CREATE|O_TRUNC打开目标路径并以0600权限创建/覆盖文件然后一次性写入。由于 MDS3 数据块包含认证器敏感状态与信任锚信息0600 权限保证了文件仅属主可读写。输出成功信息。成功后向标准输出打印Successfully dumped WebAuthn MDS3 data with version %d from cache to file %s.其中版本号取自mds.Parsed.NumberFIDO MDS3 规范中的 metadata number可用来核对导出文件与status命令显示的版本是否一致。资源释放。外层StorageCacheMDS3DumpRunE通过defer确保ctx.providers.StorageProvider.Close()一定被调用存储连接不会泄漏。五、错误处理与结果判定结合源码该命令可能的失败原因与排查方向报错信息原因处理建议webauthn metadata is disabled配置未开启webauthn.metadata.enabled在配置中启用 metadata 后重试error dumping metadata: path must not be blank--path传了空白值提供有效文件路径error dumping metadata: no metadata is in the cache缓存为空从未 update 过或被 delete 清空先执行authelia storage cache mds3 updateschema 相关错误由storageWrapCheckSchemaErr包装数据库 schema 未初始化/版本过旧先执行authelia storage migrate up打开文件失败如目录不存在、无权限输出路径不可写检查路径所在目录与权限成功判定的标准是退出码为 0 且出现Successfully dumped WebAuthn MDS3 data with version N from cache to file ...。六、在完整工作流中的位置status / update / delete / dumpmds3子命令族由 newStorageCacheMDSCmd 注册共四个子命令帮助文本常量见 commands/const.go# 1. 刷新缓存可从 MDS3 服务、强制刷新、或从本地文件恢复 authelia storage cache mds3 update # 按需从网络更新 authelia storage cache mds3 update --force # 强制重新拉取 authelia storage cache mds3 update --path data.mds3 # 从本地文件恢复 # 2. 查看缓存状态Valid / Initialized / Outdated / Version / Next Update authelia storage cache mds3 status # 3. 导出缓存数据块 authelia storage cache mds3 dump authelia storage cache mds3 dump --path /backup/mds3-$(date %Y%m%d).blob # 4. 删除缓存 authelia storage cache mds3 delete其中status输出Valid、Initialized、Outdated、Version、Next Update五项状态实现见 runStorageCacheMDS3Statusupdate在未过期且未加--force时会提示 “does not require an update” 并跳过网络请求见 runStorageCacheMDS3Update。因此推荐的标准运维闭环是update保证缓存最新或从文件恢复status确认Initialized: true且版本符合预期dump将数据块落盘备份备份文件后续可作为update --path file的输入实现离线恢复。七、关键文件索引命令文档authelia_storage_cache_mds3_dump.md、父命令 authelia_storage_cache_mds3.md命令注册cobra 定义、--path默认值internal/commands/storage.go命令执行体StorageCacheMDS3DumpRunE/runStorageCacheMDS3Dumpinternal/commands/storage_run.go元数据缓存 ProviderLoadCache/getCache/SaveCache/ 网络拉取internal/webauthn/metadata.go缓存名常量mds3与缓存策略常量internal/webauthn/const.goWebAuthn 元数据配置结构体与默认值internal/configuration/schema/webauthn.go配置模板webauthn.metadata段config.template.yml适用前提与限制以上行为以当前仓库代码为准该命令要求目标环境的 Authelia 二进制包含storage cache mds3子命令即与本文仓库对应的版本并且存储后端SQLite/MySQL/PostgreSQL可连通、webauthn.metadata.enabled已启用、缓存中已有数据。dump仅导出数据库中缓存的原始 blob不会触发网络请求也不会修改任何缓存内容。【免费下载链接】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），仅供参考