文档: 新增 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-05-11 18:10:23 +08:00 · 2026-04-17 13:19:41 +08:00
parent 757b0fa5ed
commit bc3d03de7e
55 changed files with 22429 additions and 901 deletions
--- a/README.md
+++ b/README.md
@@ -1,11 +1,11 @@
 <p align="right">
-  <a href="README_EN.md">English</a> | <strong>中文</strong>
+  <strong>English</strong> | <a href="README.zh-CN.md">中文</a>
 </p>
 <p align="center">
  <h1 align="center">BackupX</h1>
  <p align="center">
-    <strong>自托管服务器备份管理平台</strong><br>
-    一个二进制，一条命令，管好你所有服务器的备份。
+    <strong>Self-hosted server backup management</strong><br>
+    One binary, one command — manage every backup of every server.
  </p>
  <p align="center">
    <a href="https://github.com/Awuqing/BackupX/stargazers"><img src="https://img.shields.io/github/stars/Awuqing/BackupX?style=flat-square&color=f5c542" alt="Stars"></a>
@@ -15,461 +15,79 @@
    <img src="https://img.shields.io/badge/SQLite-embedded-003B57?style=flat-square&logo=sqlite" alt="SQLite">
    <a href="LICENSE"><img src="https://img.shields.io/github/license/Awuqing/BackupX?style=flat-square" alt="License"></a>
  </p>
+  <p align="center">
+    <a href="https://awuqing.github.io/BackupX/"><strong>Docs</strong></a> ·
+    <a href="https://github.com/Awuqing/BackupX/releases"><strong>Downloads</strong></a> ·
+    <a href="https://hub.docker.com/r/awuqing/backupx"><strong>Docker Hub</strong></a>
+  </p>
 </p>

 ---

 <table>
 <tr>
-<td width="50%"><img src="screenshots/dashboard.png" alt="仪表盘"></td>
-<td width="50%"><img src="screenshots/backup-tasks.png" alt="备份任务"></td>
+<td width="50%"><img src="screenshots/dashboard.png" alt="Dashboard"></td>
+<td width="50%"><img src="screenshots/backup-tasks.png" alt="Backup Tasks"></td>
 </tr>
 <tr>
-<td><img src="screenshots/storage-targets.png" alt="存储目标"></td>
-<td><img src="screenshots/backup-records.png" alt="备份记录"></td>
+<td><img src="screenshots/storage-targets.png" alt="Storage Targets"></td>
+<td><img src="screenshots/backup-records.png" alt="Backup Records"></td>
 </tr>
 </table>

-## 功能亮点
+## Highlights

-| 能力 | 说明 |
-|------|------|
-| **备份类型** | 文件/目录（多源路径）、MySQL、PostgreSQL、SQLite、SAP HANA（完整/增量/差异/日志备份 + 并行通道 + 失败重试） |
-| **SAP HANA Backint 代理** | 内置 SAP HANA Backint 协议代理，HANA 原生备份接口可直接把数据路由到 BackupX 支持的任意存储后端 |
-| **70+ 存储后端** | 内置阿里云 OSS / 腾讯云 COS / 七牛云 / S3 / Google Drive / WebDAV / FTP + 通过 rclone 集成 SFTP、Azure Blob、Dropbox、OneDrive 等 70+ 后端 |
-| **自动调度** | Cron 定时 + 可视化编辑器 + 自动保留策略（按天数/份数清理，自动回收空目录） |
-| **多节点** | Master-Agent 集群，统一管理多台服务器的备份，支持远程目录浏览与节点编辑 |
-| **安全** | JWT + bcrypt + AES-256-GCM 加密配置 + 可选备份文件加密 + 完整审计日志 |
-| **通知** | 邮件 / Webhook / Telegram，备份成功或失败时自动推送 |
-| **部署** | 单二进制 + 内嵌 SQLite，Docker 一键启动，零外部依赖 |
+| Capability | Details |
+|-----------|---------|
+| **Backup Types** | Files/directories (multi-source), MySQL, PostgreSQL, SQLite, SAP HANA (full / incremental / differential / log + parallel channels + retry) |
+| **SAP HANA Backint Agent** | Built-in Backint protocol — HANA's native interface routes data directly to any BackupX storage backend |
+| **70+ Storage Backends** | Alibaba OSS, Tencent COS, Qiniu, S3, Google Drive, WebDAV, FTP + SFTP, Azure Blob, Dropbox, OneDrive and dozens more via rclone |
+| **Scheduling** | Cron + visual editor + auto-retention (by days/count + empty-directory cleanup) |
+| **Multi-Node Cluster** | Master-Agent mode via HTTP long-polling — Agents run tasks locally, upload straight to storage, no reverse connectivity required |
+| **Security** | JWT + bcrypt + AES-256-GCM encrypted config + optional backup encryption + full audit log |
+| **Notifications** | Email / Webhook / Telegram on success or failure |
+| **Deployment** | Single binary + embedded SQLite, Docker one-click, zero external dependencies |

