English | 中文

BackupX

Self-hosted Server Backup Management Platform
One binary, one command — manage all your server backups.

---

Highlights

Capability	Details
Backup Types	Files/Directories (multi-source), MySQL, PostgreSQL, SQLite, SAP HANA
70+ Storage Backends	Built-in Alibaba OSS / Tencent COS / Qiniu / S3 / Google Drive / WebDAV / FTP + 70+ backends via rclone (SFTP, Azure Blob, Dropbox, OneDrive, etc.)
Scheduling	Cron-based + visual editor + auto-retention policy (by days/count, auto empty directory cleanup)
Multi-Node	Master-Agent cluster for managing backups across multiple servers with remote directory browsing and node editing
Security	JWT + bcrypt + AES-256-GCM encrypted config + optional backup encryption + comprehensive audit logs
Notifications	Email / Webhook / Telegram — push on success or failure
Deployment	Single binary + embedded SQLite, Docker one-click, zero external dependencies

---

Quick Start

1. Install

Docker (recommended, no clone needed):

# Create a docker-compose.yml then start
docker compose up -d

# Or run directly
docker run -d --name backupx -p 8340:8340 -v backupx-data:/app/data awuqing/backupx:latest

Docker Hub: awuqing/backupx — supports linux/amd64 and linux/arm64.

docker-compose.yml reference

services:
  backupx:
    image: awuqing/backupx:latest
    container_name: backupx
    restart: unless-stopped
    ports:
      - "8340:8340"
    volumes:
      - backupx-data:/app/data
      # Mount host directories to back up (add as needed):
      # - /var/www:/mnt/www:ro
      # - /etc/nginx:/mnt/nginx-conf:ro
    environment:
      - TZ=Asia/Shanghai

volumes:
  backupx-data:

Pre-built binaries (bare metal):

Download from Releases:

tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
sudo ./install.sh        # Auto-configures systemd + Nginx

Build from source:

git clone https://github.com/Awuqing/BackupX.git && cd BackupX
make build               # Build frontend + backend
make docker-cn           # Or Docker build with 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
SFTP / Azure / Dropbox / OneDrive etc.	Select the type, fill in required fields; advanced options are collapsible

For Chinese cloud providers, just enter Region and AccessKey — the system auto-assembles the Endpoint. Rclone-type configs separate required fields from optional advanced options (collapsed by default).

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) (supports multiple), compression, retention days, encryption toggle

Save, then click Run Now to test. View real-time logs in Backup Records.

Deleting a backup task automatically cleans up remote storage files while preserving backup records for audit purposes.

5. Set Up Notifications (Optional)

Go to Notifications to configure Email, Webhook, or Telegram alerts for backup success/failure.

---

Deployment Guide

Docker

docker compose up -d     # Using the docker-compose.yml above

Mount host directories for file backup (add to volumes in docker-compose.yml):

volumes:
  - backupx-data:/app/data
  - /var/www:/mnt/www:ro
  - /etc/nginx:/mnt/nginx-conf:ro

Override config via environment variables:

environment:
  - TZ=Asia/Shanghai
  - BACKUPX_LOG_LEVEL=debug
  - BACKUPX_BACKUP_MAX_CONCURRENT=4

To upgrade: go to System Settings, click "Check for Updates" to see if a new version is available, then run docker compose pull && docker compose up -d.

Bare Metal

# From pre-built package
tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
sudo ./install.sh

# Or from source
make build
sudo ./deploy/install.sh

The install script creates a system user, installs to /opt/backupx/, configures systemd, and sets up Nginx reverse proxy.

Nginx Reverse Proxy (bare metal)

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):

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

# Bare metal
./backupx reset-password --username admin --password newpass123

# Docker
docker exec -it backupx /app/bin/backupx reset-password --username admin --password newpass123

---

Multi-Node Cluster

BackupX supports Master-Agent mode for managing multiple servers:

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

• Local node auto-detects IP address and version
• Remote nodes report system info via Agent heartbeat (hostname, IP, OS, architecture, version)
• Node names can be edited directly from the console
• Visual directory browser lets you pick directories on remote Agent nodes

---

Development

Requirements: Go >= 1.25 · Node.js >= 20 · npm

# 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

git tag v1.4.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 endpoints prefixed with /api, authenticated via JWT Bearer Token.

Module	Endpoint	Description
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
	GET /storage-targets/rclone/backends	Rclone backend list
Nodes	GET|POST /nodes	List / Add
	PUT /nodes/:id	Edit node
	GET /nodes/:id/fs/list	Directory browser
	POST /agent/heartbeat	Agent heartbeat (Token auth)
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
	GET /system/update-check	Check for updates

---

Tech Stack

Component	Technology
Backend	Go · Gin · GORM · SQLite · robfig/cron · rclone
Frontend	React 18 · TypeScript · ArcoDesign · Vite · Zustand · ECharts
Storage	rclone (70+ backends) · AWS SDK v2 · Google Drive API v3
Security	JWT · bcrypt · AES-256-GCM

Contributing

Issues and Pull Requests are welcome!

License

Apache License 2.0