diff --git a/.github/scripts/build-release.py b/.github/scripts/build-release.py new file mode 100644 index 0000000..80eeef6 --- /dev/null +++ b/.github/scripts/build-release.py @@ -0,0 +1,296 @@ +"""Build a deployment ZIP from a pinned Git commit and compiled frontend assets.""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import os +from pathlib import Path, PurePosixPath +import re +import stat +import subprocess +import tempfile +import zipfile + + +SEMVER = re.compile( + r"(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)" + r"(?:-((?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)" + r"(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?" + r"(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?", + re.ASCII, +) +REQUIRED = frozenset({ + "backend/app/main.py", "backend/alembic/env.py", "backend/alembic/script.py.mako", + "backend/alembic.ini", "backend/pyproject.toml", "backend/uv.lock", "backend/README.md", + "README.md", "openapi.json", "backend/scripts/create_admin.py", + "backend/app/local_secrets.example.py", +}) +OPTIONAL = frozenset({ + "LICENSE", "LICENSE.md", "LICENSE.txt", "NOTICE", "NOTICE.md", "NOTICE.txt", + "THIRD_PARTY_NOTICES.md", "compose.yaml", "compose.phoenix.yaml", +}) +BLOCKED_PARTS = frozenset({ + "data", "cache", "caches", "__pycache__", ".cache", ".pytest_cache", ".ruff_cache", + ".mypy_cache", ".git", ".venv", "venv", "node_modules", "logs", "uploads", "ocr", + "avatars", "chroma", "tmp", "temp", "local_secrets.py", +}) +BLOCKED_SUFFIXES = frozenset({ + ".db", ".sqlite", ".sqlite3", ".pyc", ".pyo", ".log", ".pem", ".key", ".p12", + ".pfx", ".db-wal", ".db-shm", ".sqlite-wal", ".sqlite-shm", ".bak", +}) + +DEPLOY = """# MathCraft 部署包 + +版本:{version};Git 提交:{sha}。 + +本包包含已提交的后端运行源码、Alembic 迁移、依赖锁文件及前端 dist 成品。 +不包含 Python 运行时、Python 依赖、Node.js、真实配置、数据库、索引或用户数据。 +release.json 列出除自身外的全部文件、字节数与 SHA-256;SHA256SUMS 校验整个 ZIP。 +根及后端 README 保留源码说明,其中指向未打包 docs/scripts 的链接或命令不适用本包; +部署时以本文件为准。解压到独立版本目录,升级前备份数据库、文件、索引及加密主密钥。 + +## 依赖与 Redis + +安装符合 backend/pyproject.toml 的 Python(当前至少 3.11)及 uv。 +在解压后的顶层目录执行以下 PowerShell 命令;Linux 使用对应 shell 语法: + +```powershell +docker compose -f compose.yaml up -d --wait redis +docker compose -f compose.yaml exec redis redis-cli ping +cd backend +uv sync --frozen --no-dev +``` + +Redis 应返回 PONG;已有 Redis 时直接配置 REDIS_URL,无需 Docker。 +compose.yaml 仅负责 Redis,不会启动后端或前端。Phoenix 是可选能力,默认关闭; +需要时另行使用 compose.phoenix.yaml 并安装 `uv sync --frozen --no-dev --extra phoenix`。 + +## 外置配置与持久数据 + +由服务管理器注入环境变量,或使用部署目录之外受保护的环境文件并由服务管理器加载。 +不要把密钥写入源码、前端静态文件或发布包;应用也支持固定 backend/.env, +如使用此入口,应链接或挂载外置受保护文件,避免每次更新覆盖配置。 +至少配置 APP_ENV=production、两个独立且各至少 32 字节的 AUTH_JWT_SECRET 与 +AUTH_CODE_SECRET、REDIS_URL、DATABASE_URL、CHROMA_DIR、UPLOAD_DIR、OCR_DIR、AVATAR_DIR。 +所有数据目录使用外置可写绝对路径,SQLite 的父目录须预先创建;在 backend/ 下执行命令。 +例如 DATABASE_URL=sqlite:///C:/mathcraft-data/mathcraft.db(Linux 为 sqlite:////srv/…)。 +UPLOAD_DIR 父目录中的 secret.key 是平台凭据加密主密钥,应与数据库一起备份并跨版本保留。 +生产设置 TURNSTILE_ENABLED=true,配置 TURNSTILE_SITE_KEY、TURNSTILE_SECRET_KEY、 +TURNSTILE_ALLOWED_HOSTNAMES;CORS_ORIGINS 设置为实际站点的精确 Origin。 +关闭 DEV_ACCOUNTS_ENABLED,清空所有 DEV_TEACHER_*、DEV_STUDENT_* 字段。 +按需配置 SMTP_*;个人模型凭据由应用设置保存。 +Windows 还需将服务进程 TEMP/TMP 指向外置可写临时目录。 + +## 必需的 local_secrets 模块 + +所有部署都必须在迁移、管理员初始化和后端启动之前准备 backend/app/local_secrets.py, +后端会无条件导入此模块,即使没有部署默认凭据也不能省略。 +真实 local_secrets.py 不打包;包内必须包含已提交的 backend/app/local_secrets.example.py。 +样例中的 sk-xxxx 是明显假值,不可作为有效凭据使用。 + +没有部署默认凭据时,在 backend/ 目录执行以下命令,从样例复制模块并将两项占位值置空; +已有文件或外置挂载时跳过,保留已有配置: + +```powershell +if (-not (Test-Path -LiteralPath app/local_secrets.py)) {{ + Copy-Item -LiteralPath app/local_secrets.example.py -Destination app/local_secrets.py + Set-Content -LiteralPath app/local_secrets.py -Encoding utf8 -Value @( + 'SILICONFLOW_API_KEY = ""' + 'MINERU_DEFAULT_TOKEN = ""' + ) +}} +``` + +Linux 可复制样例后用编辑器将上述两项改为空字符串。 +需要部署默认凭据时,参考样例结构在服务器外置受保护文件中配置, +将其挂载到 backend/app/local_secrets.py,并允许后端服务账号读取;不要覆盖既有真实配置。 +该模块不应随版本更新丢失,也不能提交或重新打入发布包。 + +## 迁移与后端启动 + +确认外置配置已注入,停止旧服务并完成备份;先在数据副本验证迁移: + +```powershell +uv run --frozen --no-dev alembic upgrade head +``` + +首次部署在迁移成功后,从 backend/ 目录交互创建首个管理员;已有管理员时跳过此步: + +```powershell +uv run --frozen --no-dev python scripts/create_admin.py +``` + +按提示输入登录账号、显示名称及两次初始密码,密码隐藏输入;不要通过命令行传入凭据。 +脚本使用相同的外置数据库配置,不覆盖已有账号,不创建默认账号或默认密码。 +创建成功后启动后端: + +```powershell +uv run --frozen --no-dev uvicorn app.main:app --host 127.0.0.1 ` + --port 8000 --workers 1 --no-proxy-headers +``` + +后端命令工作目录必须为 backend/。当前链路使用单实例、单 worker, +由服务管理器负责常驻与重启。检查 GET /api/health。 +backend/scripts/ 仅包含明确允许的 create_admin.py,不包含其他开发或初始化脚本; +不要执行 README 中未打包的 scripts 命令。已有部署保留账号。 + +## 前端静态托管与反向代理 + +将 frontend/dist/ 设置为 Nginx、IIS 或其他静态服务器的站点根目录, +SPA 路由回退至 index.html。必须将 /api 及其子路径、/media 及其子路径代理至 +http://127.0.0.1:8000,保留原始路径、查询串和鉴权头,支持 WebSocket 升级及长请求。 +API 和媒体路径应先匹配代理,不能落入 SPA 回退。使用 HTTPS, +按上传大小调整代理请求体限额与超时,不通过静态站点暴露 backend/ 或持久数据目录。 +前端为 CI 已构建成品,Vite 配置在构建时注入,部署时设置 VITE_* 不会修改这些文件。 +上线验证首页及深层路由、/api/health、登录、/media 资源和相关长请求。 +""" + + +def git(repo: Path, *args: str) -> bytes: + """Read Git objects without exposing command output on failure.""" + result = subprocess.run( + ["git", "-C", str(repo), *args], capture_output=True, check=False, + ) + if result.returncode: + raise ValueError("Git operation failed: " + args[0]) + return result.stdout + + +def safe_path(name: str) -> bool: + """Reject sensitive, runtime and nonportable archive paths before reading files.""" + path = PurePosixPath(name) + parts = path.parts + if (not parts or path.is_absolute() or "\\" in name or ":" in name + or any(part in {".", ".."} for part in name.split("/"))): + return False + for part in parts: + lower = part.lower() + if (lower in BLOCKED_PARTS or lower.startswith(".env") + or lower.startswith("local_secrets") and lower != "local_secrets.example.py" + or lower.endswith(".local") or ".local." in lower + or lower.startswith(("id_rsa", "id_ed25519")) + or any(lower.endswith(suffix) for suffix in BLOCKED_SUFFIXES)): + return False + return True + + +def committed_files(repo: Path, sha: str) -> dict[str, bytes]: + """Collect only whitelisted regular blobs from the verified commit tree.""" + files: dict[str, bytes] = {} + for record in git(repo, "ls-tree", "-rz", "--full-tree", sha).split(b"\0"): + if not record: + continue + metadata, raw_name = record.split(b"\t", 1) + mode, kind, oid = metadata.decode("ascii").split() + name = raw_name.decode("utf-8") + allowed = (name in REQUIRED | OPTIONAL + or name.startswith(("backend/app/", "backend/alembic/"))) + if not allowed or not safe_path(name): + continue + if kind != "blob" or mode not in {"100644", "100755"}: + raise ValueError("Non-regular Git entry: " + name) + files[name] = git(repo, "show", oid) + missing = REQUIRED - files.keys() + if missing: + raise ValueError("Missing committed deployment files: " + ", ".join(sorted(missing))) + if not any(name.startswith("backend/alembic/versions/") for name in files): + raise ValueError("Missing committed Alembic revisions") + return files + + +def reject_link(path: Path) -> None: + """Reject symlinks and Windows reparse points, including directory junctions.""" + info = path.lstat() + if (stat.S_ISLNK(info.st_mode) + or getattr(info, "st_file_attributes", 0) + & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)): + raise ValueError("Symlink/reparse point is forbidden: " + str(path)) + + +def frontend_files(directory: Path) -> dict[str, bytes]: + """Collect built static assets, rejecting links and local configuration.""" + for parent in (*reversed(directory.parents), directory): + reject_link(parent) + if not directory.is_dir() or not (directory / "index.html").is_file(): + raise ValueError("Frontend dist must contain index.html") + files: dict[str, bytes] = {} + for base, dirs, names in os.walk(directory, followlinks=False): + for name in sorted(dirs + names): + path = Path(base) / name + reject_link(path) + relative = path.relative_to(directory).as_posix() + if not safe_path(relative): + raise ValueError("Forbidden frontend asset: " + relative) + if path.is_dir(): + continue + if not stat.S_ISREG(path.lstat().st_mode): + raise ValueError("Non-regular frontend asset: " + relative) + files["frontend/dist/" + relative] = path.read_bytes() + return files + + +def build_release(version: str, sha: str, frontend_dir: Path, output_dir: Path) -> Path: + """Validate inputs and atomically publish a deterministic ZIP and checksum file.""" + if SEMVER.fullmatch(version) is None: + raise ValueError("--version must be bare SemVer 2.0.0 (no v prefix)") + if re.fullmatch(r"[0-9a-fA-F]{40}", sha, re.ASCII) is None: + raise ValueError("--sha must contain exactly 40 hexadecimal characters") + repo = Path(os.fsdecode(git(Path.cwd(), "rev-parse", "--show-toplevel")).strip()) + head = git(repo, "rev-parse", "HEAD").decode("ascii").strip() + if head != sha.lower(): + raise ValueError("HEAD does not match --sha") + frontend_dir = Path(os.path.abspath(frontend_dir)) + output_dir = output_dir.absolute() + if output_dir.resolve().is_relative_to(frontend_dir.resolve()): + raise ValueError("Output directory must be outside frontend dist") + files = committed_files(repo, head) + files.update(frontend_files(frontend_dir)) + files["DEPLOY.md"] = DEPLOY.format(version=version, sha=head).encode("utf-8") + manifest = { + "version": version, "sha": head, + "files": [ + {"path": name, "size": len(data), "sha256": hashlib.sha256(data).hexdigest()} + for name, data in sorted(files.items()) + ], + } + files["release.json"] = (json.dumps(manifest, ensure_ascii=False, indent=2) + "\n").encode() + prefix = "mathcraft-" + version + output_dir.mkdir(parents=True, exist_ok=True) + destination = output_dir / (prefix + ".zip") + with tempfile.TemporaryDirectory(prefix=".mathcraft-release-", dir=output_dir) as temporary: + archive = Path(temporary) / destination.name + with zipfile.ZipFile(archive, "w", compression=zipfile.ZIP_DEFLATED) as bundle: + for name, data in sorted(files.items()): + entry = zipfile.ZipInfo(prefix + "/" + name, date_time=(1980, 1, 1, 0, 0, 0)) + entry.create_system = 3 + entry.external_attr = (stat.S_IFREG | 0o644) << 16 + entry.compress_type = zipfile.ZIP_DEFLATED + bundle.writestr(entry, data) + with archive.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + sums = Path(temporary) / "SHA256SUMS" + sums.write_text(f"{digest} {destination.name}\n", encoding="utf-8", newline="\n") + os.replace(archive, destination) + os.replace(sums, output_dir / "SHA256SUMS") + return destination + + +def main() -> None: + """Provide the release builder command line interface.""" + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--version", required=True) + parser.add_argument("--sha", required=True) + parser.add_argument("--frontend-dir", type=Path, default=Path("frontend/dist")) + parser.add_argument("--output-dir", type=Path, default=Path("release-dist")) + args = parser.parse_args() + try: + archive = build_release(args.version, args.sha, args.frontend_dir, args.output_dir) + except (ValueError, OSError, UnicodeError) as exc: + parser.exit(1, f"Release build failed: {exc}\n") + print(archive) + + +if __name__ == "__main__": + main() diff --git a/.github/scripts/test_build_release.py b/.github/scripts/test_build_release.py new file mode 100644 index 0000000..ae270a0 --- /dev/null +++ b/.github/scripts/test_build_release.py @@ -0,0 +1,363 @@ +"""Exercise release packaging against disposable Git repositories and static assets.""" + +from __future__ import annotations + +import ast +import hashlib +import importlib.util +import json +import os +from pathlib import Path +import subprocess +import sys +import tempfile +import time +import unittest +from unittest.mock import patch +import zipfile + + +SCRIPT = Path(__file__).with_name("build-release.py").resolve() +SPEC = importlib.util.spec_from_file_location("build_release", SCRIPT) +assert SPEC is not None and SPEC.loader is not None +BUILDER = importlib.util.module_from_spec(SPEC) +SPEC.loader.exec_module(BUILDER) +EMPTY_CONFIG_TEMPLATE = 'SILICONFLOW_API_KEY = ""\nMINERU_DEFAULT_TOKEN = ""\n' + + +class ReleaseTests(unittest.TestCase): + """Use the same isolated repository fixture for all packaging scenarios.""" + + def setUp(self) -> None: + self.temporary = tempfile.TemporaryDirectory(prefix="mathcraft-release-test-") + self.addCleanup(self.clean_temporary) + self.repo = Path(self.temporary.name) + self.git("init", "-q") + self.git("config", "user.name", "Release Test") + self.git("config", "user.email", "release@example.invalid") + self.git("config", "core.autocrlf", "false") + for name in BUILDER.REQUIRED: + self.write(name, "committed: " + name + "\n") + self.write("backend/scripts/create_admin.py", '"""Fake admin entrypoint."""\n') + self.write("backend/scripts/init_auth_secrets.py", "# fake development helper\n") + self.write("backend/alembic/versions/initial.py", "# migration fixture\n") + self.write("backend/app/local_secrets.example.py", EMPTY_CONFIG_TEMPLATE) + self.write("backend/app/services/prompts.json", '{"prompt": "测试"}\n') + self.write("compose.yaml", "services: {}\n") + self.write("compose.phoenix.yaml", "services: {}\n") + self.write("LICENSE", "license fixture\n") + self.write("THIRD_PARTY_NOTICES.md", "third party fixture\n") + self.commit() + self.sha = self.git("rev-parse", "HEAD").strip() + self.write("frontend/dist/index.html", "fixture\n") + self.write("frontend/dist/assets/app.js", "console.log('fixture');\n") + self.write("frontend/dist/assets/app.css", "body { margin: 0; }\n") + + def clean_temporary(self) -> None: + """Allow Windows a bounded interval to release completed child-process handles.""" + for attempt in range(10): + try: + self.temporary.cleanup() + return + except PermissionError: + if attempt == 9: + raise + time.sleep(0.1) + + def git(self, *args: str) -> str: + """Run fixture-only Git operations with no machine identity dependency.""" + return subprocess.run( + ["git", "-C", str(self.repo), *args], check=True, capture_output=True, + ).stdout.decode("utf-8") + + def write(self, name: str, data: str) -> Path: + """Create a fixture file, including any required parent directories.""" + path = self.repo / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(data, encoding="utf-8", newline="\n") + return path + + def commit(self) -> None: + """Commit the fixture's explicit staged and untracked test files.""" + self.git("add", "--all") + self.git("-c", "commit.gpgsign=false", "commit", "-qm", "test: fixture") + + def run_builder(self, *extra: str) -> subprocess.CompletedProcess[str]: + """Run the real CLI with its default directory parameters.""" + return subprocess.run( + [sys.executable, "-B", str(SCRIPT), "--version", "1.2.3-rc.1+build.007", + "--sha", self.sha, *extra], + cwd=self.repo, capture_output=True, text=True, encoding="utf-8", + env={**os.environ, "PYTHONIOENCODING": "utf-8"}, + ) + + def archive(self) -> Path: + """Return the default fixture release archive path.""" + return self.repo / "release-dist/mathcraft-1.2.3-rc.1+build.007.zip" + + def assert_failed(self, result: subprocess.CompletedProcess[str], message: str) -> None: + """Check validation fails before publishing an output directory.""" + self.assertNotEqual(result.returncode, 0) + self.assertIn(message, result.stderr) + self.assertFalse((self.repo / "release-dist").exists()) + + def test_manifest_contents_checksums_and_reproducibility(self) -> None: + """A complete package records byte-accurate provenance and stable output.""" + result = self.run_builder() + self.assertEqual(result.returncode, 0, result.stderr) + original = self.archive().read_bytes() + with zipfile.ZipFile(self.archive()) as bundle: + prefix = "mathcraft-1.2.3-rc.1+build.007/" + self.assertTrue(all(name.startswith(prefix) for name in bundle.namelist())) + manifest = json.loads(bundle.read(prefix + "release.json")) + self.assertEqual(manifest["version"], "1.2.3-rc.1+build.007") + self.assertEqual(manifest["sha"], self.sha) + paths = {entry["path"] for entry in manifest["files"]} + self.assertEqual(paths, {name.removeprefix(prefix) for name in bundle.namelist()} + - {"release.json"}) + self.assertTrue(BUILDER.REQUIRED <= paths) + self.assertIn("backend/scripts/create_admin.py", BUILDER.REQUIRED) + self.assertIn("backend/app/local_secrets.example.py", BUILDER.REQUIRED) + self.assertEqual(bundle.read(prefix + "backend/app/local_secrets.example.py"), + EMPTY_CONFIG_TEMPLATE.encode("utf-8")) + template_module = ast.parse( + bundle.read(prefix + "backend/app/local_secrets.example.py").decode("utf-8"), + ) + self.assertEqual(len(template_module.body), 2) + template_values = { + target.id: ast.literal_eval(statement.value) + for statement in template_module.body if isinstance(statement, ast.Assign) + for target in statement.targets if isinstance(target, ast.Name) + } + self.assertEqual(template_values, + {"SILICONFLOW_API_KEY": "", "MINERU_DEFAULT_TOKEN": ""}) + self.assertNotIn("backend/app/local_secrets.py", paths) + self.assertEqual({name for name in paths if name.startswith("backend/scripts/")}, + {"backend/scripts/create_admin.py"}) + self.assertEqual(bundle.read(prefix + "backend/scripts/create_admin.py"), + b'"""Fake admin entrypoint."""\n') + self.assertTrue({"DEPLOY.md", "compose.yaml", "compose.phoenix.yaml", "LICENSE", + "THIRD_PARTY_NOTICES.md", "frontend/dist/index.html", + "frontend/dist/assets/app.js", "frontend/dist/assets/app.css", + "backend/app/local_secrets.example.py", + "backend/app/services/prompts.json"} <= paths) + for entry in manifest["files"]: + data = bundle.read(prefix + entry["path"]) + self.assertEqual(entry["size"], len(data)) + self.assertEqual(entry["sha256"], hashlib.sha256(data).hexdigest()) + deploy = bundle.read(prefix + "DEPLOY.md").decode("utf-8") + for expected in ("uv sync --frozen --no-dev", "alembic upgrade head", "Redis", + "app.main:app", "/api", "/media", "外置", "Python 运行时", + "uv run --frozen --no-dev python scripts/create_admin.py", + "已有管理员时跳过", "密码隐藏输入", + "backend/scripts/ 仅包含明确允许的 create_admin.py"): + self.assertIn(expected, deploy) + self.assertNotIn("包中不包含 backend/scripts", deploy) + self.assertLess(deploy.index("alembic upgrade head"), + deploy.index("python scripts/create_admin.py")) + self.assertLess(deploy.index("python scripts/create_admin.py"), + deploy.index("uvicorn app.main:app")) + self.assertIn("所有部署都必须", deploy) + self.assertIn("即使没有部署默认凭据也不能省略", deploy) + self.assertIn("已有文件或外置挂载时跳过", deploy) + self.assertIn("服务器外置受保护文件", deploy) + self.assertIn("sk-xxxx 是明显假值", deploy) + prepare_module = "Copy-Item -LiteralPath app/local_secrets.example.py" + self.assertIn(prepare_module + " -Destination app/local_secrets.py", deploy) + self.assertIn("if (-not (Test-Path -LiteralPath app/local_secrets.py)) {", deploy) + self.assertIn("Set-Content -LiteralPath app/local_secrets.py", deploy) + for setting in ("SILICONFLOW_API_KEY", "MINERU_DEFAULT_TOKEN"): + self.assertIn(f"'{setting} = \"\"'", deploy) + self.assertLess(deploy.index(prepare_module), deploy.index("alembic upgrade head")) + checksum = (self.repo / "release-dist/SHA256SUMS").read_text(encoding="utf-8") + self.assertEqual(checksum, hashlib.sha256(original).hexdigest() + + " " + self.archive().name + "\n") + self.assertEqual(self.run_builder().returncode, 0) + self.assertEqual(original, self.archive().read_bytes()) + self.assertEqual(sorted(path.name for path in self.archive().parent.iterdir()), + ["SHA256SUMS", self.archive().name]) + + def test_committed_sources_ignore_worktree_and_index(self) -> None: + """Even staged edits and deleted workspace files cannot change source blobs.""" + self.write("backend/app/main.py", "staged replacement\n") + self.git("add", "backend/app/main.py") + self.write("backend/app/main.py", "workspace replacement\n") + self.write("backend/scripts/create_admin.py", "staged admin replacement\n") + self.git("add", "backend/scripts/create_admin.py") + self.write("backend/scripts/create_admin.py", "workspace admin replacement\n") + self.write("backend/app/local_secrets.example.py", "# staged template replacement\n") + self.git("add", "backend/app/local_secrets.example.py") + self.write("backend/app/local_secrets.example.py", "# workspace template replacement\n") + (self.repo / "backend/uv.lock").unlink() + self.write("backend/app/untracked.py", "untracked\n") + result = self.run_builder() + self.assertEqual(result.returncode, 0, result.stderr) + with zipfile.ZipFile(self.archive()) as bundle: + prefix = "mathcraft-1.2.3-rc.1+build.007/" + self.assertEqual(bundle.read(prefix + "backend/app/main.py"), + b"committed: backend/app/main.py\n") + self.assertEqual(bundle.read(prefix + "backend/scripts/create_admin.py"), + b'"""Fake admin entrypoint."""\n') + self.assertEqual(bundle.read(prefix + "backend/app/local_secrets.example.py"), + EMPTY_CONFIG_TEMPLATE.encode("utf-8")) + self.assertIn(prefix + "backend/uv.lock", bundle.namelist()) + self.assertNotIn(prefix + "backend/app/untracked.py", bundle.namelist()) + + def test_tracked_and_untracked_sensitive_files_are_excluded(self) -> None: + """Sensitive names are excluded before blob reads, even when committed.""" + forbidden = [ + "backend/app/local_secrets.py", + "backend/app/.env", "backend/app/nested/.env.production", + "backend/app/nested/local_secrets.backup.py", "backend/app/config.local.json", + "backend/app/data/store.json", "backend/app/__pycache__/main.pyc", + "backend/app/store.db", "backend/app/store.sqlite3", "backend/app/secret.key", + "backend/alembic/.env", "backend/alembic/cache/state.json", + "backend/alembic/store.db-wal", "backend/.env", "backend/.env.example", + "backend/scripts/extra.py", "frontend/src/main.tsx", "unlisted.yaml", + ] + for name in forbidden: + self.write(name, "FAKE_SENSITIVE_FIXTURE\n") + self.commit() + self.sha = self.git("rev-parse", "HEAD").strip() + self.write("backend/app/untracked-secret.py", "FAKE_UNTRACKED\n") + self.write("backend/app/local_secrets.py", "FAKE_WORKSPACE_ONLY\n") + result = self.run_builder() + self.assertEqual(result.returncode, 0, result.stderr) + with zipfile.ZipFile(self.archive()) as bundle: + for name in bundle.namelist(): + data = bundle.read(name) + self.assertNotIn(b"FAKE_SENSITIVE_FIXTURE", data) + self.assertNotIn(b"FAKE_UNTRACKED", data) + self.assertNotIn(b"FAKE_WORKSPACE_ONLY", data) + # Also prove the collector never asks Git for a sensitive blob's contents. + original_git = BUILDER.git + secret_oid = self.git("rev-parse", self.sha + ":backend/app/local_secrets.py").strip() + with patch.object(BUILDER, "git", wraps=original_git) as read_git: + BUILDER.committed_files(self.repo, self.sha) + self.assertNotIn((self.repo, "show", secret_oid), + [call.args for call in read_git.call_args_list]) + self.assertFalse(BUILDER.safe_path("backend/app/LOCAL_SECRETS.PY")) + + def test_missing_dist_or_entrypoint_fails(self) -> None: + """Neither absent output nor an incomplete build is releasable.""" + self.assert_failed(self.run_builder("--frontend-dir", "absent"), "Release build failed") + (self.repo / "frontend/dist/index.html").unlink() + self.assert_failed(self.run_builder(), "index.html") + + def test_sha_mismatch_and_malformed_sha_fail(self) -> None: + """Require a full commit identity matching HEAD, before writing artifacts.""" + self.assert_failed(self.run_builder("--sha", "0" * 40), "HEAD does not match") + for sha in (self.sha[:12], "g" * 40, "HEAD"): + with self.subTest(sha=sha): + self.assert_failed(self.run_builder("--sha", sha), "40 hexadecimal") + + def test_semver_accepted_and_rejected(self) -> None: + """Cover SemVer numeric identifiers, ASCII grammar and full-string matching.""" + valid = ["0.0.0", "1.2.3", "10.20.30", "1.0.0-0", "1.0.0-alpha.1", + "1.0.0-01alpha", "1.0.0--", "1.0.0+001", "1.2.3-rc.1+build.007"] + invalid = ["v1.2.3", "1.2", "1.2.3.4", "01.2.3", "1.02.3", "1.2.03", + "1.2.3-01", "1.2.3-alpha.01", "1.2.3-", "1.2.3+", "1.2.3-a..b", + "1.2.3+a..b", "1.2.3+build+more", "1.2.3_a", "1.2.3-测试", + "1.2.3", "1.2.3\n", " 1.2.3", "1.2.3/../../escape"] + for version in valid: + with self.subTest(version=version): + self.assertIsNotNone(BUILDER.SEMVER.fullmatch(version)) + for version in invalid: + with self.subTest(version=version): + self.assert_failed(self.run_builder("--version", version), "bare SemVer") + + def test_frontend_local_config_fails(self) -> None: + """Local configuration inside dist cannot silently leak into a release.""" + for name in (".env", ".env.production", "settings.local.json", "local_secrets.py", + "data/store.json", "cache/state.json", "private.pem"): + with self.subTest(name=name): + path = self.write("frontend/dist/" + name, "FAKE_ONLY\n") + self.assert_failed(self.run_builder(), "Forbidden frontend asset") + path.unlink() + if "/" in name: + path.parent.rmdir() + + def test_git_symlink_is_rejected_without_windows_symlink_privileges(self) -> None: + """Git symlink modes are validated even on Windows without native symlinks.""" + oid = subprocess.run( + ["git", "-C", str(self.repo), "hash-object", "-w", "--stdin"], + input=b"../../outside.py", capture_output=True, check=True, + ).stdout.decode().strip() + self.git("update-index", "--add", "--cacheinfo", "120000", oid, + "backend/app/link.py") + self.git("-c", "commit.gpgsign=false", "commit", "-qm", "test: symlink") + self.sha = self.git("rev-parse", "HEAD").strip() + self.assert_failed(self.run_builder(), "Non-regular Git entry") + + def test_frontend_symlink_is_rejected(self) -> None: + """Reject internal and escaping file, directory and dist-root symlinks.""" + target = self.write("outside.txt", "FAKE_OUTSIDE\n") + link = self.repo / "frontend/dist/link.txt" + try: + link.symlink_to(target) + except OSError: + self.skipTest("Native symlinks require Windows Developer Mode or privileges") + self.assert_failed(self.run_builder(), "Symlink/reparse") + link.unlink() + link.symlink_to(self.repo / "frontend/dist/index.html") + self.assert_failed(self.run_builder(), "Symlink/reparse") + link.unlink() + link.symlink_to(self.repo, target_is_directory=True) + self.assert_failed(self.run_builder(), "Symlink/reparse") + link.unlink() + root_link = self.repo / "linked-dist" + root_link.symlink_to(self.repo / "frontend/dist", target_is_directory=True) + self.assert_failed(self.run_builder("--frontend-dir", str(root_link)), "Symlink/reparse") + + def test_output_cannot_contaminate_frontend(self) -> None: + """Avoid collecting previous artifacts as static frontend files.""" + self.assert_failed(self.run_builder("--output-dir", "frontend/dist/release"), + "outside frontend dist") + + @unittest.skipUnless(sys.platform == "win32", "Windows junction test") + def test_frontend_windows_junction_is_rejected(self) -> None: + """Exercise real Windows directory reparse points without symlink privileges.""" + target = self.repo / "outside-assets" + target.mkdir() + link = self.repo / "frontend/dist/linked-assets" + result = subprocess.run( + ["cmd", "/c", "mklink", "/J", str(link), str(target)], + capture_output=True, check=False, + ) + self.assertEqual(result.returncode, 0, "Cannot create fixture directory junction") + try: + self.assert_failed(self.run_builder(), "Symlink/reparse") + finally: + link.rmdir() + + def test_missing_committed_backend_file_fails(self) -> None: + """A working-tree replacement cannot conceal an incomplete Git commit.""" + self.git("rm", "-q", "backend/uv.lock") + self.commit() + self.sha = self.git("rev-parse", "HEAD").strip() + self.write("backend/uv.lock", "untracked lock\n") + self.assert_failed(self.run_builder(), "Missing committed deployment files") + + def test_missing_committed_admin_cannot_be_replaced_by_worktree_or_index(self) -> None: + """First-deployment support must exist in HEAD, not just in a local checkout.""" + self.assert_required_committed("backend/scripts/create_admin.py") + + def test_missing_committed_secrets_example_cannot_be_replaced_locally(self) -> None: + """Every deployment needs a committed template, even without default credentials.""" + self.assert_required_committed("backend/app/local_secrets.example.py") + + def assert_required_committed(self, name: str) -> None: + """Reject missing required blobs despite untracked or staged local replacements.""" + self.git("rm", "-q", name) + self.commit() + self.sha = self.git("rev-parse", "HEAD").strip() + self.write(name, "# fake untracked replacement\n") + self.assert_failed(self.run_builder(), + "Missing committed deployment files: " + name) + self.git("add", name) + self.assert_failed(self.run_builder(), + "Missing committed deployment files: " + name) + + +if __name__ == "__main__": + unittest.main() diff --git a/.github/scripts/validate-release-tag.cjs b/.github/scripts/validate-release-tag.cjs new file mode 100644 index 0000000..a7a8e81 --- /dev/null +++ b/.github/scripts/validate-release-tag.cjs @@ -0,0 +1,77 @@ +const SEMVER = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-((?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?![\s\S])/ +const SHA = /^[a-f0-9]{40}(?![\s\S])/ + +function isValidReleaseTag(tag) { + return typeof tag === 'string' && SEMVER.test(tag) +} + +async function validateReleaseTag({ github, context, core }) { + let tag + if (context.eventName === 'push' && context.payload?.deleted !== true + && typeof context.ref === 'string' && context.ref.startsWith('refs/tags/')) { + tag = context.ref.slice('refs/tags/'.length) + } else if (context.eventName === 'release' && context.payload?.action === 'published' + && context.payload.release?.draft === false) { + tag = context.payload.release.tag_name + if (context.ref !== `refs/tags/${tag}`) throw new Error('Release 的 tag 与事件 ref 不一致') + } else { + throw new Error('仅接受 tag push 或 release.published 事件,禁止删除 tag') + } + if (!isValidReleaseTag(tag)) { + throw new Error('发布 tag 必须为裸 SemVer 2.0.0,禁止 v 前缀或数字前导零') + } + if (typeof context.sha !== 'string' || !SHA.test(context.sha)) { + throw new Error('发布事件缺少有效固定 SHA') + } + + const { data: reference } = await github.rest.git.getRef({ + ...context.repo, ref: `tags/${tag}`, + }) + if (reference.ref !== `refs/tags/${tag}`) throw new Error('Git API 返回的 tag ref 不匹配') + let object = reference.object + const eventObjectSha = object?.sha + const seen = new Set() + while (object?.type === 'tag') { + if (!SHA.test(object.sha) || seen.has(object.sha) || seen.size >= 10) { + throw new Error('附注 tag 对象无效、循环或嵌套过深') + } + seen.add(object.sha) + const { data } = await github.rest.git.getTag({ ...context.repo, tag_sha: object.sha }) + object = data.object + } + if (object?.type !== 'commit' || typeof object.sha !== 'string' || !SHA.test(object.sha)) { + throw new Error('发布 tag 必须指向有效 Git commit') + } + if (context.sha !== object.sha && context.sha !== eventObjectSha) { + throw new Error('Tag 目标已偏离触发事件 SHA,禁止发布') + } + const result = { version: tag, sha: object.sha } + core.setOutput('version', result.version) + core.setOutput('sha', result.sha) + core.info(`发布 tag 已固定:${tag}@${result.sha}`) + return result +} + +async function requireLongTermBranchChecks({ github, context, core, sha, + verify = require('./verify-release.cjs') }) { + if (typeof sha !== 'string' || !SHA.test(sha)) throw new Error('发布 SHA 无效') + const failures = [] + for (const branch of ['main', 'agent']) { + try { + await verify({ github, core, + context: { ...context, sha, ref: `refs/heads/${branch}`, eventName: 'workflow_dispatch' } }) + core.info(`发布提交已通过长期分支门禁:${branch}@${sha}`) + return branch + } catch (error) { + const reason = error instanceof Error ? error.message : String(error) + const message = `${branch}@${sha} 发布候选校验失败:${reason}` + failures.push(message) + core.warning(message) + } + } + throw new Error(`所有长期分支候选均未通过,禁止发布:\n${failures.join('\n')}`) +} + +module.exports = validateReleaseTag +module.exports.isValidReleaseTag = isValidReleaseTag +module.exports.requireLongTermBranchChecks = requireLongTermBranchChecks diff --git a/.github/scripts/validate-release-tag.test.cjs b/.github/scripts/validate-release-tag.test.cjs new file mode 100644 index 0000000..eaac473 --- /dev/null +++ b/.github/scripts/validate-release-tag.test.cjs @@ -0,0 +1,242 @@ +const assert = require('node:assert/strict') +const { test } = require('node:test') +const validateReleaseTag = require('./validate-release-tag.cjs') +const { isValidReleaseTag, requireLongTermBranchChecks } = validateReleaseTag + +const COMMIT = 'a'.repeat(40) +const TAG_OBJECT = 'b'.repeat(40) + +for (const version of [ + '0.0.0', '1.2.3', '10.20.30', '1.2.3-0', '1.2.3-alpha.1', + '1.2.3-01alpha', '1.2.3-001a', '1.2.3--', '1.2.3-alpha-01', + '1.2.3+001', '1.2.3+build.01', '1.2.3-rc.0+build.001', + '999999999999999999999.2.3', +]) { + test(`接受裸 SemVer ${version}`, () => assert.equal(isValidReleaseTag(version), true)) +} + +for (const version of [ + '', 'v1.2.3', 'V1.2.3', '1.2', '1.2.3.4', '01.2.3', '1.02.3', '1.2.03', + '1.2.3-01', '1.2.3-00', '1.2.3-alpha.01', '1.2.3-01.alpha', + '1.2.3-', '1.2.3+', '1.2.3-a..b', '1.2.3+a..b', '1.2.3-a_b', + '1.2.3+build_1', '1.2.3+abc+def', '1.2.3/other', + ' 1.2.3', '1.2.3 ', '1.2.3\n', '1.2.3\r\n', '1.2.3\u2028', + '1.2.3\u2029', '1.2.3\0', 'prefix1.2.3', '1.2.3$(id)', + '1.2.3', '1.2.3-α', null, undefined, 123, {}, +]) { + test(`拒绝非严格 SemVer ${JSON.stringify(version)}`, () => + assert.equal(isValidReleaseTag(version), false)) +} + +function fixture() { + const state = { outputs: {}, requests: [], messages: [], warnings: [], + reference: { ref: 'refs/tags/1.2.3', object: { type: 'commit', sha: COMMIT } }, + tags: {} } + state.args = { + context: { repo: { owner: 'example', repo: 'project' }, eventName: 'push', + ref: 'refs/tags/1.2.3', sha: COMMIT, payload: { deleted: false } }, + core: { + setOutput(name, value) { state.outputs[name] = value }, + info(message) { state.messages.push(message) }, + warning(message) { state.warnings.push(message) }, + }, + github: { rest: { git: { + async getRef(params) { + state.requests.push(['getRef', params]) + if (state.error) throw state.error + return { data: structuredClone(state.reference) } + }, + async getTag(params) { + state.requests.push(['getTag', params]) + if (state.tagError) throw state.tagError + return { data: { object: structuredClone(state.tags[params.tag_sha]) } } + }, + } } }, + } + return state +} + +test('轻量 tag 解析固定 commit 并输出版本和 SHA', async () => { + const state = fixture() + const result = await validateReleaseTag(state.args) + assert.deepEqual(result, { version: '1.2.3', sha: COMMIT }) + assert.deepEqual(state.outputs, result) + assert.deepEqual(state.requests, [['getRef', { + owner: 'example', repo: 'project', ref: 'tags/1.2.3', + }]]) +}) + +for (const eventSha of [COMMIT, TAG_OBJECT]) { + test(`附注 tag 固定底层 commit,支持事件 SHA ${eventSha}`, async () => { + const state = fixture() + state.args.context.sha = eventSha + state.reference.object = { type: 'tag', sha: TAG_OBJECT } + state.tags[TAG_OBJECT] = { type: 'commit', sha: COMMIT } + await validateReleaseTag(state.args) + assert.deepEqual(state.outputs, { version: '1.2.3', sha: COMMIT }) + assert.deepEqual(state.requests[1], ['getTag', { + owner: 'example', repo: 'project', tag_sha: TAG_OBJECT, + }]) + }) +} + +test('release.published 从 release.tag_name 校验并固定提交', async () => { + const state = fixture() + state.args.context.eventName = 'release' + state.args.context.payload = { action: 'published', + release: { tag_name: '1.2.3', draft: false, prerelease: false } } + await validateReleaseTag(state.args) + assert.deepEqual(state.outputs, { version: '1.2.3', sha: COMMIT }) +}) + +test('预发布版本与 build metadata 保持原样', async () => { + const state = fixture() + const version = '1.2.3-rc.0+build.001' + state.args.context.eventName = 'release' + state.args.context.ref = `refs/tags/${version}` + state.args.context.payload = { action: 'published', + release: { tag_name: version, draft: false, prerelease: true } } + state.reference.ref = state.args.context.ref + await validateReleaseTag(state.args) + assert.deepEqual(state.outputs, { version, sha: COMMIT }) +}) + +for (const context of [ + { eventName: 'workflow_dispatch' }, { eventName: 'pull_request' }, + { ref: 'refs/heads/main' }, { payload: { deleted: true } }, + { ref: 'refs/tags/v1.2.3' }, { ref: 'refs/tags/1.2.3\n' }, + { sha: 'main' }, { sha: COMMIT + '\n' }, + { eventName: 'release', payload: { action: 'created', + release: { tag_name: '1.2.3', draft: false } } }, + { eventName: 'release', payload: { action: 'published', + release: { tag_name: '1.2.3', draft: true } } }, + { eventName: 'release', payload: { action: 'published', + release: { tag_name: '2.0.0', draft: false } } }, +]) { + test(`无效发布事件必须在 API 查询前拒绝 ${JSON.stringify(context)}`, async () => { + const state = fixture() + Object.assign(state.args.context, context) + await assert.rejects(validateReleaseTag(state.args)) + assert.deepEqual(state.outputs, {}) + assert.deepEqual(state.requests, []) + }) +} + +for (const object of [ + { type: 'tree', sha: COMMIT }, { type: 'blob', sha: COMMIT }, + { type: 'commit', sha: 'invalid' }, { type: 'commit', sha: COMMIT + '\n' }, + { type: 'commit', sha: 'c'.repeat(40) }, null, +]) { + test(`tag 无有效且一致的 commit 时拒绝 ${JSON.stringify(object)}`, async () => { + const state = fixture() + state.reference.object = object + await assert.rejects(validateReleaseTag(state.args)) + assert.deepEqual(state.outputs, {}) + }) +} + +test('拒绝 API 返回其他 tag', async () => { + const state = fixture() + state.reference.ref = 'refs/tags/2.0.0' + await assert.rejects(validateReleaseTag(state.args), /ref 不匹配/) + assert.deepEqual(state.outputs, {}) +}) + +test('嵌套附注 tag 解析到同一固定提交', async () => { + const state = fixture() + state.reference.object = { type: 'tag', sha: TAG_OBJECT } + state.tags[TAG_OBJECT] = { type: 'tag', sha: 'c'.repeat(40) } + state.tags['c'.repeat(40)] = { type: 'commit', sha: COMMIT } + await validateReleaseTag(state.args) + assert.equal(state.outputs.sha, COMMIT) +}) + +test('附注 tag 循环必须拒绝', async () => { + const state = fixture() + state.reference.object = { type: 'tag', sha: TAG_OBJECT } + state.tags[TAG_OBJECT] = { type: 'tag', sha: TAG_OBJECT } + await assert.rejects(validateReleaseTag(state.args), /循环或嵌套过深/) + assert.deepEqual(state.outputs, {}) +}) + +test('附注 tag 超过十层必须拒绝', async () => { + const state = fixture() + const shas = Array.from({ length: 11 }, (_, index) => (index + 1).toString(16).padStart(40, '0')) + state.reference.object = { type: 'tag', sha: shas[0] } + for (const [index, sha] of shas.entries()) { + state.tags[sha] = index === shas.length - 1 + ? { type: 'commit', sha: COMMIT } : { type: 'tag', sha: shas[index + 1] } + } + await assert.rejects(validateReleaseTag(state.args), /循环或嵌套过深/) + assert.deepEqual(state.outputs, {}) +}) + +for (const operation of ['getRef', 'getTag']) { + test(`${operation} API 异常必须拒绝发布`, async () => { + const state = fixture() + if (operation === 'getRef') state.error = new Error('fixture ref forbidden') + else { + state.reference.object = { type: 'tag', sha: TAG_OBJECT } + state.tagError = new Error('fixture tag forbidden') + } + await assert.rejects(validateReleaseTag(state.args), /fixture .* forbidden/) + assert.deepEqual(state.outputs, {}) + }) +} + +test('main 通过时使用固定 SHA 合成门禁上下文,不修改原 context', async () => { + const state = fixture() + const original = structuredClone(state.args.context) + const calls = [] + const branch = await requireLongTermBranchChecks({ ...state.args, sha: COMMIT, + verify: async args => { calls.push(args) } }) + assert.equal(branch, 'main') + assert.equal(calls.length, 1) + assert.deepEqual(calls[0].context, { ...original, sha: COMMIT, + ref: 'refs/heads/main', eventName: 'workflow_dispatch' }) + assert.deepEqual(state.args.context, original) + assert.equal(calls[0].github, state.args.github) + assert.equal(calls[0].core, state.args.core) + assert.deepEqual(state.warnings, []) +}) + +test('main 候选失败必须报告原因,并允许同 SHA 的 agent 成功', async () => { + const state = fixture() + const calls = [] + const branch = await requireLongTermBranchChecks({ ...state.args, sha: COMMIT, + verify: async ({ context }) => { + calls.push(context) + if (context.ref === 'refs/heads/main') throw new Error('fixture main CI failed') + } }) + assert.equal(branch, 'agent') + assert.deepEqual(calls.map(context => [context.ref, context.sha, context.eventName]), [ + ['refs/heads/main', COMMIT, 'workflow_dispatch'], + ['refs/heads/agent', COMMIT, 'workflow_dispatch'], + ]) + assert.equal(state.warnings.length, 1) + assert.match(state.warnings[0], /main@.*fixture main CI failed/) +}) + +test('两个长期分支失败必须报告各自原因并拒绝', async () => { + const state = fixture() + await assert.rejects(requireLongTermBranchChecks({ ...state.args, sha: COMMIT, + verify: async ({ context }) => { throw new Error(`fixture ${context.ref} failed`) } }), + error => /main@.*fixture refs\/heads\/main failed/.test(error.message) + && /agent@.*fixture refs\/heads\/agent failed/.test(error.message)) + assert.equal(state.warnings.length, 2) +}) + +test('非 Error 的候选失败也必须报告并拒绝', async () => { + const state = fixture() + await assert.rejects(requireLongTermBranchChecks({ ...state.args, sha: COMMIT, + verify: async () => { throw 'fixture failure' } }), /fixture failure/) + assert.equal(state.warnings.length, 2) +}) + +test('无效 SHA 不调用长期分支门禁', async () => { + const state = fixture() + let called = false + await assert.rejects(requireLongTermBranchChecks({ ...state.args, sha: 'main', + verify: async () => { called = true } }), /SHA 无效/) + assert.equal(called, false) +}) diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index d495d6e..dc8a8be 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -3,7 +3,9 @@ name: Code checks on: pull_request: push: + branches: ['**'] workflow_dispatch: + workflow_call: permissions: contents: read @@ -41,7 +43,9 @@ jobs: run: npm ci working-directory: frontend - name: Release gate regression - run: node --test .github/scripts/verify-release.test.cjs + run: node --test .github/scripts/verify-release.test.cjs .github/scripts/validate-release-tag.test.cjs + - name: Deployment package regression + run: .venv/bin/python -B -m unittest discover -s .github/scripts -p test_build_release.py -v - name: Create placeholder local configuration run: cp backend/app/local_secrets.example.py backend/app/local_secrets.py - name: Ruff diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..8491525 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,101 @@ +name: Build release artifact + +on: + push: + tags: ['**'] + release: + types: [published] + +permissions: + contents: read + actions: read + security-events: read + +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false + +jobs: + validate: + name: Validate release tag + runs-on: ubuntu-24.04 + timeout-minutes: 5 + outputs: + version: ${{ steps.tag.outputs.version }} + sha: ${{ steps.tag.outputs.sha }} + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.sha }} + persist-credentials: false + - uses: actions/setup-node@v4 + with: + node-version: '22' + - name: Tag validation regression + run: node --test .github/scripts/validate-release-tag.test.cjs + - name: Validate version and resolve commit + id: tag + uses: actions/github-script@v7 + with: + script: | + const validate = require('./.github/scripts/validate-release-tag.cjs'); + await validate({github, context, core}); + + ci: + needs: validate + uses: ./.github/workflows/checks.yml + + build: + name: Build release ZIP + needs: [validate, ci] + runs-on: ubuntu-24.04 + timeout-minutes: 20 + env: + RELEASE_VERSION: ${{ needs.validate.outputs.version }} + RELEASE_SHA: ${{ needs.validate.outputs.sha }} + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ needs.validate.outputs.sha }} + persist-credentials: false + - name: Require long-term branch CI and CodeQL before build + uses: actions/github-script@v7 + with: + script: | + const {requireLongTermBranchChecks} = require('./.github/scripts/validate-release-tag.cjs'); + await requireLongTermBranchChecks({github, context, core, sha: process.env.RELEASE_SHA}); + - uses: actions/setup-node@v4 + with: + node-version: '22' + cache: npm + cache-dependency-path: frontend/package-lock.json + - uses: actions/setup-python@v5 + with: + python-version: '3.11' + - name: Install frontend dependencies + run: npm ci + working-directory: frontend + - name: Build frontend + run: npm run build + working-directory: frontend + - name: Package release + run: >- + python .github/scripts/build-release.py + --version "$RELEASE_VERSION" + --sha "$RELEASE_SHA" + --frontend-dir frontend/dist + --output-dir release-dist + - name: Recheck long-term branch CI and CodeQL before upload + uses: actions/github-script@v7 + with: + script: | + const {requireLongTermBranchChecks} = require('./.github/scripts/validate-release-tag.cjs'); + await requireLongTermBranchChecks({github, context, core, sha: process.env.RELEASE_SHA}); + - name: Upload release ZIP and checksums + uses: actions/upload-artifact@v4 + with: + name: mathcraft-${{ needs.validate.outputs.version }} + path: | + release-dist/*.zip + release-dist/SHA256SUMS + if-no-files-found: error diff --git a/.gitignore b/.gitignore index 771ffc6..089ab6e 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ node_modules/ dist/ build/ +/release-dist/ *.egg-info/ *.tsbuildinfo .vite/ diff --git "a/docs/\346\265\213\350\257\225\344\270\216\346\214\201\347\273\255\351\233\206\346\210\220.md" "b/docs/\346\265\213\350\257\225\344\270\216\346\214\201\347\273\255\351\233\206\346\210\220.md" index 618f5cc..c35f980 100644 --- "a/docs/\346\265\213\350\257\225\344\270\216\346\214\201\347\273\255\351\233\206\346\210\220.md" +++ "b/docs/\346\265\213\350\257\225\344\270\216\346\214\201\347\273\255\351\233\206\346\210\220.md" @@ -114,7 +114,8 @@ Node 语法检查和两份工作流的 actionlint 检查通过。 PR 的 edited 活动也触发扫描,覆盖已有 PR 将目标改为 main 的情况。 仓库默认 CodeQL 设置须关闭,避免与显式工作流冲突。agent 过去为默认扫描添加过传统分支保护; -在新工作流验证成功后移除该保护,扫描范围由 YAML 决定。现有独立代码质量 ruleset 保持原配置。 +新工作流在两条长期分支验证成功后已移除该保护,protection API 返回 404;扫描范围由 YAML 决定。 +现有独立代码质量 ruleset 保持原配置。 main Ruleset 27438512 要求 GitHub Actions 提供以下全部必需检查: Analyze (actions)、Analyze (javascript-typescript)、Analyze (python)、CodeQL required。 @@ -131,3 +132,31 @@ Default setup 的旧 dynamic 成功记录不能替代新工作流;发布时同 验收包括门禁回归和 actionlint、目标为 main 的真实 PR CodeQL/CI、合入后两条长期分支的 push 扫描、 main Ruleset 配置回读,以及删除 agent 传统保护后的 protection API 404。 配置变更不触发实际 Pages 部署。 + +PR #22 经完整 CI 与 CodeQL 后合入提交 `11b8ab2`,main 的 push 检查为 Code checks `44042044863`、 +CodeQL `44042044937`,agent 为 Code checks `44042134557`、CodeQL `44042134556`,全部成功。 + +## Tag 自动构建部署包 + +`.github/workflows/release.yml` 响应手动创建的 Tag push,以及 GitHub Release 的 published 事件。 +可以在本地 Git 推送标签、使用个人账号的 gh 创建引用,或在 GitHub Releases 页面填写新 Tag 并发布。 +Tag 必须使用裸 SemVer 2.0.0:例如 `1.2.3`、`1.2.3-rc.1`、`1.2.3+build.5`; +不接受 `v1.2.3`、`01.2.3`、`1.2.3-01`。校验失败会终止构建,已经创建的 Tag 不会因此自动删除。 +不依赖企业版的标签命名规则,不修改用户自行创建的 Tag ruleset。 + +流程为版本与提交校验 → 复用完整 Code checks → 前端生产构建 → 打包 → 上传 Actions Artifact。 +Code checks 继续检查所有分支推送和 PR,并提供 workflow_call 供 Tag 流程复用;普通 Tag push 不再额外启动独立 Code checks。 +所有构建使用标签解析后的固定提交。构建前与上传前核对该 SHA 在 main 或 agent 上已有成功的完整 CI 与显式 CodeQL, +任一分支满足即可,其他分支或 PR 结果不能替代。检查缺失、失败、取消、跳过或仍在运行时停止生成发布产物; +等待长期分支检查成功后可重跑失败的构建。不会创建新 Tag、发布 GitHub Release 或部署服务器。 + +构建产物包含 `mathcraft-{version}.zip` 和 `SHA256SUMS`。 +ZIP 内顶层目录为 `mathcraft-{version}/`,包含已提交的后端运行源码、Alembic 迁移、依赖声明与锁文件、 +前端 `frontend/dist/`、部署说明 `DEPLOY.md` 及文件哈希清单 `release.json`。 +这是需要在服务器安装依赖的完整应用部署包,不包含 Python 运行时、已安装依赖、真实密钥、数据库、用户上传或索引。 +部署依照包内 DEPLOY.md 配置外置数据与凭据、Redis、数据库迁移、后端服务和前端反向代理。 + +后端只从固定 Git 提交读取白名单文件,前端只接收本次构建的 dist,拒绝符号链接、路径越界、敏感配置和运行时文件。 +本地回归使用临时假 Git 仓库、假静态文件与假 API,不读取真实配置、不调用真实模型或 Redis。 +验收包括 SemVer 边界、ZIP 内容与清单、提交一致性、敏感路径排除及工作流静态校验; +真实版本标签由用户选择并创建,不以自动创建版本标签作为配置验收手段。