# UniversalBackupSystem

**Repository Path**: ngcb/universal-backup-system

## Basic Information

- **Project Name**: UniversalBackupSystem
- **Description**: 统一备份平台系统
- **Primary Language**: Rust
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-24
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Universal Backup System (UBS)

通用数据备份系统，支持从远程服务器自动同步文件到本地存储，提供周期/镜像两种备份模式。

## 功能特性

- **多协议支持**：SFTP、SSH 脚本执行
- **两种备份模式**：
  - **周期模式**：保留多个历史版本，按 cron 定期全量+增量备份，自动清理过期周期
  - **镜像模式**：始终同步最新状态，远端删除则本地同步删除
- **SSH 脚本执行**：支持在远端执行自定义脚本（如数据库 dump），再将产物下载备份
- **WebSocket 实时进度**：前端实时展示文件传输进度和速度
- **通知系统**：Webhook / 企业微信 / 钉钉 / 邮件通知备份结果
- **RBAC 权限控制**：Admin / Operator / Viewer 三级角色
- **全局限速**：令牌桶算法，避免打满带宽
- **审计日志**：记录所有管理操作
- **优雅停机**：SIGTERM/SIGINT 时取消任务、标记状态、关闭连接池
- **生产就绪部署**：systemd 服务安装/升级/卸载脚本

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Rust + Axum + Tokio + SQLx (SQLite WAL) |
| 前端 | React 18 + TypeScript + Ant Design + Vite |
| SSH/SFTP | russh + russh-sftp |
| 调度 | tokio-cron-scheduler |
| 加密 | AES-256-GCM + Argon2 + JWT |
| 部署 | systemd + bash 脚本 |

## 快速开始

### 环境要求

- Rust 1.75+
- Node.js 18+
- 系统：Linux (x86_64 / ARM64)
- 无需系统 OpenSSL — 后端使用 rustls 纯 Rust TLS 实现

### 安装 Rust（Linux）

通过 rustup 安装 Rust 工具链：

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

安装过程中选择默认选项（1），完成后加载环境变量：

```bash
source "$HOME/.cargo/env"
cargo --version
```

如果服务器在国内，建议先配置镜像加速再安装：

```bash
export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

装完后配置 cargo 国内源，加速依赖下载：

```bash
mkdir -p ~/.cargo
cat > ~/.cargo/config.toml <<'EOF'
[source.tuna]
registry = "https://mirrors.tuna.tsinghua.edu.cn/git/crates.io-index.git"

[source.crates-io]
replace-with = "tuna"
EOF
```

### 安装 Node.js（Ubuntu）

```bash
sudo apt install nodejs npm
```

### 编译

```bash
# 后端
cd backend
cargo build --release

# 前端
cd frontend
npm install
npm run build
```

### 配置

拷贝示例配置并修改：

```bash
cp backend/config/ubs.toml.example backend/config/ubs.toml
```

主要配置项：

```toml
[server]
host = "0.0.0.0"
port = 8000

[database]
url = "sqlite://./data/ubs.db"

[storage]
root = "./data/backups"
static_dir = "../frontend/dist"

[transfer]
concurrency = 4
speed_limit_bps = 0   # 0 表示不限速

[auth]
max_failed_attempts = 5
lock_minutes = 15
session_timeout_minutes = 480

[ssh]
host_key_policy = "accept-new"   # strict | accept-new | insecure
```

### 运行

```bash
# 直接运行
ubs --config config/ubs.toml

# 首次启动会自动创建 admin 用户，密码输出到控制台
# 也可通过环境变量重置：
UBS_ADMIN_PASSWORD=yourpassword ubs --config config/ubs.toml
```

### 部署

项目根目录下的 `ubs.sh` 是统一管理脚本，集成安装/升级/卸载/数据库备份四类操作。运行时数据（数据库、备份、日志）统一保存在源码目录下的 `data/` 中。

```bash
# 安装为 systemd 服务（自动编译前后端 + 生成配置 + 写入服务单元）
sudo ./ubs.sh install

# 升级（git pull + 编译 + 备份数据库 + 重启服务）
sudo ./ubs.sh upgrade

# 卸载
sudo ./ubs.sh uninstall          # 仅移除服务，保留数据
sudo ./ubs.sh uninstall --purge # 彻底清除数据和编译产物

