mirror of
https://github.com/Awuqing/BackupX.git
synced 2026-05-30 09:59:34 +08:00
文档: 新增 Docusaurus 官网与双语文档，README 切换为英文默认 (#39)
- 新建 docs-site/ Docusaurus 项目，支持 en + zh-Hans 双语 - 从 README 迁移内容为独立文档页面： - Getting Started（安装、快速开始） - Deployment（Docker、裸机、Nginx、配置参考） - Features（备份类型、存储后端、SAP HANA、多节点集群、通知） - Reference（API、CLI） - Development（开发、贡献） - 自定义 BackupX 主题色、logo、落地页组件 - 新增 .github/workflows/docs.yml，Actions 自动构建并发布到 GitHub Pages - README.md 切换为英文，中文版挪到 README.zh-CN.md，两者均精简为导航型 - 配置站点 URL：https://awuqing.github.io/BackupX/
This commit is contained in:
Wu Qing
86
docs-site/docs/deployment/bare-metal.md
Normal file
86
docs-site/docs/deployment/bare-metal.md
Normal file
@@ -0,0 +1,86 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Bare-metal Deployment
|
||||
description: systemd + Nginx deployment from the prebuilt release tarball or source.
|
||||
---
|
||||
|
||||
# Bare-metal Deployment
|
||||
|
||||
## From prebuilt release
|
||||
|
||||
```bash
|
||||
# Download the matching tarball
|
||||
curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-v1.6.0-linux-amd64.tar.gz
|
||||
|
||||
# Extract and install
|
||||
tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
|
||||
sudo ./install.sh
|
||||
```
|
||||
|
||||
The installer performs these steps automatically:
|
||||
|
||||
1. Creates a system user `backupx`
|
||||
2. Copies the binary to `/opt/backupx/`
|
||||
3. Generates a default `config.yaml` with safe JWT/encryption secrets
|
||||
4. Installs `backupx.service` (systemd), enabled at boot
|
||||
5. (Optional) installs an Nginx site file — see [Nginx Reverse Proxy](./nginx)
|
||||
|
||||
## From source
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Awuqing/BackupX.git && cd BackupX
|
||||
make build
|
||||
sudo ./deploy/install.sh
|
||||
```
|
||||
|
||||
`make build` compiles:
|
||||
|
||||
- `server/bin/backupx` (Go backend, no CGO)
|
||||
- `web/dist/` (React frontend, `npm run build`)
|
||||
|
||||
## systemd
|
||||
|
||||
The installed unit:
|
||||
|
||||
```ini title="/etc/systemd/system/backupx.service"
|
||||
[Unit]
|
||||
Description=BackupX backup management service
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=backupx
|
||||
WorkingDirectory=/opt/backupx
|
||||
ExecStart=/opt/backupx/backupx --config /opt/backupx/config.yaml
|
||||
Restart=on-failure
|
||||
RestartSec=5s
|
||||
LimitNOFILE=65536
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Typical operations:
|
||||
|
||||
```bash
|
||||
sudo systemctl status backupx
|
||||
sudo journalctl -u backupx -f # live logs
|
||||
sudo systemctl restart backupx
|
||||
```
|
||||
|
||||
## Password reset
|
||||
|
||||
If the admin password is lost:
|
||||
|
||||
```bash
|
||||
/opt/backupx/backupx reset-password \
|
||||
--username admin \
|
||||
--password 'newpass123' \
|
||||
--config /opt/backupx/config.yaml
|
||||
```
|
||||
|
||||
Docker equivalent:
|
||||
|
||||
```bash
|
||||
docker exec -it backupx /app/bin/backupx reset-password --username admin --password 'newpass123'
|
||||
```
|
||||
52
docs-site/docs/deployment/configuration.md
Normal file
52
docs-site/docs/deployment/configuration.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: Configuration Reference
|
||||
description: All server.yaml configuration keys with defaults and matching environment variables.
|
||||
---
|
||||
|
||||
# Configuration Reference
|
||||
|
||||
BackupX loads `./config.yaml` from the working directory by default. You can override the path with `--config`. Every key can also be set via a `BACKUPX_` prefixed environment variable.
|
||||
|
||||
## Full config reference
|
||||
|
||||
```yaml title="config.yaml"
|
||||
server:
|
||||
host: "0.0.0.0" # BACKUPX_SERVER_HOST
|
||||
port: 8340 # BACKUPX_SERVER_PORT
|
||||
mode: "release" # release | debug
|
||||
|
||||
database:
|
||||
path: "./data/backupx.db" # BACKUPX_DATABASE_PATH — embedded SQLite
|
||||
|
||||
security:
|
||||
jwt_secret: "" # BACKUPX_SECURITY_JWT_SECRET — auto-generated if empty
|
||||
jwt_expires_in: "24h"
|
||||
encryption_key: "" # AES-256-GCM key for storage config encryption
|
||||
|
||||
backup:
|
||||
temp_dir: "/tmp/backupx" # BACKUPX_BACKUP_TEMP_DIR
|
||||
max_concurrent: 2 # BACKUPX_BACKUP_MAX_CONCURRENT
|
||||
retries: 3 # Per-upload rclone low-level retries
|
||||
bandwidth_limit: "" # e.g. "10M" to cap transfers at 10 MB/s
|
||||
|
||||
log:
|
||||
level: "info" # debug | info | warn | error
|
||||
file: "./data/backupx.log"
|
||||
```
|
||||
|
||||
## Secret generation
|
||||
|
||||
If `jwt_secret` or `encryption_key` is empty on first start, BackupX generates a random value and persists it to the `system_configs` table. Keep a backup of `data/backupx.db` — losing it invalidates all existing encrypted storage configurations.
|
||||
|
||||
## Environment variables
|
||||
|
||||
The environment wins when both file and env are set. All dot-paths become underscores and uppercase:
|
||||
|
||||
| Config key | Env variable |
|
||||
|------------|--------------|
|
||||
| `server.port` | `BACKUPX_SERVER_PORT` |
|
||||
| `log.level` | `BACKUPX_LOG_LEVEL` |
|
||||
| `backup.max_concurrent` | `BACKUPX_BACKUP_MAX_CONCURRENT` |
|
||||
| `backup.temp_dir` | `BACKUPX_BACKUP_TEMP_DIR` |
|
||||
| `backup.bandwidth_limit` | `BACKUPX_BACKUP_BANDWIDTH_LIMIT` |
|
||||
68
docs-site/docs/deployment/docker.md
Normal file
68
docs-site/docs/deployment/docker.md
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Docker Deployment
|
||||
description: Production-style Docker deployment with docker compose, mounted source directories, and environment overrides.
|
||||
---
|
||||
|
||||
# Docker Deployment
|
||||
|
||||
BackupX's official Docker image [`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx) supports multi-architecture (linux/amd64 + linux/arm64).
|
||||
|
||||
## Compose file
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
backupx:
|
||||
image: awuqing/backupx:latest
|
||||
container_name: backupx
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "8340:8340"
|
||||
volumes:
|
||||
- backupx-data:/app/data
|
||||
# Mount host directories you want to back up:
|
||||
- /var/www:/mnt/www:ro
|
||||
- /etc/nginx:/mnt/nginx-conf:ro
|
||||
environment:
|
||||
- TZ=Asia/Shanghai
|
||||
- BACKUPX_LOG_LEVEL=info
|
||||
- BACKUPX_BACKUP_MAX_CONCURRENT=2
|
||||
|
||||
volumes:
|
||||
backupx-data:
|
||||
```
|
||||
|
||||
Start with:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Host-directory backup
|
||||
|
||||
To back up files from the host, mount them into the container. When creating a file-type task in the web UI, point the source path at the mount location (e.g. `/mnt/www`). Make sure the directory is visible inside the container.
|
||||
|
||||
## Environment variables
|
||||
|
||||
All configuration keys can be overridden with the `BACKUPX_` prefix:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- TZ=Asia/Shanghai
|
||||
- BACKUPX_SERVER_PORT=8340
|
||||
- BACKUPX_LOG_LEVEL=debug
|
||||
- BACKUPX_BACKUP_MAX_CONCURRENT=4
|
||||
- BACKUPX_BACKUP_TEMP_DIR=/tmp/backupx
|
||||
```
|
||||
|
||||
See the [Configuration](./configuration) page for the full list.
|
||||
|
||||
## Upgrades
|
||||
|
||||
Check **System Settings → Check Updates** in the UI to see if a new version is available, then on the host:
|
||||
|
||||
```bash
|
||||
docker compose pull && docker compose up -d
|
||||
```
|
||||
|
||||
No migrations needed — BackupX auto-migrates the SQLite schema on startup.
|
||||
53
docs-site/docs/deployment/nginx.md
Normal file
53
docs-site/docs/deployment/nginx.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Nginx Reverse Proxy
|
||||
description: Expose BackupX behind Nginx with HTTPS and SSE-friendly buffering disabled.
|
||||
---
|
||||
|
||||
# Nginx Reverse Proxy
|
||||
|
||||
A minimal production-ready Nginx site for BackupX:
|
||||
|
||||
```nginx title="/etc/nginx/sites-available/backupx"
|
||||
server {
|
||||
listen 80;
|
||||
server_name backup.example.com;
|
||||
|
||||
# Static UI (served from /opt/backupx/web)
|
||||
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_http_version 1.1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
# Large uploads (restore flow)
|
||||
client_max_body_size 0;
|
||||
|
||||
# Live log stream uses SSE — buffering must be off
|
||||
proxy_buffering off;
|
||||
proxy_read_timeout 3600s;
|
||||
proxy_send_timeout 3600s;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## HTTPS with certbot
|
||||
|
||||
```bash
|
||||
sudo apt install certbot python3-certbot-nginx
|
||||
sudo certbot --nginx -d backup.example.com
|
||||
```
|
||||
|
||||
Certbot rewrites the config to listen on 443 with auto-renewal.
|
||||
|
||||
:::caution Agent needs a stable URL
|
||||
If Master is behind HTTPS, remote Agent deployments must use the public HTTPS URL for `--master`. Self-signed certs require `--insecure-tls` (testing only).
|
||||
:::
|
||||
41
docs-site/docs/development/contributing.md
Normal file
41
docs-site/docs/development/contributing.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Contributing
|
||||
description: How to report issues, propose changes, and submit PRs.
|
||||
---
|
||||
|
||||
# Contributing
|
||||
|
||||
BackupX is open-source under Apache License 2.0. Issues and pull requests are welcome.
|
||||
|
||||
## Reporting bugs
|
||||
|
||||
Open an issue at [github.com/Awuqing/BackupX/issues](https://github.com/Awuqing/BackupX/issues). Please include:
|
||||
|
||||
- BackupX version (`backupx --version`)
|
||||
- Your deployment mode (Docker / bare metal / from source)
|
||||
- Relevant backup task type and storage backend
|
||||
- Steps to reproduce
|
||||
- Stdout / `backupx.log` excerpt for the window around the problem
|
||||
|
||||
## Proposing changes
|
||||
|
||||
For significant features or refactors, open an issue first to align on scope before investing in a PR.
|
||||
|
||||
## Pull requests
|
||||
|
||||
1. Fork and create a topic branch (e.g. `fix/windows-path-escape`)
|
||||
2. Run `make test` and make sure everything passes
|
||||
3. Keep changes focused — one concern per PR
|
||||
4. Write commit messages in Chinese following `类型: 简要描述` — examples:
|
||||
- `功能: 新增审计日志模块`
|
||||
- `修复: 目录浏览器无法进入子目录`
|
||||
- `重构: 简化存储目标解密逻辑`
|
||||
- Types: `功能` / `修复` / `重构` / `文档` / `构建` / `测试`
|
||||
5. PR title and body in Chinese too. Describe the why and how, not just the what.
|
||||
|
||||
## Coding guidelines
|
||||
|
||||
- **Go** — handle every error (no `_ = err`); use the existing logger (`zap`); no `fmt.Println` in production paths
|
||||
- **TypeScript** — strict mode, no implicit any, follow existing ESLint/Prettier configs
|
||||
- **Commit scope** — one logical change per commit; don't mix drive-by cleanups with feature work
|
||||
83
docs-site/docs/development/setup.md
Normal file
83
docs-site/docs/development/setup.md
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Development Setup
|
||||
description: Get a BackupX dev environment running — backend, frontend, tests.
|
||||
---
|
||||
|
||||
# Development Setup
|
||||
|
||||
**Requirements:** Go ≥ 1.25, Node.js ≥ 20, npm.
|
||||
|
||||
## Clone & install
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Awuqing/BackupX.git && cd BackupX
|
||||
cd web && npm install && cd ..
|
||||
```
|
||||
|
||||
## Dev servers
|
||||
|
||||
Run the backend and the Vite dev server in two terminals:
|
||||
|
||||
```bash
|
||||
# Terminal 1: backend on :8340
|
||||
make dev-server
|
||||
|
||||
# Terminal 2: Vite with HMR on :5173
|
||||
make dev-web
|
||||
```
|
||||
|
||||
The Vite config proxies `/api` to `http://127.0.0.1:8340` so you can open the UI at `http://localhost:5173`.
|
||||
|
||||
## Tests
|
||||
|
||||
```bash
|
||||
make test # runs Go + Web test suites
|
||||
make test-server # Go only
|
||||
make test-web # Vitest only
|
||||
```
|
||||
|
||||
## Production build
|
||||
|
||||
```bash
|
||||
make build # server/bin/backupx + web/dist
|
||||
make docker # Docker image
|
||||
make docker-cn # Docker image with mainland China mirrors
|
||||
```
|
||||
|
||||
## Tech stack
|
||||
|
||||
| Component | Stack |
|
||||
|-----------|-------|
|
||||
| **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 |
|
||||
|
||||
## Project layout
|
||||
|
||||
```
|
||||
BackupX/
|
||||
├── server/ # Go backend
|
||||
│ ├── cmd/backupx/ # Entry point + subcommands (agent, backint, reset-password)
|
||||
│ ├── internal/
|
||||
│ │ ├── agent/ # Agent CLI logic
|
||||
│ │ ├── app/ # Wiring (repositories → services → handlers)
|
||||
│ │ ├── backup/ # Backup runners (file / mysql / postgres / sqlite / saphana)
|
||||
│ │ ├── backint/ # SAP HANA Backint protocol
|
||||
│ │ ├── http/ # HTTP handlers + router
|
||||
│ │ ├── model/ # GORM models
|
||||
│ │ ├── repository/ # DB access
|
||||
│ │ ├── service/ # Business logic
|
||||
│ │ └── storage/ # Storage providers (rclone + direct SDKs)
|
||||
│ └── pkg/ # Generic utilities
|
||||
├── web/ # React frontend (Vite)
|
||||
│ └── src/
|
||||
│ ├── components/
|
||||
│ ├── pages/
|
||||
│ ├── services/
|
||||
│ └── types/
|
||||
├── docs-site/ # This documentation site (Docusaurus)
|
||||
├── deploy/ # install.sh, systemd unit, nginx config
|
||||
└── Makefile
|
||||
```
|
||||
42
docs-site/docs/features/backup-types.md
Normal file
42
docs-site/docs/features/backup-types.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Backup Types
|
||||
description: File, MySQL, PostgreSQL, SQLite and SAP HANA — what they back up and what to configure.
|
||||
---
|
||||
|
||||
# Backup Types
|
||||
|
||||
BackupX supports five built-in backup types. Type determines which runner executes the job.
|
||||
|
||||
## File / Directory
|
||||
|
||||
Tars (and optionally gzips) one or more filesystem paths.
|
||||
|
||||
- **Source** accepts multiple paths — one per line in the UI
|
||||
- **Exclude patterns** accept gitignore-style globs
|
||||
- Supports following symlinks, preserving permissions
|
||||
- Output is a single `.tar` or `.tar.gz` artifact
|
||||
|
||||
## MySQL
|
||||
|
||||
Uses `mysqldump` under the hood. Requires `mysqldump` to be on `$PATH` of the host running the task (Master or Agent).
|
||||
|
||||
- **Host / port / user / password / database** — multi-database allowed (comma-separated)
|
||||
- Output: `.sql` or `.sql.gz`
|
||||
- Default flags: `--single-transaction --routines --triggers --events`
|
||||
|
||||
## PostgreSQL
|
||||
|
||||
Uses `pg_dump`. Same connection fields as MySQL plus database name.
|
||||
|
||||
## SQLite
|
||||
|
||||
Copies the database file directly (with a consistency snapshot). No external tool required.
|
||||
|
||||
## SAP HANA
|
||||
|
||||
Two modes are supported — see the dedicated [SAP HANA](./sap-hana) page.
|
||||
|
||||
## Deletion behavior
|
||||
|
||||
When a task is deleted, BackupX removes backup artifacts from every storage target but preserves backup records for audit. Task deletion also tears down the cron schedule entry.
|
||||
118
docs-site/docs/features/multi-node.md
Normal file
118
docs-site/docs/features/multi-node.md
Normal file
@@ -0,0 +1,118 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: Multi-Node Cluster
|
||||
description: Master-Agent mode — route backups to remote servers via HTTP long-polling.
|
||||
---
|
||||
|
||||
# Multi-Node Cluster
|
||||
|
||||
BackupX supports Master-Agent mode: backup tasks can be routed to specific nodes. The Agent runs the backup locally and uploads straight to storage. All connections are initiated by the Agent, so remote networks only need outbound HTTP access.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
[Web Console] ─── JWT ──→ [Master (backupx)]
|
||||
↑ ↓
|
||||
│ │ HTTP long-poll (token auth)
|
||||
│ ↓
|
||||
[Agent (backupx agent)] ← runs on remote host
|
||||
↓
|
||||
[70+ Storage Backends]
|
||||
```
|
||||
|
||||
- **Protocol** — HTTP long-polling; the Agent initiates every connection
|
||||
- **Heartbeat** — Agent reports every 15s; Master marks nodes offline after 45s of silence
|
||||
- **Dispatch** — Master persists `run_task` commands to a queue; Agent polls and claims them
|
||||
- **Execution** — Agent reuses the same BackupRunner (file / mysql / postgresql / sqlite / saphana) and uploads directly to storage
|
||||
- **Security** — Each node has its own token; the Agent never holds the Master's JWT secret or AES-256 key
|
||||
|
||||
## Walkthrough
|
||||
|
||||
### 1. Create a node on Master
|
||||
|
||||
Web Console → **Node Management** → **Add Node**. A 64-byte hex token is shown **once** — keep it safe.
|
||||
|
||||
### 2. Deploy the Agent on a remote host
|
||||
|
||||
Upload the BackupX binary (same file as Master) to the target host, then start the Agent:
|
||||
|
||||
**Option A: CLI flags**
|
||||
|
||||
```bash
|
||||
backupx agent --master http://master.example.com:8340 --token <token>
|
||||
```
|
||||
|
||||
**Option B: config file**
|
||||
|
||||
```yaml title="/etc/backupx/agent.yaml"
|
||||
master: http://master.example.com:8340
|
||||
token: <token>
|
||||
heartbeatInterval: 15s
|
||||
pollInterval: 5s
|
||||
tempDir: /var/lib/backupx-agent
|
||||
```
|
||||
|
||||
```bash
|
||||
backupx agent --config /etc/backupx/agent.yaml
|
||||
```
|
||||
|
||||
**Option C: environment variables** (Docker / systemd friendly)
|
||||
|
||||
```bash
|
||||
BACKUPX_AGENT_MASTER=http://master.example.com:8340 \
|
||||
BACKUPX_AGENT_TOKEN=<token> \
|
||||
backupx agent
|
||||
```
|
||||
|
||||
Once connected, the node shows as **online** in the list.
|
||||
|
||||
### 3. Route a task to the node
|
||||
|
||||
In the **Backup Tasks** page, pick the target node when creating the task. When the task runs:
|
||||
|
||||
- Local (`nodeId=0`) → Master executes in-process
|
||||
- Remote node → Master enqueues the command → Agent claims → Agent runs locally → uploads → reports back
|
||||
|
||||
## Known limitations
|
||||
|
||||
- **Encrypted backups don't work via Agent** — the Agent doesn't hold Master's AES-256 key. Tasks with `encrypt: true` will fail if routed to an Agent
|
||||
- **Directory browser timeout** — remote dir listing is a synchronous RPC through the queue (15s default)
|
||||
- **Dispatched command timeout** — claimed-but-unfinished commands are marked `timeout` after 10 minutes
|
||||
|
||||
## CLI reference
|
||||
|
||||
```
|
||||
backupx agent --help
|
||||
-master string Master URL
|
||||
-token string Agent auth token
|
||||
-config string YAML config path (takes precedence over env)
|
||||
-temp-dir string Local temp directory (default /tmp/backupx-agent)
|
||||
-insecure-tls Skip TLS verification (testing only)
|
||||
```
|
||||
|
||||
## systemd unit
|
||||
|
||||
```ini title="/etc/systemd/system/backupx-agent.service"
|
||||
[Unit]
|
||||
Description=BackupX Agent
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=backupx
|
||||
Environment="BACKUPX_AGENT_MASTER=https://master.example.com"
|
||||
Environment="BACKUPX_AGENT_TOKEN=your-token"
|
||||
ExecStart=/opt/backupx/backupx agent
|
||||
Restart=on-failure
|
||||
RestartSec=10s
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Enable and start:
|
||||
|
||||
```bash
|
||||
sudo systemctl enable --now backupx-agent
|
||||
sudo journalctl -u backupx-agent -f
|
||||
```
|
||||
49
docs-site/docs/features/notifications.md
Normal file
49
docs-site/docs/features/notifications.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
title: Notifications
|
||||
description: Email, webhook, and Telegram notifications on backup success or failure.
|
||||
---
|
||||
|
||||
# Notifications
|
||||
|
||||
BackupX supports three notification channels. Configure per-channel rules for success-only, failure-only, or both.
|
||||
|
||||
## Email (SMTP)
|
||||
|
||||
| Field | Notes |
|
||||
|-------|-------|
|
||||
| SMTP host / port | e.g. `smtp.gmail.com:587` |
|
||||
| Username / password | App-specific password recommended |
|
||||
| From address | Used in `From:` header |
|
||||
| Recipients | Comma-separated list |
|
||||
| Use TLS / StartTLS | Match your SMTP provider |
|
||||
|
||||
## Webhook
|
||||
|
||||
Send a JSON POST to an arbitrary URL. Body shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "backup_result",
|
||||
"task": {"id": 1, "name": "web-files", "type": "file"},
|
||||
"record": {"id": 42, "status": "success", "fileSize": 1048576, "durationSeconds": 12},
|
||||
"error": ""
|
||||
}
|
||||
```
|
||||
|
||||
Useful for custom workflows: Slack incoming webhook, PagerDuty, your own API, etc.
|
||||
|
||||
## Telegram
|
||||
|
||||
| Field | Notes |
|
||||
|-------|-------|
|
||||
| Bot token | From [@BotFather](https://t.me/BotFather) |
|
||||
| Chat ID | Numeric — obtain via `/start` + bot's `getUpdates` |
|
||||
|
||||
## Event rules
|
||||
|
||||
Each notification configuration can be scoped to:
|
||||
|
||||
- **Success only** — quiet during normal runs, pings on first failure
|
||||
- **Failure only** — recommended for loud channels
|
||||
- **Both** — useful during initial setup to verify notifications flow
|
||||
79
docs-site/docs/features/sap-hana.md
Normal file
79
docs-site/docs/features/sap-hana.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: SAP HANA Support
|
||||
description: Two SAP HANA backup modes — managed hdbsql runner and native Backint protocol agent.
|
||||
---
|
||||
|
||||
# SAP HANA Support
|
||||
|
||||
BackupX provides two SAP HANA backup modes. Pick whichever fits your operations workflow.
|
||||
|
||||
## Mode 1: hdbsql Runner (console-managed)
|
||||
|
||||
Create a SAP HANA backup task in the Web console. The backend invokes `hdbsql` to execute the backup. Use this when BackupX should own the schedule.
|
||||
|
||||
**Source configuration supports:**
|
||||
|
||||
| Field | Options | Description |
|
||||
|-------|---------|-------------|
|
||||
| Backup type | `data` / `log` | Data or log backup |
|
||||
| Backup level | `full` / `incremental` / `differential` | Auto-disabled for log backups |
|
||||
| Parallel channels | `1 ~ 32` | Multi-path SQL (`BACKUP DATA USING FILE ('c1', 'c2', ...)`) |
|
||||
| Retry count | `1 ~ 10` | Exponential backoff (`5s × attempt²`) |
|
||||
| Instance number | Optional | Inferred from port or specified manually |
|
||||
|
||||
## Mode 2: Backint Protocol Agent (HANA native)
|
||||
|
||||
BackupX ships a built-in Backint Agent. SAP HANA calls it via the native `BACKUP DATA USING BACKINT` syntax, and data is routed automatically to any BackupX storage target (S3 / OSS / COS / WebDAV / 70+ backends).
|
||||
|
||||
### 1. Parameter file
|
||||
|
||||
```ini title="/opt/backupx/backint_params.ini"
|
||||
#STORAGE_TYPE = s3
|
||||
#STORAGE_CONFIG_JSON = /opt/backupx/storage.json
|
||||
#PARALLEL_FACTOR = 4
|
||||
#COMPRESS = true
|
||||
#KEY_PREFIX = hana-backup
|
||||
#CATALOG_DB = /opt/backupx/backint_catalog.db
|
||||
#LOG_FILE = /var/log/backupx/backint.log
|
||||
```
|
||||
|
||||
### 2. Storage config (same schema as storage targets)
|
||||
|
||||
```json title="/opt/backupx/storage.json"
|
||||
{
|
||||
"endpoint": "https://s3.amazonaws.com",
|
||||
"region": "us-east-1",
|
||||
"bucket": "hana-prod",
|
||||
"accessKeyId": "AKIA...",
|
||||
"secretAccessKey": "..."
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Create the hdbbackint symlink
|
||||
|
||||
```bash
|
||||
ln -s /opt/backupx/backupx /usr/sap/<SID>/SYS/global/hdb/opt/hdbbackint
|
||||
```
|
||||
|
||||
### 4. Enable Backint in HANA `global.ini`
|
||||
|
||||
```ini
|
||||
[backup]
|
||||
data_backup_using_backint = true
|
||||
catalog_backup_using_backint = true
|
||||
log_backup_using_backint = true
|
||||
data_backup_parameter_file = /opt/backupx/backint_params.ini
|
||||
log_backup_parameter_file = /opt/backupx/backint_params.ini
|
||||
```
|
||||
|
||||
### 5. Manual CLI invocation (troubleshooting)
|
||||
|
||||
```bash
|
||||
backupx backint -f backup -i input.txt -o output.txt -p backint_params.ini
|
||||
backupx backint -f restore -i input.txt -o output.txt -p backint_params.ini
|
||||
backupx backint -f inquire -i input.txt -o output.txt -p backint_params.ini
|
||||
backupx backint -f delete -i input.txt -o output.txt -p backint_params.ini
|
||||
```
|
||||
|
||||
The Backint Agent maintains an `EBID ↔ object-key` catalog in a local SQLite DB. All operations follow the SAP HANA Backint protocol (`#PIPE` / `#SAVED` / `#RESTORED` / `#BACKUP` / `#NOTFOUND` / `#DELETED` / `#ERROR`).
|
||||
38
docs-site/docs/features/storage-backends.md
Normal file
38
docs-site/docs/features/storage-backends.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Storage Backends
|
||||
description: 70+ storage backends — built-in cloud providers plus any rclone backend.
|
||||
---
|
||||
|
||||
# Storage Backends
|
||||
|
||||
BackupX aims to accept any place you'd want to drop a backup file.
|
||||
|
||||
## Built-in providers
|
||||
|
||||
| Type | Required fields |
|
||||
|------|-----------------|
|
||||
| **Alibaba OSS** | Region + AccessKey ID/Secret + Bucket (endpoint auto-assembled) |
|
||||
| **Tencent COS** | Region + SecretId/SecretKey + Bucket (format `name-appid`) |
|
||||
| **Qiniu Kodo** | Region + AccessKey/SecretKey + Bucket |
|
||||
| **S3-compatible** | Endpoint + AccessKey + Bucket |
|
||||
| **Google Drive** | Client ID/Secret + OAuth authorization |
|
||||
| **WebDAV** | URL + username/password |
|
||||
| **FTP / FTPS** | Host + port + username/password |
|
||||
| **Local disk** | Target directory (absolute path) |
|
||||
|
||||
## Rclone backends
|
||||
|
||||
Every [rclone backend](https://rclone.org/overview/) is exposed as a first-class storage type — SFTP, Azure Blob, Dropbox, OneDrive, Backblaze B2, Wasabi, pCloud, HDFS, and many more.
|
||||
|
||||
- The form groups fields into **required** and **advanced** (advanced collapsed by default)
|
||||
- Validation and connection tests reuse rclone's built-in probe
|
||||
|
||||
## Multiple targets per task
|
||||
|
||||
A backup task can fan out to multiple targets in parallel. All targets receive the same artifact; a per-target status is recorded:
|
||||
|
||||
- Success: storage path + size
|
||||
- Failed: error message
|
||||
|
||||
If any target fails after retries, the record status is `failed` but successful targets are preserved (no rollback).
|
||||
82
docs-site/docs/getting-started/installation.md
Normal file
82
docs-site/docs/getting-started/installation.md
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Installation
|
||||
description: Install BackupX via Docker, prebuilt archive, or from source.
|
||||
---
|
||||
|
||||
# Installation
|
||||
|
||||
BackupX ships as a single static binary. Three ways to install, pick the one that matches your environment.
|
||||
|
||||
## Docker (recommended)
|
||||
|
||||
No cloning required.
|
||||
|
||||
```bash
|
||||
docker run -d --name backupx \
|
||||
-p 8340:8340 \
|
||||
-v backupx-data:/app/data \
|
||||
awuqing/backupx:latest
|
||||
```
|
||||
|
||||
Or use `docker compose`:
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
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 (as needed):
|
||||
# - /var/www:/mnt/www:ro
|
||||
# - /etc/nginx:/mnt/nginx-conf:ro
|
||||
environment:
|
||||
- TZ=Asia/Shanghai
|
||||
|
||||
volumes:
|
||||
backupx-data:
|
||||
```
|
||||
|
||||
Images: [`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx) — supports `linux/amd64` and `linux/arm64`.
|
||||
|
||||
## Prebuilt archive (bare metal)
|
||||
|
||||
Download from the [Releases page](https://github.com/Awuqing/BackupX/releases) and run the installer:
|
||||
|
||||
```bash
|
||||
tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
|
||||
sudo ./install.sh # creates system user, installs to /opt/backupx, sets up systemd + nginx
|
||||
```
|
||||
|
||||
The installer:
|
||||
|
||||
1. Creates a `backupx` system user
|
||||
2. Installs binary to `/opt/backupx/backupx`
|
||||
3. Creates `/opt/backupx/config.yaml` with safe defaults
|
||||
4. Installs and enables the `backupx.service` systemd unit
|
||||
5. (Optional) Configures an Nginx reverse proxy
|
||||
|
||||
## From source
|
||||
|
||||
Requires Go ≥ 1.25 and Node.js ≥ 20.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Awuqing/BackupX.git && cd BackupX
|
||||
make build
|
||||
# or, for builds behind the great firewall
|
||||
make docker-cn
|
||||
```
|
||||
|
||||
After `make build`, the binary is at `server/bin/backupx` and the built web UI is at `web/dist/`.
|
||||
|
||||
## Verify the install
|
||||
|
||||
```bash
|
||||
backupx --version # e.g. v1.6.0
|
||||
```
|
||||
|
||||
Then open `http://your-server:8340` to see the initial admin setup screen.
|
||||
59
docs-site/docs/getting-started/quick-start.md
Normal file
59
docs-site/docs/getting-started/quick-start.md
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Quick Start
|
||||
description: Set up BackupX, add a storage target, create your first backup task.
|
||||
---
|
||||
|
||||
# Quick Start
|
||||
|
||||
After [installation](./installation), get a first backup running in five minutes.
|
||||
|
||||
## 1. Open the console
|
||||
|
||||
Browse to `http://your-server:8340`. The first time, you'll be guided through creating an admin account.
|
||||
|
||||
## 2. Add a storage target
|
||||
|
||||
Navigate to **Storage Targets → Add**. Pick a type and fill the required fields:
|
||||
|
||||
| Type | Fields |
|
||||
|------|--------|
|
||||
| Alibaba OSS | Region + AccessKey ID/Secret + Bucket |
|
||||
| Tencent COS | Region + SecretId/SecretKey + Bucket (format `name-appid`) |
|
||||
| Qiniu Kodo | Region + AccessKey/SecretKey + Bucket |
|
||||
| S3-compatible | Endpoint + AccessKey + Bucket |
|
||||
| Google Drive | Client ID/Secret → click "Authorize" for OAuth flow |
|
||||
| WebDAV | URL + username/password |
|
||||
| FTP | Host + port + username/password |
|
||||
| Local disk | Target directory |
|
||||
| SFTP / Azure / Dropbox / OneDrive | Type-specific required fields; advanced options collapsed |
|
||||
|
||||
:::tip
|
||||
For mainland China cloud vendors you only fill Region and AccessKey — BackupX assembles the endpoint automatically. Rclone-style providers separate required fields from advanced ones, with advanced collapsed by default.
|
||||
:::
|
||||
|
||||
Click **Test Connection** to verify.
|
||||
|
||||
## 3. Create a backup task
|
||||
|
||||
Go to **Backup Tasks → New**. Three steps:
|
||||
|
||||
1. **Basic info** — name, type, cron expression (leave empty for manual-only)
|
||||
2. **Source** — paths for file backup (multi-source supported), or connection info for databases
|
||||
3. **Storage & policy** — pick target(s), compression, retention days, encryption on/off
|
||||
|
||||
Save, then click **Run Now** to trigger a test. Live logs stream on the **Backup Records** page.
|
||||
|
||||
:::note
|
||||
Deleting a task also removes remote backup files to prevent orphans, but records are kept for audit.
|
||||
:::
|
||||
|
||||
## 4. Configure notifications (optional)
|
||||
|
||||
**Notifications** page supports email, webhook, and Telegram. Configure per-channel rules for success/failure events.
|
||||
|
||||
## Next up
|
||||
|
||||
- Explore [backup types](/docs/features/backup-types) and [storage backends](/docs/features/storage-backends)
|
||||
- Running SAP HANA? See [SAP HANA Support](/docs/features/sap-hana)
|
||||
- Managing many servers? See [Multi-Node Cluster](/docs/features/multi-node)
|
||||
40
docs-site/docs/intro.md
Normal file
40
docs-site/docs/intro.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
id: intro
|
||||
slug: /intro
|
||||
sidebar_position: 1
|
||||
title: Introduction
|
||||
description: Overview of BackupX — a self-hosted server backup management platform.
|
||||
---
|
||||
|
||||
# BackupX
|
||||
|
||||
**BackupX** is a self-hosted server backup management platform. One static binary, one command, and every backup job for every server is under control.
|
||||
|
||||
- **Single binary + embedded SQLite** — no external database or orchestrator required
|
||||
- **Files, databases, SAP HANA** — in one place, with a visual scheduler
|
||||
- **70+ storage backends** — Alibaba OSS, Tencent COS, Qiniu, S3, Google Drive, WebDAV, FTP, plus SFTP / Azure Blob / Dropbox / OneDrive and dozens more via rclone
|
||||
- **Multi-node cluster** — Master-Agent mode manages backups across servers, agents run tasks locally and upload straight to storage
|
||||
- **Secure by default** — JWT auth, bcrypt, AES-256-GCM encrypted config, optional backup encryption, full audit log
|
||||
|
||||
## Architecture at a Glance
|
||||
|
||||
```
|
||||
[Web Console] ─── JWT ──→ [Master (backupx)]
|
||||
│
|
||||
│ HTTP long-poll (token auth)
|
||||
▼
|
||||
[Agent (backupx agent)]
|
||||
│
|
||||
▼
|
||||
[70+ Storage Backends]
|
||||
```
|
||||
|
||||
Tasks routed to the local Master run in-process; tasks assigned to remote nodes are dispatched through a command queue and executed by the Agent locally. Agents only ever initiate outbound HTTP — no reverse connectivity required.
|
||||
|
||||
## Where to Next
|
||||
|
||||
- **New to BackupX?** Read the [Quick Start](/docs/getting-started/quick-start) first.
|
||||
- **Deploying to production?** See the [Deployment Guide](/docs/deployment/docker).
|
||||
- **SAP HANA operator?** Both `hdbsql` Runner and native Backint are supported — see [SAP HANA](/docs/features/sap-hana).
|
||||
- **Managing multiple servers?** See [Multi-Node Cluster](/docs/features/multi-node).
|
||||
- **Integrating programmatically?** See the [API Reference](/docs/reference/api).
|
||||
83
docs-site/docs/reference/api.md
Normal file
83
docs-site/docs/reference/api.md
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: API Reference
|
||||
description: REST API endpoints — all under /api with JWT Bearer authentication.
|
||||
---
|
||||
|
||||
# API Reference
|
||||
|
||||
All endpoints are prefixed with `/api` and authenticated with a JWT Bearer token, obtained via `POST /api/auth/login`. Agent endpoints use `X-Agent-Token` instead.
|
||||
|
||||
## Authentication
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `POST /api/auth/setup` | Initialize the first admin (only when no user exists) |
|
||||
| `POST /api/auth/login` | Log in and receive a JWT |
|
||||
| `PUT /api/auth/password` | Change password |
|
||||
|
||||
## Backup tasks
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `GET /api/backup/tasks` | List tasks |
|
||||
| `POST /api/backup/tasks` | Create |
|
||||
| `GET /api/backup/tasks/:id` | Detail |
|
||||
| `PUT /api/backup/tasks/:id` | Update |
|
||||
| `DELETE /api/backup/tasks/:id` | Delete |
|
||||
| `PUT /api/backup/tasks/:id/toggle` | Enable / disable |
|
||||
| `POST /api/backup/tasks/:id/run` | Manual run |
|
||||
|
||||
## Backup records
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `GET /api/backup/records` | List records with filters |
|
||||
| `GET /api/backup/records/:id/logs/stream` | Live logs (SSE) |
|
||||
| `GET /api/backup/records/:id/download` | Download artifact |
|
||||
| `POST /api/backup/records/:id/restore` | Restore into the original source |
|
||||
|
||||
## Storage targets
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `GET /api/storage-targets` | List |
|
||||
| `POST /api/storage-targets` | Create |
|
||||
| `POST /api/storage-targets/test` | Test connection with pending config |
|
||||
| `GET /api/storage-targets/rclone/backends` | List all available rclone backends |
|
||||
|
||||
## Nodes (cluster)
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `GET /api/nodes` | List nodes |
|
||||
| `POST /api/nodes` | Create a node and return token |
|
||||
| `PUT /api/nodes/:id` | Rename |
|
||||
| `DELETE /api/nodes/:id` | Delete (rejected if tasks are attached) |
|
||||
| `GET /api/nodes/:id/fs/list` | Browse directory (remote node = async RPC) |
|
||||
|
||||
## Agent protocol (X-Agent-Token)
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `POST /api/agent/heartbeat` | Report liveness |
|
||||
| `POST /api/agent/commands/poll` | Claim one pending command |
|
||||
| `POST /api/agent/commands/:id/result` | Report command result |
|
||||
| `GET /api/agent/tasks/:id` | Fetch task spec with decrypted storage configs |
|
||||
| `POST /api/agent/records/:id` | Append logs / update record status |
|
||||
|
||||
## Notifications
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `GET /api/notifications` | List |
|
||||
| `POST /api/notifications` | Create |
|
||||
|
||||
## Dashboard / audit / system
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `GET /api/dashboard/stats` | Overview statistics |
|
||||
| `GET /api/audit-logs` | Audit log list |
|
||||
| `GET /api/system/info` | System information |
|
||||
| `GET /api/system/update-check` | Check for a newer release |
|
||||
69
docs-site/docs/reference/cli.md
Normal file
69
docs-site/docs/reference/cli.md
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: CLI Reference
|
||||
description: backupx subcommands — server, agent, backint, reset-password.
|
||||
---
|
||||
|
||||
# CLI Reference
|
||||
|
||||
The `backupx` binary ships several subcommands. Running `backupx` with no subcommand starts the main server process.
|
||||
|
||||
## `backupx` (default: server)
|
||||
|
||||
```bash
|
||||
backupx --config /opt/backupx/config.yaml
|
||||
backupx --version
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--config <path>` | Path to config YAML (default: `./config.yaml`) |
|
||||
| `--version` | Print version and exit |
|
||||
|
||||
## `backupx agent`
|
||||
|
||||
Run in Agent mode, connecting to a Master. See [Multi-Node Cluster](../features/multi-node).
|
||||
|
||||
```bash
|
||||
backupx agent --master http://master:8340 --token <token>
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--master <url>` | Master URL |
|
||||
| `--token <token>` | Agent auth token |
|
||||
| `--config <path>` | YAML config (takes precedence over env) |
|
||||
| `--temp-dir <path>` | Local temp directory (default `/tmp/backupx-agent`) |
|
||||
| `--insecure-tls` | Skip TLS verification (testing only) |
|
||||
|
||||
Environment variables: `BACKUPX_AGENT_MASTER`, `BACKUPX_AGENT_TOKEN`, `BACKUPX_AGENT_HEARTBEAT`, `BACKUPX_AGENT_POLL`, `BACKUPX_AGENT_TEMP_DIR`, `BACKUPX_AGENT_INSECURE_TLS`.
|
||||
|
||||
## `backupx backint`
|
||||
|
||||
SAP HANA Backint protocol agent. See [SAP HANA Support](../features/sap-hana).
|
||||
|
||||
```bash
|
||||
backupx backint -f <function> -i <input> -o <output> -p <params>
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `-f <fn>` | `backup` / `restore` / `inquire` / `delete` |
|
||||
| `-i <path>` | Input file |
|
||||
| `-o <path>` | Output file |
|
||||
| `-p <path>` | Parameter file |
|
||||
| `-u / -c / -l / -v` | Accepted and ignored for SAP compatibility |
|
||||
|
||||
## `backupx reset-password`
|
||||
|
||||
Reset an admin password directly in the SQLite database. No server restart needed.
|
||||
|
||||
```bash
|
||||
backupx reset-password --username admin --password 'newpass123' [--config /path/to/config.yaml]
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--username` | Target username (default: `admin`) |
|
||||
| `--password` | New password (min 8 chars, required) |
|
||||
| `--config` | Config path (used to locate the database file) |
|
||||
Reference in New Issue
Block a user