Alembic

数据库迁移 (Alembic)

数据库迁移 (Alembic)

v2.4.0 引入 Flask-Migrate（封装 Alembic） 统一管理 schema 版本，支持升级/回滚与插件迁移脚本接入。

旧站自动迁移

1. 检测旧库（存在核心表但无 alembic_version）
2. 自动 stamp baseline（标记为 0001，对应 v2.3.0 schema）
3. 执行增量迁移（0002 建搜索索引表 → 0003 插入搜索设置 → 0004 加 storage 列）

v2.3.x → v2.4.0 无需手动操作，覆盖代码后首次启动自动完成。

CLI 命令

`flask db upgrade          # 升级到最新
flask db downgrade -1     # 回滚一版
flask db current          # 查看当前版本
flask db history          # 查看迁移历史
flask db migrate -m "xxx" # 新建迁移脚本（开发用）`

⚠️ 生产环境慎用 downgrade；SQLite batch 模式下回滚会重建整表，大表可能耗时较长。

插件迁移钩子

插件通过 PluginBase.get_migration_files() 返回 migrations/versions/ 下脚本路径，核心自动合并到 Alembic version_locations：

`def get_migration_files(self):
    mig_dir = Path(self.get_plugin_dir()) / 'migrations' / 'versions'
    return sorted(str(p) for p in mig_dir.glob('*.py') if not p.name.startswith('__'))`

无迁移文件的插件仍由 db.create_all() 兜底建表；迁移钩子仅用于表结构变更场景。

数据库类型一键迁移（v3.1.0）

官方内置插件 db_migrator（默认不启用），解决「本地用 SQLite 开发、上线换 MySQL/PostgreSQL」的迁移需求。后台 插件管理 启用后，系统设置 → 数据库迁移：

1. 填写目标库类型（MySQL / PostgreSQL）、主机、端口、库名、账号密码，先在数据库服务器上建好空库；点「测试连接」确认可达。
2. 点「开始迁移」：目标库建表 → 按 metadata.sorted_tables 拓扑序逐表复制行数据（每批 500 行、单事务失败整体回滚）→ PostgreSQL 自动重置自增序列（setval）→ 同步源库 alembic_version 版本号（重启时不重复执行增量迁移）。
3. 生效方式二选一：勾选「迁移后立即切换」复用安装向导同款 switch_engine 热切换引擎，免重启即时生效（失败自动回滚配置继续用旧库）；不勾选则写入 instance/db_config.json，重启后生效，删除该文件即可放弃切换。

⚠️ 高危操作：迁移会读取当前库全部业务表并写入目标库，请在维护时段执行并提前备份；目标库与本系统同名的表已有数据时拒绝迁移，确认清空重迁需勾选「覆盖目标库已有数据」（drop_all 仅删除本系统已知表）。搜索引擎索引与上传文件不受迁移影响。权限点 db_migrator:manage 不向预设角色默认授权，仅超管或显式授权角色可用。