"""已发布 Alembic 迁移文件的不可变校验。 Alembic 只记录 revision,不记录脚本内容。修改已经执行过的迁移不会再次运行, 但全新库会执行新内容,最终造成生产与开发/新环境结构分叉。 本模块用提交到仓库的 SHA256 manifest 锁定每个迁移文件。新增迁移后显式运行: uv run python -m web.backend.migrations.immutability --write 已有迁移的任何内容变化都会让应用启动和测试直接失败。修正历史迁移只能新增 后续 repair revision,不能改写旧文件。 """ from __future__ import annotations import argparse import hashlib import json import re from pathlib import Path from typing import Any MIGRATIONS_DIR = Path(__file__).resolve().parent VERSIONS_DIR = MIGRATIONS_DIR / "versions" MANIFEST_PATH = MIGRATIONS_DIR / "migration_manifest.json" _REVISION_RE = re.compile( r'^revision(?::\s*str)?\s*=\s*["\']([^"\']+)["\']', re.MULTILINE, ) class MigrationManifestError(RuntimeError): """迁移文件与不可变 manifest 不一致。""" def _migration_files(versions_dir: Path = VERSIONS_DIR) -> list[Path]: return sorted( ( path for path in versions_dir.glob("*.py") if path.is_file() and not path.name.startswith("__") ), key=lambda path: path.name, ) def _revision(path: Path) -> str: match = _REVISION_RE.search(path.read_text(encoding="utf-8")) if match is None: raise MigrationManifestError(f"迁移文件缺少 revision: {path.name}") return match.group(1) def _sha256(path: Path) -> str: return hashlib.sha256(path.read_bytes()).hexdigest() def build_manifest(versions_dir: Path = VERSIONS_DIR) -> dict[str, Any]: migrations = { path.name: { "revision": _revision(path), "sha256": _sha256(path), } for path in _migration_files(versions_dir) } return { "schema_version": 1, "description": "Alembic migration immutability manifest; never edit released files.", "migrations": migrations, } def write_manifest( *, versions_dir: Path = VERSIONS_DIR, manifest_path: Path = MANIFEST_PATH, force: bool = False, ) -> None: current = build_manifest(versions_dir) if manifest_path.exists() and not force: expected = load_manifest(manifest_path)["migrations"] current_migrations = current["migrations"] deleted = sorted(set(expected) - set(current_migrations)) changed = sorted( filename for filename in set(expected) & set(current_migrations) if expected[filename] != current_migrations[filename] ) if deleted or changed: details = [*(f"删除: {name}" for name in deleted), *( f"修改: {name}" for name in changed )] raise MigrationManifestError( "拒绝更新已发布迁移,只有新增迁移可以写入 manifest:\n- " + "\n- ".join(details) + "\n如确属灾难恢复,必须显式使用 --force 并人工审查 diff。" ) manifest_path.write_text( json.dumps(current, ensure_ascii=False, indent=2) + "\n", encoding="utf-8", ) def load_manifest(manifest_path: Path = MANIFEST_PATH) -> dict[str, Any]: if not manifest_path.exists(): raise MigrationManifestError( f"缺少迁移不可变 manifest: {manifest_path}。" " 请运行 python -m web.backend.migrations.immutability --write" ) try: payload = json.loads(manifest_path.read_text(encoding="utf-8")) except (OSError, ValueError) as exc: raise MigrationManifestError( f"迁移 manifest 无法读取: {manifest_path}: {exc}" ) from exc if not isinstance(payload, dict) or payload.get("schema_version") != 1: raise MigrationManifestError("迁移 manifest 格式或 schema_version 不正确") migrations = payload.get("migrations") if not isinstance(migrations, dict): raise MigrationManifestError("迁移 manifest 缺少 migrations 映射") return payload def verify_manifest( *, versions_dir: Path = VERSIONS_DIR, manifest_path: Path = MANIFEST_PATH, ) -> None: expected = load_manifest(manifest_path)["migrations"] actual = build_manifest(versions_dir)["migrations"] errors: list[str] = [] missing = sorted(set(expected) - set(actual)) added = sorted(set(actual) - set(expected)) if missing: errors.append(f"已锁定迁移文件被删除: {', '.join(missing)}") if added: errors.append(f"存在未登记新迁移: {', '.join(added)}") for filename in sorted(set(expected) & set(actual)): old = expected[filename] current = actual[filename] if not isinstance(old, dict): errors.append(f"manifest 条目格式错误: {filename}") continue if old.get("revision") != current["revision"]: errors.append( f"迁移 revision 被修改: {filename} " f"{old.get('revision')} -> {current['revision']}" ) if old.get("sha256") != current["sha256"]: errors.append(f"已发布迁移内容被修改: {filename}") if errors: raise MigrationManifestError( "迁移不可变校验失败:\n- " + "\n- ".join(errors) + "\n修正历史结构必须新增 revision;" "只有新增迁移时才允许更新 migration_manifest.json。" ) def main() -> None: parser = argparse.ArgumentParser(description="斗鱼迁移不可变 manifest") parser.add_argument( "--write", action="store_true", help="登记新增迁移(默认拒绝修改已存在迁移)", ) parser.add_argument( "--force", action="store_true", help="灾难恢复时强制重写已有迁移哈希;必须先人工审查", ) args = parser.parse_args() if args.write: write_manifest(force=args.force) print(f"已写入 {MANIFEST_PATH}") return verify_manifest() print("迁移不可变校验通过") if __name__ == "__main__": main()