English | δΈζ
π‘οΈ BackupX
Self-hosted Server Backup Management Platform with Web UI
Features β’
Quick Start β’
Configuration β’
Architecture β’
Cluster β’
Development β’
API
---
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, or local disk.
Supports **multi-node cluster management** for unified control of backup tasks across different servers.
> **For**: Individual developers / small teams / DevOps with Linux servers
## Screenshots
### Login
### Dashboard
### Backup Tasks
### Backup Records
### Storage Targets
### Node Management
### Notification Settings
### System Settings
## Features
### π¦ Multiple Backup Types
- **Files / Directories** β Custom exclude rules (e.g. `node_modules`, `*.log`)
- **MySQL** β Via native `mysqldump` tool
- **SQLite** β Safe file copy
- **PostgreSQL** β Via native `pg_dump` tool
### βοΈ 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. |
| πΎ **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)
### π Monitoring & Notifications
- Dashboard stats (success rate, storage usage, backup trend charts)
- Email / Webhook / Telegram notifications
- Real-time backup execution logs (SSE)
### π Other
- Chinese & English i18n
- Zero external dependencies (embedded SQLite, single binary deployment)
- systemd service support
## Quick Start
### Build from Source
```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
```
### 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 β ββ
β ββββββββββββ β β 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 |
| **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
```
### 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)
β β β βββ 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
β β βββ 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
β β βββ 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
βββ .github/ # GitHub configuration
β βββ workflows/ci.yml # CI workflow
β βββ workflows/release.yml # Release workflow
β βββ ISSUE_TEMPLATE/ # Issue templates
βββ 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
# Clean build artifacts
make clean
```
## 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)
### Manual Deployment
```bash
# 1. Build
cd server && go build -o backupx ./cmd/backupx
cd ../web && npm run build
# 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
# 3. Start
ssh your-server '/opt/backupx/bin/backupx -config /etc/backupx/config.yaml'
```
### Nginx Config Example
```nginx
server {
listen 80;
server_name backup.example.com;
# Frontend static files
location / {
root /opt/backupx/web;
try_files $uri $uri/ /index.html;
}
# 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;
}
}
```
## API Reference
All APIs are prefixed with `/api` and use JWT Bearer Token authentication (unless noted otherwise).
| 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 |
| **System** | `GET /api/system/info` | System info (version/disk) |
| | `GET/PUT /api/settings` | System settings |
> β‘ `POST /api/agent/heartbeat` is a public endpoint authenticated via Node Token instead of JWT.
## Cloud Storage Setup Guide
### 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
## 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).
---
Made with β€οΈ for self-hosters