mirror of https://github.com/Awuqing/BackupX.git synced 2026-05-07 05:22:42 +08:00

Files

Wu Qing bc3d03de7e 文档: 新增 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/

2026-04-17 13:19:41 +08:00

3.6 KiB

Raw Blame History

sidebar_position, title, description

sidebar_position	title	description
4	Multi-Node Cluster	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

backupx agent --master http://master.example.com:8340 --token <token>

Option B: config file

master: http://master.example.com:8340
token: <token>
heartbeatInterval: 15s
pollInterval: 5s
tempDir: /var/lib/backupx-agent

backupx agent --config /etc/backupx/agent.yaml

Option C: environment variables (Docker / systemd friendly)

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

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

sudo systemctl enable --now backupx-agent
sudo journalctl -u backupx-agent -f

3.6 KiB Raw Blame History