GithubBackup/BackupX
1
0
Fork 0
mirror of https://github.com/Awuqing/BackupX.git synced 2026-05-06 20:02:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: restructure README with user-friendly guides and deployment instructions

Browse Source 
Rewrite both README.md and README_EN.md:
- Reorganize around user journey: install → setup → add storage → create task → monitor
- Add step-by-step "Quick Start" guide (5 steps from zero to first backup)
- Add storage target config reference table
- Consolidate duplicate deployment sections into single "Deployment Guide"
- Remove redundant password reset entries (was listed twice)
- Move Project Structure / Architecture to end (dev-facing, not user-facing)
- Compact API reference table (remove verbose endpoint prefixes)
- Add screenshot grid layout for better visual impact
This commit is contained in:
Awuqing
2026-03-31 00:10:06 +08:00
parent 0aa25d99f2
commit 6c1e988920
2 changed files with 396 additions and 1013 deletions
Download Patch File Download Diff File Expand all files Collapse all files

676
README.md
View File

@@ -2,506 +2,168 @@
<a href="README_EN.md">English</a> | <strong>中文</strong>
</p>
<p align="center">
<h1 align="center">🛡️ BackupX</h1>
<h1 align="center">BackupX</h1>
<p align="center">
<strong>Self-hosted Server Backup Management Platform with Web UI</strong>
</p>
<p align="center">
<a href="#features">Features</a> •
<a href="#quick-start">Quick Start</a> •
<a href="#configuration">Configuration</a> •
<a href="#architecture">Architecture</a> •
<a href="#cluster-mode">Cluster</a> •
<a href="#development">Development</a> •
<a href="#api-reference">API</a>
<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.21+-00ADD8?style=flat-square&logo=go" alt="Go">
<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/TypeScript-5-3178C6?style=flat-square&logo=typescript" alt="TypeScript">
<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>
<a href="https://github.com/Awuqing/BackupX/issues"><img src="https://img.shields.io/github/issues/Awuqing/BackupX?style=flat-square" alt="Issues"></a>
</p>
</p>
---
BackupX 是一个面向 **Linux / macOS 服务器**的自托管备份管理平台。通过企业级 Web 控制台，轻松配置目录备份、数据库备份，并将备份文件安全存储到阿里云 OSS、腾讯云 COS、七牛云 Kodo、Google Drive、S3 兼容存储、WebDAV、FTP/FTPS 或本地磁盘。
<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>
支持 **多节点集群管理**，可统一管控分布在不同服务器上的备份任务。
## 功能亮点
> **适用人群**：拥有 Linux 服务器的个人开发者 / 小团队 / 企业运维
| 能力 | 说明 |
|------|------|
| **备份类型** | 文件/目录（多源路径）、MySQL、PostgreSQL、SQLite、SAP HANA |
| **存储后端** | 阿里云 OSS、腾讯云 COS、七牛云、S3 兼容(AWS/MinIO/R2)、Google Drive、WebDAV、FTP/FTPS、本地磁盘 |
| **自动调度** | Cron 定时 + 可视化编辑器 + 自动保留策略（按天数/份数清理） |
| **多节点** | Master-Agent 集群，统一管理多台服务器的备份 |
| **安全** | JWT + bcrypt + AES-256-GCM 加密配置 + 可选备份文件加密 + 审计日志 |
| **通知** | 邮件 / Webhook / Telegram，备份成功或失败时自动推送 |
| **部署** | 单二进制 + 内嵌 SQLite，Docker 一键启动，零外部依赖 |
## Screenshots
---
### 登录页面
![登录页面](screenshots/login.png)
## 快速开始
### 仪表盘
![仪表盘](screenshots/dashboard.png)
### 1. 安装
### 备份任务
![备份任务](screenshots/backup-tasks.png)
### 备份记录
![备份记录](screenshots/backup-records.png)
### 存储目标
![存储目标](screenshots/storage-targets.png)
### 节点管理
![节点管理](screenshots/nodes.png)
### 通知配置
![通知配置](screenshots/notifications.png)
### 系统设置
![系统设置](screenshots/settings.png)
## Features
### 📦 多种备份类型
- **文件/目录** — 支持多源路径备份，自定义排除规则（如 `node_modules`、`*.log`）
- **MySQL** — 通过 `mysqldump` 原生工具
- **SQLite** — 安全文件拷贝
- **PostgreSQL** — 通过 `pg_dump` 原生工具
- **SAP HANA** — 通过 `hdbsql+backint` （支持多租户数据库）
### ☁️ 多云存储后端
| 厂商 | 类型 | 说明 |
|------|------|------|
| 🇨🇳 **阿里云 OSS** | `aliyun_oss` | 自动组装 Endpoint，支持内网传输 |
| 🇨🇳 **腾讯云 COS** | `tencent_cos` | 自动组装 Endpoint |
| 🇨🇳 **七牛云 Kodo** | `qiniu_kodo` | 6 大区域精确映射 |
| 🌍 **S3 Compatible** | `s3` | AWS S3 / MinIO / Cloudflare R2 等 |
| 🌍 **Google Drive** | `google_drive` | 完整 OAuth 2.0 授权流程 |
| 🌍 **WebDAV** | `webdav` | 坚果云 / Nextcloud 等 |
| 🌍 **FTP / FTPS** | `ftp` | 标准 FTP 协议，支持 Explicit TLS 加密 |
| 💾 **本地磁盘** | `local_disk` | 备份到服务器本地目录 |
> 国内云厂商仅需填写 **Region** 和 **AccessKey**，系统自动完成 Endpoint 组装，底层复用 S3 引擎零额外依赖。
### 🖥️ 集群管理 (Master-Agent)
- **节点管理** — 注册远程服务器节点，Token 认证
- **本机节点** — 自动创建，单机用户零感知升级
- **目录浏览** — 可视化文件树选择备份源路径，告别手动输入
- **Agent 心跳** — 节点在线状态实时监控
- **任务标签** — 按标签/节点分类管理备份任务
### ⏰ 自动化与调度
- Cron 表达式定时调度
- 可视化 Cron 编辑器
- 自动保留策略（按天数 / 按份数过期清理）
- 最大并发备份数限制
### 🔐 安全
- JWT 认证 + bcrypt 密码存储
- AES-256-GCM 加密存储敏感配置（数据库密码、OAuth Token）
- 可选备份文件加密
- 登录限流防暴力破解
- 节点 Token 认证（一次性显示，安全传输）
- CLI 密码重置（Docker 用户通过 `docker exec` 执行，无需邮件找回）
### 📊 监控与通知
- 仪表盘统计（成功率、存储用量、备份趋势图表）
- 邮件 / Webhook / Telegram 通知
- 实时备份执行日志 (SSE)
- **审计日志** — 全操作链可溯源，记录登录、任务创建/修改/删除、备份执行/恢复等关键事件
### 🌐 其他
- 中英文国际化 (i18n)
- 零外部依赖（内嵌 SQLite，单二进制部署）
- Docker / Docker Compose 一键部署
- systemd 服务支持
## Quick Start
### Docker 部署 (推荐)
**Docker（推荐）：**
```bash
# 克隆项目
git clone https://github.com/Awuqing/BackupX.git
cd BackupX
# 一键启动
git clone https://github.com/Awuqing/BackupX.git && cd BackupX
docker compose up -d
```
如需备份宿主机上的目录，在 `docker-compose.yml` 中挂载对应路径：
**预编译包：**
```yaml
volumes:
- backupx-data:/app/data
- /path/to/backup/source:/mnt/source:ro
```
### 从源码构建
从 [Releases](https://github.com/Awuqing/BackupX/releases) 下载对应平台的压缩包，解压后运行安装脚本：
```bash
# 克隆项目
git clone https://github.com/Awuqing/BackupX.git
cd BackupX
# 一键构建前后端
make build
# 启动后端服务（默认监听 :8340）
cd server && ./bin/backupx
tar xzf backupx-v*.tar.gz && cd backupx-*
sudo ./install.sh # 自动配置 systemd + Nginx
```
### 国内用户构建
如果因网络原因下载依赖缓慢，可使用国内镜像加速：
**国内用户源码构建：**
```bash
# 方式一：Docker 构建（推荐，一行搞定）
make docker-cn
# 方式二：手动设置镜像后裸机构建
export GOPROXY=https://goproxy.cn,direct # Go 模块代理
npm config set registry https://registry.npmmirror.com # npm 淘宝源
make build
git clone https://github.com/Awuqing/BackupX.git && cd BackupX
make docker-cn # 自动使用国内镜像（goproxy.cn / npmmirror / 阿里云 apk）
```
### 访问 Web UI
### 2. 打开控制台
打开浏览器访问 `http://your-server:8340`，首次使用会引导您创建管理员账户。
浏览器访问 `http://your-server:8340`，首次打开会引导创建管理员账户。
## Configuration
### 3. 添加存储目标
配置文件路径默认为 `./config.yaml`，也可通过环境变量 `BACKUPX_` 前缀覆盖。
进入 **存储目标** 页面，点击 **添加**，选择存储类型并填写凭证：
```yaml
# config.yaml
server:
host: "0.0.0.0"
port: 8340
mode: "release" # debug | release
| 存储类型 | 需要填写 |
|---------|---------|
| 阿里云 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 | 主机 + 端口 + 用户名/密码 |
| 本地磁盘 | 目标目录路径 |
database:
path: "./data/backupx.db" # SQLite 数据库路径
> 国内云厂商只需填 Region 和 AccessKey，系统自动组装 Endpoint。
security:
jwt_secret: "" # 留空则自动生成
jwt_expire: "24h"
encryption_key: "" # AES 加密密钥，留空自动生成
添加后点击 **测试连接** 确认配置正确。
backup:
temp_dir: "/tmp/backupx" # 备份临时文件目录
max_concurrent: 2 # 最大并发备份数
### 4. 创建备份任务
log:
level: "info" # debug | info | warn | error
file: "./data/backupx.log"
max_size: 100 # 日志文件大小上限 (MB)
max_backups: 3 # 保留旧日志文件数
max_age: 30 # 日志保留天数
```
进入 **备份任务** 页面，点击 **新建**，三步完成：
> 💡 `jwt_secret` 和 `encryption_key` 首次启动时自动生成并持久化到数据库，无需手动配置。
1. **基础信息** — 任务名称、备份类型、Cron 表达式（留空则仅手动执行）
2. **源配置** — 文件备份选择源路径（支持多个）、数据库备份填写连接信息
3. **存储与策略** — 选择存储目标、压缩策略、保留天数、是否加密
## Architecture
保存后可以点击 **立即执行** 测试，在 **备份记录** 页面实时查看执行日志。
```
┌─────────────────────┐
│ Nginx (反向代理) │
│ / → 前端静态文件 │
│ /api → :8340 │
└─────────┬───────────┘
│
▼
┌──────────────────────────────────────────────────────┐
│ BackupX Master (Go API Server) │
│ :8340 │
│ │
│ ┌──────┐ ┌────────────┐ ┌───────────────────────┐│
│ │ Auth │ │Backup Engine│ │ Storage Registry ││
│ └──────┘ └──────┬─────┘ │ ┌─────────────────┐ ││
│ │ │ │ Aliyun OSS │ ││
│ ┌──────────┐ │ │ │ Tencent COS │ ││
│ │ Cron │◄───┘ │ │ Qiniu Kodo │ ││
│ │Scheduler │ │ │ S3 Compatible │ ││
│ └──────────┘ │ │ Google Drive │ ││
│ │ │ WebDAV │ ││
│ │ │ FTP / FTPS │ ││
│ ┌──────────┐ │ │ Local Disk │ ││
│ │ Notify │ │ └─────────────────┘ ││
│ │ Module │ └───────────────────────┘│
│ └──────────┘ │
│ │
│ ┌──────────────┐ ┌────────────────────┐ │
│ │ Node Manager │ │ SQLite (backupx.db)│ │
│ └──────┬───────┘ └────────────────────┘ │
└─────────┼────────────────────────────────────────────┘
│ Heartbeat / Task Dispatch
▼
┌──────────────────┐ ┌──────────────────┐
│ Agent Node A │ │ Agent Node B │
│ (远程服务器) │ │ (远程服务器) │
└──────────────────┘ └──────────────────┘
```
### 5. 配置通知（可选）
### 技术栈
进入 **通知配置** 页面，支持邮件、Webhook、Telegram 三种方式，可分别配置成功/失败时是否推送。
| 组件 | 技术 |
|------|------|
| **后端** | Go · Gin · GORM · SQLite · robfig/cron |
| **前端** | React 18 · TypeScript · ArcoDesign · Vite · Zustand · ECharts |
| **存储** | AWS SDK v2 (S3/OSS/COS/Kodo) · Google Drive API v3 · gowebdav · jlaffaye/ftp |
| **安全** | JWT · bcrypt · AES-256-GCM |
| **日志** | zap + lumberjack (自动轮转) |
---
## Cluster Mode
BackupX 支持 **Master-Agent** 模式，可管理多台服务器的备份任务。
### 工作原理
1. **Master** 为运行 BackupX Web 控制台的主控服务器
2. **Agent** 部署在需要备份的远程服务器上
3. Agent 启动后通过 Token 向 Master 注册并定期发送心跳
4. Master 将备份任务下发至对应 Agent 执行
### 添加节点
```bash
# 在 Web 控制台 → 节点管理 → 添加节点
# 系统将生成一个唯一的 64 位十六进制 Token
# 在远程服务器上配置 Agent 启动参数
./backupx-agent --master http://master-server:8340 --token <your-token>
```
### 目录探针 API
Master 提供 `GET /api/nodes/:id/fs/list?path=/` 接口，可远程浏览节点的文件系统目录。前端在创建备份任务的"源路径"输入时可使用树形选择器直接浏览目标机器的目录结构。
## Project Structure
```
BackupX/
├── server/ # Go 后端
│ ├── cmd/backupx/ # 程序入口
│ ├── internal/
│ │ ├── app/ # 应用组装 (DI)
│ │ ├── apperror/ # 统一错误类型
│ │ ├── backup/ # 备份引擎 (file/mysql/sqlite/pgsql/saphana)
│ │ │ └── retention/ # 保留策略
│ │ ├── config/ # 配置加载 (viper)
│ │ ├── database/ # 数据库初始化 + 迁移
│ │ ├── http/ # HTTP 处理器 + 路由 + 中间件
│ │ ├── httpapi/ # HTTP API 辅助工具
│ │ ├── logger/ # 日志初始化 (zap + lumberjack)
│ │ ├── model/ # GORM 数据模型
│ │ ├── notify/ # 通知 (email/webhook/telegram)
│ │ ├── repository/ # 数据访问层
│ │ ├── scheduler/ # Cron 调度器
│ │ ├── security/ # JWT + 限流
│ │ ├── service/ # 业务逻辑层
│ │ └── storage/ # 存储后端 (插件化接口)
│ │ ├── aliyun/ # 阿里云 OSS
│ │ ├── tencent/ # 腾讯云 COS
│ │ ├── qiniu/ # 七牛云 Kodo
│ │ ├── s3/ # S3 Compatible 核心
│ │ ├── s3provider/ # S3 Provider 辅助
│ │ ├── googledrive/ # Google Drive
│ │ ├── webdav/ # WebDAV 核心
│ │ ├── webdavprovider/ # WebDAV Provider 辅助
│ │ ├── localdisk/ # 本地磁盘
│ │ ├── ftp/ # FTP / FTPS
│ │ └── codec/ # 配置编解码
│ └── pkg/ # 工具包 (compress/crypto/response)
├── web/ # React 前端
│ └── src/
│ ├── components/ # 通用组件 (CronEditor/FormDrawer/...)
│ ├── hooks/ # 自定义 Hooks
│ ├── layouts/ # 布局组件 (AppLayout)
│ ├── pages/ # 页面模块
│ │ ├── dashboard/ # 仪表盘
│ │ ├── backup-tasks/ # 备份任务
│ │ ├── backup-records/ # 备份记录
│ │ ├── storage-targets/ # 存储目标
│ │ ├── nodes/ # 节点管理
│ │ ├── notifications/ # 通知配置
│ │ ├── audit/ # 审计日志
│ │ ├── settings/ # 系统设置
│ │ └── login/ # 登录页
│ ├── services/ # API 请求封装
│ ├── stores/ # Zustand 状态管理
│ ├── styles/ # 全局样式
│ ├── types/ # TypeScript 类型定义
│ ├── utils/ # 工具函数
│ ├── locales/ # i18n 语言包 (zh-CN / en-US)
│ └── router/ # 路由配置
├── deploy/ # 部署配置
│ ├── nginx.conf # Nginx 参考配置
│ ├── backupx.service # systemd 服务单元
│ ├── install.sh # 一键安装脚本
│ └── docker/ # Docker 部署配置
│ ├── nginx.conf # 容器内 Nginx 配置
│ └── entrypoint.sh # 容器启动脚本
├── .github/ # GitHub 配置
│ ├── workflows/ci.yml # CI 工作流
│ ├── workflows/release.yml # Release 工作流
│ └── ISSUE_TEMPLATE/ # Issue 模板
├── Dockerfile # Docker 多阶段构建
├── docker-compose.yml # Docker Compose 配置
└── Makefile # 构建命令
```
## Development
### 前置条件
- **Go** ≥ 1.21
- **Node.js** ≥ 18
- **npm**
### 开发模式
```bash
# 终端 1：启动后端 (热重载需配合 air)
make dev-server
# 终端 2：启动前端 (Vite HMR)
make dev-web
```
### 运行测试
```bash
# 运行全部测试
make test
# 仅后端
make test-server # go test ./...
# 仅前端
make test-web # npm run test
```
### 构建
```bash
# 构建前后端
make build
# Docker 构建
make docker
# 国内 Docker 构建（使用国内镜像加速）
make docker-cn
# 清理构建产物
make clean
```
### 发版
推送 Git tag 即可自动触发 GitHub Actions 完成全部发布流程：
```bash
git tag v1.2.3
git push --tags
# GitHub Actions 自动：编译二进制 → 发布 Release → 推送 Docker Hub 镜像
```
也可以在 GitHub Actions 页面手动触发 Release workflow，输入版本号即可。
## Deployment
### 一键安装 (推荐)
```bash
# 先构建
make build
# 以 root 执行安装脚本
sudo ./deploy/install.sh
```
安装脚本将自动：
1. 创建 `backupx` 系统用户
2. 安装二进制到 `/opt/backupx/bin/`
3. 部署前端到 `/opt/backupx/web/`
4. 生成配置文件 `/etc/backupx/config.yaml`
5. 注册并启动 systemd 服务
6. 配置 Nginx 反向代理（如已安装）
## 部署指南
### Docker 部署
```bash
# 使用 docker compose
docker compose up -d
# 或手动构建镜像
docker build -t backupx .
docker run -d --name backupx -p 8340:8340 -v backupx-data:/app/data backupx
```
**密码重置**（忘记管理员密码时）：
备份宿主机目录时需要挂载路径：
```bash
docker exec -it backupx /app/bin/backupx reset-password --username admin --password newpass123
```yaml
# docker-compose.yml
volumes:
- backupx-data:/app/data
- /var/www:/mnt/www:ro # 挂载需要备份的目录
- /etc/nginx:/mnt/nginx-conf:ro # 可以挂载多个
```
通过环境变量覆盖配置：
通过环境变量调整配置：
```bash
docker run -d --name backupx \
-p 8340:8340 \
docker run -d --name backupx -p 8340:8340 \
-v backupx-data:/app/data \
-e TZ=Asia/Shanghai \
-e BACKUPX_LOG_LEVEL=debug \
-e BACKUPX_BACKUP_MAX_CONCURRENT=4 \
backupx
```
### 手动部署
### 裸机部署
```bash
# 1. 构建
cd server && go build -o backupx ./cmd/backupx
cd ../web && npm run build
# 使用预编译包
tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
sudo ./install.sh
# 2. 部署文件
scp server/backupx your-server:/opt/backupx/bin/
scp -r web/dist/ your-server:/opt/backupx/web/
scp server/config.example.yaml your-server:/etc/backupx/config.yaml
# 3. 启动
ssh your-server '/opt/backupx/bin/backupx -config /etc/backupx/config.yaml'
# 或从源码
make build
sudo ./deploy/install.sh
```
### 密码重置
安装脚本自动完成：创建系统用户 → 安装二进制到 `/opt/backupx/` → 配置 systemd → 配置 Nginx 反向代理。
忘记管理员密码时，可通过 CLI 直接重置（需要服务器 shell 权限）：
```bash
# 裸机部署
./backupx reset-password --username admin --password newpass123
# Docker 部署
docker exec -it backupx /app/bin/backupx reset-password --username admin --password newpass123
```
### Nginx 配置示例
### Nginx 反向代理（裸机部署时）
```nginx
server {
listen 80;
server_name backup.example.com;
# 前端静态文件
location / {
root /opt/backupx/web;
try_files $uri $uri/ /index.html;
}
# API 反向代理
location /api/ {
proxy_pass http://127.0.0.1:8340;
proxy_set_header Host $host;
@@ -510,90 +172,122 @@ server {
}
```
## API Reference
### 配置文件
所有 API 均以 `/api` 为前缀，使用 JWT Bearer Token 认证（除特殊标注外）。
配置文件路径 `./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 自动下发任务
创建文件备份任务时，可通过可视化目录浏览器远程选择 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.2.3 && git push --tags
# GitHub Actions 自动：编译双架构二进制 → 发布 GitHub Release → 推送 Docker Hub 镜像
```
也可在 GitHub Actions 页面手动触发 Release workflow。
---
## API 参考
所有接口以 `/api` 为前缀，使用 JWT Bearer Token 认证。
| 模块 | 端点 | 说明 |
|------|------|------|
| **认证** | `POST /api/auth/setup` | 首次初始化管理员 |
| | `POST /api/auth/login` | 登录获取 Token |
| | `POST /api/auth/logout` | 登出 |
| | `GET /api/auth/profile` | 当前用户信息 |
| | `PUT /api/auth/password` | 修改密码 |
| **备份任务** | `GET/POST /api/backup/tasks` | 任务列表 / 创建 |
| | `GET/PUT/DELETE /api/backup/tasks/:id` | 详情 / 更新 / 删除 |
| | `PUT /api/backup/tasks/:id/toggle` | 启用/禁用 |
| | `POST /api/backup/tasks/:id/run` | 手动触发执行 |
| **备份记录** | `GET /api/backup/records` | 记录列表 (支持筛选) |
| | `GET /api/backup/records/:id` | 记录详情 |
| | `GET /api/backup/records/:id/logs/stream` | 实时执行日志 (SSE) |
| | `GET /api/backup/records/:id/download` | 下载备份文件 |
| | `POST /api/backup/records/:id/restore` | 恢复备份 |
| **存储目标** | `GET/POST /api/storage-targets` | 存储列表 / 添加 |
| | `GET/PUT/DELETE /api/storage-targets/:id` | 详情 / 更新 / 删除 |
| | `POST /api/storage-targets/test` | 测试连接 |
| | `POST /api/storage-targets/:id/test` | 测试已保存连接 |
| | `GET /api/storage-targets/:id/usage` | 查询用量 |
| **节点管理** | `GET/POST /api/nodes` | 节点列表 / 添加 |
| | `GET/DELETE /api/nodes/:id` | 详情 / 删除 |
| | `GET /api/nodes/:id/fs/list` | 目录浏览 |
| | `POST /api/agent/heartbeat` | Agent 心跳 ⚡ |
| **通知** | `GET/POST /api/notifications` | 通知列表 / 添加 |
| | `POST /api/notifications/test` | 测试通知 |
| | `POST /api/notifications/:id/test` | 测试已保存通知 |
| **仪表盘** | `GET /api/dashboard/stats` | 概览统计 |
| | `GET /api/dashboard/timeline` | 备份趋势时间线 |
| **审计日志** | `GET /api/audit-logs` | 审计日志列表 (支持分类筛选/分页) |
| **系统** | `GET /api/system/info` | 系统信息 (版本/磁盘) |
| | `GET/PUT /api/settings` | 系统设置读写 |
| **认证** | `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\|POST /nodes` | 列表 / 添加 |
| | `GET /nodes/:id/fs/list` | 目录浏览 |
| **通知** | `GET\|POST /notifications` | 列表 / 添加 |
| **仪表盘** | `GET /dashboard/stats` | 概览统计 |
| **审计日志** | `GET /audit-logs` | 操作审计 |
| **系统** | `GET /system/info` | 系统信息 |
> ⚡ `POST /api/agent/heartbeat` 为公开端点，使用 Node Token 认证而非 JWT。
---
## 云存储配置指南
## 技术栈
### 阿里云 OSS
1. 登录[阿里云控制台](https://oss.console.aliyun.com/)，创建 Bucket
2. 前往 RAM 控制台创建 AccessKey
3. 在 BackupX 添加存储目标时选择"阿里云 OSS"
4. 填写 Region（如 `cn-hangzhou`）和 AccessKey，系统自动组装 Endpoint
### 腾讯云 COS
1. 登录[腾讯云控制台](https://console.cloud.tencent.com/cos)，创建存储桶
2. 前往 API 密钥管理创建 SecretId/SecretKey
3. Bucket 名称格式为 `BucketName-APPID`（如 `backup-1250000000`）
### 七牛云 Kodo
1. 登录[七牛云控制台](https://portal.qiniu.com/)，创建存储空间
2. 支持区域：`z0`(华东) / `cn-east-2`(华东-浙江2) / `z1`(华北) / `z2`(华南) / `na0`(北美) / `as0`(东南亚)
### Google Drive
1. 前往 [Google Cloud Console](https://console.cloud.google.com/) 创建项目
2. 启用 **Google Drive API**
3. 创建 **OAuth 2.0 客户端 ID**（Web 应用类型）
4. 添加重定向 URI：`http://your-server/api/storage-targets/google-drive/callback`
5. 在 BackupX 存储管理页面填入 Client ID / Secret，点击授权
| 组件 | 技术 |
|------|------|
| **后端** | Go · Gin · GORM · SQLite · robfig/cron |
| **前端** | React 18 · TypeScript · ArcoDesign · Vite · Zustand · ECharts |
| **存储** | AWS SDK v2 · Google Drive API v3 · gowebdav · jlaffaye/ftp |
| **安全** | JWT · bcrypt · AES-256-GCM |
## Contributing
欢迎提交 Issue 和 Pull Request！
1. Fork 本项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request
## License
本项目采用 [Apache License 2.0](LICENSE) 开源协议。
---
<p align="center">
Made with ❤️ for self-hosters
</p>
[Apache License 2.0](LICENSE)

733
README_EN.md
View File

@@ -2,485 +2,196 @@
<strong>English</strong> | <a href="README.md">中文</a>
</p>
<p align="center">
<h1 align="center">🛡️ BackupX</h1>
<h1 align="center">BackupX</h1>
<p align="center">
<strong>Self-hosted Server Backup Management Platform with Web UI</strong>
</p>
<p align="center">
<a href="#features">Features</a> •
<a href="#quick-start">Quick Start</a> •
<a href="#configuration">Configuration</a> •
<a href="#architecture">Architecture</a> •
<a href="#cluster-mode">Cluster</a> •
<a href="#development">Development</a> •
<a href="#api-reference">API</a>
<strong>Self-hosted Server Backup Management Platform</strong><br>
One binary, one command — manage all your server backups.
</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.21+-00ADD8?style=flat-square&logo=go" alt="Go">
<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/TypeScript-5-3178C6?style=flat-square&logo=typescript" alt="TypeScript">
<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>
<a href="https://github.com/Awuqing/BackupX/issues"><img src="https://img.shields.io/github/issues/Awuqing/BackupX?style=flat-square" alt="Issues"></a>
</p>
</p>
---
BackupX is a self-hosted backup management platform for **Linux / macOS servers**. Through an enterprise-grade Web console, you can easily configure directory backups, database backups, and securely store backup files to Alibaba Cloud OSS, Tencent Cloud COS, Qiniu Cloud Kodo, Google Drive, S3-compatible storage, WebDAV, FTP/FTPS, or local disk.
<table>
<tr>
<td width="50%"><img src="screenshots/dashboard.png" alt="Dashboard"></td>
<td width="50%"><img src="screenshots/backup-tasks.png" alt="Backup Tasks"></td>
</tr>
<tr>
<td><img src="screenshots/storage-targets.png" alt="Storage Targets"></td>
<td><img src="screenshots/backup-records.png" alt="Backup Records"></td>
</tr>
</table>
Supports **multi-node cluster management** for unified control of backup tasks across different servers.
## Highlights
> **For**: Individual developers / small teams / DevOps with Linux servers
| Capability | Details |
|-----------|---------|
| **Backup Types** | Files/Directories (multi-source), MySQL, PostgreSQL, SQLite, SAP HANA |
| **Storage Backends** | Alibaba Cloud OSS, Tencent COS, Qiniu Kodo, S3-compatible (AWS/MinIO/R2), Google Drive, WebDAV, FTP/FTPS, Local Disk |
| **Scheduling** | Cron-based scheduling + visual editor + auto-retention policy (by days/count) |
| **Multi-Node** | Master-Agent cluster for managing backups across multiple servers |
| **Security** | JWT + bcrypt + AES-256-GCM encrypted config + optional backup encryption + audit logs |
| **Notifications** | Email / Webhook / Telegram — push on success or failure |
| **Deployment** | Single binary + embedded SQLite, Docker one-click, zero external dependencies |
## Screenshots
### Login
![Login](screenshots/login.png)
### Dashboard
![Dashboard](screenshots/dashboard.png)
### Backup Tasks
![Backup Tasks](screenshots/backup-tasks.png)
### Backup Records
![Backup Records](screenshots/backup-records.png)
### Storage Targets
![Storage Targets](screenshots/storage-targets.png)
### Node Management
![Node Management](screenshots/nodes.png)
### Notification Settings
![Notification Settings](screenshots/notifications.png)
### System Settings
![System Settings](screenshots/settings.png)
## Features
### 📦 Multiple Backup Types
- **Files / Directories** — Multi-source path backup, custom exclude rules (e.g. `node_modules`, `*.log`)
- **MySQL** — Via native `mysqldump` tool
- **SQLite** — Safe file copy
- **PostgreSQL** — Via native `pg_dump` tool
- **SAP HANA** — Via native `hdbsql` tool (multi-tenant database support)
### ☁️ Multi-Cloud Storage Backends
| Provider | Type | Description |
|----------|------|-------------|
| 🇨🇳 **Alibaba Cloud OSS** | `aliyun_oss` | Auto endpoint assembly, internal network support |
| 🇨🇳 **Tencent Cloud COS** | `tencent_cos` | Auto endpoint assembly |
| 🇨🇳 **Qiniu Cloud Kodo** | `qiniu_kodo` | 6 region precise mapping |
| 🌍 **S3 Compatible** | `s3` | AWS S3 / MinIO / Cloudflare R2, etc. |
| 🌍 **Google Drive** | `google_drive` | Full OAuth 2.0 flow |
| 🌍 **WebDAV** | `webdav` | Nextcloud / Nutstore, etc. |
| 🌍 **FTP / FTPS** | `ftp` | Standard FTP protocol with Explicit TLS support |
| 💾 **Local Disk** | `local_disk` | Backup to local server directory |
> Chinese cloud providers only require **Region** and **AccessKey** — the system auto-assembles the endpoint. Powered by the S3 engine under the hood with zero extra dependencies.
### 🖥️ Cluster Management (Master-Agent)
- **Node Management** — Register remote server nodes with Token authentication
- **Local Node** — Auto-created, zero-friction upgrade for single-machine users
- **Directory Browser** — Visual file tree selector for backup source paths
- **Agent Heartbeat** — Real-time node online status monitoring
- **Task Tags** — Categorize and manage backup tasks by tags/nodes
### ⏰ Automation & Scheduling
- Cron expression scheduling
- Visual Cron editor
- Auto-retention policy (by days / by count)
- Max concurrent backup limit
### 🔐 Security
- JWT authentication + bcrypt password hashing
- AES-256-GCM encrypted sensitive config storage (DB passwords, OAuth tokens)
- Optional backup file encryption
- Login rate limiting (brute force protection)
- Node Token authentication (one-time display, secure transport)
- CLI password reset (Docker users can run `docker exec` — no email recovery needed)
### 📊 Monitoring & Notifications
- Dashboard stats (success rate, storage usage, backup trend charts)
- Email / Webhook / Telegram notifications
- Real-time backup execution logs (SSE)
- **Audit Logs** — Full operation traceability, records login, task CRUD, backup execution/restore and other key events
### 🌐 Other
- Chinese & English i18n
- Zero external dependencies (embedded SQLite, single binary deployment)
- Docker / Docker Compose one-click deployment
- systemd service support
---
## Quick Start
### Docker Deployment (Recommended)
### 1. Install
**Docker (recommended):**
```bash
# Clone the project
git clone https://github.com/Awuqing/BackupX.git
cd BackupX
# Start with one command
git clone https://github.com/Awuqing/BackupX.git && cd BackupX
docker compose up -d
```
To back up host directories, mount them in `docker-compose.yml`:
**Pre-built binaries:**
Download from [Releases](https://github.com/Awuqing/BackupX/releases), extract and run:
```bash
tar xzf backupx-v*.tar.gz && cd backupx-*
sudo ./install.sh # Auto-configures systemd + Nginx
```
**Build from source (China mirror):**
```bash
git clone https://github.com/Awuqing/BackupX.git && cd BackupX
make docker-cn # Uses China mirrors (goproxy.cn / npmmirror / Aliyun apk)
```
### 2. Open the Console
Visit `http://your-server:8340` in your browser. First-time access guides you through admin account creation.
### 3. Add a Storage Target
Go to **Storage Targets** → **Add**, choose a storage type and enter credentials:
| Storage Type | Required Fields |
|-------------|----------------|
| Alibaba Cloud OSS | Region + AccessKey ID/Secret + Bucket |
| Tencent Cloud COS | Region + SecretId/SecretKey + Bucket (`name-appid`) |
| Qiniu Cloud Kodo | Region + AccessKey/SecretKey + Bucket |
| S3 Compatible | Endpoint + AccessKey + Bucket |
| Google Drive | Client ID/Secret → click Authorize for OAuth |
| WebDAV | Server URL + Username/Password |
| FTP | Host + Port + Username/Password |
| Local Disk | Target directory path |
Click **Test Connection** to verify.
### 4. Create a Backup Task
Go to **Backup Tasks** → **Create**, complete 3 steps:
1. **Basic Info** — Task name, backup type, Cron expression (leave empty for manual-only)
2. **Source Config** — File backup: select source paths (supports multiple); Database: enter connection info
3. **Storage & Policy** — Select storage target(s), compression, retention days, encryption toggle
Save, then click **Run Now** to test. View real-time logs in **Backup Records**.
### 5. Set Up Notifications (Optional)
Go to **Notifications** to configure Email, Webhook, or Telegram alerts for backup success/failure.
---
## Deployment Guide
### Docker
```bash
docker compose up -d
```
Mount host directories for file backup:
```yaml
# docker-compose.yml
volumes:
- backupx-data:/app/data
- /path/to/backup/source:/mnt/source:ro
- /var/www:/mnt/www:ro
- /etc/nginx:/mnt/nginx-conf:ro
```
### Build from Source
Override config via environment variables:
```bash
# Clone the project
git clone https://github.com/Awuqing/BackupX.git
cd BackupX
# Build frontend and backend
make build
# Start the backend service (default port :8340)
cd server && ./bin/backupx
```
### China Mirror Build
If downloading dependencies is slow due to network restrictions, use China mirror acceleration:
```bash
# Option 1: Docker build (recommended, one command)
make docker-cn
# Option 2: Set mirrors manually, then build
export GOPROXY=https://goproxy.cn,direct
npm config set registry https://registry.npmmirror.com
make build
```
### Access Web UI
Open `http://your-server:8340` in your browser. First-time use will guide you through creating an admin account.
## Configuration
The config file defaults to `./config.yaml`. Settings can also be overridden via `BACKUPX_` prefixed environment variables.
```yaml
# config.yaml
server:
host: "0.0.0.0"
port: 8340
mode: "release" # debug | release
database:
path: "./data/backupx.db" # SQLite database path
security:
jwt_secret: "" # Leave empty to auto-generate
jwt_expire: "24h"
encryption_key: "" # AES encryption key, auto-generated if empty
backup:
temp_dir: "/tmp/backupx" # Backup temp directory
max_concurrent: 2 # Max concurrent backups
log:
level: "info" # debug | info | warn | error
file: "./data/backupx.log"
max_size: 100 # Max log file size (MB)
max_backups: 3 # Number of old log files to retain
max_age: 30 # Log retention days
```
> 💡 `jwt_secret` and `encryption_key` are auto-generated on first startup and persisted to the database.
## Architecture
```
┌─────────────────────┐
│ Nginx (Reverse │
│ Proxy) │
│ / → Static Files │
│ /api → :8340 │
└─────────┬───────────┘
│
▼
┌──────────────────────────────────────────────────────┐
│ BackupX Master (Go API Server) │
│ :8340 │
│ │
│ ┌──────┐ ┌────────────┐ ┌───────────────────────┐│
│ │ Auth │ │Backup Engine│ │ Storage Registry ││
│ └──────┘ └──────┬─────┘ │ ┌─────────────────┐ ││
│ │ │ │ Alibaba Cloud │ ││
│ ┌──────────┐ │ │ │ Tencent Cloud │ ││
│ │ Cron │◄───┘ │ │ Qiniu Cloud │ ││
│ │Scheduler │ │ │ S3 Compatible │ ││
│ └──────────┘ │ │ Google Drive │ ││
│ │ │ WebDAV │ ││
│ │ │ FTP / FTPS │ ││
│ ┌──────────┐ │ │ Local Disk │ ││
│ │ Notify │ │ └─────────────────┘ ││
│ │ Module │ └───────────────────────┘│
│ └──────────┘ │
│ │
│ ┌──────────────┐ ┌────────────────────┐ │
│ │ Node Manager │ │ SQLite (backupx.db)│ │
│ └──────┬───────┘ └────────────────────┘ │
└─────────┼────────────────────────────────────────────┘
│ Heartbeat / Task Dispatch
▼
┌──────────────────┐ ┌──────────────────┐
│ Agent Node A │ │ Agent Node B │
│ (Remote Server)│ │ (Remote Server)│
└──────────────────┘ └──────────────────┘
```
### Tech Stack
| Component | Technology |
|-----------|-----------|
| **Backend** | Go · Gin · GORM · SQLite · robfig/cron |
| **Frontend** | React 18 · TypeScript · ArcoDesign · Vite · Zustand · ECharts |
| **Storage** | AWS SDK v2 (S3/OSS/COS/Kodo) · Google Drive API v3 · gowebdav · jlaffaye/ftp |
| **Security** | JWT · bcrypt · AES-256-GCM |
| **Logging** | zap + lumberjack (auto-rotation) |
## Cluster Mode
BackupX supports **Master-Agent** mode for managing backup tasks across multiple servers.
### How It Works
1. **Master** is the server running the BackupX Web console
2. **Agent** is deployed on remote servers that need to be backed up
3. Agents register with the Master using a Token and send periodic heartbeats
4. Master dispatches backup tasks to the corresponding Agent for execution
### Adding Nodes
```bash
# In Web Console → Node Management → Add Node
# The system generates a unique 64-character hex Token
# Configure the Agent on the remote server
./backupx-agent --master http://master-server:8340 --token <your-token>
```
### Directory Probe API
Master provides `GET /api/nodes/:id/fs/list?path=/` to remotely browse a node's file system. The frontend uses a tree selector to browse the target machine's directory structure when creating backup tasks.
## Project Structure
```
BackupX/
├── server/ # Go backend
│ ├── cmd/backupx/ # Entry point
│ ├── internal/
│ │ ├── app/ # App assembly (DI)
│ │ ├── apperror/ # Unified error types
│ │ ├── backup/ # Backup engine (file/mysql/sqlite/pgsql/saphana)
│ │ │ └── retention/ # Retention policy
│ │ ├── config/ # Config loading (viper)
│ │ ├── database/ # Database init + migrations
│ │ ├── http/ # HTTP handlers + routes + middleware
│ │ ├── httpapi/ # HTTP API helpers
│ │ ├── logger/ # Logger init (zap + lumberjack)
│ │ ├── model/ # GORM data models
│ │ ├── notify/ # Notifications (email/webhook/telegram)
│ │ ├── repository/ # Data access layer
│ │ ├── scheduler/ # Cron scheduler
│ │ ├── security/ # JWT + rate limiting
│ │ ├── service/ # Business logic
│ │ └── storage/ # Storage backends (plugin interface)
│ │ ├── aliyun/ # Alibaba Cloud OSS
│ │ ├── tencent/ # Tencent Cloud COS
│ │ ├── qiniu/ # Qiniu Cloud Kodo
│ │ ├── s3/ # S3 Compatible core
│ │ ├── s3provider/ # S3 Provider helper
│ │ ├── googledrive/ # Google Drive
│ │ ├── webdav/ # WebDAV core
│ │ ├── webdavprovider/ # WebDAV Provider helper
│ │ ├── localdisk/ # Local disk
│ │ ├── ftp/ # FTP / FTPS
│ │ └── codec/ # Config codec
│ └── pkg/ # Utilities (compress/crypto/response)
├── web/ # React frontend
│ └── src/
│ ├── components/ # Shared components (CronEditor/FormDrawer/...)
│ ├── hooks/ # Custom Hooks
│ ├── layouts/ # Layout components (AppLayout)
│ ├── pages/ # Page modules
│ │ ├── dashboard/ # Dashboard
│ │ ├── backup-tasks/ # Backup tasks
│ │ ├── backup-records/ # Backup records
│ │ ├── storage-targets/ # Storage targets
│ │ ├── nodes/ # Node management
│ │ ├── notifications/ # Notification settings
│ │ ├── audit/ # Audit logs
│ │ ├── settings/ # System settings
│ │ └── login/ # Login page
│ ├── services/ # API request wrappers
│ ├── stores/ # Zustand state management
│ ├── styles/ # Global styles
│ ├── types/ # TypeScript type definitions
│ ├── utils/ # Utility functions
│ ├── locales/ # i18n language packs (zh-CN / en-US)
│ └── router/ # Route configuration
├── deploy/ # Deployment configs
│ ├── nginx.conf # Nginx reference config
│ ├── backupx.service # systemd service unit
│ ├── install.sh # One-click install script
│ └── docker/ # Docker deployment configs
│ ├── nginx.conf # In-container Nginx config
│ └── entrypoint.sh # Container entrypoint script
├── .github/ # GitHub configuration
│ ├── workflows/ci.yml # CI workflow
│ ├── workflows/release.yml # Release workflow
│ └── ISSUE_TEMPLATE/ # Issue templates
├── Dockerfile # Docker multi-stage build
├── docker-compose.yml # Docker Compose config
└── Makefile # Build commands
```
## Development
### Prerequisites
- **Go** ≥ 1.21
- **Node.js** ≥ 18
- **npm**
### Dev Mode
```bash
# Terminal 1: Start backend (use air for hot-reload)
make dev-server
# Terminal 2: Start frontend (Vite HMR)
make dev-web
```
### Run Tests
```bash
# Run all tests
make test
# Backend only
make test-server # go test ./...
# Frontend only
make test-web # npm run test
```
### Build
```bash
# Build frontend and backend
make build
# Docker build
make docker
# Docker build with China mirrors
make docker-cn
# Clean build artifacts
make clean
```
### Release
Push a Git tag to automatically trigger the full release pipeline via GitHub Actions:
```bash
git tag v1.2.3
git push --tags
# GitHub Actions will: compile binaries → publish GitHub Release → push Docker Hub image
```
You can also manually trigger the Release workflow from the GitHub Actions page.
## Deployment
### One-Click Install (Recommended)
```bash
# Build first
make build
# Run install script as root
sudo ./deploy/install.sh
```
The install script will automatically:
1. Create a `backupx` system user
2. Install the binary to `/opt/backupx/bin/`
3. Deploy the frontend to `/opt/backupx/web/`
4. Generate config at `/etc/backupx/config.yaml`
5. Register and start the systemd service
6. Configure Nginx reverse proxy (if installed)
### Docker Deployment
```bash
# Using docker compose
docker compose up -d
# Or build and run manually
docker build -t backupx .
docker run -d --name backupx -p 8340:8340 -v backupx-data:/app/data backupx
```
**Password Reset** (when you forget the admin password):
```bash
docker exec -it backupx /app/bin/backupx reset-password --username admin --password newpass123
```
Override configuration via environment variables:
```bash
docker run -d --name backupx \
-p 8340:8340 \
docker run -d --name backupx -p 8340:8340 \
-v backupx-data:/app/data \
-e TZ=Asia/Shanghai \
-e BACKUPX_LOG_LEVEL=debug \
-e BACKUPX_BACKUP_MAX_CONCURRENT=4 \
backupx
```
### Manual Deployment
### Bare Metal
```bash
# 1. Build
cd server && go build -o backupx ./cmd/backupx
cd ../web && npm run build
# From pre-built package
tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
sudo ./install.sh
# 2. Deploy files
scp server/backupx your-server:/opt/backupx/bin/
scp -r web/dist/ your-server:/opt/backupx/web/
scp server/config.example.yaml your-server:/etc/backupx/config.yaml
# Or from source
make build
sudo ./deploy/install.sh
```
# 3. Start
ssh your-server '/opt/backupx/bin/backupx -config /etc/backupx/config.yaml'
The install script creates a system user, installs to `/opt/backupx/`, configures systemd, and sets up Nginx reverse proxy.
### Nginx Reverse Proxy (bare metal)
```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;
}
}
```
### Configuration
Config file: `./config.yaml` (or override with `BACKUPX_` prefixed env vars):
```yaml
server:
port: 8340
database:
path: "./data/backupx.db"
security:
jwt_secret: "" # Auto-generated and persisted to DB
encryption_key: "" # Auto-generated
backup:
temp_dir: "/tmp/backupx"
max_concurrent: 2
log:
level: "info" # debug | info | warn | error
file: "./data/backupx.log"
```
### Password Reset
When you forget the admin password, reset it via CLI (requires server shell access):
```bash
# Bare metal
./backupx reset-password --username admin --password newpass123
@@ -489,112 +200,90 @@ When you forget the admin password, reset it via CLI (requires server shell acce
docker exec -it backupx /app/bin/backupx reset-password --username admin --password newpass123
```
### Nginx Config Example
---
```nginx
server {
listen 80;
server_name backup.example.com;
## Multi-Node Cluster
# Frontend static files
location / {
root /opt/backupx/web;
try_files $uri $uri/ /index.html;
}
BackupX supports Master-Agent mode for managing multiple servers:
# API reverse proxy
location /api/ {
proxy_pass http://127.0.0.1:8340;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
1. Web Console → **Node Management** → **Add Node** — system generates a Token
2. Deploy Agent on remote server, connect using the Token
3. Create backup tasks and assign to specific nodes — Master dispatches automatically
The visual directory browser lets you pick directories on remote Agent nodes — no manual path typing.
---
## Development
**Requirements:** Go >= 1.25 · Node.js >= 20 · npm
```bash
# Dev mode
make dev-server # Terminal 1: backend (:8340)
make dev-web # Terminal 2: frontend (Vite HMR)
# Test
make test # Run all tests
# Build
make build # Build frontend + backend
make docker # Docker build
make docker-cn # Docker build with China mirrors
```
### Release
```bash
git tag v1.2.3 && git push --tags
# GitHub Actions: compile dual-arch binaries → publish GitHub Release → push Docker Hub image
```
Or manually trigger the Release workflow from GitHub Actions page.
---
## API Reference
All APIs are prefixed with `/api` and use JWT Bearer Token authentication (unless noted otherwise).
All endpoints prefixed with `/api`, authenticated via JWT Bearer Token.
| Module | Endpoint | Description |
|--------|----------|-------------|
| **Auth** | `POST /api/auth/setup` | Initialize admin (first time) |
| | `POST /api/auth/login` | Login to get Token |
| | `POST /api/auth/logout` | Logout |
| | `GET /api/auth/profile` | Current user info |
| | `PUT /api/auth/password` | Change password |
| **Backup Tasks** | `GET/POST /api/backup/tasks` | List / Create tasks |
| | `GET/PUT/DELETE /api/backup/tasks/:id` | Detail / Update / Delete |
| | `PUT /api/backup/tasks/:id/toggle` | Enable / Disable |
| | `POST /api/backup/tasks/:id/run` | Trigger manual execution |
| **Backup Records** | `GET /api/backup/records` | List records (with filter) |
| | `GET /api/backup/records/:id` | Record detail |
| | `GET /api/backup/records/:id/logs/stream` | Real-time execution logs (SSE) |
| | `GET /api/backup/records/:id/download` | Download backup file |
| | `POST /api/backup/records/:id/restore` | Restore backup |
| **Storage Targets** | `GET/POST /api/storage-targets` | List / Add targets |
| | `GET/PUT/DELETE /api/storage-targets/:id` | Detail / Update / Delete |
| | `POST /api/storage-targets/test` | Test connection |
| | `POST /api/storage-targets/:id/test` | Test saved connection |
| | `GET /api/storage-targets/:id/usage` | Query usage |
| **Nodes** | `GET/POST /api/nodes` | List / Add nodes |
| | `GET/DELETE /api/nodes/:id` | Detail / Delete |
| | `GET /api/nodes/:id/fs/list` | Directory browser |
| | `POST /api/agent/heartbeat` | Agent heartbeat ⚡ |
| **Notifications** | `GET/POST /api/notifications` | List / Add |
| | `POST /api/notifications/test` | Test notification |
| | `POST /api/notifications/:id/test` | Test saved notification |
| **Dashboard** | `GET /api/dashboard/stats` | Overview statistics |
| | `GET /api/dashboard/timeline` | Backup trend timeline |
| **Audit Logs** | `GET /api/audit-logs` | Audit log list (with category filter/pagination) |
| **System** | `GET /api/system/info` | System info (version/disk) |
| | `GET/PUT /api/settings` | System settings |
| **Auth** | `POST /auth/setup` | Initialize admin |
| | `POST /auth/login` | Login |
| | `PUT /auth/password` | Change password |
| **Backup Tasks** | `GET\|POST /backup/tasks` | List / Create |
| | `GET\|PUT\|DELETE /backup/tasks/:id` | Detail / Update / Delete |
| | `PUT /backup/tasks/:id/toggle` | Enable / Disable |
| | `POST /backup/tasks/:id/run` | Manual run |
| **Backup Records** | `GET /backup/records` | List (with filter) |
| | `GET /backup/records/:id/logs/stream` | Real-time logs (SSE) |
| | `GET /backup/records/:id/download` | Download |
| | `POST /backup/records/:id/restore` | Restore |
| **Storage Targets** | `GET\|POST /storage-targets` | List / Add |
| | `POST /storage-targets/test` | Test connection |
| **Nodes** | `GET\|POST /nodes` | List / Add |
| | `GET /nodes/:id/fs/list` | Directory browser |
| **Notifications** | `GET\|POST /notifications` | List / Add |
| **Dashboard** | `GET /dashboard/stats` | Overview stats |
| **Audit Logs** | `GET /audit-logs` | Operation audit |
| **System** | `GET /system/info` | System info |
> ⚡ `POST /api/agent/heartbeat` is a public endpoint authenticated via Node Token instead of JWT.
---
## Cloud Storage Setup Guide
## Tech Stack
### Alibaba Cloud OSS
1. Log in to [Alibaba Cloud Console](https://oss.console.aliyun.com/), create a Bucket
2. Go to RAM Console to create an AccessKey
3. Select "Alibaba Cloud OSS" when adding a storage target in BackupX
4. Enter the Region (e.g. `cn-hangzhou`) and AccessKey — the system auto-assembles the endpoint
### Tencent Cloud COS
1. Log in to [Tencent Cloud Console](https://console.cloud.tencent.com/cos), create a bucket
2. Go to API Key Management to create SecretId/SecretKey
3. Bucket name format is `BucketName-APPID` (e.g. `backup-1250000000`)
### Qiniu Cloud Kodo
1. Log in to [Qiniu Cloud Console](https://portal.qiniu.com/), create a storage space
2. Supported regions: `z0` (East China) / `cn-east-2` (East China-Zhejiang 2) / `z1` (North China) / `z2` (South China) / `na0` (North America) / `as0` (Southeast Asia)
### Google Drive
1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create a project
2. Enable the **Google Drive API**
3. Create an **OAuth 2.0 Client ID** (Web application type)
4. Add redirect URI: `http://your-server/api/storage-targets/google-drive/callback`
5. Enter the Client ID / Secret in BackupX storage management and click Authorize
| Component | Technology |
|-----------|-----------|
| **Backend** | Go · Gin · GORM · SQLite · robfig/cron |
| **Frontend** | React 18 · TypeScript · ArcoDesign · Vite · Zustand · ECharts |
| **Storage** | AWS SDK v2 · Google Drive API v3 · gowebdav · jlaffaye/ftp |
| **Security** | JWT · bcrypt · AES-256-GCM |
## Contributing
Issues and Pull Requests are welcome!
1. Fork this repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the [Apache License 2.0](LICENSE).
---
<p align="center">
Made with ❤️ for self-hosters
</p>
[Apache License 2.0](LICENSE)