Autheliastorage migrate命令详解SQLite / MySQL / PostgreSQL 数据库 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 使用 SQL 数据库SQLite、MySQL 或 PostgreSQL持久化用户凭证、TOTP 配置、WebAuthn 凭据、OAuth2/OIDC 状态等敏感数据其 Schema 由一组版本化迁移脚本管理。本文围绕authelia storage migrate命令参考展开完整覆盖该命令组的用法、全部可继承的全局选项并结合 internal/commands/storage.go、internal/commands/storage_run.go 与 internal/storage/sql_provider_schema.go 的源码实现讲解每个子命令的实际执行链路、Schema 版本语义与迁移的安全机制帮助你在升级 Authelia、排障或做数据库运维时准确掌控迁移过程。命令总览authelia storage migrate是什么根据 命令定义源码authelia storage migrate是一个只负责“执行或列出迁移”的命令组节点本身Use: migrate Short: Perform or list migrations Args: cobra.NoArgs它的 Synopsis来源 internal/commands/const.go为Perform or list migrations.This subcommand handles schema migration tasks.该节点本身不接受任何位置参数cobra.NoArgs也不带RunE直接执行只会展示帮助。文档给出的唯一示例即authelia storage migrate --help它挂载了 5 个子命令见 newStorageMigrateCmd子命令作用源码入口up执行“升”迁移默认升到最新版本可用--target指定目标版本newStorageMigrateUpCmddown执行“降”迁移必须指定--target并需确认数据销毁newStorageMigrateDownCmdlist-up列出当前版本以上、本版本 Authelia 可用的全部 up 迁移newStorageMigrateListUpCmdlist-down列出当前版本以下、本版本 Authelia 可用的全部 down 迁移newStorageMigrateListDownCmdhistory显示数据库migrations表中已执行的迁移历史newStorageMigrateHistoryCmd执行前会发生什么配置加载与存储 Provider 装配在任何一个storage子命令真正执行前都会先走 internal/commands/storage.go#L22-L27 中定义的PersistentPreRunE四步链PersistentPreRunE: ctx.ChainRunE( ctx.ConfigStorageCommandLineConfigRunE, ctx.HelperConfigLoadRunE, ctx.ConfigValidateStorageRunE, ctx.LoadProvidersStorageRunE, ),命令行标志映射到配置键ConfigStorageCommandLineConfigRunE 将 CLI 标志映射为配置项例如--encryption-key → storage.encryption_key、--sqlite.path → storage.local.path、--mysql.address → storage.mysql.address、--postgres.schema → storage.postgres.schema等。也就是说命令行参数可以覆盖configuration.yml中的存储配置。加载配置文件HelperConfigLoadRunE读取-c/--config指定的文件或目录默认configuration.yml。校验存储与 TOTP 配置ConfigValidateStorageRunE 调用validator.ValidateStorage与validator.ValidateTOTP任何校验错误都会导致命令直接失败。加载受信任证书并构建存储 ProviderLoadProvidersStorageRunE 先加载 TLS 受信任证书用于 MySQL/PostgreSQL 连接再创建StorageProvider放入命令上下文供后续RunE使用每个RunE结束时都会defer StorageProvider.Close()关闭连接。理解这条链路非常重要它解释了为什么authelia storage migrate --help之外的所有存储类命令都要求“能连上数据库且配置合法”也是--postgres.password等敏感参数只能通过命令行传递的原因。子命令详解authelia storage migrate up升级到目标默认最新版本官方示例来自 internal/commands/const.go#L535-L538authelia storage migrate up authelia storage migrate up --config config.yml authelia storage migrate up --target 20 --config config.yml authelia storage migrate up --encryption-key b3453fde-ecc2-4a1f-9422-2707ddbed495 --postgres.address tcp://postgres:5432 --postgres.password autheliapw标志定义storage.go#L857-t, --target int sets the version to migrate to, by default this is the latest version执行逻辑在 runStorageMigrationup方向未显式指定--target时自动取storage.SchemaLatest最新版本down方向未指定--target则直接报错you must set a target version。随后统一调用store.SchemaMigrate(ctx, up, version)。authelia storage migrate down降级迁移高风险需确认官方示例internal/commands/const.go#L547-L549authelia storage migrate down --target 20 authelia storage migrate down --target 20 --config config.yml authelia storage migrate down --target 20 --encryption-key b3453fde-ecc2-4a1f-9422-2707ddbed495 --postgres.address tcp://postgres:5432 --postgres.password autheliapw标志定义storage.go#L874-L875-t, --target int sets the version to migrate to --destroy-data bool confirms you want to destroy data with this migrationrunStorageMigration 对down方向有强防护除非提供--destroy-data标志否则会在终端交互式提示Schema Down Migrations may DESTROY data, type DESTROY and press return to continue:输入不是DESTROY就会以cancelling down migration due to user not accepting data destruction退出。这是防止误操作清空/回退数据的关键安全门。authelia storage migrate list-up/list-down预览可用迁移官方示例internal/commands/const.go#L513-L515 与 #L524-L526authelia storage migrate list-up authelia storage migrate list-up --config config.yml authelia storage migrate list-up --encryption-key b3453fde-ecc2-4a1f-9422-2707ddbed495 --postgres.address tcp://postgres:5432 --postgres.password autheliapw authelia storage migrate list-down authelia storage migrate list-down --config config.yml两者共用 runStorageMigrateList 实现分别调用 Provider 接口的 SchemaMigrationsUp 与 SchemaMigrationsDown接口定义见 provider.go#L318-L324。输出为tabwriter对齐的两列表格Storage Schema Migration List (Up) Version Description当当前版本与目标版本相同ErrMigrateCurrentVersionSameAsTarget、或没有可用迁移ErrNoAvailableMigrations时输出No Migrations Available并正常退出——即“无迁移可做”不算错误。authelia storage migrate history查看已执行迁移记录官方示例internal/commands/const.go#L502-L504authelia storage migrate history authelia storage migrate history --config config.yml authelia storage migrate history --encryption-key b3453fde-ecc2-4a1f-9422-2707ddbed495 --postgres.address tcp://postgres:5432 --postgres.password autheliapw实现见 runStorageMigrateHistory先读取SchemaVersion若数据库版本小于 1 则输出No migration history is available for schemas that are not version 1 or above.否则查询migrations表并输出表头为ID Date Before After Authelia Version的表格如果查不到任何历史记录会报错no migration history found which may indicate a broken schema提示数据库可能处于异常状态。每次迁移成功应用后都会由 schemaMigrateFinalize 向migrations表插入一条含“前版本/后版本/所用 Authelia 版本号”的记录这正是history的数据来源。可继承的全局选项Options inherited from parent commands以下是命令参考文档列出的全部继承选项其定义与默认值可在 newStorageCmd 中逐一对应验证-c, --config strings configuration files or directories to load, for more information run authelia -h authelia config (default [configuration.yml]) --config.experimental.filters strings list of filters to apply to all configuration files, for more information run authelia -h authelia filters --encryption-key string the storage encryption key to use --mysql.address string the MySQL server address (default tcp://127.0.0.1:3306) --mysql.database string the MySQL database name (default authelia) --mysql.password string the MySQL password --mysql.username string the MySQL username (default authelia) --postgres.address string the PostgreSQL server address (default tcp://127.0.0.1:5432) --postgres.database string the PostgreSQL database name (default authelia) --postgres.password string the PostgreSQL password --postgres.schema string the PostgreSQL schema name (default public) --postgres.username string the PostgreSQL username (default authelia) --sqlite.path string the SQLite database path补充说明源码依据--encryption-key、--sqlite.path及--mysql.*、--postgres.*全部是authelia storage的PersistentFlagsstorage.go#L33-L46因此migrate及其全部子命令都能继承-c/--config与--config.experimental.filters来自根命令默认配置文件为configuration.yml这些标志通过 ConfigStorageCommandLineConfigRunE 映射到storage.*配置路径等价于在configuration.yml中配置storage: {sqlite: {path: ...}, mysql: {...}, postgres: {...}}与storage.encryption_key完整配置结构可参考根目录的 config.template.yml。migrate命令组自身的唯一专有选项是帮助标志-h, --help help for migrate而up/down各自追加--targetdown追加--destroy-data见上文子命令详解。迁移脚本从哪里来内嵌 SQL 与命名规范迁移脚本以 Goembed方式编译进二进制internal/storage/migrations.go#L20-L21//go:embed migrations/* var migrationsFS embed.FS按数据库方言分为三套目录当前仓库中共有29 个版本覆盖从初始 Schema 到 OAuth2 Resource 的演进internal/storage/migrations/mysql/internal/storage/migrations/postgres/internal/storage/migrations/sqlite/命名规范为V4位版本号.描述名.{up|down}.sql例如 V0004.OpenIDConnect.up.sql引入 OpenIDConnect 相关表、V0013.OneTimeCode.up.sql、V0029.OAuth2Resource.up.sql。scanMigration 用正则解析文件名得到Version、方向up/down与描述下划线转空格并把文件内容作为Query载入 model.SchemaMigrationloadMigrations 再按“当前版本 → 目标版本”过滤出需要执行的脚本升序up或降序down排列。这意味着list-up/list-down看到的“可用迁移”就是嵌入脚本中版本高于/低于数据库当前 Schema 版本的部分。Schema 版本语义与迁移安全机制版本值的特殊含义SchemaVersionToString 定义了版本语义值字符串含义-2unknown未知 Schema 状态如含 v1 表的 pre1 混合结构-1pre1旧版1.x 之前Schema非迁移体系0N/A空库尚无任何表≥1数字当前 Schema 版本号SchemaVersion 通过检查migrations表是否存在、以及是否残留 pre1 时代的表结构来推断版本。前置检查schemaMigrateChecksSchemaMigrate 在执行前会调用 schemaMigrateChecks 拦截非法场景常见错误包括数据库处于pre1-1状态时尝试 up 迁移会提示应先用当前版本升到 v1 再降级目标版本 当前版本ErrFmtMigrateAlreadyOnTargetVersion数据库版本高于本版本 Authelia 已知最新版本errFmtSchemaCurrentGreaterThanLatestKnown——提示你可能在用旧二进制操作新库up 时目标版本低于当前版本、或高于嵌入的最新版本down 时目标版本为负数、或高于当前版本目标已是最新时 up 返回ErrSchemaAlreadyUpToDate。事务、锁与失败回滚从源码结构看迁移执行有三个值得注意的安全设计sql_provider_schema.go#L190-L244事务包裹MySQL 因 DDL 隐式提交特性不在外层开事务每个迁移单独走 schemaMigrateApply 中的独立事务PostgreSQL/SQLite 则由外层BeginTxx开启统一事务PostgreSQL 加锁对 PostgreSQL 会先LOCK TABLE migrations IN ACCESS EXCLUSIVEschemaMigrateLock防止并发迁移互相踩踏失败回滚若某条迁移应用失败非事务路径会反向加载并应用回滚迁移schemaMigrateRollbackWithoutTx最终错误信息形如migration rollback complete. rollback caused by: ...。另外首次从空库版本 0升到 v1 时schemaMigrateApply 会写入存储加密校验值写入encryption检查数据并依据目标版本选择传统密钥派生方式这就是为什么迁移命令同样需要传入正确的--encryption-key——密钥不一致会导致后续storage encryption check报 FAILURE。服务启动时也会自动迁移值得注意的是Authelia 服务自身的启动检查 StartupCheck 会先校验加密密钥然后自动执行SchemaMigrate(ctx, true, SchemaLatest)已是最新则记录日志Storage schema is already up to date。因此正常运行中的服务通常会自动把 Schema 升到当前二进制支持的最新版本authelia storage migrate up主要用于服务停机维护、使用独立二进制/容器镜像做数据库运维、或需要显式指定--target只升到某一中间版本的场景反过来降级down绝不会自动发生必须人工执行down --target N并通过确认。实战排障流程建议结合上述命令与 schema-info 命令 提供的诊断能力推荐的运维检查顺序为authelia storage schema-info --config config.yml—— 查看Schema Version、Schema Upgrade Available、Schema Tables、Schema Encryption Keyvalid/invalid/unsupported实现逻辑见 runStorageSchemaInfoauthelia storage migrate list-up --config config.yml—— 确认待应用的迁移清单Version Descriptionauthelia storage migrate up --config config.yml必要时加--target N或--encryption-key ...authelia storage migrate history --config config.yml—— 核对migrations表新增记录及所用 Authelia 版本号若怀疑密钥问题配套使用 storage encryption 子命令组check支持--verbose逐行校验见 runStorageSchemaEncryptionCheckKey。相关文档authelia storage父命令含 schema-info / encryption / user / bans 等子命令authelia storage migrate upauthelia storage migrate downauthelia storage migrate historyauthelia storage migrate list-downauthelia storage migrate list-up对应源码与测试入口internal/commands/storage_run_test.go、internal/storage/migrations_test.go、internal/storage/sql_provider_schema_test.go 与 internal/storage/migrations_backfill_test.go可用于理解迁移选择、检查与回滚逻辑的验证方式。【免费下载链接】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 `storage migrate` 命令详解：SQLite / MySQL / PostgreSQL 数据库 Schema 迁移管理指南
Autheliastorage migrate命令详解SQLite / MySQL / PostgreSQL 数据库 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 使用 SQL 数据库SQLite、MySQL 或 PostgreSQL持久化用户凭证、TOTP 配置、WebAuthn 凭据、OAuth2/OIDC 状态等敏感数据其 Schema 由一组版本化迁移脚本管理。本文围绕authelia storage migrate命令参考展开完整覆盖该命令组的用法、全部可继承的全局选项并结合 internal/commands/storage.go、internal/commands/storage_run.go 与 internal/storage/sql_provider_schema.go 的源码实现讲解每个子命令的实际执行链路、Schema 版本语义与迁移的安全机制帮助你在升级 Authelia、排障或做数据库运维时准确掌控迁移过程。命令总览authelia storage migrate是什么根据 命令定义源码authelia storage migrate是一个只负责“执行或列出迁移”的命令组节点本身Use: migrate Short: Perform or list migrations Args: cobra.NoArgs它的 Synopsis来源 internal/commands/const.go为Perform or list migrations.This subcommand handles schema migration tasks.该节点本身不接受任何位置参数cobra.NoArgs也不带RunE直接执行只会展示帮助。文档给出的唯一示例即authelia storage migrate --help它挂载了 5 个子命令见 newStorageMigrateCmd子命令作用源码入口up执行“升”迁移默认升到最新版本可用--target指定目标版本newStorageMigrateUpCmddown执行“降”迁移必须指定--target并需确认数据销毁newStorageMigrateDownCmdlist-up列出当前版本以上、本版本 Authelia 可用的全部 up 迁移newStorageMigrateListUpCmdlist-down列出当前版本以下、本版本 Authelia 可用的全部 down 迁移newStorageMigrateListDownCmdhistory显示数据库migrations表中已执行的迁移历史newStorageMigrateHistoryCmd执行前会发生什么配置加载与存储 Provider 装配在任何一个storage子命令真正执行前都会先走 internal/commands/storage.go#L22-L27 中定义的PersistentPreRunE四步链PersistentPreRunE: ctx.ChainRunE( ctx.ConfigStorageCommandLineConfigRunE, ctx.HelperConfigLoadRunE, ctx.ConfigValidateStorageRunE, ctx.LoadProvidersStorageRunE, ),命令行标志映射到配置键ConfigStorageCommandLineConfigRunE 将 CLI 标志映射为配置项例如--encryption-key → storage.encryption_key、--sqlite.path → storage.local.path、--mysql.address → storage.mysql.address、--postgres.schema → storage.postgres.schema等。也就是说命令行参数可以覆盖configuration.yml中的存储配置。加载配置文件HelperConfigLoadRunE读取-c/--config指定的文件或目录默认configuration.yml。校验存储与 TOTP 配置ConfigValidateStorageRunE 调用validator.ValidateStorage与validator.ValidateTOTP任何校验错误都会导致命令直接失败。加载受信任证书并构建存储 ProviderLoadProvidersStorageRunE 先加载 TLS 受信任证书用于 MySQL/PostgreSQL 连接再创建StorageProvider放入命令上下文供后续RunE使用每个RunE结束时都会defer StorageProvider.Close()关闭连接。理解这条链路非常重要它解释了为什么authelia storage migrate --help之外的所有存储类命令都要求“能连上数据库且配置合法”也是--postgres.password等敏感参数只能通过命令行传递的原因。子命令详解authelia storage migrate up升级到目标默认最新版本官方示例来自 internal/commands/const.go#L535-L538authelia storage migrate up authelia storage migrate up --config config.yml authelia storage migrate up --target 20 --config config.yml authelia storage migrate up --encryption-key b3453fde-ecc2-4a1f-9422-2707ddbed495 --postgres.address tcp://postgres:5432 --postgres.password autheliapw标志定义storage.go#L857-t, --target int sets the version to migrate to, by default this is the latest version执行逻辑在 runStorageMigrationup方向未显式指定--target时自动取storage.SchemaLatest最新版本down方向未指定--target则直接报错you must set a target version。随后统一调用store.SchemaMigrate(ctx, up, version)。authelia storage migrate down降级迁移高风险需确认官方示例internal/commands/const.go#L547-L549authelia storage migrate down --target 20 authelia storage migrate down --target 20 --config config.yml authelia storage migrate down --target 20 --encryption-key b3453fde-ecc2-4a1f-9422-2707ddbed495 --postgres.address tcp://postgres:5432 --postgres.password autheliapw标志定义storage.go#L874-L875-t, --target int sets the version to migrate to --destroy-data bool confirms you want to destroy data with this migrationrunStorageMigration 对down方向有强防护除非提供--destroy-data标志否则会在终端交互式提示Schema Down Migrations may DESTROY data, type DESTROY and press return to continue:输入不是DESTROY就会以cancelling down migration due to user not accepting data destruction退出。这是防止误操作清空/回退数据的关键安全门。authelia storage migrate list-up/list-down预览可用迁移官方示例internal/commands/const.go#L513-L515 与 #L524-L526authelia storage migrate list-up authelia storage migrate list-up --config config.yml authelia storage migrate list-up --encryption-key b3453fde-ecc2-4a1f-9422-2707ddbed495 --postgres.address tcp://postgres:5432 --postgres.password autheliapw authelia storage migrate list-down authelia storage migrate list-down --config config.yml两者共用 runStorageMigrateList 实现分别调用 Provider 接口的 SchemaMigrationsUp 与 SchemaMigrationsDown接口定义见 provider.go#L318-L324。输出为tabwriter对齐的两列表格Storage Schema Migration List (Up) Version Description当当前版本与目标版本相同ErrMigrateCurrentVersionSameAsTarget、或没有可用迁移ErrNoAvailableMigrations时输出No Migrations Available并正常退出——即“无迁移可做”不算错误。authelia storage migrate history查看已执行迁移记录官方示例internal/commands/const.go#L502-L504authelia storage migrate history authelia storage migrate history --config config.yml authelia storage migrate history --encryption-key b3453fde-ecc2-4a1f-9422-2707ddbed495 --postgres.address tcp://postgres:5432 --postgres.password autheliapw实现见 runStorageMigrateHistory先读取SchemaVersion若数据库版本小于 1 则输出No migration history is available for schemas that are not version 1 or above.否则查询migrations表并输出表头为ID Date Before After Authelia Version的表格如果查不到任何历史记录会报错no migration history found which may indicate a broken schema提示数据库可能处于异常状态。每次迁移成功应用后都会由 schemaMigrateFinalize 向migrations表插入一条含“前版本/后版本/所用 Authelia 版本号”的记录这正是history的数据来源。可继承的全局选项Options inherited from parent commands以下是命令参考文档列出的全部继承选项其定义与默认值可在 newStorageCmd 中逐一对应验证-c, --config strings configuration files or directories to load, for more information run authelia -h authelia config (default [configuration.yml]) --config.experimental.filters strings list of filters to apply to all configuration files, for more information run authelia -h authelia filters --encryption-key string the storage encryption key to use --mysql.address string the MySQL server address (default tcp://127.0.0.1:3306) --mysql.database string the MySQL database name (default authelia) --mysql.password string the MySQL password --mysql.username string the MySQL username (default authelia) --postgres.address string the PostgreSQL server address (default tcp://127.0.0.1:5432) --postgres.database string the PostgreSQL database name (default authelia) --postgres.password string the PostgreSQL password --postgres.schema string the PostgreSQL schema name (default public) --postgres.username string the PostgreSQL username (default authelia) --sqlite.path string the SQLite database path补充说明源码依据--encryption-key、--sqlite.path及--mysql.*、--postgres.*全部是authelia storage的PersistentFlagsstorage.go#L33-L46因此migrate及其全部子命令都能继承-c/--config与--config.experimental.filters来自根命令默认配置文件为configuration.yml这些标志通过 ConfigStorageCommandLineConfigRunE 映射到storage.*配置路径等价于在configuration.yml中配置storage: {sqlite: {path: ...}, mysql: {...}, postgres: {...}}与storage.encryption_key完整配置结构可参考根目录的 config.template.yml。migrate命令组自身的唯一专有选项是帮助标志-h, --help help for migrate而up/down各自追加--targetdown追加--destroy-data见上文子命令详解。迁移脚本从哪里来内嵌 SQL 与命名规范迁移脚本以 Goembed方式编译进二进制internal/storage/migrations.go#L20-L21//go:embed migrations/* var migrationsFS embed.FS按数据库方言分为三套目录当前仓库中共有29 个版本覆盖从初始 Schema 到 OAuth2 Resource 的演进internal/storage/migrations/mysql/internal/storage/migrations/postgres/internal/storage/migrations/sqlite/命名规范为V4位版本号.描述名.{up|down}.sql例如 V0004.OpenIDConnect.up.sql引入 OpenIDConnect 相关表、V0013.OneTimeCode.up.sql、V0029.OAuth2Resource.up.sql。scanMigration 用正则解析文件名得到Version、方向up/down与描述下划线转空格并把文件内容作为Query载入 model.SchemaMigrationloadMigrations 再按“当前版本 → 目标版本”过滤出需要执行的脚本升序up或降序down排列。这意味着list-up/list-down看到的“可用迁移”就是嵌入脚本中版本高于/低于数据库当前 Schema 版本的部分。Schema 版本语义与迁移安全机制版本值的特殊含义SchemaVersionToString 定义了版本语义值字符串含义-2unknown未知 Schema 状态如含 v1 表的 pre1 混合结构-1pre1旧版1.x 之前Schema非迁移体系0N/A空库尚无任何表≥1数字当前 Schema 版本号SchemaVersion 通过检查migrations表是否存在、以及是否残留 pre1 时代的表结构来推断版本。前置检查schemaMigrateChecksSchemaMigrate 在执行前会调用 schemaMigrateChecks 拦截非法场景常见错误包括数据库处于pre1-1状态时尝试 up 迁移会提示应先用当前版本升到 v1 再降级目标版本 当前版本ErrFmtMigrateAlreadyOnTargetVersion数据库版本高于本版本 Authelia 已知最新版本errFmtSchemaCurrentGreaterThanLatestKnown——提示你可能在用旧二进制操作新库up 时目标版本低于当前版本、或高于嵌入的最新版本down 时目标版本为负数、或高于当前版本目标已是最新时 up 返回ErrSchemaAlreadyUpToDate。事务、锁与失败回滚从源码结构看迁移执行有三个值得注意的安全设计sql_provider_schema.go#L190-L244事务包裹MySQL 因 DDL 隐式提交特性不在外层开事务每个迁移单独走 schemaMigrateApply 中的独立事务PostgreSQL/SQLite 则由外层BeginTxx开启统一事务PostgreSQL 加锁对 PostgreSQL 会先LOCK TABLE migrations IN ACCESS EXCLUSIVEschemaMigrateLock防止并发迁移互相踩踏失败回滚若某条迁移应用失败非事务路径会反向加载并应用回滚迁移schemaMigrateRollbackWithoutTx最终错误信息形如migration rollback complete. rollback caused by: ...。另外首次从空库版本 0升到 v1 时schemaMigrateApply 会写入存储加密校验值写入encryption检查数据并依据目标版本选择传统密钥派生方式这就是为什么迁移命令同样需要传入正确的--encryption-key——密钥不一致会导致后续storage encryption check报 FAILURE。服务启动时也会自动迁移值得注意的是Authelia 服务自身的启动检查 StartupCheck 会先校验加密密钥然后自动执行SchemaMigrate(ctx, true, SchemaLatest)已是最新则记录日志Storage schema is already up to date。因此正常运行中的服务通常会自动把 Schema 升到当前二进制支持的最新版本authelia storage migrate up主要用于服务停机维护、使用独立二进制/容器镜像做数据库运维、或需要显式指定--target只升到某一中间版本的场景反过来降级down绝不会自动发生必须人工执行down --target N并通过确认。实战排障流程建议结合上述命令与 schema-info 命令 提供的诊断能力推荐的运维检查顺序为authelia storage schema-info --config config.yml—— 查看Schema Version、Schema Upgrade Available、Schema Tables、Schema Encryption Keyvalid/invalid/unsupported实现逻辑见 runStorageSchemaInfoauthelia storage migrate list-up --config config.yml—— 确认待应用的迁移清单Version Descriptionauthelia storage migrate up --config config.yml必要时加--target N或--encryption-key ...authelia storage migrate history --config config.yml—— 核对migrations表新增记录及所用 Authelia 版本号若怀疑密钥问题配套使用 storage encryption 子命令组check支持--verbose逐行校验见 runStorageSchemaEncryptionCheckKey。相关文档authelia storage父命令含 schema-info / encryption / user / bans 等子命令authelia storage migrate upauthelia storage migrate downauthelia storage migrate historyauthelia storage migrate list-downauthelia storage migrate list-up对应源码与测试入口internal/commands/storage_run_test.go、internal/storage/migrations_test.go、internal/storage/sql_provider_schema_test.go 与 internal/storage/migrations_backfill_test.go可用于理解迁移选择、检查与回滚逻辑的验证方式。【免费下载链接】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），仅供参考