feat: 数据备份管理系统 v0.1.0

带 Web 操作界面的备份系统，支持：
- 数据源：MySQL 数据库（mysqldump）、服务器目录（tar.gz）
- 存储目标：本地目录、S3 兼容对象存储（MinIO/Ceph/AWS S3）
- 触发方式：手动 + Cron 定时调度（APScheduler）
- 备份还原：MySQL 库、目录
- JWT 登录认证 + Fernet 字段加密
- 保留策略：按数量 + 按天数双重清理

技术栈：FastAPI + SQLAlchemy 2 + APScheduler + aioboto3；
前端 Vite + React 18 + TypeScript + Ant Design 5 + Zustand。
Docker Compose 一键起。

Co-Authored-By: Claude <noreply@anthropic.com>

backend/app/core/backup/base.py

@@ -0,0 +1,36 @@
+"""备份执行抽象基类：MySQL / Directory 都实现此接口。"""
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import AsyncIterator, Optional
+
+
+@dataclass
+class BackupMetadata:
+    """备份产物的元信息。"""
+
+    suggested_filename: str  # e.g. "db-20260622-030000.sql.gz" 或 "logs-20260622.tar.gz"
+    content_type: str = "application/octet-stream"
+    extra: Optional[dict] = None
+
+
+class BaseBackup(ABC):
+    """所有数据源类型实现此接口。
+
+    方法职责：
+      - metadata(): 计算建议文件名等
+      - produce(): 以异步字节流形式产出备份内容
+    """
+
+    def __init__(self, source_config: dict, job_name: str):
+        self.source_config = source_config
+        self.job_name = job_name
+
+    @abstractmethod
+    def metadata(self) -> BackupMetadata: ...
+
+    @abstractmethod
+    async def produce(self) -> AsyncIterator[bytes]:
+        """异步产出备份字节流。"""
+        # 子类应使用 async with + async generator
+        ...
+        yield b""  # pragma: no cover

backend/app/core/backup/directory.py

@@ -0,0 +1,127 @@
+"""目录备份：使用 tarfile 流式打包为 tar.gz。"""
+import asyncio
+import fnmatch
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import AsyncIterator
+
+from app.core.backup.base import BackupMetadata, BaseBackup
+from app.utils.logging import get_logger
+
+log = get_logger(__name__)
+
+
+class DirectoryBackup(BaseBackup):
+    def __init__(self, source_config: dict, job_name: str):
+        super().__init__(source_config, job_name)
+        self.path: str = source_config["path"]
+        self.exclude_patterns: list[str] = source_config.get("exclude_patterns", []) or []
+        self.base_dir = os.path.basename(os.path.normpath(self.path)) or "root"
+        self.root_path = Path(self.path).resolve()
+
+    def metadata(self) -> BackupMetadata:
+        ts = datetime.now().strftime("%Y%m%d-%H%M%S")
+        safe = "".join(c if c.isalnum() or c in ("_", "-") else "_" for c in self.base_dir)
+        return BackupMetadata(
+            suggested_filename=f"{self.job_name}-{safe}-{ts}.tar.gz",
+            content_type="application/gzip",
+            extra={"path": self.path, "base_dir": self.base_dir},
+        )
+
+    def _is_excluded(self, rel_path: str) -> bool:
+        name = os.path.basename(rel_path)
+        for pat in self.exclude_patterns:
+            if fnmatch.fnmatch(name, pat) or fnmatch.fnmatch(rel_path, pat):
+                return True
+        return False
+
+    async def produce(self) -> AsyncIterator[bytes]:
+        if not self.root_path.exists():
+            raise FileNotFoundError(f"Source path does not exist: {self.path}")
+        if not self.root_path.is_dir():
+            raise NotADirectoryError(f"Source path is not a directory: {self.path}")
+
+        log.info("Taring directory %s (exclude=%s)", self.path, self.exclude_patterns)
+
+        # 用一个 Queue 在同步线程和异步消费者之间桥接 tar 产出
+        queue: asyncio.Queue[bytes | None] = asyncio.Queue(maxsize=32)
+
+        def _tar_worker() -> None:
+            import tarfile
+
+            try:
+                with tarfile.open(mode="w:gz", bufsize=1024 * 1024) as tar:
+                    # 顶层目录名固定为 base_dir，便于解压后还原
+                    for dirpath, dirnames, filenames in os.walk(self.root_path):
+                        # 排除目录
+                        dirnames[:] = [
+                            d for d in dirnames
+                            if not self._is_excluded(os.path.relpath(os.path.join(dirpath, d), self.root_path))
+                        ]
+                        for fn in filenames:
+                            abs_path = os.path.join(dirpath, fn)
+                            rel = os.path.relpath(abs_path, self.root_path)
+                            if self._is_excluded(rel):
+                                continue
+                            try:
+                                tar.add(abs_path, arcname=os.path.join(self.base_dir, rel), recursive=False)
+                            except (PermissionError, OSError) as e:
+                                log.warning("Skip %s: %s", abs_path, e)
+                                continue
+                            # 周期性 flush 到 queue
+                            if tar.fileobj.tell() and (tar.fileobj.tell() % (256 * 1024) == 0):
+                                # 这里我们用 tarfile 的 fileobj 直接喂到 queue 更高效
+                                pass
+            except Exception as e:
+                log.exception("tar worker error: %s", e)
+            finally:
+                # tarfile 关闭后会写完 gzip trailer，我们需要在关闭时把 fileobj 全部送出
+                pass
+
+        # 实现简化：使用 tarfile 的 fileobj=BytesIO 会在循环中累积，
+        # 对超大目录会爆内存。下面用一个临时文件 + 异步读取的方案。
+        import tempfile
+
+        tmp_path = Path(tempfile.gettempdir()) / f"backup_{self.job_name}_{os.getpid()}.tar.gz"
+
+        def _tar_to_file() -> None:
+            import tarfile
+
+            try:
+                with tarfile.open(str(tmp_path), mode="w:gz") as tar:
+                    for dirpath, dirnames, filenames in os.walk(self.root_path):
+                        dirnames[:] = [
+                            d for d in dirnames
+                            if not self._is_excluded(os.path.relpath(os.path.join(dirpath, d), self.root_path))
+                        ]
+                        for fn in filenames:
+                            abs_path = os.path.join(dirpath, fn)
+                            rel = os.path.relpath(abs_path, self.root_path)
+                            if self._is_excluded(rel):
+                                continue
+                            try:
+                                tar.add(abs_path, arcname=os.path.join(self.base_dir, rel), recursive=False)
+                            except (PermissionError, OSError) as e:
+                                log.warning("Skip %s: %s", abs_path, e)
+            except Exception:
+                log.exception("tar file worker failed")
+
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, _tar_to_file)
+
+        if not tmp_path.exists() or tmp_path.stat().st_size == 0:
+            raise RuntimeError(f"Failed to create tar.gz for {self.path}")
+
+        try:
+            with open(tmp_path, "rb") as f:
+                while True:
+                    chunk = await loop.run_in_executor(None, f.read, 64 * 1024)
+                    if not chunk:
+                        break
+                    yield chunk
+        finally:
+            try:
+                tmp_path.unlink(missing_ok=True)
+            except Exception:
+                pass

