文档: 新增 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-06-28 04:51:26 +08:00 · 2026-04-17 13:19:41 +08:00
parent 757b0fa5ed
commit bc3d03de7e
55 changed files with 22429 additions and 901 deletions
--- a/docs-site/docs/features/backup-types.md
+++ b/docs-site/docs/features/backup-types.md
@@ -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.
--- a/docs-site/docs/features/multi-node.md
+++ b/docs-site/docs/features/multi-node.md
@@ -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
+```
--- a/docs-site/docs/features/notifications.md
+++ b/docs-site/docs/features/notifications.md
@@ -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
--- a/docs-site/docs/features/sap-hana.md
+++ b/docs-site/docs/features/sap-hana.md
@@ -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`).
--- a/docs-site/docs/features/storage-backends.md
+++ b/docs-site/docs/features/storage-backends.md
@@ -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).