Authelia storage migrate down 命令详解：安全执行数据库 Schema 降级迁移

Authelia storage migrate down 命令详解：安全执行数据库 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 storage migrate down是 Authelia CLI 中用于将存储后端（SQLite / MySQL / PostgreSQL）的数据库 Schema回退（migrate down）到指定目标版本的子命令。读完本文，你将完整掌握该命令的选项、目标版本规则与交互式破坏性确认机制，并理解其背后的版本化 SQL 迁移模型——包括迁移文件如何被内嵌加载、按什么顺序执行、如何预览与审计，以及在涉及数据加密字段降级时的特殊行为，从而在生产环境变更前做出有依据的操作决策。

命令概览与完整选项

Synopsis

storage migrate down执行"降级迁移"：它运行当前 Authelia 版本中所有版本低于数据库当前 Schema 版本的 down 迁移脚本，把数据库结构回退到目标版本：

authelia storage migrate down [flags]

官方示例（摘自 命令参考文档）覆盖了从"仅指定目标版本"到"完整指定 PostgreSQL 连接参数"的典型用法：

authelia 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父命令注册了一组持久标志（见 internal/commands/storage.go），所有storage子命令均可用。这些标志可以覆盖配置文件中的对应项：

这些命令行标志到配置键的映射关系在 internal/commands/storage_run.go 的ConfigStorageCommandLineConfigRunE中显式定义，例如--encryption-key映射到storage.encryption_key、--sqlite.path映射到storage.local.path、--postgres.address映射到storage.postgres.address。这意味着你完全可以用命令行标志"就地"指定一套与配置文件不同的存储连接，而无需修改任何 YAML 文件。

破坏性确认机制：--destroy-data与交互式 DESTROY

降级迁移最大的风险是数据丢失（down 脚本可能删除表、列或约束）。Authelia 在 internal/commands/storage_run.go 的runStorageMigration中实现了双重保护：

1. down 方向强制要求目标版本：未显式指定--target时直接报错you must set a target version（up方向则默认迁移到最新版本，down没有"默认值"，这是刻意设计的防御）；

2. 交互式确认：除非传入--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。

--destroy-data标志的作用是把confirmed直接置为true（见 internal/commands/storage.go 中该标志的定义："confirms you want to destroy data with this migration"），主要面向脚本化/自动化场景，避免阻塞在交互输入上。

操作建议：在首次执行降级前，先用authelia storage migrate list-down预览将被执行的 down 迁移列表，再决定目标版本；--destroy-data只应在已做过备份、且由自动化流程触发的场景中使用。

迁移模型：版本化 SQL 文件与加载规则

迁移文件的存放与内嵌

Authelia 将每个支持的后端（sqlite、mysql、postgres）的迁移 SQL 文件按统一命名约定存放在internal/storage/migrations/目录下，并通过//go:embed在编译期内嵌进二进制（见 internal/storage/migrations.go）：

internal/storage/migrations/ ├── mysql/ ├── postgres/ └── sqlite/ ├── V0001.Initial_Schema.up.sql ├── V0001.Initial_Schema.down.sql ├── ... └── V0029.OAuth2Resource.down.sql

以 SQLite 为例，当前仓库包含V0001 至 V0029共 29 个版本，每个版本都有配对的.up.sql/.down.sql（如 V0020.Regulation.up.sql 与 V0020.Regulation.down.sql）。

scanMigration通过正则解析文件名得到Version、Direction、Name三个字段并读取 SQL 内容（internal/storage/migrations.go）。loadMigrations则在给定prior（当前版本）与target（目标版本）之间筛选出需要执行的迁移：

• 方向由prior < target判定，down场景只取.down.sql文件；
• down 方向只保留满足target < Version <= prior的迁移，即从当前版本一直执行到目标版本+1，目标版本本身的 down 脚本不会执行；
• 执行顺序按版本降序排列（见 internal/storage/migrations.go），保证 V0029 → V0028 → … → V0021 的逆序回退。

此外，当prior == target时会返回ErrMigrateCurrentVersionSameAsTarget错误，用于提示"当前版本与目标版本相同，无操作可执行"。

历史审计表