backend/app/core/backup/mysql.py

@@ -0,0 +1,97 @@
+"""MySQL 备份：通过 mysqldump 子进程流式输出。"""
+import asyncio
+import gzip
+import shlex
+from datetime import datetime
+from typing import AsyncIterator
+
+from app.core.backup.base import BackupMetadata, BaseBackup
+from app.utils.logging import get_logger
+
+log = get_logger(__name__)
+
+CHUNK_SIZE = 64 * 1024
+
+
+class MySQLBackup(BaseBackup):
+    def __init__(self, source_config: dict, job_name: str):
+        super().__init__(source_config, job_name)
+        self.host: str = source_config["host"]
+        self.port: int = int(source_config.get("port", 3306))
+        self.user: str = source_config["user"]
+        self.password: str = source_config.get("password", "")
+        self.database: str = source_config["database"]
+        self.extra_args: str = source_config.get("extra_args", "")
+
+    def metadata(self) -> BackupMetadata:
+        ts = datetime.now().strftime("%Y%m%d-%H%M%S")
+        safe_db = "".join(c if c.isalnum() or c in ("_", "-") else "_" for c in self.database)
+        return BackupMetadata(
+            suggested_filename=f"{self.job_name}-{safe_db}-{ts}.sql.gz",
+            content_type="application/gzip",
+            extra={"database": self.database, "host": self.host, "port": self.port},
+        )
+
+    async def produce(self) -> AsyncIterator[bytes]:
+        args = [
+            "mysqldump",
+            "-h", self.host,
+            "-P", str(self.port),
+            "-u", self.user,
+            "--single-transaction",
+            "--quick",
+            "--routines",
+            "--triggers",
+            "--events",
+            "--default-character-set=utf8mb4",
+        ]
+        if self.extra_args:
+            args.extend(shlex.split(self.extra_args))
+        args.append(self.database)
+
+        log.info("Executing mysqldump for db=%s host=%s", self.database, self.host)
+
+        # mysqldump 直接写 stdout，我们 pipe 给 gzip 再 yield
+        # 用 -p 紧贴密码避免出现在 ps 里（空密码时 mysqldump 会要求交互输入）
+        if self.password:
+            args_with_pwd = args.copy()
+            # 找到 -u 后插入 -pXXX
+            u_idx = args_with_pwd.index("-u")
+            args_with_pwd.insert(u_idx + 2, f"-p{self.password}")
+        else:
+            args_with_pwd = args
+
+        proc = await asyncio.create_subprocess_exec(
+            *args_with_pwd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        assert proc.stdout is not None
+
+        # 在线程里跑 gzip.compress，因为它是阻塞的
+        loop = asyncio.get_event_loop()
+
+        async def gzip_stream() -> AsyncIterator[bytes]:
+            chunk_buf = bytearray()
+            async for chunk in proc.stdout:  # type: ignore[union-attr]
+                # gzip 接受 bytes，返回 bytes
+                compressed = await loop.run_in_executor(None, gzip.compress, chunk)
+                if compressed:
+                    yield compressed
+
+        try:
+            async for piece in gzip_stream():
+                yield piece
+        finally:
+            try:
+                await proc.wait()
+            except Exception:
+                proc.kill()
+                await proc.wait()
+
+        if proc.returncode != 0:
+            stderr = (await proc.stderr.read()).decode(errors="replace") if proc.stderr else ""
+            raise RuntimeError(
+                f"mysqldump failed (exit={proc.returncode}): {stderr.strip()[:2000]}"
+            )