# 备份数据库（可加入 crontab）
sudo ./ubs.sh backup-db 7        # 保留最近 7 份
# 0 3 * * * /path/to/ubs.sh backup-db 7
```

服务以专用用户 `ubs` 运行，配置文件权限自动设为 `root:ubs 0640`，防止敏感信息泄露。

### 目录结构（部署后）

```
<源码根目录>/
├── backend/
│   ├── target/release/ubs   # 编译产物
│   └── ...
├── frontend/
│   ├── dist/                # 前端编译产物
│   └── ...
├── data/                    # 运行时数据（gitignore）
│   ├── config/ubs.toml      # 运行配置
│   ├── db/ubs.db            # SQLite 数据库
│   ├── backups/             # 备份文件存储
│   └── logs/                # 任务日志
└── ...
```

## 目录结构

```
universal-backup-system/
├── backend/
│   ├── src/
│   │   ├── api/           # REST API 路由（认证/用户/数据源/脚本/计划/任务/统计/审计）
│   │   ├── engine/        # 备份引擎（runner/mirror/cycle/progress/registry/storage/logger）
│   │   ├── protocols/     # 协议适配器（SFTP/SSH 脚本 + 连接池）
│   │   ├── main.rs        # 入口，优雅停机
│   │   ├── scheduler.rs   # cron 调度器
│   │   ├── ws.rs          # WebSocket 连接管理
│   │   ├── throttle.rs    # 令牌桶限速
│   │   ├── notify.rs      # 通知（Webhook/企业微信/钉钉/邮件）
│   │   ├── cleanup.rs     # 定时清理
│   │   └── ...
│   ├── migrations/        # SQL 迁移脚本
│   └── Cargo.toml
├── frontend/
│   ├── src/               # React + TypeScript
│   └── package.json
├── ubs.sh                 # 统一管理脚本（install/upgrade/uninstall/backup-db）
└── docs/
```

## API 概览

| 类别 | 端点 | 方法 |
|------|------|------|
| 认证 | `/api/auth/login` | POST |
| 认证 | `/api/auth/logout` | POST |
| 认证 | `/api/auth/me` | GET |
| 认证 | `/api/auth/password` | POST |
| 用户 | `/api/users` | GET / POST |
| 用户 | `/api/users/:id` | GET / PUT / DELETE |
| 数据源 | `/api/sources` | GET / POST |
| 数据源 | `/api/sources/:id` | GET / PUT / DELETE |
| 数据源 | `/api/sources/:id/test` | POST |
| 脚本 | `/api/scripts` | GET / POST |
| 脚本 | `/api/scripts/:id` | GET / PUT / DELETE |
| 计划 | `/api/plans` | GET / POST |
| 计划 | `/api/plans/:id` | GET / PUT / DELETE |
| 计划 | `/api/plans/:id/run` | POST |
| 计划 | `/api/plans/:id/enable` | POST |
| 计划 | `/api/plans/:id/disable` | POST |
| 任务 | `/api/tasks/running` | GET |
| 任务 | `/api/tasks/:id` | GET |
| 任务 | `/api/tasks/:id/stop` | POST |
| 历史 | `/api/history` | GET |
| 历史 | `/api/history/:id/logs` | GET |
| 统计 | `/api/stats/overview` | GET |
| 统计 | `/api/storage/usage` | GET |
| 通知 | `/api/notifications` | GET / POST |
| 设置 | `/api/settings` | GET / PUT |
| 审计 | `/api/audit-logs` | GET |
| WS | `/ws/tasks?token=<jwt>` | WebSocket |

## 权限模型

| 角色 | 读数据 | 写数据 | 管理用户 | 修改设置 |
|------|--------|--------|----------|----------|
| Admin | ✓ | ✓ | ✓ | ✓ |
| Operator | ✓ | ✓ | ✗ | ✗ |
| Viewer | ✓ | ✗ | ✗ | ✗ |

## 备份流程

```
定时/手动触发
    └→ 创建 backup_tasks 记录
        └→ 建立 SSH 连接（连接池复用）
            └→ SFTP 列举远端文件
                ├→ 周期模式：对比索引决定全量/增量
                └→ 镜像模式：按 size + mtime 对比决定下载/删除
                    └→ 并发下载（支持限速、重试）
                        └→ 更新文件索引 + backup_sets
                            └→ 发送 WebSocket 进度广播
                                └→ 发送通知（webhook/企业微信/钉钉/邮件）
```

## License

MIT