mirror of
https://github.com/Awuqing/BackupX.git
synced 2026-07-08 09:52:35 +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
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"version.label": {"message": "Next"},
|
||||
"sidebar.docs.category.Getting Started": {"message": "快速开始"},
|
||||
"sidebar.docs.category.Deployment": {"message": "部署"},
|
||||
"sidebar.docs.category.Features": {"message": "功能特性"},
|
||||
"sidebar.docs.category.Reference": {"message": "参考"},
|
||||
"sidebar.docs.category.Development": {"message": "开发"}
|
||||
}
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: 裸机部署
|
||||
description: 从预编译包或源码部署 BackupX（systemd + Nginx）。
|
||||
---
|
||||
|
||||
# 裸机部署
|
||||
|
||||
## 使用预编译包
|
||||
|
||||
```bash
|
||||
# 下载对应平台的压缩包
|
||||
curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-v1.6.0-linux-amd64.tar.gz
|
||||
|
||||
# 解压并安装
|
||||
tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
|
||||
sudo ./install.sh
|
||||
```
|
||||
|
||||
安装脚本自动完成以下步骤：
|
||||
|
||||
1. 创建系统用户 `backupx`
|
||||
2. 复制二进制到 `/opt/backupx/`
|
||||
3. 生成默认 `config.yaml`（含安全的 JWT/加密密钥）
|
||||
4. 安装并启用 `backupx.service` systemd 单元
|
||||
5. （可选）生成 Nginx 站点配置 — 参见 [Nginx 反向代理](./nginx)
|
||||
|
||||
## 从源码构建
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Awuqing/BackupX.git && cd BackupX
|
||||
make build
|
||||
sudo ./deploy/install.sh
|
||||
```
|
||||
|
||||
`make build` 会产出：
|
||||
|
||||
- `server/bin/backupx`（Go 后端，无 CGO）
|
||||
- `web/dist/`（React 前端，执行 `npm run build`）
|
||||
|
||||
## systemd
|
||||
|
||||
安装后的 service 文件：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
常用命令：
|
||||
|
||||
```bash
|
||||
sudo systemctl status backupx
|
||||
sudo journalctl -u backupx -f # 实时日志
|
||||
sudo systemctl restart backupx
|
||||
```
|
||||
|
||||
## 密码重置
|
||||
|
||||
忘记管理员密码时：
|
||||
|
||||
```bash
|
||||
/opt/backupx/backupx reset-password \
|
||||
--username admin \
|
||||
--password 'newpass123' \
|
||||
--config /opt/backupx/config.yaml
|
||||
```
|
||||
|
||||
Docker 等效命令：
|
||||
|
||||
```bash
|
||||
docker exec -it backupx /app/bin/backupx reset-password --username admin --password 'newpass123'
|
||||
```
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: 配置参考
|
||||
description: server.yaml 所有配置项及对应的环境变量。
|
||||
---
|
||||
|
||||
# 配置参考
|
||||
|
||||
BackupX 默认从工作目录加载 `./config.yaml`，可通过 `--config` 指定其他路径。所有配置项都可通过 `BACKUPX_` 前缀环境变量覆盖。
|
||||
|
||||
## 完整配置
|
||||
|
||||
```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 — 内嵌 SQLite
|
||||
|
||||
security:
|
||||
jwt_secret: "" # BACKUPX_SECURITY_JWT_SECRET — 留空自动生成
|
||||
jwt_expires_in: "24h"
|
||||
encryption_key: "" # 用于加密存储配置的 AES-256-GCM 密钥
|
||||
|
||||
backup:
|
||||
temp_dir: "/tmp/backupx" # BACKUPX_BACKUP_TEMP_DIR
|
||||
max_concurrent: 2 # BACKUPX_BACKUP_MAX_CONCURRENT
|
||||
retries: 3 # 单次上传的 rclone 底层重试次数
|
||||
bandwidth_limit: "" # 例如 "10M" 表示限速 10 MB/s
|
||||
|
||||
log:
|
||||
level: "info" # debug | info | warn | error
|
||||
file: "./data/backupx.log"
|
||||
```
|
||||
|
||||
## 密钥生成
|
||||
|
||||
如果首次启动时 `jwt_secret` 或 `encryption_key` 为空，BackupX 会自动生成随机值并写入 `system_configs` 表。请妥善备份 `data/backupx.db`，一旦丢失将导致所有已加密的存储配置失效。
|
||||
|
||||
## 环境变量
|
||||
|
||||
文件和环境变量同时存在时，环境变量优先。配置路径转换规则：小写字母下划线 → 大写字母下划线：
|
||||
|
||||
| 配置项 | 环境变量 |
|
||||
|--------|----------|
|
||||
| `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` |
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Docker 部署
|
||||
description: 生产级 Docker 部署方案，含 compose 配置、宿主目录挂载、环境变量覆盖。
|
||||
---
|
||||
|
||||
# Docker 部署
|
||||
|
||||
BackupX 官方 Docker 镜像 [`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx) 支持多架构（linux/amd64 + linux/arm64）。
|
||||
|
||||
## 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
|
||||
# 挂载需要备份的宿主机目录：
|
||||
- /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:
|
||||
```
|
||||
|
||||
启动：
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## 备份宿主机目录
|
||||
|
||||
想备份宿主机上的文件，需要将对应路径挂载进容器。在 Web UI 创建文件类型任务时，把源路径指向挂载后的容器内路径（如 `/mnt/www`）。
|
||||
|
||||
## 环境变量
|
||||
|
||||
所有配置项都可以通过 `BACKUPX_` 前缀环境变量覆盖：
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- TZ=Asia/Shanghai
|
||||
- BACKUPX_SERVER_PORT=8340
|
||||
- BACKUPX_LOG_LEVEL=debug
|
||||
- BACKUPX_BACKUP_MAX_CONCURRENT=4
|
||||
- BACKUPX_BACKUP_TEMP_DIR=/tmp/backupx
|
||||
```
|
||||
|
||||
完整列表见 [配置参考](./configuration)。
|
||||
|
||||
## 升级
|
||||
|
||||
在 UI **系统设置 → 检查更新** 页面查看是否有新版，然后在宿主机上：
|
||||
|
||||
```bash
|
||||
docker compose pull && docker compose up -d
|
||||
```
|
||||
|
||||
无需手工迁移：BackupX 启动时自动迁移 SQLite schema。
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: Nginx 反向代理
|
||||
description: 通过 Nginx 发布 BackupX（HTTPS + SSE 友好的缓冲配置）。
|
||||
---
|
||||
|
||||
# Nginx 反向代理
|
||||
|
||||
生产环境可用的 Nginx 站点模板：
|
||||
|
||||
```nginx title="/etc/nginx/sites-available/backupx"
|
||||
server {
|
||||
listen 80;
|
||||
server_name backup.example.com;
|
||||
|
||||
# 静态 UI（由 /opt/backupx/web 提供）
|
||||
location / {
|
||||
root /opt/backupx/web;
|
||||
try_files $uri $uri/ /index.html;
|
||||
}
|
||||
|
||||
# API 反向代理
|
||||
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;
|
||||
|
||||
# 大文件上传（用于恢复流程）
|
||||
client_max_body_size 0;
|
||||
|
||||
# 实时日志使用 SSE，必须关闭缓冲
|
||||
proxy_buffering off;
|
||||
proxy_read_timeout 3600s;
|
||||
proxy_send_timeout 3600s;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## certbot 配置 HTTPS
|
||||
|
||||
```bash
|
||||
sudo apt install certbot python3-certbot-nginx
|
||||
sudo certbot --nginx -d backup.example.com
|
||||
```
|
||||
|
||||
certbot 会自动改写配置监听 443 并设置续期。
|
||||
|
||||
:::caution Agent 需要稳定的 URL
|
||||
如果 Master 部署在 HTTPS 后面，远程 Agent 的 `--master` 必须使用公网 HTTPS 地址。自签名证书需加 `--insecure-tls`（仅供测试）。
|
||||
:::
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: 贡献指南
|
||||
description: 如何反馈问题、提出改进、提交 PR。
|
||||
---
|
||||
|
||||
# 贡献指南
|
||||
|
||||
BackupX 使用 Apache License 2.0 开源，欢迎提交 Issue 与 Pull Request。
|
||||
|
||||
## 报告 Bug
|
||||
|
||||
在 [github.com/Awuqing/BackupX/issues](https://github.com/Awuqing/BackupX/issues) 提交 Issue，请附上：
|
||||
|
||||
- BackupX 版本（`backupx --version`）
|
||||
- 部署方式（Docker / 裸机 / 源码）
|
||||
- 相关的备份任务类型和存储后端
|
||||
- 复现步骤
|
||||
- 问题发生时段的 stdout / `backupx.log` 片段
|
||||
|
||||
## 提议改动
|
||||
|
||||
对于重要功能或重构，建议先开 Issue 对齐方案，避免 PR 大改动后被 Review 回退。
|
||||
|
||||
## 提交 PR
|
||||
|
||||
1. Fork 仓库，创建主题分支（如 `fix/windows-path-escape`）
|
||||
2. 执行 `make test` 确认本地全通过
|
||||
3. 保持每个 PR 只做一件事
|
||||
4. Commit message 使用中文，格式 `类型: 简要描述`：
|
||||
- `功能: 新增审计日志模块`
|
||||
- `修复: 目录浏览器无法进入子目录`
|
||||
- `重构: 简化存储目标解密逻辑`
|
||||
- 类型：`功能` / `修复` / `重构` / `文档` / `构建` / `测试`
|
||||
5. PR 标题和正文同样使用中文，描述"为什么"和"怎么做"，而非仅仅"做了什么"
|
||||
|
||||
## 代码规范
|
||||
|
||||
- **Go** — 所有错误必须处理（禁止 `_ = err`），日志使用现有 `zap`，禁止生产路径中出现 `fmt.Println`
|
||||
- **TypeScript** — 严格模式，禁止隐式 any，遵循现有 ESLint/Prettier 配置
|
||||
- **Commit 粒度** — 每个 commit 一件事，不要把顺手的小修改和功能代码混在一起
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: 开发环境
|
||||
description: 搭建 BackupX 本地开发环境 — 后端、前端、测试。
|
||||
---
|
||||
|
||||
# 开发环境
|
||||
|
||||
**环境要求：** Go ≥ 1.25，Node.js ≥ 20，npm。
|
||||
|
||||
## 克隆与依赖
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Awuqing/BackupX.git && cd BackupX
|
||||
cd web && npm install && cd ..
|
||||
```
|
||||
|
||||
## 开发服务
|
||||
|
||||
开两个终端分别跑后端和前端：
|
||||
|
||||
```bash
|
||||
# 终端 1：后端，监听 :8340
|
||||
make dev-server
|
||||
|
||||
# 终端 2：Vite HMR，监听 :5173
|
||||
make dev-web
|
||||
```
|
||||
|
||||
Vite 配置了 `/api` 代理到 `http://127.0.0.1:8340`，浏览器直接访问 `http://localhost:5173`。
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
make test # 运行 Go + Web 全部测试
|
||||
make test-server # 仅 Go
|
||||
make test-web # 仅 Vitest
|
||||
```
|
||||
|
||||
## 生产构建
|
||||
|
||||
```bash
|
||||
make build # server/bin/backupx + web/dist
|
||||
make docker # Docker 镜像
|
||||
make docker-cn # 国内镜像加速构建
|
||||
```
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 组件 | 技术 |
|
||||
|------|------|
|
||||
| **后端** | 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 |
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
BackupX/
|
||||
├── server/ # Go 后端
|
||||
│ ├── cmd/backupx/ # 入口 + 子命令（agent / backint / reset-password）
|
||||
│ ├── internal/
|
||||
│ │ ├── agent/ # Agent CLI 逻辑
|
||||
│ │ ├── app/ # 装配（repo → service → handler）
|
||||
│ │ ├── backup/ # 备份 runner（file / mysql / postgres / sqlite / saphana）
|
||||
│ │ ├── backint/ # SAP HANA Backint 协议
|
||||
│ │ ├── http/ # HTTP handler + router
|
||||
│ │ ├── model/ # GORM 模型
|
||||
│ │ ├── repository/ # 数据访问
|
||||
│ │ ├── service/ # 业务逻辑
|
||||
│ │ └── storage/ # 存储 provider（rclone + 直接 SDK）
|
||||
│ └── pkg/ # 通用工具
|
||||
├── web/ # React 前端（Vite）
|
||||
│ └── src/
|
||||
│ ├── components/
|
||||
│ ├── pages/
|
||||
│ ├── services/
|
||||
│ └── types/
|
||||
├── docs-site/ # 文档站（Docusaurus）
|
||||
├── deploy/ # install.sh / systemd unit / nginx config
|
||||
└── Makefile
|
||||
```
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: 备份类型
|
||||
description: 文件、MySQL、PostgreSQL、SQLite 和 SAP HANA — 各自的能力与配置说明。
|
||||
---
|
||||
|
||||
# 备份类型
|
||||
|
||||
BackupX 支持五种内置备份类型，类型决定了用哪个 runner 执行。
|
||||
|
||||
## 文件 / 目录
|
||||
|
||||
打包（可选 gzip）一个或多个文件系统路径。
|
||||
|
||||
- **源路径** 支持多个（UI 中每行一个）
|
||||
- **排除模式** 支持 gitignore 风格的通配符
|
||||
- 可选跟随符号链接、保留权限
|
||||
- 输出单个 `.tar` 或 `.tar.gz`
|
||||
|
||||
## MySQL
|
||||
|
||||
底层使用 `mysqldump`，需要执行任务的主机（Master 或 Agent）的 `$PATH` 中有 `mysqldump`。
|
||||
|
||||
- **主机 / 端口 / 用户 / 密码 / 数据库** — 支持多库（英文逗号分隔）
|
||||
- 输出：`.sql` 或 `.sql.gz`
|
||||
- 默认参数：`--single-transaction --routines --triggers --events`
|
||||
|
||||
## PostgreSQL
|
||||
|
||||
底层使用 `pg_dump`，连接字段与 MySQL 一致加数据库名。
|
||||
|
||||
## SQLite
|
||||
|
||||
直接复制数据库文件（使用一致性快照），无需外部工具。
|
||||
|
||||
## SAP HANA
|
||||
|
||||
支持两种模式 — 详见 [SAP HANA](./sap-hana) 专题页。
|
||||
|
||||
## 删除行为
|
||||
|
||||
删除备份任务时，BackupX 会从所有存储目标上移除备份产物，但保留备份记录以供审计。删除任务同时拆除其 Cron 定时调度。
|
||||
@@ -0,0 +1,118 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: 多节点集群
|
||||
description: Master-Agent 模式 — 通过 HTTP 长轮询把备份路由到远程服务器。
|
||||
---
|
||||
|
||||
# 多节点集群
|
||||
|
||||
BackupX 支持 Master-Agent 模式：备份任务可以指定在哪个节点执行，Agent 在本地完成备份并直接上传到存储。所有连接都由 Agent 主动发起，所以远程服务器只需要出站 HTTP 访问权限。
|
||||
|
||||
## 架构
|
||||
|
||||
```
|
||||
[Web 控制台] ─── JWT ──→ [Master (backupx)]
|
||||
↑ ↓
|
||||
│ │ HTTP 长轮询（Token 认证）
|
||||
│ ↓
|
||||
[Agent (backupx agent)] ← 运行在远程服务器
|
||||
↓
|
||||
[70+ 存储后端]
|
||||
```
|
||||
|
||||
- **协议** — HTTP 长轮询，Agent 主动发起所有连接
|
||||
- **心跳** — Agent 每 15s 上报一次；Master 超过 45s 未收到心跳即判为离线
|
||||
- **下发** — Master 把 `run_task` 命令写入队列，Agent 轮询拉取
|
||||
- **执行** — Agent 复用 BackupRunner（file / mysql / postgresql / sqlite / saphana）并直接上传到存储
|
||||
- **安全** — 每个节点独立 Token；Agent 不持有 Master 的 JWT 密钥或 AES-256 加密密钥
|
||||
|
||||
## 使用步骤
|
||||
|
||||
### 1. 在 Master 创建节点
|
||||
|
||||
Web 控制台 → **节点管理** → **添加节点**。界面会**一次性**显示 64 字节十六进制令牌，请妥善保存。
|
||||
|
||||
### 2. 在远程服务器部署 Agent
|
||||
|
||||
把 BackupX 二进制上传到目标服务器（与 Master 同一个文件），然后用以下任一方式启动：
|
||||
|
||||
**方式 A：CLI 参数**
|
||||
|
||||
```bash
|
||||
backupx agent --master http://master.example.com:8340 --token <token>
|
||||
```
|
||||
|
||||
**方式 B：配置文件**
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
**方式 C：环境变量**（适合 Docker / systemd）
|
||||
|
||||
```bash
|
||||
BACKUPX_AGENT_MASTER=http://master.example.com:8340 \
|
||||
BACKUPX_AGENT_TOKEN=<token> \
|
||||
backupx agent
|
||||
```
|
||||
|
||||
连接成功后节点在列表中显示为 **在线**。
|
||||
|
||||
### 3. 把任务路由到该节点
|
||||
|
||||
在 **备份任务** 页面新建任务时选择对应节点。任务触发时：
|
||||
|
||||
- 本机 / 未指定（`nodeId=0`）：Master 进程内直接执行
|
||||
- 远程节点：Master 写入命令队列 → Agent 拉取 → Agent 本地执行 → 上传 → 回报
|
||||
|
||||
## 已知限制
|
||||
|
||||
- **Agent 不支持加密备份**：Agent 不持有 Master 的 AES-256 密钥。`encrypt: true` 的任务路由到 Agent 时会直接上报失败
|
||||
- **目录浏览超时**：远程目录浏览通过命令队列做同步 RPC，默认 15s 超时
|
||||
- **派发命令超时**：Agent 领取但未完成的命令超过 10 分钟会被置 `timeout`
|
||||
|
||||
## CLI 参考
|
||||
|
||||
```
|
||||
backupx agent --help
|
||||
-master string Master URL
|
||||
-token string Agent 认证令牌
|
||||
-config string YAML 配置文件路径（优先级高于环境变量）
|
||||
-temp-dir string 本地临时目录（默认 /tmp/backupx-agent）
|
||||
-insecure-tls 跳过 TLS 证书校验（仅测试用）
|
||||
```
|
||||
|
||||
## systemd 单元
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
启用并启动：
|
||||
|
||||
```bash
|
||||
sudo systemctl enable --now backupx-agent
|
||||
sudo journalctl -u backupx-agent -f
|
||||
```
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
title: 通知
|
||||
description: 备份成功或失败时通过邮件、Webhook、Telegram 推送通知。
|
||||
---
|
||||
|
||||
# 通知
|
||||
|
||||
BackupX 支持三种通知渠道，可为每个渠道单独配置成功/失败事件是否推送。
|
||||
|
||||
## 邮件（SMTP）
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| SMTP 主机 / 端口 | 如 `smtp.gmail.com:587` |
|
||||
| 用户名 / 密码 | 建议使用专用应用密码 |
|
||||
| 发件人地址 | 邮件 `From:` 头 |
|
||||
| 收件人列表 | 英文逗号分隔 |
|
||||
| 使用 TLS / StartTLS | 按 SMTP 提供方要求选择 |
|
||||
|
||||
## Webhook
|
||||
|
||||
向任意 URL 发送 JSON POST，请求体结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "backup_result",
|
||||
"task": {"id": 1, "name": "web-files", "type": "file"},
|
||||
"record": {"id": 42, "status": "success", "fileSize": 1048576, "durationSeconds": 12},
|
||||
"error": ""
|
||||
}
|
||||
```
|
||||
|
||||
适合自定义场景：Slack incoming webhook、PagerDuty、自建 API 等。
|
||||
|
||||
## Telegram
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| Bot Token | 在 [@BotFather](https://t.me/BotFather) 创建 |
|
||||
| Chat ID | 数字型，可通过 `/start` 后调 Bot 的 `getUpdates` 获取 |
|
||||
|
||||
## 事件规则
|
||||
|
||||
每个通知配置可以指定触发范围：
|
||||
|
||||
- **仅成功** — 正常运行时静默
|
||||
- **仅失败** — 适合高噪敏感通道
|
||||
- **全部** — 初始化配置时用于验证链路
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: SAP HANA 支持
|
||||
description: 两种 SAP HANA 备份模式 — 控制台托管的 hdbsql Runner 和原生 Backint 协议代理。
|
||||
---
|
||||
|
||||
# SAP HANA 支持
|
||||
|
||||
BackupX 提供两种 SAP HANA 备份模式，按实际运维流程选择。
|
||||
|
||||
## 模式一：hdbsql Runner（控制台托管）
|
||||
|
||||
通过 Web 控制台创建 SAP HANA 备份任务，后端调用 `hdbsql` 执行备份。适合希望 BackupX 来管理调度的场景。
|
||||
|
||||
**源配置支持：**
|
||||
|
||||
| 字段 | 可选值 | 说明 |
|
||||
|------|--------|------|
|
||||
| 备份类型 | `data` / `log` | 数据备份或日志备份 |
|
||||
| 备份级别 | `full` / `incremental` / `differential` | 日志备份时自动禁用 |
|
||||
| 并行通道数 | `1 ~ 32` | 多路径 SQL（`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. 参数文件
|
||||
|
||||
```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. 存储配置（与存储目标 schema 相同）
|
||||
|
||||
```json title="/opt/backupx/storage.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`）。
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: 存储后端
|
||||
description: 70+ 存储后端 — 内置云服务商 + 任意 rclone 后端。
|
||||
---
|
||||
|
||||
# 存储后端
|
||||
|
||||
BackupX 的目标是接入任何你想放置备份文件的地方。
|
||||
|
||||
## 内置后端
|
||||
|
||||
| 类型 | 必填字段 |
|
||||
|------|---------|
|
||||
| **阿里云 OSS** | Region + AccessKey ID/Secret + Bucket（endpoint 自动组装） |
|
||||
| **腾讯云 COS** | Region + SecretId/SecretKey + Bucket（格式 `name-appid`） |
|
||||
| **七牛云 Kodo** | Region + AccessKey/SecretKey + Bucket |
|
||||
| **S3 兼容** | Endpoint + AccessKey + Bucket |
|
||||
| **Google Drive** | Client ID/Secret + OAuth 授权 |
|
||||
| **WebDAV** | 地址 + 用户名/密码 |
|
||||
| **FTP / FTPS** | 主机 + 端口 + 用户名/密码 |
|
||||
| **本地磁盘** | 目标目录（绝对路径） |
|
||||
|
||||
## Rclone 后端
|
||||
|
||||
每一种 [rclone 后端](https://rclone.org/overview/) 都作为一等公民暴露 — SFTP、Azure Blob、Dropbox、OneDrive、Backblaze B2、Wasabi、pCloud、HDFS 等。
|
||||
|
||||
- 表单字段分为 **必填** 和 **高级**（高级默认折叠）
|
||||
- 校验与连接测试复用 rclone 自带的探测
|
||||
|
||||
## 一个任务多个目标
|
||||
|
||||
一个备份任务可以并行上传到多个存储目标。每个目标获得相同的产物，每目标的状态会单独记录：
|
||||
|
||||
- 成功：storage_path + 文件大小
|
||||
- 失败：错误信息
|
||||
|
||||
如果任一目标在重试后仍失败，整条记录的状态为 `failed`，但已成功的目标产物会被保留（不回滚）。
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: 安装
|
||||
description: 通过 Docker、预编译包或源码安装 BackupX。
|
||||
---
|
||||
|
||||
# 安装
|
||||
|
||||
BackupX 以单个静态二进制发布。三种安装方式，按实际环境选一种。
|
||||
|
||||
## Docker（推荐）
|
||||
|
||||
无需克隆仓库：
|
||||
|
||||
```bash
|
||||
docker run -d --name backupx \
|
||||
-p 8340:8340 \
|
||||
-v backupx-data:/app/data \
|
||||
awuqing/backupx:latest
|
||||
```
|
||||
|
||||
或使用 `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
|
||||
# 挂载需要备份的宿主机目录（按需添加）：
|
||||
# - /var/www:/mnt/www:ro
|
||||
# - /etc/nginx:/mnt/nginx-conf:ro
|
||||
environment:
|
||||
- TZ=Asia/Shanghai
|
||||
|
||||
volumes:
|
||||
backupx-data:
|
||||
```
|
||||
|
||||
Docker Hub：[`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx)，支持 linux/amd64 和 linux/arm64。
|
||||
|
||||
## 预编译包（裸机）
|
||||
|
||||
从 [Releases 页面](https://github.com/Awuqing/BackupX/releases) 下载对应平台的压缩包，执行安装脚本：
|
||||
|
||||
```bash
|
||||
tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
|
||||
sudo ./install.sh # 创建系统用户、安装到 /opt/backupx、配置 systemd + Nginx
|
||||
```
|
||||
|
||||
安装脚本会自动：
|
||||
|
||||
1. 创建 `backupx` 系统用户
|
||||
2. 安装二进制到 `/opt/backupx/backupx`
|
||||
3. 生成 `/opt/backupx/config.yaml`（含安全默认值）
|
||||
4. 注册并启用 `backupx.service` systemd 单元
|
||||
5. （可选）配置 Nginx 反向代理
|
||||
|
||||
## 从源码构建
|
||||
|
||||
依赖：Go ≥ 1.25，Node.js ≥ 20。
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Awuqing/BackupX.git && cd BackupX
|
||||
make build
|
||||
# 或使用国内镜像加速构建 Docker
|
||||
make docker-cn
|
||||
```
|
||||
|
||||
`make build` 完成后，二进制位于 `server/bin/backupx`，构建好的 Web UI 位于 `web/dist/`。
|
||||
|
||||
## 验证安装
|
||||
|
||||
```bash
|
||||
backupx --version # 输出如 v1.6.0
|
||||
```
|
||||
|
||||
打开浏览器访问 `http://your-server:8340`，会进入初始化管理员账户页面。
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: 快速开始
|
||||
description: 部署 BackupX、添加存储目标、创建第一个备份任务。
|
||||
---
|
||||
|
||||
# 快速开始
|
||||
|
||||
完成 [安装](./installation) 后，花五分钟跑通第一个备份。
|
||||
|
||||
## 1. 打开控制台
|
||||
|
||||
浏览器访问 `http://your-server:8340`。首次打开会引导创建管理员账户。
|
||||
|
||||
## 2. 添加存储目标
|
||||
|
||||
进入 **存储目标 → 添加**，选择类型并填写凭证：
|
||||
|
||||
| 类型 | 需要填写 |
|
||||
|------|---------|
|
||||
| 阿里云 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 等 | 选择对应类型后填写必填项，高级配置默认折叠 |
|
||||
|
||||
:::tip
|
||||
国内云厂商只需填 Region 和 AccessKey，系统自动组装 Endpoint。Rclone 类型的配置项按"必填 / 可选"分层展示，高级选项默认折叠。
|
||||
:::
|
||||
|
||||
添加后点击 **测试连接** 确认配置正确。
|
||||
|
||||
## 3. 创建备份任务
|
||||
|
||||
进入 **备份任务 → 新建**，三步完成：
|
||||
|
||||
1. **基础信息** — 任务名称、备份类型、Cron 表达式（留空则仅手动执行）
|
||||
2. **源配置** — 文件备份选择源路径（支持多个），数据库备份填写连接信息
|
||||
3. **存储与策略** — 选择存储目标（支持多个）、压缩策略、保留天数、是否加密
|
||||
|
||||
保存后可点击 **立即执行** 测试，**备份记录** 页面实时查看执行日志。
|
||||
|
||||
:::note
|
||||
删除备份任务时会自动清理远端存储上的备份文件，但保留备份记录以供审计追溯。
|
||||
:::
|
||||
|
||||
## 4. 配置通知（可选）
|
||||
|
||||
**通知配置** 页面支持邮件、Webhook、Telegram 三种方式，可分别配置成功/失败时是否推送。
|
||||
|
||||
## 继续阅读
|
||||
|
||||
- 了解 [备份类型](/docs/features/backup-types) 和 [存储后端](/docs/features/storage-backends)
|
||||
- 使用 SAP HANA？参考 [SAP HANA 支持](/docs/features/sap-hana)
|
||||
- 管理多台服务器？参考 [多节点集群](/docs/features/multi-node)
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
id: intro
|
||||
slug: /intro
|
||||
sidebar_position: 1
|
||||
title: 项目简介
|
||||
description: BackupX——自托管服务器备份管理平台概览。
|
||||
---
|
||||
|
||||
# BackupX
|
||||
|
||||
**BackupX** 是一款自托管的服务器备份管理平台：一个二进制，一条命令，管好所有服务器的所有备份。
|
||||
|
||||
- **单二进制 + 内嵌 SQLite** — 不依赖外部数据库或编排器
|
||||
- **文件、数据库、SAP HANA** — 统一管理，可视化调度
|
||||
- **70+ 存储后端** — 阿里云 OSS、腾讯云 COS、七牛、S3、Google Drive、WebDAV、FTP，以及通过 rclone 接入的 SFTP / Azure Blob / Dropbox / OneDrive 等数十种
|
||||
- **多节点集群** — Master-Agent 模式跨服务器管理备份，Agent 在本地执行并直接上传到存储
|
||||
- **默认安全** — JWT 认证、bcrypt、AES-256-GCM 加密配置、可选备份加密、完整审计日志
|
||||
|
||||
## 架构概览
|
||||
|
||||
```
|
||||
[Web 控制台] ─── JWT ──→ [Master (backupx)]
|
||||
│
|
||||
│ HTTP 长轮询（Token 认证）
|
||||
▼
|
||||
[Agent (backupx agent)]
|
||||
│
|
||||
▼
|
||||
[70+ 存储后端]
|
||||
```
|
||||
|
||||
路由到本机的任务在 Master 进程内直接执行；派到远程节点的任务通过命令队列下发，由 Agent 在本地执行。Agent 只发起出站 HTTP 连接 — 不需要任何反向连通性。
|
||||
|
||||
## 下一步
|
||||
|
||||
- **第一次使用 BackupX？** 先看 [快速开始](/docs/getting-started/quick-start)
|
||||
- **生产部署？** 参考 [部署指南](/docs/deployment/docker)
|
||||
- **SAP HANA 用户？** 支持 `hdbsql` Runner 和原生 Backint 两种模式 — 详见 [SAP HANA](/docs/features/sap-hana)
|
||||
- **管理多台服务器？** 参考 [多节点集群](/docs/features/multi-node)
|
||||
- **程序化集成？** 参考 [API 参考](/docs/reference/api)
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: API 参考
|
||||
description: REST API 端点 — 统一以 /api 为前缀，使用 JWT Bearer 认证。
|
||||
---
|
||||
|
||||
# API 参考
|
||||
|
||||
所有端点都以 `/api` 为前缀，使用 JWT Bearer 令牌认证（通过 `POST /api/auth/login` 获取）。Agent 专用端点使用 `X-Agent-Token` 头认证。
|
||||
|
||||
## 认证
|
||||
|
||||
| 端点 | 说明 |
|
||||
|------|------|
|
||||
| `POST /api/auth/setup` | 初始化首个管理员（仅当系统无任何用户时） |
|
||||
| `POST /api/auth/login` | 登录，返回 JWT |
|
||||
| `PUT /api/auth/password` | 修改密码 |
|
||||
|
||||
## 备份任务
|
||||
|
||||
| 端点 | 说明 |
|
||||
|------|------|
|
||||
| `GET /api/backup/tasks` | 列表 |
|
||||
| `POST /api/backup/tasks` | 创建 |
|
||||
| `GET /api/backup/tasks/:id` | 详情 |
|
||||
| `PUT /api/backup/tasks/:id` | 更新 |
|
||||
| `DELETE /api/backup/tasks/:id` | 删除 |
|
||||
| `PUT /api/backup/tasks/:id/toggle` | 启用 / 禁用 |
|
||||
| `POST /api/backup/tasks/:id/run` | 手动执行 |
|
||||
|
||||
## 备份记录
|
||||
|
||||
| 端点 | 说明 |
|
||||
|------|------|
|
||||
| `GET /api/backup/records` | 列表（支持筛选） |
|
||||
| `GET /api/backup/records/:id/logs/stream` | 实时日志（SSE） |
|
||||
| `GET /api/backup/records/:id/download` | 下载备份 |
|
||||
| `POST /api/backup/records/:id/restore` | 恢复到原始源 |
|
||||
|
||||
## 存储目标
|
||||
|
||||
| 端点 | 说明 |
|
||||
|------|------|
|
||||
| `GET /api/storage-targets` | 列表 |
|
||||
| `POST /api/storage-targets` | 添加 |
|
||||
| `POST /api/storage-targets/test` | 用待审核配置测试连接 |
|
||||
| `GET /api/storage-targets/rclone/backends` | 列出可用 rclone 后端 |
|
||||
|
||||
## 节点（集群）
|
||||
|
||||
| 端点 | 说明 |
|
||||
|------|------|
|
||||
| `GET /api/nodes` | 节点列表 |
|
||||
| `POST /api/nodes` | 创建节点并返回 Token |
|
||||
| `PUT /api/nodes/:id` | 重命名 |
|
||||
| `DELETE /api/nodes/:id` | 删除（有关联任务时会被拒绝） |
|
||||
| `GET /api/nodes/:id/fs/list` | 浏览目录（远程节点走异步 RPC） |
|
||||
|
||||
## Agent 协议（X-Agent-Token）
|
||||
|
||||
| 端点 | 说明 |
|
||||
|------|------|
|
||||
| `POST /api/agent/heartbeat` | 上报心跳 |
|
||||
| `POST /api/agent/commands/poll` | 领取一条待执行命令 |
|
||||
| `POST /api/agent/commands/:id/result` | 上报命令结果 |
|
||||
| `GET /api/agent/tasks/:id` | 拉取任务规格（含解密后的存储配置） |
|
||||
| `POST /api/agent/records/:id` | 追加日志 / 更新记录状态 |
|
||||
|
||||
## 通知
|
||||
|
||||
| 端点 | 说明 |
|
||||
|------|------|
|
||||
| `GET /api/notifications` | 列表 |
|
||||
| `POST /api/notifications` | 创建 |
|
||||
|
||||
## 仪表盘 / 审计 / 系统
|
||||
|
||||
| 端点 | 说明 |
|
||||
|------|------|
|
||||
| `GET /api/dashboard/stats` | 概览统计 |
|
||||
| `GET /api/audit-logs` | 审计日志 |
|
||||
| `GET /api/system/info` | 系统信息 |
|
||||
| `GET /api/system/update-check` | 检查是否有新版本 |
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: CLI 参考
|
||||
description: backupx 子命令 — server / agent / backint / reset-password。
|
||||
---
|
||||
|
||||
# CLI 参考
|
||||
|
||||
`backupx` 二进制内置多个子命令。无子命令时默认启动主服务进程。
|
||||
|
||||
## `backupx`（默认：服务进程）
|
||||
|
||||
```bash
|
||||
backupx --config /opt/backupx/config.yaml
|
||||
backupx --version
|
||||
```
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `--config <path>` | 配置文件路径（默认 `./config.yaml`） |
|
||||
| `--version` | 打印版本后退出 |
|
||||
|
||||
## `backupx agent`
|
||||
|
||||
以 Agent 模式运行，连接到 Master。详见 [多节点集群](../features/multi-node)。
|
||||
|
||||
```bash
|
||||
backupx agent --master http://master:8340 --token <token>
|
||||
```
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `--master <url>` | Master URL |
|
||||
| `--token <token>` | Agent 认证令牌 |
|
||||
| `--config <path>` | YAML 配置文件（优先级高于环境变量） |
|
||||
| `--temp-dir <path>` | 本地临时目录（默认 `/tmp/backupx-agent`） |
|
||||
| `--insecure-tls` | 跳过 TLS 校验（仅测试用） |
|
||||
|
||||
环境变量：`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 协议代理，详见 [SAP HANA 支持](../features/sap-hana)。
|
||||
|
||||
```bash
|
||||
backupx backint -f <function> -i <input> -o <output> -p <params>
|
||||
```
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `-f <fn>` | `backup` / `restore` / `inquire` / `delete` |
|
||||
| `-i <path>` | 输入文件 |
|
||||
| `-o <path>` | 输出文件 |
|
||||
| `-p <path>` | 参数文件 |
|
||||
| `-u / -c / -l / -v` | 接收但忽略（兼容 SAP 约定） |
|
||||
|
||||
## `backupx reset-password`
|
||||
|
||||
直接在 SQLite 中重置管理员密码，无需重启服务。
|
||||
|
||||
```bash
|
||||
backupx reset-password --username admin --password 'newpass123' [--config /path/to/config.yaml]
|
||||
```
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `--username` | 目标用户名（默认 `admin`） |
|
||||
| `--password` | 新密码（最少 8 字符，必填） |
|
||||
| `--config` | 配置文件路径（用于定位数据库文件） |
|
||||
Reference in New Issue
Block a user