feat: 解决 CDC 去重、集中备份与首次初始化问题 (#105)

实现 CDC 内容寻址仓库、远程 Agent 中央中转备份与首次初始化体验，并补充安全校验、测试及双语文档。 Closes #94 Closes #101 Closes #104
2026-09-04 23:16:41 +08:00 · 2026-08-07 23:01:29 +08:00
parent 50ce6587d8
commit 00151e466c
74 changed files with 4507 additions and 400 deletions
@@ -10,20 +10,21 @@ description: 从预编译包或源码部署 BackupX（systemd + Nginx）。

 ```bash
 # 下载对应平台的压缩包
-curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-v1.6.0-linux-amd64.tar.gz
+curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-linux-amd64.tar.gz

 # 解压并安装
-tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
+tar xzf backupx-linux-amd64.tar.gz && cd backupx-*-linux-amd64
 sudo ./install.sh
 ```

 安装脚本自动完成以下步骤：

 1. 创建系统用户 `backupx`
-2. 复制二进制到 `/opt/backupx/`
-3. 生成默认 `config.yaml`（含安全的 JWT/加密密钥）
+2. 复制二进制到 `/opt/backupx/bin/backupx`，并把 Web 控制台复制到 `/opt/backupx/web`
+3. 把默认配置安装到 `/etc/backupx/config.yaml`
 4. 安装并启用 `backupx.service` systemd 单元
 5. （可选）生成 Nginx 站点配置 — 参见 [Nginx 反向代理](./nginx)
+6. 验证首次初始化接口就绪后才报告安装成功

 如果要部署多节点集群，安装后请编辑 `/etc/backupx/config.yaml`，设置远程 Agent 可访问到的 Master URL：

@@ -63,11 +64,13 @@ After=network.target
 [Service]
 Type=simple
 User=backupx
+Group=backupx
 WorkingDirectory=/opt/backupx
-ExecStart=/opt/backupx/backupx --config /opt/backupx/config.yaml
+ExecStart=/opt/backupx/bin/backupx -config /etc/backupx/config.yaml
 Restart=on-failure
-RestartSec=5s
-LimitNOFILE=65536
+RestartSec=5
+NoNewPrivileges=true
+LimitNOFILE=65535

 [Install]
 WantedBy=multi-user.target
@@ -79,17 +82,20 @@ WantedBy=multi-user.target
 sudo systemctl status backupx
 sudo journalctl -u backupx -f    # 实时日志
 sudo systemctl restart backupx
+curl -fsS http://127.0.0.1:8340/api/auth/setup/status
 ```

+访问 `http://your-server:8340`，可按需切换到 English，然后在“系统初始化 / System setup”页面创建首个管理员。若监听端口不是默认值，请为安装脚本传入对应的 `HEALTH_URL`。
+
 ## 密码重置

 忘记管理员密码时：

 ```bash
-/opt/backupx/backupx reset-password \
+/opt/backupx/bin/backupx reset-password \
  --username admin \
  --password 'newpass123' \
-  --config /opt/backupx/config.yaml
+  --config /etc/backupx/config.yaml
 ```

 Docker 等效命令：
@@ -12,12 +12,22 @@ BackupX 支持五种内置备份类型，类型决定了用哪个 runner 执行

 ## 文件 / 目录

-打包（可选 gzip）一个或多个文件系统路径。
+文件任务提供三种备份模式：
+
+- **全量归档** — 每次生成一份可独立使用的 tar 产物
+- **差异归档** — 只保存相对当前全量基线的变化，并按周期刷新全量基线
+- **CDC 去重仓库** — 按稳定的 512 KiB / 1 MiB / 4 MiB 内容边界切块，将新块合并到不可变的 32 MiB pack，每次运行只新增一份小型快照清单
+
+CDC 仓库会在不同文件、不同快照之间复用相同内容。完整恢复、选择性恢复、完整性校验、下载为 tar、保留策略和垃圾回收都通过仓库索引定位分块。压缩与加密按块执行；启用加密时使用带密钥的块 ID，不暴露明文哈希。
+
+当前仓库索引采用单写者模型，因此 CDC 模式仅在 Master 本机执行。如需保存多份完整仓库，请在任务中直接多选主存储目标。对象级副本复制会被禁用，因为只有快照清单、没有共享 pack 与索引并不是完整备份。
+
+文件任务的通用选项：

 - **源路径** 支持多个（UI 中每行一个）
 - **排除模式** 支持 gitignore 风格的通配符
 - 可选跟随符号链接、保留权限
- 输出单个 `.tar` 或 `.tar.gz`
+- 全量与差异模式输出 `.tar`、`.tar.gz` 或 `.tar.zst`

 ## MySQL

@@ -26,6 +26,27 @@ BackupX 支持 Master-Agent 模式：备份任务可以指定在哪个节点执
 - **执行** — Agent 复用 BackupRunner（file / mysql / postgresql / sqlite / saphana）并直接上传到存储
 - **安全** — 每个节点独立 Token；Agent 不持有 Master 的 JWT 密钥或 AES-256 加密密钥

+## 把 B/C/D 服务器集中备份到 M
+
+Master 作为控制面，每台源服务器安装一个 Agent。任务里的 **源服务器** 决定源路径和数据库工具在哪台机器解析，**存储目标** 决定备份产物最终保留在哪里。
+
+BackupX 会根据目标类型选择数据路径：
+
+| 目标 | 数据路径 |
+| --- | --- |
+| S3、WebDAV、FTP、云盘或其他网络后端 | Agent 直接流式上传到目标 |
+| 启用 **远程备份经 Master 中转** 的 `local_disk`（例如通过 NFS 挂载的存储服务器 M） | Agent 通过认证后的 Master API 流式中转，由 Master 写入配置目录 |
+
+中转过程不会在 Master 上额外落一份完整临时文件。把 Master 本地磁盘中的备份恢复到源 Agent 时会走反向流式通道。Agent 与 Master 之间跨越不可信网络时必须配置 HTTPS。
+
+典型的 `A → {B,C,D} → M` 拓扑按以下步骤配置：
+
+1. 在 A 运行 BackupX Master；如果 M 以 NFS 等文件系统提供存储，先把 M 挂载到 A。
+2. 为该挂载点创建 `local_disk` 目标并保持 **远程备份经 Master 中转** 开启；如果 M 提供 S3/WebDAV，也可直接创建对应网络目标。升级前已有的本地磁盘目标会继续沿用 Agent 本机落盘，手动开启该选项后才切换到中央目录。
+3. 从 **节点管理** 分别在 B、C、D 安装 Agent。
+4. 为每台源服务器创建任务，在 **源服务器** 选择 B/C/D，浏览该服务器的路径，再把 M 选为存储目标。相同任务也可用源服务器池标签动态调度。
+5. 在备份记录中检查逐目标结果。Master 本地磁盘目标会记录 `master_relay` 中转模式，网络后端仍为 `direct` 直传。
+
 ## 一键部署步骤

 ### 0. 为生产集群设置 Master 对外 URL
@@ -78,7 +99,7 @@ Docker 模式使用同一组环境变量约定：`BACKUPX_AGENT_MASTER`、`BACKU

 ### 5. 把任务路由到该节点

-在 **备份任务** 页面新建任务时选择对应节点。任务触发时：
+在 **备份任务** 页面新建任务时选择对应源服务器。任务触发时：

 - 本机 / 未指定（`nodeId=0`）：Master 进程内直接执行
 - 远程节点：Master 写入命令队列 → Agent 拉取 → Agent 本地执行 → 上传 → 回报
@@ -19,7 +19,9 @@ BackupX 的目标是接入任何你想放置备份文件的地方。
 | **Google Drive** | Client ID/Secret + OAuth 授权 |
 | **WebDAV** | 地址 + 用户名/密码 |
 | **FTP / FTPS** | 主机 + 端口 + 用户名/密码 |
-| **本地磁盘** | 目标目录（绝对路径） |
+| **本地磁盘** | 目标目录（绝对路径）+ 可选的远程 Agent 经 Master 中转 |
+
+新建本地磁盘目标默认开启 **远程备份经 Master 中转**。开启时，配置目录属于 Master，挂载到 Master 的存储服务器可集中接收多台源 Agent 的备份；如果该路径本就属于各 Agent，请关闭此选项。升级前已有目标保持原来的 Agent 本机落盘行为，只有显式开启后才会切换。

 ## Rclone 后端

@@ -55,10 +55,11 @@ sudo ./install.sh        # 创建系统用户、安装到 /opt/backupx、配置
 安装脚本会自动：

 1. 创建 `backupx` 系统用户
-2. 安装二进制到 `/opt/backupx/backupx`
-3. 生成 `/opt/backupx/config.yaml`（含安全默认值）
+2. 安装二进制到 `/opt/backupx/bin/backupx`，并把 Web 控制台安装到 `/opt/backupx/web`
+3. 生成 `/etc/backupx/config.yaml`（含安全默认值）
 4. 注册并启用 `backupx.service` systemd 单元
 5. （可选）配置 Nginx 反向代理
+6. 等待 `/api/auth/setup/status` 就绪；启动失败时输出 systemd 诊断并返回非零状态

 ## 从源码构建

@@ -67,16 +68,17 @@ sudo ./install.sh        # 创建系统用户、安装到 /opt/backupx、配置
 ```bash
 git clone https://github.com/Awuqing/BackupX.git && cd BackupX
 make build
-# 或使用国内镜像加速构建 Docker
-make docker-cn
+sudo ./deploy/install.sh
 ```

 `make build` 完成后，二进制位于 `server/bin/backupx`，构建好的 Web UI 位于 `web/dist/`。
+安装脚本会直接使用这两个路径，不需要 Docker 运行时。如果已有配置修改了默认端口，可覆盖就绪检查地址，例如：`sudo HEALTH_URL=http://127.0.0.1:9000/api/auth/setup/status ./deploy/install.sh`。

 ## 验证安装

 ```bash
-backupx --version           # 输出如 v1.6.0
+/opt/backupx/bin/backupx --version
+curl -fsS http://127.0.0.1:8340/api/auth/setup/status
 ```

-打开浏览器访问 `http://your-server:8340`，会进入初始化管理员账户页面。
+打开浏览器访问 `http://your-server:8340`，可在右上角选择 **中文** 或 **English**。全新数据库会显示“系统初始化 / System setup”，在这里创建首个管理员用户名和密码。如果没有出现初始化表单，请先重试上面的状态接口，不要直接尝试登录。