#!/usr/bin/env python3 """Root-owned Linux host updater; no shell, Docker socket, or code in Web. Use --check for notification, --apply [v2.x.y] for an operator update, or --run from the timer. --dry-run never contacts GitHub or Docker or writes files. """ from __future__ import annotations import argparse from contextlib import contextmanager from dataclasses import dataclass, fields from datetime import timedelta import json import os from pathlib import Path, PurePosixPath import re import shutil import signal import stat import subprocess import sys import tarfile import tempfile import tomllib import uuid # This import is standard-library-only; no FastAPI/Qt installation on the host. sys.path.insert(0, str(Path(__file__).resolve().parents[2])) from ranch_web import updates # noqa: E402 _DIGEST = re.compile(r"sha256:[0-9a-f]{64}", re.ASCII) _CONTAINER = re.compile(r"[0-9a-f]{12,64}", re.ASCII) _CONTROL_FILES = {"update-check.json", "update-request.json", "updater-status.json"} class UpdaterError(RuntimeError): """Only a fixed public error is printed by the CLI.""" @dataclass(frozen=True) class Config: project_dir: Path = Path("/opt/ranch-web") data_dir: Path = Path("/opt/ranch-web/data") control_dir: Path = Path("/opt/ranch-web/updater-control") backup_dir: Path = Path("/opt/ranch-web/backups") failed_data_dir: Path = Path("/opt/ranch-web/failed-data") compose_project: str = "ranch-web" accept_web_requests: bool = False auto_apply: bool = False check_interval_seconds: int = 3600 wait_timeout_seconds: int = 180 shutdown_timeout_seconds: int = 120 @classmethod def load(cls, path, *, dry_run=False): with open(path, "rb") as stream: value = tomllib.load(stream) if set(value) - {field.name for field in fields(cls)}: raise UpdaterError("执行器配置包含未知字段。") for key in ("project_dir", "data_dir", "control_dir", "backup_dir", "failed_data_dir"): if key in value: item = Path(value[key]) if not item.is_absolute() and not (dry_run and PurePosixPath(value[key]).is_absolute()): raise UpdaterError("执行器目录必须为绝对路径。") value[key] = item.resolve() result = cls(**value) if not re.fullmatch(r"[a-z0-9][a-z0-9_-]{0,62}", result.compose_project): raise UpdaterError("Compose 项目名称无效。") if type(result.accept_web_requests) is not bool or type(result.auto_apply) is not bool: raise UpdaterError("执行器开关必须为布尔值。") for key, lower, upper in (("check_interval_seconds", 300, 604800), ("wait_timeout_seconds", 30, 600), ("shutdown_timeout_seconds", 30, 600)): if type(getattr(result, key)) is not int or not lower <= getattr(result, key) <= upper: raise UpdaterError("执行器时间配置超出允许范围。") directories = [result.data_dir, result.control_dir, result.backup_dir, result.failed_data_dir] for index, directory in enumerate(directories): if directory == result.project_dir or directory in result.project_dir.parents: raise UpdaterError("数据与控制目录不能覆盖项目目录。") for other in directories[index + 1:]: if directory == other or directory in other.parents or other in directory.parents: raise UpdaterError("数据、控制、备份及失败数据目录必须相互独立。") return result class Docker: def __init__(self, config): self.config = config def run(self, arguments, *, image=None, timeout=120): environment = {key: value for key, value in os.environ.items() if not key.startswith("COMPOSE_") and key not in { "DOCKER_HOST", "DOCKER_CONTEXT", "DOCKER_TLS_VERIFY", "DOCKER_CERT_PATH", }} if image: environment["RANCH_WEB_IMAGE"] = image try: completed = subprocess.run( ["docker", "--context", "default", *arguments], cwd=self.config.project_dir, env=environment, stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=timeout, check=False, ) except (OSError, subprocess.TimeoutExpired): raise UpdaterError("Docker 命令不可用或超时。") from None if completed.returncode: # Never print compose config, environment, or container logs. raise UpdaterError("Docker 操作失败;请在宿主机检查服务状态。") return completed.stdout.strip() def compose(self, arguments, *, image=None, timeout=120): cfg = self.config return self.run([ "compose", "--project-name", cfg.compose_project, "--project-directory", str(cfg.project_dir), "--env-file", str(cfg.project_dir / ".env"), "--env-file", str(cfg.project_dir / ".image.env"), "--file", str(cfg.project_dir / "compose.yaml"), *arguments, ], image=image, timeout=timeout) def inspect_service(self, *, allow_missing=False): identity = self.compose(["ps", "--all", "--quiet", "web"]) if not identity and allow_missing: return None if not _CONTAINER.fullmatch(identity): raise UpdaterError("必须先部署且只运行一个 web 容器。") try: values = json.loads(self.run(["container", "inspect", identity])) container = values[0] if len(values) == 1 else None image = container["Image"] version = container["Config"]["Labels"]["org.opencontainers.image.version"] updates.current_version_key(version) except (KeyError, ValueError, TypeError, IndexError): raise UpdaterError("现有容器缺少有效的 Web 2 版本标记。") from None if not _DIGEST.fullmatch(image): raise UpdaterError("无法固定旧镜像用于回滚。") mounts = {mount["Destination"]: mount for mount in container.get("Mounts", [])} if Path(mounts.get("/data", {}).get("Source", "")).resolve() != self.config.data_dir: raise UpdaterError("现有容器的数据挂载与更新器配置不一致。") capability = mounts.get("/run/ranch-updater", {}) if Path(capability.get("Source", "")).resolve() != self.config.control_dir or capability.get("RW") is not False: raise UpdaterError("执行器心跳必须使用独立的只读挂载。") return {"image": image, "version": version, "running": container["State"]["Running"], "health": container["State"].get("Health", {}).get("Status")} def validate(self, image): try: config = json.loads(self.compose(["config", "--format", "json"], image=image)) services = config["services"] service = services["web"] volumes = {mount["target"]: mount for mount in service["volumes"]} valid = (set(services) == {"web"} and service["image"] == image and service.get("user") == "10001:10001" and not service.get("privileged") and set(volumes) == {"/data", "/run/ranch-updater"} and volumes["/data"].get("type") == "bind" and Path(volumes["/data"]["source"]).resolve() == self.config.data_dir and Path(volumes["/run/ranch-updater"]["source"]).resolve() == self.config.control_dir and volumes["/run/ranch-updater"].get("read_only") is True) except (KeyError, ValueError, TypeError): valid = False if not valid: raise UpdaterError("Compose 必须是固定 web 单服务、非 root 用户和指定挂载。") def pull(self, image): self.compose(["pull", "--policy", "always", "web"], image=image, timeout=900) def stop(self): self.compose(["stop", "--timeout", str(self.config.shutdown_timeout_seconds), "web"], timeout=self.config.shutdown_timeout_seconds + 30) remaining = self.inspect_service(allow_missing=True) if remaining and remaining["running"]: raise UpdaterError("旧服务未停止,拒绝创建不一致的备份。") def up(self, image): self.compose(["up", "-d", "--no-build", "--pull", "never", "--wait", "--wait-timeout", str(self.config.wait_timeout_seconds), "web"], image=image, timeout=self.config.wait_timeout_seconds + self.config.shutdown_timeout_seconds + 60) running = self.inspect_service() if not running["running"] or running["health"] != "healthy": raise UpdaterError("容器未通过 /api/health 健康检查。") if image.startswith(f"{updates.IMAGE}:") and running["version"] != image[len(updates.IMAGE) + 2:]: raise UpdaterError("新镜像版本标记与正式发布标签不一致。") def snapshot_data(config, request_id): """Create a complete directory snapshot only while all app writers are stopped.""" config.backup_dir.mkdir(parents=True, mode=0o700, exist_ok=True) destination = config.backup_dir / f"{request_id}.tar.gz" if destination.exists(): raise UpdaterError("备份标识冲突,已停止更新。") descriptor, temporary = tempfile.mkstemp(prefix=".snapshot-", dir=config.backup_dir) try: with os.fdopen(descriptor, "wb") as stream: os.chmod(temporary, 0o600) with tarfile.open(fileobj=stream, mode="w:gz", dereference=False) as archive: for directory, subdirs, filenames in os.walk(config.data_dir, followlinks=False): for name in sorted(subdirs + filenames): path = Path(directory) / name info = path.lstat() if stat.S_ISLNK(info.st_mode) or not (stat.S_ISREG(info.st_mode) or stat.S_ISDIR(info.st_mode)): raise UpdaterError("数据目录存在非普通文件,已中止备份并恢复旧服务。") if stat.S_ISREG(info.st_mode) and info.st_nlink != 1: raise UpdaterError("数据目录存在硬链接,已中止备份并恢复旧服务。") # Control status is preserved live; application data and keys are backed up. relative = path.relative_to(config.data_dir) if len(relative.parts) == 1 and name in _CONTROL_FILES: continue archive.add(path, arcname=str(relative), recursive=False) stream.flush() os.fsync(stream.fileno()) os.replace(temporary, destination) finally: if os.path.exists(temporary): os.unlink(temporary) return destination def restore_data(config, backup, request_id): """Swap in the snapshot, retaining failed-version data for operator inspection.""" if backup.parent != config.backup_dir or backup.name != f"{request_id}.tar.gz": raise UpdaterError("回滚备份标识无效。") temporary = Path(tempfile.mkdtemp(prefix=".restore-", dir=config.data_dir.parent)) try: with tarfile.open(backup, "r:gz") as archive: for member in archive.getmembers(): relative = Path(member.name) if relative.is_absolute() or ".." in relative.parts or not (member.isfile() or member.isdir()): raise UpdaterError("备份包含不安全路径,拒绝回滚。") archive.extractall(temporary, filter="data") for name in _CONTROL_FILES: value = updates.read_json(config.data_dir / name) if value is not None: updates.atomic_json(temporary / name, value, mode=0o600 if name == "update-request.json" else 0o644) # The runtime image always uses this UID/GID. Restore encrypted keys with it. if hasattr(os, "chown"): for directory, subdirs, filenames in os.walk(temporary): for name in subdirs + filenames: os.chown(Path(directory) / name, 10001, 10001) os.chown(temporary, 10001, 10001) config.failed_data_dir.mkdir(parents=True, mode=0o700, exist_ok=True) failed = config.failed_data_dir / request_id if failed.exists(): raise UpdaterError("失败数据隔离目录已存在,拒绝覆盖。") os.replace(config.data_dir, failed) try: os.replace(temporary, config.data_dir) except BaseException: os.replace(failed, config.data_dir) raise finally: if temporary.exists(): shutil.rmtree(temporary) class HostUpdater: def __init__(self, config, docker=None): self.config = config self.docker = docker or Docker(config) self.journal = config.control_dir / "transaction.json" def capability(self): old = updates.read_json(self.config.control_dir / "capability.json") old = old if isinstance(old, dict) else {} identity = old.get("executor_id") if not updates.valid_id(identity): identity = uuid.uuid4().hex now = updates.utc_now() value = {"protocol": updates.PROTOCOL, "executor_id": identity, "enabled": self.config.accept_web_requests, "auto_apply": self.config.auto_apply, "heartbeat_at": updates.timestamp(now), "expires_at": updates.timestamp(now + timedelta(minutes=15))} updates.atomic_json(self.config.control_dir / "capability.json", value) return value def publish(self, request_id, version, status): value = {"protocol": updates.PROTOCOL, "request_id": request_id, "version": version, "status": status, "updated_at": updates.timestamp(), "error": None} updates.atomic_json(self.config.data_dir / "updater-status.json", value) return value def check(self, current_version): return updates.UpdateService(self.config.data_dir, current_version).check() def persist_image(self, image): if not (_DIGEST.fullmatch(image) or image.startswith(f"{updates.IMAGE}:")): raise UpdaterError("只能保存官方镜像或已固定的本地回滚镜像。") if not _DIGEST.fullmatch(image): updates.stable_version(image[len(updates.IMAGE) + 1:]) descriptor, temporary = tempfile.mkstemp(prefix=".image-env-", dir=self.config.project_dir) try: with os.fdopen(descriptor, "w", encoding="ascii", newline="\n") as stream: stream.write(f"RANCH_WEB_IMAGE={image}\n") stream.flush() os.fsync(stream.fileno()) os.replace(temporary, self.config.project_dir / ".image.env") finally: if os.path.exists(temporary): os.unlink(temporary) def rollback(self, transaction): request_id, version = transaction["request_id"], transaction["version"] old_image = transaction["old_image"] if not _DIGEST.fullmatch(old_image) or not updates.valid_id(request_id): raise UpdaterError("回滚事务记录无效。") if transaction.get("backup_ready") and transaction.get("new_started"): self.docker.stop() restore_data(self.config, self.config.backup_dir / f"{request_id}.tar.gz", request_id) transaction["new_started"] = False updates.atomic_json(self.journal, transaction, mode=0o600) self.persist_image(old_image) self.docker.up(old_image) self.journal.unlink(missing_ok=True) return self.publish(request_id, version, "rolled_back") def recover(self): transaction = updates.read_json(self.journal) if transaction is not None: return self.rollback(transaction) return None def apply(self, version=None, *, request_id=None): # Source and monotonicity are rechecked here, including Web requests. old = self.docker.inspect_service() if not old["running"]: raise UpdaterError("现有服务未运行,请先由操作者处理。") try: tags = updates.official_tags(updates.github_releases()) except Exception: raise UpdaterError("无法独立验证官方 GitHub 正式发布,保留现有服务。") from None target = version or (max(tags, key=updates.stable_version) if tags else None) if target is None: return {"status": "no_release", "message": "官方尚无稳定 Web 2 正式版。"} if target not in tags or updates.stable_version(target) <= updates.current_version_key(old["version"]): raise UpdaterError("目标必须是官方已发布且比现有容器更新的稳定 v2.x.y。") image = f"{updates.IMAGE}:{target}" request_id = request_id or uuid.uuid4().hex if not updates.valid_id(request_id): raise UpdaterError("更新请求标识无效。") self.docker.validate(image) self.docker.pull(image) # Pull failure leaves the old container running. transaction = {"protocol": 1, "request_id": request_id, "version": target, "old_image": old["image"], "backup_ready": False, "new_started": False} updates.atomic_json(self.journal, transaction, mode=0o600) self.publish(request_id, target, "applying") try: self.docker.stop() snapshot_data(self.config, request_id) transaction["backup_ready"] = True updates.atomic_json(self.journal, transaction, mode=0o600) # Mark before startup, since failed startups can already migrate data. transaction["new_started"] = True updates.atomic_json(self.journal, transaction, mode=0o600) self.docker.up(image) self.persist_image(image) except (Exception, KeyboardInterrupt): try: return self.rollback(transaction) except Exception: self.publish(request_id, target, "failed") raise UpdaterError("更新及自动回滚失败;已保留备份、失败数据和恢复事务。") from None self.journal.unlink(missing_ok=True) return self.publish(request_id, target, "succeeded") def run(self): capability = self.capability() recovery = self.recover() if recovery: return recovery request = updates.read_json(self.config.data_dir / "update-request.json") if self.config.accept_web_requests and request is not None: if not isinstance(request, dict): return {"status": "failed", "message": "更新请求无效,未执行。"} previous = updates.read_json(self.config.data_dir / "updater-status.json") previous = previous if isinstance(previous, dict) else {} if previous.get("request_id") != request.get("request_id") or previous.get("status") not in {"succeeded", "failed", "rolled_back"}: identity, target = request.get("request_id"), request.get("version") try: if set(request) != {"protocol", "request_id", "executor_id", "version", "requested_at"}: raise ValueError issued = updates.parse_time(request.get("requested_at")) now = updates.utc_now() if (request["protocol"] != updates.PROTOCOL or not updates.valid_id(identity) or request["executor_id"] != capability["executor_id"] or issued is None or not now - timedelta(hours=24) <= issued <= now + timedelta(seconds=60)): raise ValueError updates.stable_version(target) return self.apply(target, request_id=identity) except (ValueError, UpdaterError): if updates.valid_id(identity): try: updates.stable_version(target) except ValueError: pass else: return self.publish(identity, target, "failed") return {"status": "failed", "message": "更新请求无效,未执行。"} current = self.docker.inspect_service()["version"] cached = updates.read_json(self.config.data_dir / "update-check.json") cached = cached if isinstance(cached, dict) else {} checked = updates.parse_time(cached.get("checked_at")) state = updates.UpdateService(self.config.data_dir, current).status() if checked is None or updates.utc_now() - checked >= timedelta(seconds=self.config.check_interval_seconds): state = self.check(current) if self.config.auto_apply and state["available"]: return self.apply(state["latest_version"]) return state @contextmanager def exclusive(config): import fcntl path = config.project_dir / ".web-updater.lock" descriptor = os.open(path, os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW, 0o600) try: try: fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB) except BlockingIOError: raise UpdaterError("已有宿主机更新任务正在执行。") from None yield finally: os.close(descriptor) def dry_run(config, mode, version): if version: updates.stable_version(version) return {"dry_run": True, "mode": mode, "repository": updates.REPOSITORY, "image": f"{updates.IMAGE}:{version or ''}", "auto_apply": config.auto_apply, "accept_web_requests": config.accept_web_requests, "steps": ["verify official stable release and running version", "validate single-service mounts", "compose pull while old service runs", "stop; snapshot all data and encrypted keys", "compose up -d --no-build --pull never --wait --wait-timeout", "on failure: stop, restore snapshot, start pinned old image"]} def interrupt_update(signum, frame): raise InterruptedError("宿主机正在停止更新任务。") def main(argv=None): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--config", default="/etc/ranch-web-updater.toml") mode = parser.add_mutually_exclusive_group(required=True) mode.add_argument("--check", action="store_true") mode.add_argument("--apply", nargs="?", const="", metavar="v2.x.y") mode.add_argument("--run", action="store_true") parser.add_argument("--dry-run", action="store_true") args = parser.parse_args(argv) try: config = Config.load(args.config, dry_run=args.dry_run) if args.dry_run: result = dry_run(config, "check" if args.check else "run" if args.run else "apply", args.apply) else: if sys.platform != "linux" or os.geteuid() != 0: raise UpdaterError("执行更新需要 Linux 宿主机上的受控 root 服务;Windows 仅支持 dry-run。") operator_config = Path(args.config) if (not operator_config.is_file() or operator_config.is_symlink() or operator_config.stat().st_uid != 0 or operator_config.stat().st_mode & 0o022): raise UpdaterError("执行器配置必须由 root 持有,且不能被其他用户写入。") if config.project_dir.stat().st_uid != 0 or config.project_dir.stat().st_mode & 0o022: raise UpdaterError("部署项目目录必须由 root 持有且禁止其他用户写入。") for path in (config.project_dir / "compose.yaml", config.project_dir / ".env", config.project_dir / ".image.env"): if not path.is_file() or path.is_symlink() or path.stat().st_uid != 0 or path.stat().st_mode & 0o022: raise UpdaterError("部署配置必须由 root 持有,且不能被其他用户写入。") if not config.data_dir.is_dir() or config.data_dir.is_symlink() or config.data_dir.stat().st_uid != 10001: raise UpdaterError("请先建立 UID 10001 可读写的独立 Web 数据目录。") if not config.control_dir.is_dir() or config.control_dir.is_symlink() or config.control_dir.stat().st_uid != 0 or config.control_dir.stat().st_mode & 0o022: raise UpdaterError("执行器控制目录必须由 root 持有且禁止其他用户写入。") signal.signal(signal.SIGTERM, interrupt_update) with exclusive(config): updater = HostUpdater(config) recovery = updater.recover() if recovery: result = recovery elif args.check: result = updater.check(updater.docker.inspect_service()["version"]) elif args.run: result = updater.run() else: result = updater.apply(args.apply or None) print(json.dumps(result, ensure_ascii=False, indent=2)) return int(result.get("status") in {"failed", "check_failed", "rolled_back"}) except UpdaterError as error: print(json.dumps({"status": "failed", "message": str(error)}, ensure_ascii=False)) return 1 except (OSError, ValueError, TypeError): print(json.dumps({"status": "failed", "message": "执行器配置、发布验证或 Docker 操作失败;未输出凭据或私有路径。"}, ensure_ascii=False)) return 1 if __name__ == "__main__": raise SystemExit(main())