mirror of
https://github.com/Awuqing/BackupX.git
synced 2026-06-07 18:59:34 +08:00
文档: 更新多节点文档，描述一键部署向导（中英双份）
- Walkthrough 章节改写为三步向导流程 - 新增 Token 轮换说明、批量部署说明 - 对应 Issue #43 功能
This commit is contained in:
Awuqing
@@ -28,45 +28,42 @@ BackupX supports Master-Agent mode: backup tasks can be routed to specific nodes
|
|||||||
|
|
||||||
## Walkthrough
|
## Walkthrough
|
||||||
|
|
||||||
### 1. Create a node on Master
|
### 1. Open the install wizard
|
||||||
|
|
||||||
Web Console → **Node Management** → **Add Node**. A 64-byte hex token is shown **once** — keep it safe.
|
In the Web Console → **Node Management** → **Add Node**. You'll see a three-step wizard.
|
||||||
|
|
||||||
### 2. Deploy the Agent on a remote host
|
- **Step 1 — Node info.** Give the node a name, or switch to batch mode and paste multiple names (one per line, max 50).
|
||||||
|
- **Step 2 — Deploy options.** Pick install mode (`systemd` recommended, `docker`, or `foreground` for debugging), architecture (auto-detect by default), agent version (defaults to the master's version), TTL for the install link (5 min / 15 min / 1 h / 24 h), and download source (`github` direct, or the `ghproxy` mirror for mainland China).
|
||||||
|
- **Step 3 — Copy the command.** A single `curl ... | sudo sh` line is shown with a live countdown. Click copy, paste into the target machine, and run with root privileges.
|
||||||
|
|
||||||
Upload the BackupX binary (same file as Master) to the target host, then start the Agent:
|
### 2. One-line install on the target host
|
||||||
|
|
||||||
**Option A: CLI flags**
|
Example (systemd mode):
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
backupx agent --master http://master.example.com:8340 --token <token>
|
curl -fsSL https://master.example.com/install/Xk3p9...vM | sudo sh
|
||||||
```
|
```
|
||||||
|
|
||||||
**Option B: config file**
|
The script runs automatically and:
|
||||||
|
|
||||||
```yaml title="/etc/backupx/agent.yaml"
|
1. Detects OS and architecture (`uname -m`)
|
||||||
master: http://master.example.com:8340
|
2. Downloads the matching `backupx` binary from GitHub Release (or the ghproxy mirror)
|
||||||
token: <token>
|
3. Installs to `/opt/backupx-agent` and creates a `backupx` system user
|
||||||
heartbeatInterval: 15s
|
4. Writes `/etc/systemd/system/backupx-agent.service` with the token baked into environment variables
|
||||||
pollInterval: 5s
|
5. Runs `systemctl enable --now backupx-agent`
|
||||||
tempDir: /var/lib/backupx-agent
|
6. Polls `/api/v1/agent/self` until the master confirms `status: online` (up to 30 s)
|
||||||
```
|
|
||||||
|
|
||||||
```bash
|
Reruns are idempotent — to upgrade or re-provision, simply generate a new install command and run it again. The one-time install link expires after its TTL or after first consumption, whichever is sooner.
|
||||||
backupx agent --config /etc/backupx/agent.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
**Option C: environment variables** (Docker / systemd friendly)
|
### 3. Rotate agent tokens at any time
|
||||||
|
|
||||||
```bash
|
Go to the node's action menu (︙) → **Rotate Token**. The new token is shown once and the old token remains valid for 24 h, allowing rolling restarts without downtime. After 24 h, the old token is rejected.
|
||||||
BACKUPX_AGENT_MASTER=http://master.example.com:8340 \
|
|
||||||
BACKUPX_AGENT_TOKEN=<token> \
|
|
||||||
backupx agent
|
|
||||||
```
|
|
||||||
|
|
||||||
Once connected, the node shows as **online** in the list.
|
### 4. Batch deployment
|
||||||
|
|
||||||
### 3. Route a task to the node
|
In Step 1 choose "Batch" and paste node names (one per line, max 50). Step 3 shows a table with one command per node plus a **Download .sh** button that bundles all commands into a shell script, convenient for SSH loops or Ansible tasks.
|
||||||
|
|
||||||
|
### 5. Route a task to the node
|
||||||
|
|
||||||
In the **Backup Tasks** page, pick the target node when creating the task. When the task runs:
|
In the **Backup Tasks** page, pick the target node when creating the task. When the task runs:
|
||||||
|
|
||||||
|
|||||||
@@ -26,47 +26,44 @@ BackupX 支持 Master-Agent 模式：备份任务可以指定在哪个节点执
|
|||||||
- **执行** — Agent 复用 BackupRunner（file / mysql / postgresql / sqlite / saphana）并直接上传到存储
|
- **执行** — Agent 复用 BackupRunner（file / mysql / postgresql / sqlite / saphana）并直接上传到存储
|
||||||
- **安全** — 每个节点独立 Token；Agent 不持有 Master 的 JWT 密钥或 AES-256 加密密钥
|
- **安全** — 每个节点独立 Token；Agent 不持有 Master 的 JWT 密钥或 AES-256 加密密钥
|
||||||
|
|
||||||
## 使用步骤
|
## 一键部署步骤
|
||||||
|
|
||||||
### 1. 在 Master 创建节点
|
### 1. 打开安装向导
|
||||||
|
|
||||||
Web 控制台 → **节点管理** → **添加节点**。界面会**一次性**显示 64 字节十六进制令牌，请妥善保存。
|
Web 控制台 → **节点管理** → **添加节点**，打开三步向导：
|
||||||
|
|
||||||
### 2. 在远程服务器部署 Agent
|
- **第一步 · 节点信息**：填写节点名称；或切换"批量创建"粘贴多行名称（每行一个，最多 50 个）
|
||||||
|
- **第二步 · 部署参数**：选择安装模式（`systemd` 推荐、`Docker`、`前台运行` 调试用）、架构（默认自动检测）、Agent 版本（默认跟随 Master 版本）、有效期（5 分钟 / 15 分钟 / 1 小时 / 24 小时）、下载源（`GitHub` 直连或 `ghproxy` 镜像，国内服务器建议后者）
|
||||||
|
- **第三步 · 安装命令**：一行 `curl ... | sudo sh` 命令 + 实时倒计时。点击复制，粘贴到目标机以 root 权限执行
|
||||||
|
|
||||||
把 BackupX 二进制上传到目标服务器（与 Master 同一个文件），然后用以下任一方式启动：
|
### 2. 目标机一条命令完成
|
||||||
|
|
||||||
**方式 A：CLI 参数**
|
示例（systemd 模式）：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
backupx agent --master http://master.example.com:8340 --token <token>
|
curl -fsSL https://master.example.com/install/Xk3p9...vM | sudo sh
|
||||||
```
|
```
|
||||||
|
|
||||||
**方式 B：配置文件**
|
脚本会自动：
|
||||||
|
|
||||||
```yaml title="/etc/backupx/agent.yaml"
|
1. 检测操作系统与架构（`uname -m`）
|
||||||
master: http://master.example.com:8340
|
2. 从 GitHub Release（或 ghproxy 镜像）下载匹配的 `backupx` 二进制
|
||||||
token: <token>
|
3. 安装到 `/opt/backupx-agent`，创建系统用户 `backupx`
|
||||||
heartbeatInterval: 15s
|
4. 写入 `/etc/systemd/system/backupx-agent.service`（token 已烧入环境变量）
|
||||||
pollInterval: 5s
|
5. 执行 `systemctl enable --now backupx-agent`
|
||||||
tempDir: /var/lib/backupx-agent
|
6. 轮询 `/api/v1/agent/self`，直到 Master 确认 `status: online`（最多 30 秒）
|
||||||
```
|
|
||||||
|
|
||||||
```bash
|
脚本是幂等的：升级或重装只需重新生成一条安装命令再跑一次。一次性安装链接在 TTL 到期或被首次消费后立即作废。
|
||||||
backupx agent --config /etc/backupx/agent.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
**方式 C：环境变量**（适合 Docker / systemd）
|
### 3. 随时轮换 Agent Token
|
||||||
|
|
||||||
```bash
|
节点操作列（︙）→ **重新生成 Token**。新 Token 一次性显示，旧 Token 24 小时内仍有效，便于滚动替换无需停机。24 小时后旧 Token 被拒绝。
|
||||||
BACKUPX_AGENT_MASTER=http://master.example.com:8340 \
|
|
||||||
BACKUPX_AGENT_TOKEN=<token> \
|
|
||||||
backupx agent
|
|
||||||
```
|
|
||||||
|
|
||||||
连接成功后节点在列表中显示为 **在线**。
|
### 4. 批量部署
|
||||||
|
|
||||||
### 3. 把任务路由到该节点
|
第一步选"批量创建"粘贴节点名（每行一个，最多 50 个）。第三步显示每个节点对应的命令表格，底部「导出 .sh」可打包为单个 shell 文件，方便 SSH 循环或 Ansible 任务。
|
||||||
|
|
||||||
|
### 5. 把任务路由到该节点
|
||||||
|
|
||||||
在 **备份任务** 页面新建任务时选择对应节点。任务触发时：
|
在 **备份任务** 页面新建任务时选择对应节点。任务触发时：
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user