mirror of
https://github.com/Awuqing/BackupX.git
synced 2026-05-07 06:03:00 +08:00
241a4808be
- 存储后端描述更新为 70+ rclone 集成 - API 参考补充新增端点（节点编辑、Rclone 后端列表、版本检查、Agent 心跳） - 技术栈补充 rclone - 多节点集群章节补充 IP 检测、节点编辑等新功能描述 - 存储目标添加指南补充 Rclone 类型配置项分层说明 - 任务删除行为说明（清理远端文件、保留记录） - 版本升级指引从一键更新改为手动 docker compose pull - 发版示例更新为 v1.4.3
335 lines
10 KiB
Markdown
335 lines
10 KiB
Markdown
<p align="right">
|
||
<a href="README_EN.md">English</a> | <strong>中文</strong>
|
||
</p>
|
||
<p align="center">
|
||
<h1 align="center">BackupX</h1>
|
||
<p align="center">
|
||
<strong>自托管服务器备份管理平台</strong><br>
|
||
一个二进制，一条命令，管好你所有服务器的备份。
|
||
</p>
|
||
<p align="center">
|
||
<a href="https://github.com/Awuqing/BackupX/stargazers"><img src="https://img.shields.io/github/stars/Awuqing/BackupX?style=flat-square&color=f5c542" alt="Stars"></a>
|
||
<a href="https://github.com/Awuqing/BackupX/releases"><img src="https://img.shields.io/github/v/release/Awuqing/BackupX?style=flat-square&color=brightgreen" alt="Release"></a>
|
||
<img src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat-square&logo=go" alt="Go">
|
||
<img src="https://img.shields.io/badge/React-18-61DAFB?style=flat-square&logo=react" alt="React">
|
||
<img src="https://img.shields.io/badge/SQLite-embedded-003B57?style=flat-square&logo=sqlite" alt="SQLite">
|
||
<a href="LICENSE"><img src="https://img.shields.io/github/license/Awuqing/BackupX?style=flat-square" alt="License"></a>
|
||
</p>
|
||
</p>
|
||
|
||
---
|
||
|
||
<table>
|
||
<tr>
|
||
<td width="50%"><img src="screenshots/dashboard.png" alt="仪表盘"></td>
|
||
<td width="50%"><img src="screenshots/backup-tasks.png" alt="备份任务"></td>
|
||
</tr>
|
||
<tr>
|
||
<td><img src="screenshots/storage-targets.png" alt="存储目标"></td>
|
||
<td><img src="screenshots/backup-records.png" alt="备份记录"></td>
|
||
</tr>
|
||
</table>
|
||
|
||
## 功能亮点
|
||
|
||
| 能力 | 说明 |
|
||
|------|------|
|
||
| **备份类型** | 文件/目录（多源路径）、MySQL、PostgreSQL、SQLite、SAP HANA |
|
||
| **70+ 存储后端** | 内置阿里云 OSS / 腾讯云 COS / 七牛云 / S3 / Google Drive / WebDAV / FTP + 通过 rclone 集成 SFTP、Azure Blob、Dropbox、OneDrive 等 70+ 后端 |
|
||
| **自动调度** | Cron 定时 + 可视化编辑器 + 自动保留策略（按天数/份数清理，自动回收空目录） |
|
||
| **多节点** | Master-Agent 集群，统一管理多台服务器的备份，支持远程目录浏览与节点编辑 |
|
||
| **安全** | JWT + bcrypt + AES-256-GCM 加密配置 + 可选备份文件加密 + 完整审计日志 |
|
||
| **通知** | 邮件 / Webhook / Telegram，备份成功或失败时自动推送 |
|
||
| **部署** | 单二进制 + 内嵌 SQLite，Docker 一键启动，零外部依赖 |
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装
|
||
|
||
**Docker（推荐，无需克隆仓库）：**
|
||
|
||
```bash
|
||
# 创建 docker-compose.yml 后一键启动
|
||
docker compose up -d
|
||
|
||
# 或直接运行
|
||
docker run -d --name backupx -p 8340:8340 -v backupx-data:/app/data awuqing/backupx:latest
|
||
```
|
||
|
||
> Docker Hub 镜像：[`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx)，支持 linux/amd64 和 linux/arm64。
|
||
|
||
<details>
|
||
<summary>docker-compose.yml 参考</summary>
|
||
|
||
```yaml
|
||
services:
|
||
backupx:
|
||
image: awuqing/backupx:latest
|
||
container_name: backupx
|
||
restart: unless-stopped
|
||
ports:
|
||
- "8340:8340"
|
||
volumes:
|
||
- backupx-data:/app/data
|
||
# 挂载需要备份的宿主机目录（按需添加）：
|
||
# - /var/www:/mnt/www:ro
|
||
# - /etc/nginx:/mnt/nginx-conf:ro
|
||
environment:
|
||
- TZ=Asia/Shanghai
|
||
|
||
volumes:
|
||
backupx-data:
|
||
```
|
||
|
||
</details>
|
||
|
||
**预编译包（裸机部署）：**
|
||
|
||
从 [Releases](https://github.com/Awuqing/BackupX/releases) 下载对应平台的压缩包：
|
||
|
||
```bash
|
||
tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
|
||
sudo ./install.sh # 自动配置 systemd + Nginx
|
||
```
|
||
|
||
**从源码构建：**
|
||
|
||
```bash
|
||
git clone https://github.com/Awuqing/BackupX.git && cd BackupX
|
||
make build # 构建前后端
|
||
make docker-cn # 或用国内镜像构建 Docker（goproxy.cn / npmmirror / 阿里云 apk）
|
||
```
|
||
|
||
### 2. 打开控制台
|
||
|
||
浏览器访问 `http://your-server:8340`，首次打开会引导创建管理员账户。
|
||
|
||
### 3. 添加存储目标
|
||
|
||
进入 **存储目标** 页面，点击 **添加**，选择存储类型并填写凭证：
|
||
|
||
| 存储类型 | 需要填写 |
|
||
|---------|---------|
|
||
| 阿里云 OSS | Region + AccessKey ID/Secret + Bucket |
|
||
| 腾讯云 COS | Region + SecretId/SecretKey + Bucket（格式 `name-appid`） |
|
||
| 七牛云 Kodo | Region + AccessKey/SecretKey + Bucket |
|
||
| S3 兼容 | Endpoint + AccessKey + Bucket |
|
||
| Google Drive | Client ID/Secret → 点击授权完成 OAuth |
|
||
| WebDAV | 服务器地址 + 用户名/密码 |
|
||
| FTP | 主机 + 端口 + 用户名/密码 |
|
||
| 本地磁盘 | 目标目录路径 |
|
||
| SFTP / Azure / Dropbox / OneDrive 等 | 选择对应类型后填写必填项，高级配置可折叠展开 |
|
||
|
||
> 国内云厂商只需填 Region 和 AccessKey，系统自动组装 Endpoint。Rclone 类型的配置项按必填/可选分层展示，高级选项默认折叠。
|
||
|
||
添加后点击 **测试连接** 确认配置正确。
|
||
|
||
### 4. 创建备份任务
|
||
|
||
进入 **备份任务** 页面，点击 **新建**，三步完成：
|
||
|
||
1. **基础信息** — 任务名称、备份类型、Cron 表达式（留空则仅手动执行）
|
||
2. **源配置** — 文件备份选择源路径（支持多个）、数据库备份填写连接信息
|
||
3. **存储与策略** — 选择存储目标（支持多个）、压缩策略、保留天数、是否加密
|
||
|
||
保存后可以点击 **立即执行** 测试，在 **备份记录** 页面实时查看执行日志。
|
||
|
||
> 删除备份任务时会自动清理远端存储上的备份文件，但保留备份记录以供审计追溯。
|
||
|
||
### 5. 配置通知（可选）
|
||
|
||
进入 **通知配置** 页面，支持邮件、Webhook、Telegram 三种方式，可分别配置成功/失败时是否推送。
|
||
|
||
---
|
||
|
||
## 部署指南
|
||
|
||
### Docker 部署
|
||
|
||
```bash
|
||
docker compose up -d # 使用上方的 docker-compose.yml
|
||
```
|
||
|
||
备份宿主机目录时需要挂载路径（在 docker-compose.yml 的 `volumes` 中添加）：
|
||
|
||
```yaml
|
||
volumes:
|
||
- backupx-data:/app/data
|
||
- /var/www:/mnt/www:ro # 挂载需要备份的目录
|
||
- /etc/nginx:/mnt/nginx-conf:ro # 可以挂载多个
|
||
```
|
||
|
||
通过环境变量调整配置：
|
||
|
||
```yaml
|
||
environment:
|
||
- TZ=Asia/Shanghai
|
||
- BACKUPX_LOG_LEVEL=debug
|
||
- BACKUPX_BACKUP_MAX_CONCURRENT=4
|
||
```
|
||
|
||
版本更新：在 **系统设置** 页面点击「检查更新」查看是否有新版本，然后手动执行 `docker compose pull && docker compose up -d` 完成升级。
|
||
|
||
### 裸机部署
|
||
|
||
```bash
|
||
# 使用预编译包
|
||
tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
|
||
sudo ./install.sh
|
||
|
||
# 或从源码
|
||
make build
|
||
sudo ./deploy/install.sh
|
||
```
|
||
|
||
安装脚本自动完成：创建系统用户 → 安装二进制到 `/opt/backupx/` → 配置 systemd → 配置 Nginx 反向代理。
|
||
|
||
### Nginx 反向代理（裸机部署时）
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name backup.example.com;
|
||
|
||
location / {
|
||
root /opt/backupx/web;
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
location /api/ {
|
||
proxy_pass http://127.0.0.1:8340;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 配置文件
|
||
|
||
配置文件路径 `./config.yaml`，也可通过 `BACKUPX_` 前缀环境变量覆盖：
|
||
|
||
```yaml
|
||
server:
|
||
port: 8340
|
||
database:
|
||
path: "./data/backupx.db"
|
||
security:
|
||
jwt_secret: "" # 留空自动生成并持久化到数据库
|
||
encryption_key: "" # 留空自动生成
|
||
backup:
|
||
temp_dir: "/tmp/backupx"
|
||
max_concurrent: 2
|
||
log:
|
||
level: "info" # debug | info | warn | error
|
||
file: "./data/backupx.log"
|
||
```
|
||
|
||
### 密码重置
|
||
|
||
忘记管理员密码时通过 CLI 重置：
|
||
|
||
```bash
|
||
# 裸机
|
||
./backupx reset-password --username admin --password newpass123
|
||
|
||
# Docker
|
||
docker exec -it backupx /app/bin/backupx reset-password --username admin --password newpass123
|
||
```
|
||
|
||
---
|
||
|
||
## 多节点集群
|
||
|
||
BackupX 支持 Master-Agent 模式管理多台服务器：
|
||
|
||
1. Web 控制台 → **节点管理** → **添加节点**，系统生成 Token
|
||
2. 在远程服务器部署 Agent 并使用 Token 连接 Master
|
||
3. 创建备份任务时选择对应节点，Master 自动下发任务
|
||
|
||
- 本机节点自动检测 IP 地址和版本信息
|
||
- 远程节点通过 Agent 心跳上报系统信息（主机名、IP、OS、架构、版本）
|
||
- 支持在控制台直接编辑节点名称
|
||
- 创建文件备份任务时可通过目录浏览器远程选择 Agent 节点上的目录
|
||
|
||
---
|
||
|
||
## 开发指南
|
||
|
||
**环境要求：** Go >= 1.25 · Node.js >= 20 · npm
|
||
|
||
```bash
|
||
# 开发模式
|
||
make dev-server # 终端 1：后端（默认 :8340）
|
||
make dev-web # 终端 2：前端（Vite HMR）
|
||
|
||
# 测试
|
||
make test # 运行全部测试
|
||
|
||
# 构建
|
||
make build # 前后端一起构建
|
||
make docker # Docker 构建
|
||
make docker-cn # 国内 Docker 构建（镜像加速）
|
||
```
|
||
|
||
### 发版
|
||
|
||
```bash
|
||
git tag v1.4.3 && git push --tags
|
||
# GitHub Actions 自动：编译双架构二进制 → 发布 GitHub Release → 推送 Docker Hub 镜像
|
||
```
|
||
|
||
也可在 GitHub Actions 页面手动触发 Release workflow。
|
||
|
||
---
|
||
|
||
## API 参考
|
||
|
||
所有接口以 `/api` 为前缀，使用 JWT Bearer Token 认证。
|
||
|
||
| 模块 | 端点 | 说明 |
|
||
|------|------|------|
|
||
| **认证** | `POST /auth/setup` | 初始化管理员 |
|
||
| | `POST /auth/login` | 登录 |
|
||
| | `PUT /auth/password` | 修改密码 |
|
||
| **备份任务** | `GET\|POST /backup/tasks` | 列表 / 创建 |
|
||
| | `GET\|PUT\|DELETE /backup/tasks/:id` | 详情 / 更新 / 删除 |
|
||
| | `PUT /backup/tasks/:id/toggle` | 启用/禁用 |
|
||
| | `POST /backup/tasks/:id/run` | 手动执行 |
|
||
| **备份记录** | `GET /backup/records` | 列表（支持筛选） |
|
||
| | `GET /backup/records/:id/logs/stream` | 实时日志 (SSE) |
|
||
| | `GET /backup/records/:id/download` | 下载 |
|
||
| | `POST /backup/records/:id/restore` | 恢复 |
|
||
| **存储目标** | `GET\|POST /storage-targets` | 列表 / 添加 |
|
||
| | `POST /storage-targets/test` | 测试连接 |
|
||
| | `GET /storage-targets/rclone/backends` | Rclone 后端列表 |
|
||
| **节点** | `GET\|POST /nodes` | 列表 / 添加 |
|
||
| | `PUT /nodes/:id` | 编辑节点 |
|
||
| | `GET /nodes/:id/fs/list` | 目录浏览 |
|
||
| | `POST /agent/heartbeat` | Agent 心跳（Token 认证） |
|
||
| **通知** | `GET\|POST /notifications` | 列表 / 添加 |
|
||
| **仪表盘** | `GET /dashboard/stats` | 概览统计 |
|
||
| **审计日志** | `GET /audit-logs` | 操作审计 |
|
||
| **系统** | `GET /system/info` | 系统信息 |
|
||
| | `GET /system/update-check` | 检查版本更新 |
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 技术 |
|
||
|------|------|
|
||
| **后端** | Go · Gin · GORM · SQLite · robfig/cron · rclone |
|
||
| **前端** | React 18 · TypeScript · ArcoDesign · Vite · Zustand · ECharts |
|
||
| **存储** | rclone（70+ 后端）· AWS SDK v2 · Google Drive API v3 |
|
||
| **安全** | JWT · bcrypt · AES-256-GCM |
|
||
|
||
## Contributing
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
## License
|
||
|
||
[Apache License 2.0](LICENSE)
|