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

README.md

@@ -60,11 +60,15 @@ docker run -d --name backupx -p 8340:8340 -v backupx-data:/app/data awuqing/back
 # 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
+
+# Or build and install on bare metal without Docker
+git clone https://github.com/Awuqing/BackupX.git && cd BackupX
+make build && sudo ./deploy/install.sh
 ```
 
 For ARM64 hosts, use `backupx-linux-arm64.tar.gz`. The archive contains `backupx`, `web/`, `config.example.yaml`, and `install.sh`; run `install.sh` from the extracted directory.
 
-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).
+Open `http://your-server:8340`, choose English or Chinese on the setup screen, create the first administrator account, then follow the [5-minute Quick Start](https://awuqing.github.io/BackupX/docs/getting-started/quick-start).
 
 ## Documentation
 

README.zh-CN.md

@@ -60,11 +60,15 @@ docker run -d --name backupx -p 8340:8340 -v backupx-data:/app/data awuqing/back
 # 或使用预编译包
 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）
+git clone https://github.com/Awuqing/BackupX.git && cd BackupX
+make build && sudo ./deploy/install.sh
 ```
 
 ARM64 主机请下载 `backupx-linux-arm64.tar.gz`。预编译包内包含 `backupx`、`web/`、`config.example.yaml` 和 `install.sh`，请在解压后的目录内执行 `install.sh`。
 
-打开 `http://your-server:8340`，创建管理员账户，按 [5 分钟快速开始](https://awuqing.github.io/BackupX/zh-Hans/docs/getting-started/quick-start) 完成首次备份。
+打开 `http://your-server:8340`，在初始化页选择中文或 English 并创建首个管理员账户，按 [5 分钟快速开始](https://awuqing.github.io/BackupX/zh-Hans/docs/getting-started/quick-start) 完成首次备份。
 
 ## 文档
 

deploy/install.sh

@@ -14,7 +14,13 @@ if [ -f "$SCRIPT_DIR/backupx" ] && [ -d "$SCRIPT_DIR/web" ]; then
     CONFIG_TEMPLATE="${CONFIG_TEMPLATE:-$SCRIPT_DIR/config.example.yaml}"
     NGINX_SOURCE="${NGINX_SOURCE:-$SCRIPT_DIR/nginx.conf}"
 else
-    BIN_SOURCE="${BIN_SOURCE:-$PROJECT_ROOT/server/backupx}"
+    SOURCE_BIN_DEFAULT="$PROJECT_ROOT/server/bin/backupx"
+    # Keep compatibility with contributors who built the historical path by
+    # hand, while matching the canonical `make build` output first.
+    if [ ! -f "$SOURCE_BIN_DEFAULT" ] && [ -f "$PROJECT_ROOT/server/backupx" ]; then
+        SOURCE_BIN_DEFAULT="$PROJECT_ROOT/server/backupx"
+    fi
+    BIN_SOURCE="${BIN_SOURCE:-$SOURCE_BIN_DEFAULT}"
     WEB_SOURCE="${WEB_SOURCE:-$PROJECT_ROOT/web/dist}"
     CONFIG_TEMPLATE="${CONFIG_TEMPLATE:-$PROJECT_ROOT/server/config.example.yaml}"
     NGINX_SOURCE="${NGINX_SOURCE:-$PROJECT_ROOT/deploy/nginx.conf}"
@@ -27,8 +33,9 @@ if [ "$(id -u)" -ne 0 ]; then
 fi
 
 if [ ! -f "$BIN_SOURCE" ]; then
-    echo "未找到后端二进制：$BIN_SOURCE" >&2
-    echo "源码树安装请先执行：cd \"$PROJECT_ROOT/server\" && go build -o backupx ./cmd/backupx" >&2
+    echo "Backend binary not found / 未找到后端二进制：$BIN_SOURCE" >&2
+    echo "源码树安装请先在仓库根目录执行 make build（产物：server/bin/backupx）。" >&2
+    echo "For a source install, run 'make build' in the repository root first." >&2
     echo "发布包安装请确认当前目录包含 ./backupx、./web 和 ./install.sh。" >&2
     exit 1
 fi
@@ -92,6 +99,41 @@ fi
 systemctl daemon-reload
 systemctl enable --now "$SERVICE_NAME"
 
+# systemctl may return before the process has opened its HTTP listener. Verify
+# the same unauthenticated endpoint used by the first-administrator screen so a
+# broken bare-metal install cannot print a false success message.
+HEALTH_URL="${HEALTH_URL:-http://127.0.0.1:8340/api/auth/setup/status}"
+READY=0
+ATTEMPT=1
+while [ "$ATTEMPT" -le 30 ]; do
+    if systemctl is-active --quiet "$SERVICE_NAME"; then
+        if command -v curl >/dev/null 2>&1; then
+            if curl -fsS --max-time 2 "$HEALTH_URL" >/dev/null 2>&1; then
+                READY=1
+                break
+            fi
+        elif command -v wget >/dev/null 2>&1; then
+            if wget -q -T 2 -O /dev/null "$HEALTH_URL"; then
+                READY=1
+                break
+            fi
+        else
+            echo "Warning / 警告：未找到 curl 或 wget，仅验证 systemd 服务状态。" >&2
+            READY=1
+            break
+        fi
+    fi
+    ATTEMPT=$((ATTEMPT + 1))
+    sleep 1
+done
+
+if [ "$READY" -ne 1 ]; then
+    echo "BackupX did not become ready at $HEALTH_URL / 服务未通过就绪检查。" >&2
+    systemctl status "$SERVICE_NAME" --no-pager >&2 || true
+    journalctl -u "$SERVICE_NAME" -n 50 --no-pager >&2 || true
+    exit 1
+fi
+
 if [ -d "/etc/nginx/conf.d" ] && [ -f "$NGINX_SOURCE" ]; then
     install -m 0644 "$NGINX_SOURCE" "/etc/nginx/conf.d/$SERVICE_NAME.conf"
     if command -v nginx >/dev/null 2>&1; then
@@ -111,6 +153,11 @@ cat <<MESSAGE
 Web 控制台已由后端直接托管，无需额外的 nginx 反向代理即可访问：
   http://<本机IP>:8340
 
+首次访问 / First sign-in:
+  1. 打开上面的地址，并可在登录页右上角选择 中文 或 English。
+  2. 页面显示“系统初始化 / System setup”时，创建首个管理员用户名和密码。
+  3. 如果未显示初始化表单，请先检查：$HEALTH_URL
+
 （如已安装 nginx，脚本会自动写入反向代理配置，可继续用 80 端口访问。）
 
 排查：若服务未监听端口，请查看日志：

docs-site/docs/deployment/bare-metal.md

@@ -10,20 +10,21 @@ description: systemd + Nginx deployment from the prebuilt release tarball or sou
 
 ```bash
 # Download the matching tarball
-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
 
 # Extract and install
-tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
+tar xzf backupx-linux-amd64.tar.gz && cd backupx-*-linux-amd64
 sudo ./install.sh
 ```
 
 The installer performs these steps automatically:
 
 1. Creates a system user `backupx`
-2. Copies the binary to `/opt/backupx/`
-3. Generates a default `config.yaml` with safe JWT/encryption secrets
+2. Copies the binary to `/opt/backupx/bin/backupx` and the web console to `/opt/backupx/web`
+3. Installs the default configuration at `/etc/backupx/config.yaml`
 4. Installs `backupx.service` (systemd), enabled at boot
 5. (Optional) installs an Nginx site file — see [Nginx Reverse Proxy](./nginx)
+6. Verifies the first-setup API before reporting success
 
 For multi-node clusters, edit `/etc/backupx/config.yaml` after installation and set the Master URL that remote Agents can reach:
 
@@ -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 @@ Typical operations:
 sudo systemctl status backupx
 sudo journalctl -u backupx -f    # live logs
 sudo systemctl restart backupx
+curl -fsS http://127.0.0.1:8340/api/auth/setup/status
 ```
 
+Open `http://your-server:8340`, switch to English if desired, and create the first administrator on the **System setup** screen. For a custom listen port, run the installer with a matching `HEALTH_URL`.
+
 ## Password reset
 
 If the admin password is lost:
 
 ```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 equivalent:

docs-site/docs/features/backup-types.md

@@ -12,12 +12,22 @@ When a task is routed to a remote Agent, the source tools and paths are resolved
 
 ## File / Directory
 
-Tars (and optionally gzips) one or more filesystem paths.
+File tasks offer three backup modes:
+
+- **Full archive** — writes a self-contained tar artifact on every run
+- **Differential archive** — writes only changes since the current full baseline and periodically refreshes that baseline
+- **CDC repository** — splits content with stable 512 KiB / 1 MiB / 4 MiB boundaries, stores new chunks in immutable 32 MiB packs, and writes a small snapshot manifest for each run
+
+The CDC repository deduplicates identical content across files and snapshots. Restore, selective restore, verification, download-as-tar, retention, and garbage collection all resolve data through the repository index. Compression and encryption are applied per chunk; encrypted repositories use keyed chunk IDs so plaintext hashes are not exposed.
+
+Repository mode currently uses a single-writer index and therefore runs on the Master only. To keep repository copies on multiple backends, select multiple primary storage targets on the task. Object-level replication is intentionally disabled because a snapshot manifest without its shared packs and indexes is not a complete backup.
+
+Common file-task options:
 
 - **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
+- Full and differential modes output `.tar`, `.tar.gz`, or `.tar.zst` artifacts
 
 ## MySQL
 

docs-site/docs/features/multi-node.md

@@ -26,6 +26,27 @@ BackupX supports Master-Agent mode: backup tasks can be routed to specific nodes
 - **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
 
+## Centralize backups from servers B/C/D into storage M
+
+Use the Master as the control plane and register every source server as an Agent. A task's **Source server** determines where paths and database tools are resolved; its **Storage targets** determine where the resulting artifact is retained.
+
+BackupX chooses the data path per target:
+
+| Destination | Data path |
+| --- | --- |
+| S3, WebDAV, FTP, cloud drive, or another network backend | Agent streams directly to the destination |
+| `local_disk` with **Relay remote backups through Master** enabled (for example storage server M mounted through NFS) | Agent streams through the authenticated Master API; Master writes to its configured local path |
+
+The relay is streaming: the Master does not create a second temporary copy of the entire artifact. The reverse path is used when restoring a Master-local artifact back to its source Agent. Use HTTPS whenever Agent traffic crosses an untrusted network.
+
+To configure the common `A → {B,C,D} → M` topology:
+
+1. Run BackupX Master on A and mount M on A if M is exposed as NFS or another filesystem.
+2. Create a `local_disk` target for that mount and keep **Relay remote backups through Master** enabled, or create an S3/WebDAV target exposed by M. Existing local-disk targets keep their prior Agent-local behavior until this switch is enabled.
+3. Install one Agent on B, C, and D from **Node Management**.
+4. Create a backup task for each source, choose B/C/D under **Source server**, browse that server's paths, and select M as the storage target. A source-server pool label can route identical tasks dynamically.
+5. Verify the per-target result in the backup record. For a Master-local target, the record reports transfer mode `master_relay`; network backends remain `direct`.
+
 ## Walkthrough
 
 ### 0. Set the Master URL for production clusters
@@ -78,7 +99,7 @@ In Step 1 choose "Batch" and paste node names (one per line, max 50). Step 3 sho
 
 ### 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 source server 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

docs-site/docs/features/storage-backends.md

@@ -19,7 +19,9 @@ BackupX aims to accept any place you'd want to drop a backup file.
 | **Google Drive** | Client ID/Secret + OAuth authorization |
 | **WebDAV** | URL + username/password |
 | **FTP / FTPS** | Host + port + username/password |
-| **Local disk** | Target directory (absolute path) |
+| **Local disk** | Target directory (absolute path) + optional Master relay for remote Agents |
+
+New local-disk targets enable **Relay remote backups through Master** by default. This makes the configured path belong to the Master, so a storage server mounted there can collect backups from many source Agents. Turn the switch off when the path intentionally belongs to each Agent. Existing targets retain their previous Agent-local behavior until explicitly changed.
 
 ## Rclone backends
 

docs-site/docs/getting-started/installation.md

@@ -55,10 +55,11 @@ sudo ./install.sh        # creates system user, installs to /opt/backupx, sets u
 The installer:
 
 1. Creates a `backupx` system user
-2. Installs binary to `/opt/backupx/backupx`
-3. Creates `/opt/backupx/config.yaml` with safe defaults
+2. Installs the binary to `/opt/backupx/bin/backupx` and the web console to `/opt/backupx/web`
+3. Creates `/etc/backupx/config.yaml` with safe defaults
 4. Installs and enables the `backupx.service` systemd unit
 5. (Optional) Configures an Nginx reverse proxy
+6. Waits for `/api/auth/setup/status`; if startup fails, prints systemd diagnostics and exits non-zero
 
 ## From source
 
@@ -67,16 +68,17 @@ Requires Go ≥ 1.25 and Node.js ≥ 20.
 ```bash
 git clone https://github.com/Awuqing/BackupX.git && cd BackupX
 make build
-# or, for builds behind the great firewall
-make docker-cn
+sudo ./deploy/install.sh
 ```
 
 After `make build`, the binary is at `server/bin/backupx` and the built web UI is at `web/dist/`.
+The installer consumes those exact paths, so no Docker runtime is required. If an existing configuration uses a non-default port, set `HEALTH_URL` for the readiness check, for example `sudo HEALTH_URL=http://127.0.0.1:9000/api/auth/setup/status ./deploy/install.sh`.
 
 ## Verify the install
 
 ```bash
-backupx --version           # e.g. v1.6.0
+/opt/backupx/bin/backupx --version
+curl -fsS http://127.0.0.1:8340/api/auth/setup/status
 ```
 
-Then open `http://your-server:8340` to see the initial admin setup screen.
+Then open `http://your-server:8340`. Choose **English** or **中文** in the upper-right corner. A fresh database shows **System setup**, where you create the first administrator username and password. If that form does not appear, retry the status request above before attempting to sign in.

docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/deployment/bare-metal.md

@@ -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 等效命令：

docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/features/backup-types.md

@@ -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