You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/virsh_panel/updater.py

540 lines
24 KiB
Python

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

"""Conservative Git updater for the panel's own, fixed Gitea repository.
The web process may inspect a checkout and enqueue a job. ``run_pending_job``
must run in a separate, privileged one-shot service: the regular web service
has a read-only code directory, and restarting it from within a request is
unreliable. The caller supplies the restart/health-check callback.
The personal access token is stored by the injected encrypted database store.
It never appears in a Git URL, command argument, temporary file, or returned
API data. A private, short-lived askpass program receives it only in the
child's environment while an HTTPS Git operation is in progress.
"""
from __future__ import annotations
import fcntl
import json
import os
import re
import secrets
import stat
import subprocess
import tempfile
import threading
import time
from contextlib import contextmanager
from pathlib import Path
from typing import Callable, Protocol
REPOSITORY_URL = "https://g.luoli.live/root/virt.git"
BRANCH = "main"
_TOKEN_KEY = "update.gitea_access_token"
_ACTIVE_JOB_KEY = "update.active_job"
_JOB_PREFIX = "update.job."
_HEX_COMMIT = re.compile(r"(?:[0-9a-f]{40}|[0-9a-f]{64})\Z")
_JOB_ID = re.compile(r"[A-Za-z0-9_-]{16,64}\Z")
class UpdateStore(Protocol):
"""Small persistence surface supplied by the encrypted database layer."""
def get_secret(self, name: str) -> str | None: ...
def set_secret(self, name: str, value: str) -> None: ...
def delete_secret(self, name: str) -> None: ...
def get_value(self, name: str) -> str | None: ...
def set_value(self, name: str, value: str) -> None: ...
class UpdateError(Exception):
"""A safe error suitable for returning to the authenticated operator."""
def __init__(self, message: str, status: int = 400) -> None:
super().__init__(message)
self.status = status
class Updater:
"""Read/check/advance only the pinned ``main`` branch of the panel repo."""
def __init__(
self,
repo_dir: Path,
secret_store: UpdateStore,
*,
git_binary: str = "git",
runner: Callable[..., subprocess.CompletedProcess[str]] | None = None,
) -> None:
self.repo_dir = Path(repo_dir).absolute()
self.store = secret_store
self.git_binary = git_binary
self._run = runner or subprocess.run
self._lock = threading.RLock()
def settings(self) -> dict:
"""Return only public configuration, never the stored access token."""
active_id = self.store.get_value(_ACTIVE_JOB_KEY)
active_job = self.get_job(active_id) if active_id else None
result = {
"repository": REPOSITORY_URL,
"branch": BRANCH,
"token_configured": bool(self.store.get_secret(_TOKEN_KEY)),
"checkout_ready": False,
"current_commit": None,
"last_job_id": active_id if active_job is not None else None,
"active_job_id": (
active_id if active_job is not None
and active_job.get("status") in {"queued", "running"} else None
),
}
try:
result["current_commit"] = self._checkout_head(require_clean=False)
result["checkout_ready"] = True
except UpdateError as exc:
result["checkout_error"] = str(exc)
return result
def set_token(self, token: str) -> None:
if (
not isinstance(token, str)
or not 16 <= len(token) <= 4096
or token != token.strip()
or any(ord(char) < 33 or ord(char) > 126 for char in token)
):
raise UpdateError("Gitea 访问令牌格式无效")
self.store.set_secret(_TOKEN_KEY, token)
def clear_token(self) -> None:
self.store.delete_secret(_TOKEN_KEY)
def _environment(self) -> dict[str, str]:
# Do not inherit GIT_TRACE, Git configuration, proxy overrides or
# GIT_SSL_NO_VERIFY from the panel service environment.
return {
"PATH": os.defpath,
"LANG": "C",
"LC_ALL": "C",
"GIT_CONFIG_NOSYSTEM": "1",
"GIT_CONFIG_GLOBAL": os.devnull,
"GIT_TERMINAL_PROMPT": "0",
"GIT_OPTIONAL_LOCKS": "0",
"GIT_ALLOW_PROTOCOL": "https",
}
@contextmanager
def _git_auth(self):
token = self.store.get_secret(_TOKEN_KEY)
if not token:
raise UpdateError("请先在面板中设置 Gitea 访问令牌", 409)
with tempfile.TemporaryDirectory(prefix="virsh-panel-askpass-") as directory:
askpass = Path(directory) / "askpass"
# This script contains no credential. Git passes a prompt as one
# argument; the token is handed to the Git child only in memory.
askpass.write_text(
"#!/bin/sh\n"
"case \"$1\" in\n"
" *sername*|*SERNAM*) printf '%s\\n' \"$VIRSH_PANEL_GIT_USERNAME\" ;;\n"
" *assword*|*ASSWORD*) printf '%s\\n' \"$VIRSH_PANEL_GIT_TOKEN\" ;;\n"
" *) exit 1 ;;\n"
"esac\n",
encoding="ascii",
)
askpass.chmod(0o700)
env = self._environment()
env.update({
"GIT_ASKPASS": str(askpass),
"VIRSH_PANEL_GIT_USERNAME": "root",
"VIRSH_PANEL_GIT_TOKEN": token,
})
yield env
def _git(
self,
*args: str,
timeout: float = 15,
environment: dict[str, str] | None = None,
error: str = "Git 操作失败,请检查面板日志",
allowed_codes: tuple[int, ...] = (0,),
) -> subprocess.CompletedProcess[str]:
argv = [
self.git_binary,
"-c", "core.hooksPath=/dev/null",
"-c", "http.followRedirects=false",
"-c", "http.sslVerify=true",
"-c", "http.extraHeader=",
"-c", "credential.helper=",
"-c", "fetch.recurseSubmodules=false",
*args,
]
try:
result = self._run(
argv,
cwd=self.repo_dir,
env=environment or self._environment(),
capture_output=True,
text=True,
timeout=timeout,
check=False,
)
except (OSError, subprocess.TimeoutExpired) as exc:
# Never include stderr, a URL, or a token in a public exception.
raise UpdateError(error, 502) from exc
if result.returncode not in allowed_codes:
raise UpdateError(error, 502)
return result
def _checkout_head(self, *, require_clean: bool) -> str:
if self.repo_dir.is_symlink() or not self.repo_dir.is_dir():
raise UpdateError("面板目录不是有效的 Git 检出目录", 409)
repo_info = self.repo_dir.lstat()
if repo_info.st_uid != os.geteuid() or repo_info.st_mode & 0o022:
raise UpdateError("面板目录必须由当前服务账号拥有,且不能允许组或其他用户写入", 409)
git_dir = self.repo_dir / ".git"
if git_dir.is_symlink() or not git_dir.is_dir():
raise UpdateError("面板必须从完整 Git 仓库部署,不能使用压缩包或工作树", 409)
try:
info = git_dir.lstat()
except OSError as exc:
raise UpdateError("无法读取面板 Git 仓库", 409) from exc
if not stat.S_ISDIR(info.st_mode):
raise UpdateError("面板 Git 仓库格式无效", 409)
if info.st_uid != os.geteuid() or info.st_mode & 0o022:
raise UpdateError("面板 Git 仓库权限不安全,已拒绝在线更新", 409)
top = self._git("rev-parse", "--show-toplevel", error="无法识别面板 Git 仓库").stdout.strip()
if Path(top).resolve() != self.repo_dir.resolve():
raise UpdateError("Git 仓库根目录与面板程序目录不一致", 409)
branch = self._git(
"symbolic-ref", "--quiet", "--short", "HEAD",
error="面板 Git 仓库当前不是 main 分支",
).stdout.strip()
if branch != BRANCH:
raise UpdateError("面板只允许从 main 分支更新", 409)
configured_urls = self._git(
"config", "--local", "--get-all", "remote.origin.url",
error="面板 Git 仓库缺少 origin 地址",
).stdout.splitlines()
if configured_urls != [REPOSITORY_URL]:
raise UpdateError("Git origin 必须是已指定的 Gitea 私有仓库,且不得包含凭据", 409)
# url.*.insteadOf could silently rewrite our explicit HTTPS URL to a
# different server and disclose the access token. Refuse it outright.
rewrites = self._git(
"config", "--local", "--name-only", "--get-regexp", r"^url\..*\.insteadof$",
allowed_codes=(0, 1),
error="无法检查 Git URL 重写配置",
)
if rewrites.returncode == 0:
raise UpdateError("Git 仓库配置了 URL 重写,无法安全更新", 409)
head = self._git("rev-parse", "HEAD", error="无法读取当前面板版本").stdout.strip()
if not _HEX_COMMIT.fullmatch(head):
raise UpdateError("当前 Git 提交标识无效", 409)
if require_clean:
status = self._git(
"status", "--porcelain=v1", "--untracked-files=all",
error="无法检查面板文件变更",
).stdout
if status.strip():
raise UpdateError("面板目录存在未提交或未跟踪文件;为防止覆盖,请先处理这些文件", 409)
return head
def _remote_head(self) -> str:
with self._git_auth() as env:
output = self._git(
"ls-remote", "--exit-code", "--", REPOSITORY_URL, f"refs/heads/{BRANCH}",
environment=env,
timeout=45,
error="无法读取 Gitea 私有仓库;请检查访问令牌、TLS 证书和网络",
).stdout.strip()
fields = output.split()
if len(fields) != 2 or fields[1] != f"refs/heads/{BRANCH}" or not _HEX_COMMIT.fullmatch(fields[0]):
raise UpdateError("Gitea 返回了无效的分支信息", 502)
return fields[0]
def check(self) -> dict:
"""Inspect the remote head without altering the local checkout."""
with self._lock:
current = self._checkout_head(require_clean=True)
remote = self._remote_head()
return {
"repository": REPOSITORY_URL,
"branch": BRANCH,
"current_commit": current,
"remote_commit": remote,
"status": "current" if current == remote else "update_available",
}
def _fetch_remote(self) -> str:
with self._git_auth() as env:
self._git(
"fetch", "--no-tags", "--no-recurse-submodules", "--",
REPOSITORY_URL, f"refs/heads/{BRANCH}",
environment=env,
timeout=300,
error="无法从 Gitea 拉取更新;请检查访问令牌、TLS 证书和网络",
)
head = self._git("rev-parse", "FETCH_HEAD", error="无法识别已下载的更新版本").stdout.strip()
if not _HEX_COMMIT.fullmatch(head):
raise UpdateError("下载的 Git 提交标识无效", 502)
return head
def _assert_safe_tree(self, target: str) -> None:
listing = self._git(
"ls-tree", "-r", "--name-only", target, "--", "data", ".venv", ".gitmodules",
error="无法检查更新文件清单",
).stdout
if listing:
raise UpdateError("更新包含面板数据目录、虚拟环境或子模块配置,已拒绝覆盖", 409)
def _install_requirements(self, target: str) -> None:
venv = self.repo_dir / ".venv"
python = venv / "bin" / "python"
if venv.is_symlink() or not venv.is_dir() or not python.exists():
raise UpdateError("未找到面板虚拟环境 .venv,不能自动安装更新依赖", 409)
requirements = self._git(
"show", f"{target}:requirements.txt",
error="更新版本缺少 requirements.txt,已取消更新",
).stdout
if not requirements or len(requirements) > 262144:
raise UpdateError("更新版本的依赖清单无效", 409)
with tempfile.TemporaryDirectory(prefix="virsh-panel-requirements-") as directory:
path = Path(directory) / "requirements.txt"
path.write_text(requirements, encoding="utf-8")
path.chmod(0o600)
env = {
"PATH": os.defpath,
"LANG": "C",
"LC_ALL": "C",
"PIP_NO_INPUT": "1",
"PIP_NO_CACHE_DIR": "1",
"PIP_DISABLE_PIP_VERSION_CHECK": "1",
}
try:
result = self._run(
[str(python), "-m", "pip", "install", "--no-input", "-r", str(path)],
cwd=self.repo_dir,
env=env,
capture_output=True,
text=True,
timeout=900,
check=False,
)
except (OSError, subprocess.TimeoutExpired) as exc:
raise UpdateError("更新依赖安装失败;面板代码尚未切换", 502) from exc
if result.returncode != 0:
raise UpdateError("更新依赖安装失败;面板代码尚未切换", 502)
@contextmanager
def _apply_lock(self):
git_dir = self.repo_dir / ".git"
flags = os.O_CREAT | os.O_RDWR | getattr(os, "O_NOFOLLOW", 0)
try:
descriptor = os.open(git_dir / "virsh-panel-update.lock", flags, 0o600)
except OSError as exc:
raise UpdateError("无法获取面板更新锁;请确认独立更新服务有代码目录写权限", 500) from exc
try:
info = os.fstat(descriptor)
if not stat.S_ISREG(info.st_mode) or info.st_mode & 0o077:
raise UpdateError("面板更新锁文件权限不安全", 500)
fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
except BlockingIOError as exc:
os.close(descriptor)
raise UpdateError("另一个更新任务正在运行", 409) from exc
except BaseException:
os.close(descriptor)
raise
try:
yield
finally:
fcntl.flock(descriptor, fcntl.LOCK_UN)
os.close(descriptor)
def apply(
self, *, progress: Callable[[str], None] | None = None,
expected_current_commit: str | None = None,
expected_remote_commit: str | None = None,
) -> dict:
"""Install dependencies, then fast-forward code. No force/reset is used."""
report = progress or (lambda _phase: None)
with self._lock:
# Validate before creating a lock inside .git.
current = self._checkout_head(require_clean=True)
with self._apply_lock():
# Re-check after acquiring the cross-process lock.
current = self._checkout_head(require_clean=True)
if expected_current_commit is not None and current != expected_current_commit:
raise UpdateError("面板本地版本已变化,请重新检查更新后再执行", 409)
report("正在从 Gitea 下载更新")
target = self._fetch_remote()
if expected_remote_commit is not None and target != expected_remote_commit:
raise UpdateError("Gitea main 分支已变化,请重新检查更新后再执行", 409)
self._assert_safe_tree(target)
ancestry = self._git(
"merge-base", "--is-ancestor", current, target,
allowed_codes=(0, 1),
error="无法验证更新提交历史",
)
if ancestry.returncode != 0:
raise UpdateError("远端 main 分支与当前版本已分叉,已拒绝自动覆盖", 409)
if target == current:
return {"updated": False, "old_commit": current, "new_commit": target}
report("正在安装新版本依赖")
self._install_requirements(target)
# Keep an immutable rollback pointer for manual recovery. A
# forced reset is never part of the automatic update path.
rollback_ref = f"refs/virsh-panel/rollback/{int(time.time())}-{secrets.token_hex(4)}"
self._git(
"update-ref", rollback_ref, current,
error="无法保存更新前版本,已取消切换",
)
# Files may have been edited during a long dependency install.
self._checkout_head(require_clean=True)
report("正在切换到新版本")
self._git(
"merge", "--ff-only", "--no-stat", target,
timeout=120,
error="无法快进更新代码;请检查面板目录与 Git 日志",
)
installed = self._checkout_head(require_clean=True)
if installed != target:
raise UpdateError("更新后的 Git 提交与预期不符,请人工核查", 500)
return {
"updated": True,
"old_commit": current,
"new_commit": target,
"rollback_ref": rollback_ref,
}
def _job_key(self, job_id: str) -> str:
if not isinstance(job_id, str) or not _JOB_ID.fullmatch(job_id):
raise UpdateError("更新任务编号无效", 404)
return _JOB_PREFIX + job_id
def get_job(self, job_id: str) -> dict | None:
raw = self.store.get_value(self._job_key(job_id))
if raw is None:
return None
try:
job = json.loads(raw)
except (TypeError, ValueError) as exc:
raise UpdateError("更新任务记录损坏", 500) from exc
if not isinstance(job, dict) or job.get("job_id") != job_id:
raise UpdateError("更新任务记录损坏", 500)
return job
def _save_job(self, job: dict) -> None:
self.store.set_value(self._job_key(job["job_id"]), json.dumps(job, ensure_ascii=False))
def create_job(
self, *, expected_current_commit: str | None = None,
expected_remote_commit: str | None = None,
) -> dict:
"""Enqueue one persisted job; the web layer then starts the worker."""
with self._lock:
current = self._checkout_head(require_clean=True)
if expected_current_commit is not None:
if not _HEX_COMMIT.fullmatch(expected_current_commit):
raise UpdateError("要更新的当前版本标识无效", 422)
if current != expected_current_commit:
raise UpdateError("面板本地版本已变化,请重新检查更新后再执行", 409)
if not self.store.get_secret(_TOKEN_KEY):
raise UpdateError("请先在面板中设置 Gitea 访问令牌", 409)
if expected_remote_commit is not None:
if not _HEX_COMMIT.fullmatch(expected_remote_commit):
raise UpdateError("要更新的远端版本标识无效", 422)
if self._remote_head() != expected_remote_commit:
raise UpdateError("Gitea main 分支已变化,请重新检查更新后再执行", 409)
active_id = self.store.get_value(_ACTIVE_JOB_KEY)
if active_id:
active = self.get_job(active_id)
if active is not None and active.get("status") in {"queued", "running"}:
raise UpdateError("已有更新任务正在执行", 409)
job_id = secrets.token_urlsafe(18)
job = {
"job_id": job_id,
"status": "queued",
"phase": "等待独立更新服务启动",
"created_at": int(time.time()),
}
if expected_current_commit is not None:
job["expected_current_commit"] = expected_current_commit
if expected_remote_commit is not None:
job["expected_remote_commit"] = expected_remote_commit
self._save_job(job)
self.store.set_value(_ACTIVE_JOB_KEY, job_id)
return job.copy()
def fail_job(self, job_id: str, message: str) -> dict:
"""Mark a queued/running job failed if the service could not start."""
with self._lock:
job = self.get_job(job_id)
if job is None:
raise UpdateError("更新任务不存在", 404)
if job["status"] not in {"queued", "running"}:
return job
job.update(status="failed", phase="更新失败", error=str(message)[:300], finished_at=int(time.time()))
self._save_job(job)
return job.copy()
def run_pending_job(self, *, restart: Callable[[], None] | None = None) -> dict:
"""Run the queued job in a separate service and persist every phase.
``restart`` should restart the web unit and, ideally, verify its health.
If it fails, the job records that code may already have changed and
exposes the old commit/rollback ref for operator-led recovery.
"""
with self._lock:
job_id = self.store.get_value(_ACTIVE_JOB_KEY)
if not job_id:
raise UpdateError("没有待执行的更新任务", 404)
job = self.get_job(job_id)
if job is None or job.get("status") != "queued":
raise UpdateError("更新任务未处于等待状态;请人工核查后重新提交", 409)
job.update(status="running", phase="正在检查本地仓库", started_at=int(time.time()))
self._save_job(job)
def progress(phase: str) -> None:
with self._lock:
job["phase"] = str(phase)[:200]
self._save_job(job)
applied: dict | None = None
try:
applied = self.apply(
progress=progress,
expected_current_commit=job.get("expected_current_commit"),
expected_remote_commit=job.get("expected_remote_commit"),
)
job.update(applied)
self._save_job(job)
if applied["updated"] and restart is not None:
progress("正在重启面板并检查服务")
restart()
elif applied["updated"]:
# A worker that cannot restart the web service must not
# report a successful one-click update.
raise UpdateError("代码已更新,但未配置自动重启;请人工重启面板服务", 500)
job.update(status="succeeded", phase="更新完成" if applied["updated"] else "已是最新版本",
finished_at=int(time.time()))
self._save_job(job)
return job.copy()
except Exception as exc:
if isinstance(exc, UpdateError):
error = str(exc)
else:
error = "更新失败,请查看独立更新服务日志"
if applied is not None and applied.get("updated"):
error += ";程序代码可能已切换,请人工核查并重启或按回滚引用恢复"
job.update(status="failed", phase="更新失败", error=error, finished_at=int(time.time()))
self._save_job(job)
if isinstance(exc, UpdateError):
raise
raise UpdateError(error, 500) from exc
__all__ = ["BRANCH", "REPOSITORY_URL", "UpdateError", "UpdateStore", "Updater"]