---
-
-## 快速开始
-
-### 1. 安装
-
-**Docker（推荐，无需克隆仓库）：**
+## Quick Start

 ```bash
-# 创建 docker-compose.yml 后一键启动
-docker compose up -d
-
-# 或直接运行
+# Docker (recommended)
 docker run -d --name backupx -p 8340:8340 -v backupx-data:/app/data awuqing/backupx:latest
+
+# Or prebuilt archive
+curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-linux-amd64.tar.gz
+tar xzf backupx-*.tar.gz && cd backupx-* && sudo ./install.sh
 ```

-> Docker Hub 镜像：[`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx)，支持 linux/amd64 和 linux/arm64。
+Open `http://your-server:8340`, create the admin account, then follow the [5-minute Quick Start](https://awuqing.github.io/BackupX/docs/getting-started/quick-start).

-<details>
-<summary>docker-compose.yml 参考</summary>
+## Documentation

-```yaml
-services:
-  backupx:
-    image: awuqing/backupx:latest
-    container_name: backupx
-    restart: unless-stopped
-    ports:
-      - "8340:8340"
-    volumes:
-      - backupx-data:/app/data
-      # 挂载需要备份的宿主机目录（按需添加）：
-      # - /var/www:/mnt/www:ro
-      # - /etc/nginx:/mnt/nginx-conf:ro
-    environment:
-      - TZ=Asia/Shanghai
+The full docs live at **https://awuqing.github.io/BackupX/** — Getting Started, Deployment, SAP HANA, Multi-Node Cluster, API reference, and more. Switch to Chinese via the language dropdown in the top-right nav.

-volumes:
-  backupx-data:
-```
+Quick links:

-</details>
+- [Quick Start](https://awuqing.github.io/BackupX/docs/getting-started/quick-start) — first backup in five minutes
+- [Installation](https://awuqing.github.io/BackupX/docs/getting-started/installation) — Docker / bare metal / source
+- [Multi-Node Cluster](https://awuqing.github.io/BackupX/docs/features/multi-node) — deploy the Agent on remote servers
+- [SAP HANA Support](https://awuqing.github.io/BackupX/docs/features/sap-hana) — hdbsql Runner and native Backint
+- [API Reference](https://awuqing.github.io/BackupX/docs/reference/api) — REST endpoints

-**预编译包（裸机部署）：**
-
-从 [Releases](https://github.com/Awuqing/BackupX/releases) 下载对应平台的压缩包：
-
-```bash
-tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
-sudo ./install.sh        # 自动配置 systemd + Nginx
-```
-
-**从源码构建：**
+## Development

 ```bash
 git clone https://github.com/Awuqing/BackupX.git && cd BackupX
-make build               # 构建前后端
-make docker-cn           # 或用国内镜像构建 Docker（goproxy.cn / npmmirror / 阿里云 apk）
+make dev-server          # Terminal 1 — backend (:8340)
+make dev-web             # Terminal 2 — frontend (Vite HMR)
+make test                # run all tests
+make build               # produce server/bin/backupx + web/dist
 ```

-### 2. 打开控制台
-
-浏览器访问 `http://your-server:8340`，首次打开会引导创建管理员账户。
-
-### 3. 添加存储目标
-
-进入 **存储目标** 页面，点击 **添加**，选择存储类型并填写凭证：
-
-| 存储类型 | 需要填写 |
-|---------|---------|
-| 阿里云 OSS | Region + AccessKey ID/Secret + Bucket |
-| 腾讯云 COS | Region + SecretId/SecretKey + Bucket（格式 `name-appid`） |
-| 七牛云 Kodo | Region + AccessKey/SecretKey + Bucket |
-| S3 兼容 | Endpoint + AccessKey + Bucket |
-| Google Drive | Client ID/Secret → 点击授权完成 OAuth |
-| WebDAV | 服务器地址 + 用户名/密码 |
-| FTP | 主机 + 端口 + 用户名/密码 |
-| 本地磁盘 | 目标目录路径 |
-| SFTP / Azure / Dropbox / OneDrive 等 | 选择对应类型后填写必填项，高级配置可折叠展开 |
-
-> 国内云厂商只需填 Region 和 AccessKey，系统自动组装 Endpoint。Rclone 类型的配置项按必填/可选分层展示，高级选项默认折叠。
-
-添加后点击 **测试连接** 确认配置正确。
-
-### 4. 创建备份任务
-
-进入 **备份任务** 页面，点击 **新建**，三步完成：
-
-1. **基础信息** — 任务名称、备份类型、Cron 表达式（留空则仅手动执行）
-2. **源配置** — 文件备份选择源路径（支持多个）、数据库备份填写连接信息
-3. **存储与策略** — 选择存储目标（支持多个）、压缩策略、保留天数、是否加密
-
-保存后可以点击 **立即执行** 测试，在 **备份记录** 页面实时查看执行日志。
-
-> 删除备份任务时会自动清理远端存储上的备份文件，但保留备份记录以供审计追溯。
-
-### 5. 配置通知（可选）
-
-进入 **通知配置** 页面，支持邮件、Webhook、Telegram 三种方式，可分别配置成功/失败时是否推送。
-
---
-
-## 部署指南
-
-### Docker 部署
-
-```bash
-docker compose up -d     # 使用上方的 docker-compose.yml
-```
-
-备份宿主机目录时需要挂载路径（在 docker-compose.yml 的 `volumes` 中添加）：
-
-```yaml
-volumes:
-  - backupx-data:/app/data
-  - /var/www:/mnt/www:ro              # 挂载需要备份的目录
-  - /etc/nginx:/mnt/nginx-conf:ro     # 可以挂载多个
-```
-
-通过环境变量调整配置：
-
-```yaml
-environment:
-  - TZ=Asia/Shanghai
-  - BACKUPX_LOG_LEVEL=debug
-  - BACKUPX_BACKUP_MAX_CONCURRENT=4
-```
-
-版本更新：在 **系统设置** 页面点击「检查更新」查看是否有新版本，然后手动执行 `docker compose pull && docker compose up -d` 完成升级。
-
-### 裸机部署
-
-```bash
-# 使用预编译包
-tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
-sudo ./install.sh
-
-# 或从源码
-make build
-sudo ./deploy/install.sh
-```
-
-安装脚本自动完成：创建系统用户 → 安装二进制到 `/opt/backupx/` → 配置 systemd → 配置 Nginx 反向代理。
-
-### Nginx 反向代理（裸机部署时）
-
-```nginx
-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;
-    }
-}
-```
-
-### 配置文件
-
-配置文件路径 `./config.yaml`，也可通过 `BACKUPX_` 前缀环境变量覆盖：
-
-```yaml
-server:
-  port: 8340
-database:
-  path: "./data/backupx.db"
-security:
-  jwt_secret: ""          # 留空自动生成并持久化到数据库
-  encryption_key: ""      # 留空自动生成
-backup:
-  temp_dir: "/tmp/backupx"
-  max_concurrent: 2
-log:
-  level: "info"           # debug | info | warn | error
-  file: "./data/backupx.log"
-```
-
-### 密码重置
-
-忘记管理员密码时通过 CLI 重置：
-
-```bash
-# 裸机
-./backupx reset-password --username admin --password newpass123
-
-# Docker
-docker exec -it backupx /app/bin/backupx reset-password --username admin --password newpass123
-```
-
---
-
-## SAP HANA 支持
-
-BackupX 提供两种 SAP HANA 备份模式，按需选用：
-
-### 模式一：hdbsql Runner（Web 控制台托管）
-
-通过 Web 控制台创建 SAP HANA 备份任务，后端调用 `hdbsql` 执行备份，适合 BackupX 调度的周期性作业。
-
-**源配置步骤支持：**
-
-| 字段 | 可选值 | 说明 |
-|------|--------|------|
-| 备份类型 | `data` / `log` | 数据备份或日志备份 |
-| 备份级别 | `full` / `incremental` / `differential` | 日志备份时自动禁用 |
-| 并行通道数 | `1 ~ 32` | `BACKUP DATA USING FILE ('c1','c2',...)` 多路径并发 |
-| 失败重试次数 | `1 ~ 10` | 指数退避（5s × 尝试次数²） |
-| 实例编号 | 可选 | 从端口推断或手动指定 |
-
-### 模式二：Backint 协议代理（HANA 原生接口）
-
-BackupX 内置 Backint Agent，SAP HANA 通过原生 `BACKUP DATA USING BACKINT` 语法调用，数据自动路由到 BackupX 存储目标（S3 / OSS / COS / WebDAV / 70+ 后端）。
-
-**1. 准备参数文件** `/opt/backupx/backint_params.ini`：
-
-```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. 准备存储配置** `/opt/backupx/storage.json`（与 BackupX 存储目标配置一致）：
-
-```json
-{
-  "endpoint": "https://s3.amazonaws.com",
-  "region": "us-east-1",
-  "bucket": "hana-prod",
-  "accessKeyId": "AKIA...",
-  "secretAccessKey": "..."
-}
-```
-
-**3. 创建 hdbbackint 软链接：**
-
-```bash
-ln -s /opt/backupx/backupx /usr/sap/<SID>/SYS/global/hdb/opt/hdbbackint
-```
-
-**4. 在 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. CLI 手动调用（用于排查）：**
-
-```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
-```
-
-Backint Agent 使用本地 SQLite 维护 `EBID ↔ 对象键` 目录，所有操作遵循 SAP HANA Backint 协议（`#PIPE` / `#SAVED` / `#RESTORED` / `#BACKUP` / `#NOTFOUND` / `#DELETED` / `#ERROR`）。
-
---
-
-## 多节点集群
-
-BackupX 支持 Master-Agent 模式管理多台服务器：备份任务可以指定在哪个节点执行，Agent 在本地完成备份并直接上传到存储后端。
-
-### 架构概览
-
-```
-[Web 控制台] ←── JWT ──→ [Master (backupx)]
-                              ↑  ↓
-                              │  │ HTTP 长轮询 (token 认证)
-                              │  ↓
-                          [Agent (backupx agent)]  ← 运行在远程服务器
-                              ↓
-                          [70+ 存储后端]
-```
-
- **通信协议**：HTTP 长轮询，Agent 主动发起所有连接，无需 Master 反向访问
- **心跳**：Agent 每 15s 上报一次；Master 每 15s 扫描，超过 45s 未心跳判为离线
- **任务下发**：Master 通过数据库命令队列派发 `run_task`，Agent 轮询拉取
- **执行**：Agent 本地复用 BackupRunner（file / mysql / postgresql / sqlite / saphana）并直接上传到存储
- **安全**：每个节点独立 Token；Agent 不持有 Master 的 JWT 密钥和加密密钥
-
-### 使用步骤
-
-**1. 在 Master 创建节点并获取 Token**
-
-Web 控制台 → **节点管理** → **添加节点**，填写节点名称并保存。界面会显示一个 64 字节十六进制令牌（仅显示一次，请妥善保存）。
-
-**2. 在远程服务器部署 Agent**
-
-把 BackupX 二进制上传到目标服务器（与 Master 同一个文件），然后用以下任一方式启动：
-
-```bash
-# 方式 A：CLI 参数
-backupx agent --master http://master.example.com:8340 --token <token>
-
-# 方式 B：配置文件
-cat > /etc/backupx/agent.yaml <<EOF
-master: http://master.example.com:8340
-token: <token>
-heartbeatInterval: 15s
-pollInterval: 5s
-tempDir: /var/lib/backupx-agent
-EOF
-backupx agent --config /etc/backupx/agent.yaml
-
-# 方式 C：环境变量（适合 Docker / systemd）
-BACKUPX_AGENT_MASTER=http://master.example.com:8340 \
-BACKUPX_AGENT_TOKEN=<token> \
-backupx agent
-```
-
-启动成功后，Master 的节点列表会把该节点标记为**在线**。
-
-**3. 创建路由到该节点的备份任务**
-
-在 **备份任务** 页面新建任务时选择对应节点。任务被触发后：
-
- 本机节点或未指定节点（`nodeId=0`）：由 Master 进程本地执行
- 远程节点：Master 写入命令队列 → Agent 轮询拉取 → 本地执行并上传 → 上报记录
-
-### 限制说明
-
- **不支持加密备份**：Agent 不持有 Master 的 AES-256 加密密钥，启用 `encrypt: true` 的任务会路由到 Agent 时失败
- **目录浏览超时**：远程目录浏览通过命令队列做同步 RPC，默认 15s 超时，网络慢时可能失败
- **命令超时**：Agent 领取但未完成的命令超过 10min 会被标记为超时
-
-### CLI 参考
-
-```bash
-backupx agent --help
-  -master string    Master URL
-  -token string     Agent 认证令牌
-  -config string    YAML 配置文件路径（优先级高于环境变量）
-  -temp-dir string  本地临时目录（默认 /tmp/backupx-agent）
-  -insecure-tls     跳过 TLS 证书校验（仅测试用）
-```
-
---
-
-## 开发指南
-
-**环境要求：** Go >= 1.25 · Node.js >= 20 · npm
-
-```bash
-# 开发模式
-make dev-server          # 终端 1：后端（默认 :8340）
-make dev-web             # 终端 2：前端（Vite HMR）
-
-# 测试
-make test                # 运行全部测试
-
-# 构建
-make build               # 前后端一起构建
-make docker              # Docker 构建
-make docker-cn           # 国内 Docker 构建（镜像加速）
-```
-
-### 发版
-
-```bash
-git tag v1.4.3 && git push --tags
-# GitHub Actions 自动：编译双架构二进制 → 发布 GitHub Release → 推送 Docker Hub 镜像
-```
-
-也可在 GitHub Actions 页面手动触发 Release workflow。
-
---
-
-## API 参考
-
-所有接口以 `/api` 为前缀，使用 JWT Bearer Token 认证。
-
-| 模块 | 端点 | 说明 |
-|------|------|------|
-| **认证** | `POST /auth/setup` | 初始化管理员 |
-| | `POST /auth/login` | 登录 |
-| | `PUT /auth/password` | 修改密码 |
-| **备份任务** | `GET\|POST /backup/tasks` | 列表 / 创建 |
-| | `GET\|PUT\|DELETE /backup/tasks/:id` | 详情 / 更新 / 删除 |
-| | `PUT /backup/tasks/:id/toggle` | 启用/禁用 |
-| | `POST /backup/tasks/:id/run` | 手动执行 |
-| **备份记录** | `GET /backup/records` | 列表（支持筛选） |
-| | `GET /backup/records/:id/logs/stream` | 实时日志 (SSE) |
-| | `GET /backup/records/:id/download` | 下载 |
-| | `POST /backup/records/:id/restore` | 恢复 |
-| **存储目标** | `GET\|POST /storage-targets` | 列表 / 添加 |
-| | `POST /storage-targets/test` | 测试连接 |
-| | `GET /storage-targets/rclone/backends` | Rclone 后端列表 |
-| **节点** | `GET\|POST /nodes` | 列表 / 添加 |
-| | `PUT /nodes/:id` | 编辑节点 |
-| | `GET /nodes/:id/fs/list` | 目录浏览 |
-| | `POST /agent/heartbeat` | Agent 心跳（Token 认证） |
-| **通知** | `GET\|POST /notifications` | 列表 / 添加 |
-| **仪表盘** | `GET /dashboard/stats` | 概览统计 |
-| **审计日志** | `GET /audit-logs` | 操作审计 |
-| **系统** | `GET /system/info` | 系统信息 |
-| | `GET /system/update-check` | 检查版本更新 |
-
---
-
-## 技术栈
-
-| 组件 | 技术 |
-|------|------|
-| **后端** | Go · Gin · GORM · SQLite · robfig/cron · rclone |
-| **前端** | React 18 · TypeScript · ArcoDesign · Vite · Zustand · ECharts |
-| **存储** | rclone（70+ 后端）· AWS SDK v2 · Google Drive API v3 |
-| **安全** | JWT · bcrypt · AES-256-GCM |
+See the [development guide](https://awuqing.github.io/BackupX/docs/development/setup) for more.

 ## Contributing

-欢迎提交 Issue 和 Pull Request！
+Issues and pull requests welcome. Please read the [contributing guide](https://awuqing.github.io/BackupX/docs/development/contributing) before opening a PR — commit messages and PRs on this project are written in Chinese.

 ## License