Authelia CLI 深度解析：使用 storage cache mds3 dump 导出 WebAuthn MDS3 缓存

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 MDS3（FIDO Metadata Service 3.0）数据完整导出为本地文件；并结合 命令定义源码 与 元数据缓存实现，剖析其执行链路、前提配置与错误处理机制，帮助你在审计、备份或离线迁移 WebAuthn 认证器元数据时准确使用并验证该命令。

一、背景：MDS3 缓存是 WebAuthn 认证器校验的数据基础

Authelia 支持 WebAuthn（Passkey）作为登录与注册方式。当配置启用了 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

命令自身参数

该默认值在源码中可以直接印证：newStorageCacheMDSDumpCmd 中注册了

cmd.Flags().String(cmdFlagNamePath, "data.mds3", "the path to save the dumped mds3 data blob")

因此不带--path时，命令会把当前缓存的 MDS3 数据块写入工作目录下的data.mds3文件。

继承自父命令的参数

由于命令树中storage一级命令注册了持久化标志（PersistentFlags），mds3 dump同样支持以下参数（来自 官方文档 与 storage 命令定义）：

这些命令行参数通过ConfigStorageCommandLineConfigRunE映射为配置键（例如--sqlite.path映射到storage.local.path，--encryption-key映射到storage.encryption_key），映射表见 storage_run.go。

三、运行前提：配置与存储的硬性条件

从 StorageCacheMDS3DumpRunE 的实现看，执行 dump 前必须满足以下条件，否则会直接报错：

1. 命令链前置校验。storage命令的PersistentPreRunE依次执行标志映射、配置加载、存储配置校验、存储 Provider 加载（newStorageCmd）。若数据库不可连或加密密钥错误，命令在这些阶段就会失败，不会进入 dump 逻辑。

2. Schema 校验。执行体首先调用ctx.CheckSchema()，确保数据库 schema 可用。

3. 必须启用 WebAuthn 元数据。源码中有明确的硬性检查：

   if !ctx.config.WebAuthn.Metadata.Enabled { return fmt.Errorf("webauthn metadata is disabled") }

   即若配置中webauthn.metadata.enabled为false（默认未启用），命令会直接返回 “webauthn metadata is disabled” 错误。

4. 缓存中必须已有数据。dump走的是LoadCache（只读缓存），不会触发从网络拉取。若缓存为空，命令返回 “error dumping metadata: no metadata is in the cache”。因此典型操作顺序是：先authelia storage cache mds3 update刷新缓存，再status确认版本与时效，最后dump导出。

5. 输出路径必须非空白。--path若传空字符串会报 “error dumping metadata: path must not be blank”。

相关配置项（webauthn.metadata 段）

dump本身不直接消费这些参数，但它们决定了缓存中数据的内容与行为，来自 配置模板 与 webauthn.go：

• enabled：启用元数据拉取行为（本命令的前提）；
• cache_policy：缓存策略，取值strict/relaxed，默认strict；
• validate_trust_anchor、validate_entry、validate_entry_permit_zero_aaguid、validate_status、validate_status_permitted、validate_status_prohibited：控制导出内容在实际认证流程中的校验强度。

四、源码级执行流程：一行 dump 背后发生了什么

核心实现位于 runStorageCacheMDS3Dump，完整调用链如下：

1. 构造元数据 Provider。webauthn.NewMetaDataProvider(config, store)基于配置创建一个StoreCachedMetadataProvider（见 metadata.go）。从源码结构看，该 Provider 内嵌go-webauthn/webauthn库的cachedProvider，并用metadata.NewDecoder(metadata.WithIgnoreEntryParsingErrors())构造解码器；同时携带cachePolicy配置与生产环境 MDS3 拉取器productionMDS3Provider。

2. 只读加载缓存。provider.LoadCache(ctx)调用底层getCache，通过存储后端的LoadCachedData读取名为mds3的缓存条目（缓存名常量cacheMDS3 = "mds3"定义在 webauthn/const.go），随后用解码器解析出*metadata.Metadata。关键点：dump全程只读，绝不会访问 MDS3 网络端点——网络拉取只发生在update路径中（Load/LoadForce/LoadFile）。

3. 以 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 权限保证了文件仅属主可读写。

4. 输出成功信息。成功后向标准输出打印：

   Successfully dumped WebAuthn MDS3 data with version %d from cache to file '%s'.

   其中版本号取自mds.Parsed.Number（FIDO MDS3 规范中的 metadata number），可用来核对导出文件与status命令显示的版本是否一致。

5. 资源释放。外层StorageCacheMDS3DumpRunE通过defer确保ctx.providers.StorageProvider.Close()一定被调用，存储连接不会泄漏。

五、错误处理与结果判定

结合源码，该命令可能的失败原因与排查方向：

成功判定的标准是退出码为 0 且出现Successfully dumped WebAuthn MDS3 data with version N from cache to file '...'。

六、在完整工作流中的位置：status / update / delete / dump

mds3子命令族由 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五项状态（实现见 runStorageCacheMDS3Status）；update在未过期且未加--force时会提示 “does not require an update” 并跳过网络请求（见 runStorageCacheMDS3Update）。因此推荐的标准运维闭环是：

1. update保证缓存最新（或从文件恢复）；
2. status确认Initialized: true且版本符合预期；
3. dump将数据块落盘备份；
4. 备份文件后续可作为update --path <file>的输入实现离线恢复。

七、关键文件索引

• 命令文档：authelia_storage_cache_mds3_dump.md、父命令 authelia_storage_cache_mds3.md
• 命令注册（cobra 定义、--path默认值）：internal/commands/storage.go
• 命令执行体（StorageCacheMDS3DumpRunE/runStorageCacheMDS3Dump）：internal/commands/storage_run.go
• 元数据缓存 Provider（LoadCache/getCache/SaveCache/ 网络拉取）：internal/webauthn/metadata.go
• 缓存名常量mds3与缓存策略常量：internal/webauthn/const.go
• WebAuthn 元数据配置结构体与默认值：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