183 lines
6.2 KiB
Python
183 lines
6.2 KiB
Python
"""已发布 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()
|