每次迁移（无论 up 还是 down）都会写入历史表。authelia storage migrate history输出以ID / Date / Before / After / Authelia Version为列（见 internal/commands/storage_run.go），其中"Before/After"即迁移前后的 Schema 版本。历史行的数据结构定义在 internal/model/migration.go，包含applied时间、version_before、version_after与执行时的 Authelia 版本字符串。如果历史为空，命令会返回no migration history found which may indicate a broken schema的告警性错误，这对判断"数据库是否被手工动过"很有价值。

实战操作：一次完整的降级流程

以下流程以 PostgreSQL 为例（SQLite/MySQL 同理，替换连接参数即可）。注意每一步都应使用与线上服务一致的--config与--encryption-key。

第 1 步：确认当前 Schema 状态

authelia storage schema-info \ --config config.yml \ --postgres.address tcp://postgres:5432 --postgres.password autheliapw

schema-info会输出当前 Schema 版本、是否有可用升级、表清单以及加密密钥校验结果（实现见 internal/commands/storage_run.go）。记下Schema Version的值，它就是本次降级的prior。

第 2 步：预览将被执行的 down 迁移

authelia storage migrate list-down \ --config config.yml \ --postgres.address tcp://postgres:5432 --postgres.password autheliapw

list-down输出Storage Schema Migration List (Down)以及Version / Description两列（实现见 internal/commands/storage_run.go），描述来自迁移文件名的Name字段（下划线替换为空格）。对照这份清单确认你理解每一个即将回退的结构变更。

第 3 步：执行降级迁移

authelia storage migrate down --target 20 \ --config config.yml \ --postgres.address tcp://postgres:5432 --postgres.password autheliapw

执行时命令会先进行交互式确认（输入DESTROY），随后按降序执行 V0029 到 V0021 的.down.sql脚本。若已在自动化环境中完成备份并确认风险，可加上--destroy-data跳过交互：

authelia storage migrate down --target 20 --destroy-data \ --config config.yml --postgres.address tcp://postgres:5432 --postgres.password autheliapw

第 4 步：验证结果

authelia storage schema-info --config config.yml ... authelia storage migrate history --config config.yml ...

确认Schema Version已变为20，且history中新增的行呈现Before=29 After=20（或逐版本的连续记录），即可完成闭环。

与 up 迁移、加密降级相关的细节

up / down 行为差异

migrate up与migrate down共用同一个 RunE 工厂NewStorageMigrationRunE(up bool)（internal/commands/storage_run.go），差异在于：

• up未指定--target时回退为storage.SchemaLatest（最新版本），且不需要破坏性确认；
• down未指定--target时直接报错，且必须通过DESTROY确认（或--destroy-data）。

降级跨越加密版本时的特殊行为

Schema 版本 25/26 引入了存储加密（AAD）相关变更。从测试 internal/storage/migrations_test.go 可以确认两个重要行为：

• TestSchemaMigrateDownToZeroShouldSucceedWithStaleEncryptionKey：即使当前配置的加密密钥与数据库内数据使用的密钥不一致（"陈旧密钥"），降级到版本 0 依然可以成功；
• TestSchemaMigrateDownToPriorVersionShouldReEncryptToLegacyKey：降级到加密密钥派生版本（schemaVersionEncryptionKeyDerivation）之前时，存储层会把数据重新加密为旧版密钥格式，保证回退后的旧版本 Authelia 仍能解密数据。

这说明migrate down不只是纯 DDL 回退：跨越加密相关版本时，它还承担数据格式的双向兼容处理。

相关子命令

storage migrate命令组（定义于 internal/commands/storage.go）共有 5 个子命令，配合使用可覆盖降级操作的全流程：

小结与风险提示

• storage migrate down是高风险操作：down 迁移可能删除表/列/约束从而销毁数据，因此命令内置了--target必填约束与DESTROY交互确认，--destroy-data仅用于确认过风险后的自动化场景；
• 操作顺序建议固化为：schema-info（看当前版本）→migrate list-down（预览）→migrate down --target N（执行）→schema-info+migrate history（验证）；
• 迁移 SQL 按后端分别内嵌于internal/storage/migrations/{sqlite,mysql,postgres}/，命名遵循V00NN.Name.up.sql/V00NN.Name.down.sql约定，当前仓库最新为V0029，降级目标只能落在 1 至当前版本之间；
• 若降级会跨越存储加密相关版本（V0025/V0026 之前），存储层会自动处理旧格式重加密；变更前务必备份数据库并妥善保存--encryption-key对应的密钥。

更多命令上下文可参考父命令文档 authelia storage migrate。

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