Authelia 存储 Schema 迁移完全指南版本映射、自动升级与手动降级实战【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaAuthelia 使用数据库SQLite、MySQL/MariaDB、PostgreSQL持久化用户、会话、WebAuthn 凭据与 OpenID Connect 1.0 相关数据而每一代版本演进都会伴随存储 Schema 的变化。本文以 docs/content/configuration/storage/migrations.md 为骨架结合仓库中 internal/storage/migrations 的真实迁移脚本与 internal/storage/migrations.go 的加载逻辑系统讲解 Schema 版本与 Authelia 版本的对应关系、启动自动升级机制、迁移文件命名规范以及authelia storage migrate全套 CLI 的实操方法。读完本文你将能够判断当前数据库 Schema 所处版本、安全地执行升级与降级并理解pre1这一特殊版本的来龙去脉。为什么存储迁移如此重要存储迁移Storage Migration是保证数据库 Schema 与 Authelia 二进制版本保持兼容的关键机制。Authelia 会在启动时自动将 Schema 升级到最新版本用户通常无需手动干预。但在以下两种场景中你必须理解并手动操作迁移回退Downgrade当你希望使用旧版本的 Authelia 时旧版本可能不认识新版本的 Schema。此时需要用支持当前 Schema 版本的 Authelia 手动降级再切换到目标旧版本。特殊版本pre14.0.0 时代的初始 Schema 没有迁移管理记录回退到该版本需要特殊处理详见下文。仓库中的迁移逻辑实现在 internal/storage/sql_provider_schema.go 与 internal/storage/migrations.go而 CLI 入口位于 internal/commands/storage.go 与 internal/commands/storage_run.go。Schema 版本与 Authelia 版本映射表下表列出当前仓库已知的 Schema 版本、首次引入该版本的 Authelia 发布版本及其说明。表中两个相邻 Schema 版本之间的所有 Authelia 版本均使用前一个较小的Schema 版本。Schema 版本Authelia 版本说明pre14.0.0降级到此版本需要在 Authelia 4.37.2 上使用--pre1标志14.33.0初始的受迁移管理版本24.34.0WebAuthn新增webauthn_devices表调整totp_config增加设备创建/使用日期34.34.2WebAuthn修复 V2 迁移的kid列长度并为处于 V2 的用户提供迁移路径44.35.0新增 OpenID Connect 1.0 存储表与不透明用户标识符表54.35.1修复oauth2_consent_session表以允许尚未登录用户的subject为 NULL64.37.0调整 OpenID Connect 1.0 表以支持预配置同意改进74.37.3修复部分 Schema 不一致问题最典型的是 MySQL/MariaDB 的 Engine 与 Collation84.38.0OpenID Connect 1.0 Pushed Authorization RequestsPAR94.38.0修复 PostgreSQL 中webauthn_devices表aaguid列的 NOT NULL 约束问题104.38.0修复oauth2_access_token_session表在client credentials授权下的约束114.38.0为 OAuth 2.0 Access Token 的 JWT ProfileRFC 9068调整约束124.38.0针对多 Cookie 域变更的 WebAuthn 调整134.38.0通过邮件进行身份验证的一次性密码One-Time Password变更144.38.0撤销重置密码令牌Revoke Reset Password Token154.38.0基于时间的一次性密码TOTP安全增强164.39.0OAuth 2.0 允许 Consent Subject 为 NULL174.39.0OpenID Connect 1.0 Claims 参数184.39.0OAuth 2.0 Device Code Flow设备码流程194.39.0WebAuthn Passkeys204.39.0Regulation账户锁定/限流机制重构214.39.1MySQL 特定的 WebAuthn MDS 修复224.39.2OAuth 2.0 Consent Session 改为使用过期时间而非绑定 Subject234.39.12OAuth 2.0 Device Code Flow 空值约束244.39.20WebAuthn 调整将attestation_type重命名为attestation_format并新增attestation_type254.39.21调整存储加密实现引入 HKDF 进行密钥派生并使用列级 AAD264.39.21调整存储加密 AAD使其具体到单个列与行而不仅是列274.39.21在 Refresh Token Session 表中加入 Access Token Session 签名284.39.22修复 Refresh Token Session 表中 Access Token Session 签名的列长度294.39.23OAuth 2.0 Resource Indicators 从 Audience 中分离并单独记录表中的一个典型用法示例若想降级到pre1即 4.0.0 使用的 Schema由于pre1覆盖了 4.0.0 到 4.32.2 之间的所有版本你需要使用4.33.0 或更高版本的 Authelia 二进制来执行降级。类似地若当前 Schema 为 5 而目标为 2需要选用 4.34.2 以上版本执行down迁移。迁移文件体系命名、组织与加载原理迁移文件命名规范所有迁移脚本统一存放在 internal/storage/migrations 下按数据库引擎分为mysql/、postgres/、sqlite/三个子目录每个子目录内按V####.Name.up.sql/V####.Name.down.sql成对存放。命名规则由 internal/storage/const.go 中的正则定义reMigration regexp.MustCompile(^V(?PVersion\d{4})\.(?PName[^.])\.(?PDirection(up|down))\.sql$)Version4 位数字如0029Name语义化名称下划线会在解析时替换为空格见 migrations.go 的scanMigrationDirectionup或down决定该脚本是升级还是回滚。例如 internal/storage/migrations/sqlite/V0020.Regulation.up.sql 创建了banned_user、banned_ip两张表及相关索引对应版本 20 的 Regulation 重构同名.down.sql则负责回滚该变更。加载与筛选逻辑internal/storage/migrations.go 通过//go:embed migrations/*将三个引擎的全部脚本嵌入二进制由loadMigrations根据当前版本prior与目标版本target筛选迁移序列up方向只选取Up true且prior Version target的脚本按版本升序执行down方向只选取Up false且target Version prior的脚本按版本降序执行prior target时直接返回ErrMigrateCurrentVersionSameAsTarget避免无意义操作。latestMigrationVersion则扫描某个引擎目录下所有up脚本返回最大版本号作为“最新版本”的判定依据。启动时自动升级正常运维中Authelia 在每次启动时自动执行 Schema 升级将数据库从当前版本迁移到二进制内置的最新版本。这一设计意味着新版本发布后直接替换二进制并重启服务即可完成升级无需额外命令自动升级通常仅执行up方向down方向必须手动执行且可能销毁数据。因此若你想回退到旧版本切不可直接替换旧二进制启动——旧二进制不认识新 Schema。正确做法是先用新版本或至少支持当前 Schema 的版本的 Authelia 执行storage migrate down再启动旧版本。pre1特殊版本降级的历史包袱pre1是 4.0.0 引入、尚无迁移管理机制的初始 Schema对应内部版本号-1另有-2表示unknown、0表示空库见 sql_provider_schema.go 的SchemaVersionToString。当前版本 Authelia 对pre1有严格限制从pre1升级currentVersion -1不再支持报错并提示“必须使用旧版本 Authelia 执行此迁移”降级到pre1targetVersion -1需先使用当前版本降级到 Schema 版本 1再使用Authelia 4.37.2建议版本见 internal/storage/errors.go并携带--pre1标志完成最终降级。对应错误信息定义如下internal/storage/errors.goerrFmtMigrationPre1 schema migration %s pre1 is no longer supported: you must use an older version of authelia to perform this migration: %s errFmtMigrationPre1SuggestedVersion the suggested authelia version is 4.37.2pre1涉及的旧表totp_secrets、identity_verification_tokens、u2f_devices在 internal/storage/const.go 中被标记为“WARNING: Do not change/remove these consts. They are used for Pre1 migrations”用于识别与校验 pre1 状态的 Schema。CLI 实操authelia storage migrate 全套命令CLI 命令的注册入口在 internal/commands/storage.go主命令authelia storage migrate下包含 5 个子命令。所有命令都要求先通过配置文件或环境变量正确配置数据库连接。查看当前 Schema 状态authelia storage schema-info输出当前 Schema 版本、最新可用版本及数据库中的表清单是执行任何迁移前的第一步。实现位于 storage_run.go 的runStorageSchemaInfo。升级upauthelia storage migrate up默认将 Schema 升级到最新版本。也可以使用-t/--target指定目标版本authelia storage migrate up --target 20注意约束见 sql_provider_schema.go 的schemaMigrateChecks目标版本必须大于当前版本目标版本不能超过最新版本若数据库已是最新返回ErrSchemaAlreadyUpToDate。降级downauthelia storage migrate down --target 15降级必须显式指定目标版本-t且因为降级脚本可能销毁数据交互式终端会要求输入DESTROY确认也可用--destroy-data标志跳过交互确认storage_run.goauthelia storage migrate down --target 15 --destroy-data降级方向的校验包括目标版本不能小于 0pre1需要特殊流程且不能大于当前版本。列出可用迁移与历史authelia storage migrate list-up # 列出当前版本之后可用的升级脚本 authelia storage migrate list-down # 列出可用的降级脚本 authelia storage migrate history # 打印迁移历史ID、应用时间、迁移前后版本、Authelia 版本list-up/list-down直接调用SchemaMigrationsUp(ctx, 0)/SchemaMigrationsDown(ctx, 0)storage_run.go以表格形式输出Version与Descriptionhistory则逐行打印历史记录storage_run.go。从版本表读懂 Authelia 的功能演进把映射表与迁移脚本结合可以勾勒出 Authelia 近年来的技术路线V1–V34.33–4.34建立迁移管理框架引入 WebAuthn 设备表与 TOTP 配置日期字段属于 FIDO2/WebAuthn 基础设施建设V4–V114.35–4.38OpenID Connect 1.0 全面落地——授权、预配置同意、PAR、JWT Profile Access TokenRFC 9068、Claims 参数、Device Code Flow 相继加入并在 PostgreSQL / MySQL 上做大量约束修正V12–V194.38–4.39多 Cookie 域、邮箱一次性密码、密码重置令牌撤销、TOTP 安全增强、Passkeys 与 Regulation 重构身份验证与账户安全能力集中升级V20–V244.39–4.39.20Regulation 引入banned_user/banned_ip表见 V0020.Regulation.up.sql并持续修正 WebAuthn 属性命名与 Device Code 约束V25–V294.39.21–4.39.23存储加密体系强化——HKDF 密钥派生、列级乃至行列级 AADAdditional Authenticated Data并在刷新令牌会话中记录访问令牌签名及 OAuth 2.0 Resource Indicators属于安全与 OIDC 合规深水区。这组版本演进也解释了为何降级必须按版本映射谨慎进行例如从 V29 直接降级到 V24会丢失 Resource Indicators 数据与加密 AAD 变更若无备份将不可恢复。迁移最佳实践小结升级前用authelia storage schema-info确认当前版本与目标版本重要环境先备份数据库升级优先依赖启动自动升级如需分批用storage migrate up --target N分步执行降级永远显式指定--target理解down脚本可能销毁数据先执行list-down预览将执行的变更回退到pre1这是特例中的特例——先降级到 Schema 1再用 Authelia 4.37.2 加--pre1标志完成最后一步日常巡检storage migrate history可审计每次 Schema 变更的时间与 Authelia 版本便于定位数据异常与版本不匹配问题。相关源码与脚本可进一步查阅 internal/storage/migrations.go、internal/storage/sql_provider_schema.go 以及 internal/storage/migrations 三个引擎目录下的迁移文件。【免费下载链接】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），仅供参考