Files
live-hub-py/web/backend/migrations/immutability.py
T

183 lines
6.2 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""已发布 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()