feat: 优化集群部署与堡垒机接入 (#106)

支持受限网络、正向代理、私有 CA 与 SSH 堡垒机部署 Agent。

加固 Docker、systemd、Nginx、安装器、Release 校验与可信代理边界，并完善命令队列索引、前端安装向导及中英文运维文档。

.github/workflows/release.yml

@@ -110,6 +110,7 @@ jobs:
           cp -r web/dist "${ARCHIVE_NAME}/web"
           cp server/config.example.yaml "${ARCHIVE_NAME}/"
           cp deploy/install.sh "${ARCHIVE_NAME}/" 2>/dev/null || true
+          cp deploy/backupx.service "${ARCHIVE_NAME}/" 2>/dev/null || true
           # v2.2+: 随发布包提供 Grafana dashboard 与 nginx.conf 模板
           if [ -d deploy/grafana ]; then
             cp -r deploy/grafana "${ARCHIVE_NAME}/grafana"
@@ -117,6 +118,8 @@ jobs:
           cp deploy/nginx.conf "${ARCHIVE_NAME}/nginx.conf" 2>/dev/null || true
           tar czf "${ARCHIVE_NAME}.tar.gz" "${ARCHIVE_NAME}"
           cp "${ARCHIVE_NAME}.tar.gz" "backupx-${{ matrix.goos }}-${{ matrix.goarch }}.tar.gz"
+          sha256sum "${ARCHIVE_NAME}.tar.gz" > "${ARCHIVE_NAME}.tar.gz.sha256"
+          sha256sum "backupx-${{ matrix.goos }}-${{ matrix.goarch }}.tar.gz" > "backupx-${{ matrix.goos }}-${{ matrix.goarch }}.tar.gz.sha256"
 
       - name: Upload to GitHub Release
         uses: softprops/action-gh-release@v2
@@ -124,7 +127,9 @@ jobs:
           tag_name: ${{ env.VERSION }}
           files: |
             backupx-${{ env.VERSION }}-${{ matrix.goos }}-${{ matrix.goarch }}.tar.gz
+            backupx-${{ env.VERSION }}-${{ matrix.goos }}-${{ matrix.goarch }}.tar.gz.sha256
             backupx-${{ matrix.goos }}-${{ matrix.goarch }}.tar.gz
+            backupx-${{ matrix.goos }}-${{ matrix.goarch }}.tar.gz.sha256
           generate_release_notes: true
 
   # ─── Job 3: Docker 多架构 → Docker Hub ───

Dockerfile

@@ -51,12 +51,11 @@ RUN if [ "$USE_CHINA_MIRROR" = "true" ]; then \
       sed -i 's|dl-cdn.alpinelinux.org|mirrors.aliyun.com|g' /etc/apk/repositories; \
     fi
 
+# Database client binaries are required by MySQL and PostgreSQL backup tasks.
 RUN apk add --no-cache \
-    nginx \
     tzdata \
     ca-certificates \
-    docker-cli docker-cli-compose \
-    # Required by mysql/postgresql backup tasks
+    su-exec \
     mysql-client \
     postgresql16-client \
     && rm -rf /var/cache/apk/*
@@ -70,24 +69,30 @@ COPY --from=server-builder /build/server/backupx /app/bin/backupx
 # Copy frontend static files
 COPY --from=web-builder /build/web/dist /app/web
 
-# Copy nginx config
-COPY deploy/docker/nginx.conf /etc/nginx/http.d/default.conf
-
 # Copy entrypoint
 COPY deploy/docker/entrypoint.sh /app/entrypoint.sh
 RUN chmod +x /app/entrypoint.sh
 
 # Create data directories
 RUN mkdir -p /app/data /tmp/backupx && \
-    chown -R backupx:backupx /app /tmp/backupx
-
-# Nginx needs to write to these dirs
-RUN mkdir -p /var/lib/nginx/tmp /var/log/nginx && \
-    chown -R backupx:backupx /var/lib/nginx /var/log/nginx /run/nginx
+    touch /app/data/.backupx-owner-v2 && \
+    chown -R backupx:backupx /app/data /tmp/backupx && \
+    chmod 0750 /app/data /tmp/backupx
 
 WORKDIR /app
 EXPOSE 8340
 
 VOLUME ["/app/data"]
 
+ENV BACKUPX_SERVER_HOST=0.0.0.0 \
+    BACKUPX_SERVER_PORT=8340 \
+    BACKUPX_SERVER_WEB_ROOT=/app/web
+
+USER root
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD su-exec backupx:backupx wget -q -T 3 -O /dev/null http://127.0.0.1:8340/ready || exit 1
+
+STOPSIGNAL SIGTERM
+
 ENTRYPOINT ["/app/entrypoint.sh"]

README.md

@@ -43,7 +43,7 @@
 | **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 |
+| **Multi-Node Cluster** | Outbound-only Master-Agent polling with proxy, private-CA, and SSH-bastion support; Agents run tasks locally with 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 |
 | **Observability** | Prometheus `/metrics` endpoint + `/health` + `/ready` probes + SLA breach gauge |

README.zh-CN.md

@@ -43,7 +43,7 @@
 | **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 模式，基于 HTTP 长轮询跨多台服务器管理备份。Agent 本地执行任务并直接上传到存储，无需反向连通性 |
+| **多节点集群** | Master-Agent 模式，基于 Agent 主动出站的 HTTP 轮询跨服务器管理备份，支持代理、私有 CA 与 SSH 堡垒机，无需反向连通性 |
 | **安全** | JWT + bcrypt + AES-256-GCM 加密配置 + 可选备份文件加密 + 完整审计日志 |
 | **通知** | 邮件 / Webhook / Telegram，备份成功或失败时自动推送 |
 | **可观测性** | Prometheus `/metrics` 端点 + `/health` + `/ready` 探针 + SLA 违约监控 |

deploy/backupx.service

@@ -12,6 +12,7 @@ ExecStart=/opt/backupx/bin/backupx -config /etc/backupx/config.yaml
 Restart=on-failure
 RestartSec=5
 NoNewPrivileges=true
+UMask=0027
 LimitNOFILE=65535
 
 [Install]

deploy/docker/entrypoint.sh

@@ -1,27 +1,18 @@
 #!/bin/sh
-set -e
+set -eu
 
-if [ "${1:-}" = "agent" ]; then
-    exec /app/bin/backupx "$@"
+# 旧镜像曾以 root 写入数据卷。Master 启动时做一次所有权迁移，随后
+# 降权运行；Agent 模式由部署命令显式决定用户，以访问宿主机备份路径。
+if [ "$(id -u)" -eq 0 ] && [ "${1:-}" != "agent" ]; then
+    chown backupx:backupx /app/data /tmp/backupx
+    if [ ! -f /app/data/.backupx-owner-v2 ]; then
+        chown -R backupx:backupx /app/data
+        su-exec backupx:backupx touch /app/data/.backupx-owner-v2
+    fi
+    export HOME=/app
+    exec su-exec backupx:backupx /app/bin/backupx "$@"
 fi
 
-# Backend listens on internal port 8341, Nginx exposes 8340
-export BACKUPX_SERVER_PORT="${BACKUPX_SERVER_PORT_INTERNAL:-8341}"
-
-# Start Nginx in background
-nginx -g "daemon off;" &
-NGINX_PID=$!
-
-# Start BackupX backend
-/app/bin/backupx &
-APP_PID=$!
-
-# Trap signals for graceful shutdown
-trap 'kill $APP_PID $NGINX_PID 2>/dev/null; wait $APP_PID $NGINX_PID 2>/dev/null' SIGTERM SIGINT
-
-echo "BackupX started — Nginx :8340 -> Backend :8341"
-
-# Wait for either process to exit
-wait -n $APP_PID $NGINX_PID 2>/dev/null || true
-kill $APP_PID $NGINX_PID 2>/dev/null || true
-wait $APP_PID $NGINX_PID 2>/dev/null || true
+# Web 静态文件由 BackupX 后端直接托管。容器只运行一个前台进程，
+# 让 Docker 准确传递信号、收集退出码并执行健康检查。
+exec /app/bin/backupx "$@"

deploy/docker/nginx.conf

@@ -1,51 +0,0 @@
-server {
-    listen 8340;
-    server_name _;
-
-    root /app/web;
-    index index.html;
-
-    # API reverse proxy to backend
-    location /api/ {
-        proxy_pass http://127.0.0.1:8341/api/;
-        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;
-        proxy_set_header Connection "";
-        proxy_buffering off;
-        proxy_cache off;
-        proxy_read_timeout 3600s;
-    }
-
-    # Agent one-click install endpoints.
-    # Some external reverse proxies strip the /api prefix before reaching this
-    # container, so /install/ must be proxied here instead of falling through to
-    # the SPA index.html.
-    location /install/ {
-        proxy_pass http://127.0.0.1:8341/install/;
-        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;
-        proxy_buffering off;
-        proxy_cache off;
-    }
-
-    location = /health { proxy_pass http://127.0.0.1:8341/health; }
-    location = /ready { proxy_pass http://127.0.0.1:8341/ready; }
-    location = /metrics { proxy_pass http://127.0.0.1:8341/metrics; }
-
-    # SPA fallback
-    location / {
-        try_files $uri $uri/ /index.html;
-    }
-
-    # Static assets cache
-    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
-        expires 30d;
-        add_header Cache-Control "public, immutable";
-    }
-}

deploy/install.sh

@@ -13,6 +13,7 @@ if [ -f "$SCRIPT_DIR/backupx" ] && [ -d "$SCRIPT_DIR/web" ]; then
     WEB_SOURCE="${WEB_SOURCE:-$SCRIPT_DIR/web}"
     CONFIG_TEMPLATE="${CONFIG_TEMPLATE:-$SCRIPT_DIR/config.example.yaml}"
     NGINX_SOURCE="${NGINX_SOURCE:-$SCRIPT_DIR/nginx.conf}"
+    SERVICE_SOURCE_DEFAULT="$SCRIPT_DIR/backupx.service"
 else
     SOURCE_BIN_DEFAULT="$PROJECT_ROOT/server/bin/backupx"
     # Keep compatibility with contributors who built the historical path by
@@ -24,14 +25,38 @@ else
     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}"
+    SERVICE_SOURCE_DEFAULT="$PROJECT_ROOT/deploy/backupx.service"
 fi
-SERVICE_SOURCE="${SERVICE_SOURCE:-$PROJECT_ROOT/deploy/backupx.service}"
+SERVICE_SOURCE_EXPLICIT=0
+if [ -n "${SERVICE_SOURCE:-}" ]; then
+    SERVICE_SOURCE_EXPLICIT=1
+fi
+SERVICE_SOURCE="${SERVICE_SOURCE:-$SERVICE_SOURCE_DEFAULT}"
+INSTALL_NGINX="${INSTALL_NGINX:-0}"
 
 if [ "$(id -u)" -ne 0 ]; then
     echo "请使用 root 或 sudo 执行安装脚本。" >&2
     exit 1
 fi
 
+validate_install_path() {
+    path_name="$1"
+    path_value="$2"
+    case "$path_value" in
+        /*) ;;
+        *) echo "$path_name 必须是绝对路径: $path_value" >&2; exit 1 ;;
+    esac
+    case "$path_value" in
+        /|*"//"*|*"/./"*|*"/."|*"/../"*|*"/.."|*[!A-Za-z0-9_./+-]*)
+            echo "$path_name 必须是规范、安全且非根目录的绝对路径: $path_value" >&2
+            exit 1
+            ;;
+    esac
+}
+
+validate_install_path PREFIX "$PREFIX"
+validate_install_path ETC_DIR "$ETC_DIR"
+
 if [ ! -f "$BIN_SOURCE" ]; then
     echo "Backend binary not found / 未找到后端二进制：$BIN_SOURCE" >&2
     echo "源码树安装请先在仓库根目录执行 make build（产物：server/bin/backupx）。" >&2
@@ -52,6 +77,18 @@ if [ ! -f "$CONFIG_TEMPLATE" ]; then
     exit 1
 fi
 
+if [ "$SERVICE_SOURCE_EXPLICIT" = "1" ] && [ ! -f "$SERVICE_SOURCE" ]; then
+    echo "指定的 systemd unit 不存在：$SERVICE_SOURCE" >&2
+    exit 1
+fi
+
+for managed_path in "$PREFIX" "$PREFIX/bin" "$PREFIX/web" "$PREFIX/data" "$ETC_DIR"; do
+    if [ -L "$managed_path" ]; then
+        echo "拒绝通过符号链接写入受管目录：$managed_path" >&2
+        exit 1
+    fi
+done
+
 if ! getent group "$APP_GROUP" >/dev/null 2>&1; then
     groupadd --system "$APP_GROUP"
 fi
@@ -60,19 +97,27 @@ if ! id "$APP_USER" >/dev/null 2>&1; then
     useradd --system --gid "$APP_GROUP" --home-dir "$PREFIX" --shell /usr/sbin/nologin "$APP_USER"
 fi
 
-install -d -o "$APP_USER" -g "$APP_GROUP" "$PREFIX" "$PREFIX/bin" "$PREFIX/web" "$PREFIX/data" "$ETC_DIR"
-install -m 0755 "$BIN_SOURCE" "$PREFIX/bin/backupx"
+install -d -o root -g root -m 0755 "$PREFIX" "$PREFIX/bin" "$PREFIX/web"
+install -d -o "$APP_USER" -g "$APP_GROUP" -m 0750 "$PREFIX/data"
+install -d -o root -g "$APP_GROUP" -m 0750 "$ETC_DIR"
+install -o root -g root -m 0755 "$BIN_SOURCE" "$PREFIX/bin/backupx.new"
+mv -f "$PREFIX/bin/backupx.new" "$PREFIX/bin/backupx"
 cp -R "$WEB_SOURCE/." "$PREFIX/web/"
-chown -R "$APP_USER:$APP_GROUP" "$PREFIX"
+chown -R root:root "$PREFIX/bin" "$PREFIX/web"
+find "$PREFIX/web" -type d -exec chmod 0755 {} \;
+find "$PREFIX/web" -type f -exec chmod 0644 {} \;
+chown -R "$APP_USER:$APP_GROUP" "$PREFIX/data"
 
 if [ ! -f "$ETC_DIR/config.yaml" ]; then
-    install -o "$APP_USER" -g "$APP_GROUP" -m 0640 "$CONFIG_TEMPLATE" "$ETC_DIR/config.yaml"
+    install -o root -g "$APP_GROUP" -m 0640 "$CONFIG_TEMPLATE" "$ETC_DIR/config.yaml"
 fi
-# 确保服务账户能读取配置：历史版本曾以 root:root 0640 安装配置，
-# 导致以 backupx 身份运行的服务因无权读取配置而启动失败（exit 1）。
-chown "$APP_USER:$APP_GROUP" "$ETC_DIR/config.yaml"
+# 服务账户只需读取配置，不应拥有修改 /etc 配置或可执行文件的权限。
+chown root:"$APP_GROUP" "$ETC_DIR/config.yaml"
+chmod 0640 "$ETC_DIR/config.yaml"
 
-if [ -f "$SERVICE_SOURCE" ]; then
+# 仓库 unit 使用标准路径；自定义 PREFIX/ETC_DIR 时动态生成以保持路径一致。
+# 显式传入 SERVICE_SOURCE 表示调用方已经审核其中的路径，始终优先使用。
+if [ -f "$SERVICE_SOURCE" ] && { [ "$SERVICE_SOURCE_EXPLICIT" = "1" ] || { [ "$PREFIX" = "/opt/backupx" ] && [ "$ETC_DIR" = "/etc/backupx" ]; }; }; then
     install -m 0644 "$SERVICE_SOURCE" "/etc/systemd/system/$SERVICE_NAME.service"
 else
     cat > "/etc/systemd/system/$SERVICE_NAME.service" <<UNIT
@@ -90,6 +135,7 @@ ExecStart=$PREFIX/bin/backupx -config $ETC_DIR/config.yaml
 Restart=on-failure
 RestartSec=5
 NoNewPrivileges=true
+UMask=0027
 LimitNOFILE=65535
 
 [Install]
@@ -97,7 +143,12 @@ WantedBy=multi-user.target
 UNIT
 fi
 systemctl daemon-reload
-systemctl enable --now "$SERVICE_NAME"
+if ! systemctl enable "$SERVICE_NAME" || ! systemctl restart "$SERVICE_NAME"; then
+    echo "BackupX systemd 服务启动失败。" >&2
+    systemctl status "$SERVICE_NAME" --no-pager >&2 || true
+    journalctl -u "$SERVICE_NAME" -n 50 --no-pager >&2 || true
+    exit 1
+fi
 
 # systemctl may return before the process has opened its HTTP listener. Verify
 # the same unauthenticated endpoint used by the first-administrator screen so a
@@ -134,12 +185,15 @@ if [ "$READY" -ne 1 ]; then
     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
-        nginx -t
-        systemctl reload nginx || true
+if [ "$INSTALL_NGINX" = "1" ]; then
+    if [ ! -d "/etc/nginx/conf.d" ] || [ ! -f "$NGINX_SOURCE" ]; then
+        echo "已请求安装 Nginx 配置，但未找到 /etc/nginx/conf.d 或配置模板。" >&2
+        exit 1
     fi
+    install -o root -g root -m 0644 "$NGINX_SOURCE" "/etc/nginx/conf.d/$SERVICE_NAME.conf"
+    command -v nginx >/dev/null 2>&1 || { echo "未找到 nginx 命令。" >&2; exit 1; }
+    nginx -t
+    systemctl reload nginx
 fi
 
 cat <<MESSAGE
@@ -158,7 +212,8 @@ Web 控制台已由后端直接托管，无需额外的 nginx 反向代理即可
   2. 页面显示“系统初始化 / System setup”时，创建首个管理员用户名和密码。
   3. 如果未显示初始化表单，请先检查：$HEALTH_URL
 
-（如已安装 nginx，脚本会自动写入反向代理配置，可继续用 80 端口访问。）
+如需安装仓库提供的 Nginx 模板，请审核域名与 TLS 配置后重新执行：
+  sudo INSTALL_NGINX=1 ./install.sh
 
 排查：若服务未监听端口，请查看日志：
   journalctl -u "$SERVICE_NAME" -n 50 --no-pager

deploy/nginx.conf

@@ -8,11 +8,15 @@ server {
     location /api/ {
         proxy_pass http://127.0.0.1:8340/api/;
         proxy_http_version 1.1;
-        proxy_set_header Host $host;
+        proxy_set_header Host $http_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;
+        proxy_set_header X-Forwarded-Host $http_host;
+        proxy_set_header X-Forwarded-Port $server_port;
         proxy_set_header Connection "";
+        client_max_body_size 0;
+        proxy_request_buffering off;
         proxy_buffering off;
         proxy_cache off;
         proxy_read_timeout 3600s;
@@ -23,10 +27,12 @@ server {
     location /install/ {
         proxy_pass http://127.0.0.1:8340/install/;
         proxy_http_version 1.1;
-        proxy_set_header Host $host;
+        proxy_set_header Host $http_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;
+        proxy_set_header X-Forwarded-Host $http_host;
+        proxy_set_header X-Forwarded-Port $server_port;
     }
 
     # 健康检查端点同样不走 SPA fallback。

docker-compose.yml

@@ -3,30 +3,46 @@
 # 快速启动：docker compose up -d
 # 访问地址：http://localhost:8340
 #
-# 如需从源码构建镜像（而非拉取线上镜像），取消注释 build 行并注释 image 行。
+# 生产环境建议在 .env 中固定 BACKUPX_IMAGE 版本，并通过 HTTPS 反向代理暴露服务。
 
 services:
   backupx:
-    image: awuqing/backupx:latest
-    # build: .                              # 从源码构建时取消此行注释
+    image: ${BACKUPX_IMAGE:-awuqing/backupx:latest}
+    # build: .
     container_name: backupx
     restart: unless-stopped
+    init: true
+    stop_grace_period: 30s
     ports:
-      - "8340:8340"
+      - "${BACKUPX_BIND_ADDRESS:-0.0.0.0}:${BACKUPX_PORT:-8340}:8340"
     volumes:
       - backupx-data:/app/data
-      - /var/run/docker.sock:/var/run/docker.sock  # 支持 Web 一键更新
       # 挂载需要备份的宿主机目录（按需添加，:ro 表示只读）：
       # - /var/www:/mnt/www:ro
       # - /etc/nginx:/mnt/nginx-conf:ro
       # - /home/user/data:/mnt/data:ro
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    cap_add:
+      # 仅用于旧数据卷迁移与降权；应用进程随后以 backupx 运行。
+      - CHOWN
+      - DAC_OVERRIDE
+      - SETGID
+      - SETUID
     environment:
-      - TZ=Asia/Shanghai
-      # 远程 Agent 需要通过公网或可路由地址连接 Master 时，取消注释并改成真实 URL：
-      # - BACKUPX_SERVER_EXTERNAL_URL=https://backup.example.com
-      # 通过 BACKUPX_ 前缀环境变量覆盖配置：
-      # - BACKUPX_LOG_LEVEL=debug
-      # - BACKUPX_BACKUP_MAX_CONCURRENT=4
+      TZ: ${TZ:-Asia/Shanghai}
+      # 远程 Agent 连接 Master 时，配置为所有节点可达的稳定 HTTPS URL：
+      # BACKUPX_SERVER_EXTERNAL_URL: https://backup.example.com
+      # BACKUPX_LOG_LEVEL: debug
+      # BACKUPX_BACKUP_MAX_CONCURRENT: "4"
+    healthcheck:
+      test: ["CMD", "su-exec", "backupx:backupx", "wget", "-q", "-T", "3", "-O", "/dev/null", "http://127.0.0.1:8340/ready"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
 
 volumes:
   backupx-data:

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

@@ -1,7 +1,7 @@
 ---
 sidebar_position: 2
 title: Bare-metal Deployment
-description: systemd + Nginx deployment from the prebuilt release tarball or source.
+description: Hardened systemd deployment from the prebuilt release tarball or source, with opt-in Nginx.
 ---
 
 # Bare-metal Deployment
@@ -11,6 +11,8 @@ 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-linux-amd64.tar.gz
+curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-linux-amd64.tar.gz.sha256
+sha256sum -c backupx-linux-amd64.tar.gz.sha256
 
 # Extract and install
 tar xzf backupx-linux-amd64.tar.gz && cd backupx-*-linux-amd64
@@ -23,9 +25,17 @@ The installer performs these steps automatically:
 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)
+5. Leaves Nginx unchanged unless `INSTALL_NGINX=1` is explicitly requested
 6. Verifies the first-setup API before reporting success
 
+The executable and web assets are owned by root; only `/opt/backupx/data` is writable by the `backupx` service account. `/etc/backupx/config.yaml` is installed as `root:backupx` with mode `0640`.
+
+The bundled Nginx template is a starting point and may conflict with an existing default server. Review its hostname and TLS policy first, then opt in:
+
+```bash
+sudo INSTALL_NGINX=1 ./install.sh
+```
+
 For multi-node clusters, edit `/etc/backupx/config.yaml` after installation and set the Master URL that remote Agents can reach:
 
 ```yaml
@@ -70,6 +80,7 @@ ExecStart=/opt/backupx/bin/backupx -config /etc/backupx/config.yaml
 Restart=on-failure
 RestartSec=5
 NoNewPrivileges=true
+UMask=0027
 LimitNOFILE=65535
 
 [Install]
@@ -87,6 +98,8 @@ 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`.
 
+For production, expose BackupX through HTTPS or restrict port `8340` at the firewall. The installer does not make firewall changes.
+
 ## Password reset
 
 If the admin password is lost:

docs-site/docs/deployment/configuration.md

@@ -15,7 +15,11 @@ server:
   host: "0.0.0.0"             # BACKUPX_SERVER_HOST
   port: 8340                  # BACKUPX_SERVER_PORT
   mode: "release"             # release | debug
-  external_url: ""            # BACKUPX_SERVER_EXTERNAL_URL — public Master URL for Agent install scripts
+  external_url: ""            # BACKUPX_SERVER_EXTERNAL_URL — stable public Master URL
+  trusted_proxies:             # BACKUPX_SERVER_TRUSTED_PROXIES — exact proxy IPs/CIDRs
+    - "127.0.0.1"
+    - "::1"
+  web_root: ""                # BACKUPX_SERVER_WEB_ROOT — built frontend directory
 
 database:
   path: "./data/backupx.db"   # BACKUPX_DATABASE_PATH — embedded SQLite
@@ -48,6 +52,7 @@ The environment wins when both file and env are set. All dot-paths become unders
 |------------|--------------|
 | `server.port` | `BACKUPX_SERVER_PORT` |
 | `server.external_url` | `BACKUPX_SERVER_EXTERNAL_URL` |
+| `server.trusted_proxies` | `BACKUPX_SERVER_TRUSTED_PROXIES` (comma-separated for env) |
 | `security.jwt_expire` | `BACKUPX_SECURITY_JWT_EXPIRE` |
 | `log.level` | `BACKUPX_LOG_LEVEL` |
 | `backup.max_concurrent` | `BACKUPX_BACKUP_MAX_CONCURRENT` |
@@ -64,3 +69,18 @@ server:
 ```
 
 This value is used when BackupX renders one-click Agent install scripts and docker-compose snippets. It must be reachable from every Agent host. Leave it empty only when `X-Forwarded-Proto` / `X-Forwarded-Host` are reliable and point to the same URL that Agents can access.
+
+The install wizard can set an Agent-specific runtime URL for a proxy or SSH-bastion node. The public install link continues to use `server.external_url`, while the generated Agent config uses that override.
+
+## Trusted reverse proxies
+
+BackupX trusts forwarded client-address headers only from `server.trusted_proxies`. The default permits loopback Nginx only. If a reverse proxy runs in another container or host, add its exact IP or subnet:
+
+```yaml
+server:
+  trusted_proxies:
+    - "127.0.0.1"
+    - "172.18.0.0/16"
+```
+
+Do not configure `0.0.0.0/0`: client addresses feed authentication throttling, install-token throttling, and audit records. Set an empty list when BackupX is exposed directly and should trust no forwarded headers.

docs-site/docs/deployment/docker.md

@@ -1,81 +1,96 @@
 ---
 sidebar_position: 1
 title: Docker Deployment
-description: Production-style Docker deployment with docker compose, mounted source directories, and environment overrides.
+description: Hardened single-process Docker deployment with health checks and persistent data.
 ---
 
 # Docker Deployment
 
-BackupX's official Docker image [`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx) supports multi-architecture (linux/amd64 + linux/arm64).
+The official [`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx) image supports `linux/amd64` and `linux/arm64`.
 
 ## Compose file
 
 ```yaml title="docker-compose.yml"
 services:
   backupx:
-    image: awuqing/backupx:latest
+    image: ${BACKUPX_IMAGE:-awuqing/backupx:latest}
     container_name: backupx
     restart: unless-stopped
+    init: true
+    stop_grace_period: 30s
     ports:
-      - "8340:8340"
+      - "${BACKUPX_BIND_ADDRESS:-0.0.0.0}:${BACKUPX_PORT:-8340}:8340"
     volumes:
       - backupx-data:/app/data
-      # Mount host directories you want to back up:
-      - /var/www:/mnt/www:ro
-      - /etc/nginx:/mnt/nginx-conf:ro
+      # - /var/www:/mnt/www:ro
+      # - /etc/nginx:/mnt/nginx-conf:ro
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    cap_add:
+      - CHOWN
+      - DAC_OVERRIDE
+      - SETGID
+      - SETUID
     environment:
-      - TZ=Asia/Shanghai
-      # Required when remote Agents must connect through a public or routed URL:
-      # - BACKUPX_SERVER_EXTERNAL_URL=https://backup.example.com
-      - BACKUPX_LOG_LEVEL=info
-      - BACKUPX_BACKUP_MAX_CONCURRENT=2
+      TZ: Asia/Shanghai
+      # BACKUPX_SERVER_EXTERNAL_URL: https://backup.example.com
+      BACKUPX_LOG_LEVEL: info
+      BACKUPX_BACKUP_MAX_CONCURRENT: "2"
+    healthcheck:
+      test: ["CMD", "su-exec", "backupx:backupx", "wget", "-q", "-T", "3", "-O", "/dev/null", "http://127.0.0.1:8340/ready"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
 
 volumes:
   backupx-data:
 ```
 
-Start with:
-
 ```bash
 docker compose up -d
+docker compose ps
 ```
 
-## Host-directory backup
+The entrypoint uses root only to migrate ownership of data written by older images, then starts one unprivileged `backupx` process. Compose retains only the ownership and UID/GID transition capabilities needed for that initialization. The backend serves both the API and built web assets; the image neither mounts the Docker socket nor bundles a Docker CLI. Pin `BACKUPX_IMAGE` to a release tag in production.
 
-To back up files from the host, mount them into the container. When creating a file-type task in the web UI, point the source path at the mount location (e.g. `/mnt/www`). Make sure the directory is visible inside the container.
+## Host-directory backups
 
-## Multi-node clusters
+Mount each source directory and use its container path in the task. The container's `backupx` user must be able to read it; restore destinations need a separate, narrowly scoped writable mount. Prefer a remote Agent for privileged host paths. If a Master-side task truly requires root, make that exception explicit with `user: "0:0"` and review every mount.
 
-When deploying Agents on other machines, set `BACKUPX_SERVER_EXTERNAL_URL` on the Master container to the URL that those Agents can reach:
+## Multi-node cluster
+
+Set the stable URL that Agents can reach:
 
 ```yaml
 environment:
-  - BACKUPX_SERVER_EXTERNAL_URL=https://backup.example.com
+  BACKUPX_SERVER_EXTERNAL_URL: https://backup.example.com
 ```
 
-Use an HTTPS URL if Agents cross untrusted networks. The generated one-click install scripts and docker-compose snippets use this value as `BACKUPX_AGENT_MASTER`.
+Use HTTPS across untrusted networks. Proxy, private-CA, and SSH-bastion deployments are covered in [Multi-Node Cluster](../features/multi-node).
 
-## Environment variables
+If an external reverse proxy is in another container, add only its bridge subnet to `BACKUPX_SERVER_TRUSTED_PROXIES`, for example `172.18.0.0/16`. Do not trust every address.
 
-All configuration keys can be overridden with the `BACKUPX_` prefix:
+## Environment overrides
 
 ```yaml
 environment:
-  - TZ=Asia/Shanghai
-  - BACKUPX_SERVER_PORT=8340
-  - BACKUPX_LOG_LEVEL=debug
-  - BACKUPX_BACKUP_MAX_CONCURRENT=4
-  - BACKUPX_BACKUP_TEMP_DIR=/tmp/backupx
+  TZ: Asia/Shanghai
+  BACKUPX_LOG_LEVEL: debug
+  BACKUPX_BACKUP_MAX_CONCURRENT: "4"
+  BACKUPX_BACKUP_TEMP_DIR: /tmp/backupx
 ```
 
-See the [Configuration](./configuration) page for the full list.
+The image's internal port is fixed at `8340`; change only the published host port with `BACKUPX_PORT`.
 
-## Upgrades
-
-Check **System Settings → Check Updates** in the UI to see if a new version is available, then on the host:
+## Upgrade and rollback preparation
 
 ```bash
-docker compose pull && docker compose up -d
+docker compose pull
+docker compose up -d
+docker compose ps
 ```
 
-No migrations needed — BackupX auto-migrates the SQLite schema on startup.
+Wait for `healthy` before switching traffic or removing an old deployment. Before upgrades, stop the Master for a file-level copy or take an atomic snapshot of the entire `backupx-data` volume. Keep exactly one active Master for a data volume; SQLite does not support multiple Master containers sharing `/app/data`.

docs-site/docs/deployment/nginx.md

@@ -23,13 +23,16 @@ server {
     location /api/ {
         proxy_pass http://127.0.0.1:8340;
         proxy_http_version 1.1;
-        proxy_set_header Host $host;
+        proxy_set_header Host $http_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;
+        proxy_set_header X-Forwarded-Host $http_host;
+        proxy_set_header X-Forwarded-Port $server_port;
 
         # Large uploads (restore flow)
         client_max_body_size 0;
+        proxy_request_buffering off;
 
         # Live log stream uses SSE — buffering must be off
         proxy_buffering off;
@@ -39,6 +42,10 @@ server {
 }
 ```
 
+`proxy_request_buffering off` is required for Master-relay cluster backups. Without it, Nginx writes the complete Agent upload to its temporary storage before BackupX receives it, defeating streaming and potentially filling the proxy disk.
+
+If Nginx runs on another host or in another container, add only that proxy IP or subnet to `server.trusted_proxies`. Do not use `0.0.0.0/0`; BackupX uses the trusted client address for login throttling, install-token throttling, and audit records.
+
 ## HTTPS with certbot
 
 ```bash

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

@@ -1,155 +1,229 @@
 ---
 sidebar_position: 4
 title: Multi-Node Cluster
-description: Master-Agent mode — route backups to remote servers via HTTP long-polling.
+description: Deploy BackupX Agents through direct HTTPS, forward proxies, or SSH bastions.
 ---
 
 # Multi-Node Cluster
 
-BackupX supports Master-Agent mode: backup tasks can be routed to specific nodes. The Agent runs the backup locally and uploads straight to storage. All connections are initiated by the Agent, so remote networks only need outbound HTTP access.
+BackupX uses a single active Master as the control plane and an Agent on each source server. Agents initiate every connection, report a heartbeat every 15 seconds, and poll for commands every 5 seconds. No inbound Agent port is required.
 
-## Architecture
+## Architecture and boundaries
 
-```
-[Web Console] ─── JWT ──→ [Master (backupx)]
-                              ↑  ↓
-                              │  │ HTTP long-poll (token auth)
-                              │  ↓
-                         [Agent (backupx agent)]   ← runs on remote host
-                              ↓
-                     [70+ Storage Backends]
+```text
+[Web console] ────────> [Active Master + SQLite]
+                              ^
+                              | outbound HTTP(S) polling
+                    +---------+---------+
+                    |         |         |
+                 [Agent B] [Agent C] [Agent D]
+                    |         |         |
+                    +----> storage targets
 ```
 
-- **Protocol** — HTTP long-polling; the Agent initiates every connection
-- **Heartbeat** — Agent reports every 15s; Master marks nodes offline after 45s of silence
-- **Dispatch** — Master persists `run_task` commands to a queue; Agent polls and claims them
-- **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
+- Each node has an independent Agent Token. The Agent never receives the Master's JWT or encryption key.
+- A node is marked offline after 45 seconds without a heartbeat.
+- The Master persists commands; an Agent claims and executes them locally.
+- Network storage is normally written directly by the Agent. A Master-local target can opt into authenticated streaming relay.
 
-## Centralize backups from servers B/C/D into storage M
+:::warning Single-active Master
+The embedded SQLite database is not a shared multi-writer database. Run exactly one active Master against a data directory. For control-plane recovery, use an active/passive host, persistent-volume snapshots, and a stable DNS name or virtual IP. Never scale multiple Master replicas over the same `/app/data` or `backupx.db`.
+:::
 
-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 applies a five-second SQLite busy timeout and command-queue indexes to reduce contention from concurrent Agent polls and task updates. Keep the database on a local or block-backed filesystem. For a file-level control-plane backup, stop the Master before copying the whole data directory; do not copy only `backupx.db` while it is running.
 
-BackupX chooses the data path per target:
+## Choose a network path
 
-| 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 |
+| Scenario | Agent Master URL | Agent proxy URL | Notes |
+| --- | --- | --- | --- |
+| Routed network or public service | `https://backup.example.com` | empty | Recommended; allow only outbound TCP 443 |
+| Corporate forward proxy | `https://backup.example.com` | `http://proxy.internal:3128` | HTTP(S) and SOCKS5(H) are supported |
+| SSH dynamic tunnel through a bastion | `https://backup.internal` | `socks5h://127.0.0.1:1080` | Preserves TLS hostname and resolves internal DNS through the tunnel |
+| SSH fixed local forward | `http://127.0.0.1:18340` | empty | The HTTP hop is protected by SSH; bind the forward to loopback only |
 
-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.
+For private PKI, provide the absolute path of a pre-provisioned PEM CA certificate. Do not use `--insecure-tls` in production.
 
-To configure the common `A → {B,C,D} → M` topology:
+When no explicit proxy is configured, Agent-to-Master HTTP traffic follows `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`. A system service does not normally inherit an interactive shell's environment, so set the proxy in the install wizard or Agent YAML for systemd deployments.
 
-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`.
+## Prepare the Master
 
-## Walkthrough
+Set a stable URL before generating commands:
 
-### 0. Set the Master URL for production clusters
-
-Before generating Agent install commands, make sure the Master URL shown to Agents is stable and reachable from every target host.
-
-If BackupX runs behind Docker, Nginx, a load balancer, or an outer reverse proxy, configure `server.external_url` or `BACKUPX_SERVER_EXTERNAL_URL` on the Master:
-
-```yaml title="config.yaml"
+```yaml title="/etc/backupx/config.yaml"
 server:
   external_url: "https://backup.example.com"
+  trusted_proxies:
+    - "127.0.0.1"
+    - "::1"
+    # Add the exact reverse-proxy IP or subnet when it is not local.
+    # - "172.18.0.0/16"
 ```
 
-This URL is baked into systemd units, foreground commands, and docker-compose snippets. If it is wrong, Agents will install successfully but stay offline because they keep polling an internal or browser-only address.
+`external_url` is the default install and Agent runtime address. A restricted node can override both generated target-side URLs with its tunnel or internal address while the browser continues to use the public address.
 
-### 1. Open the install wizard
+Use HTTPS across untrusted networks. For Master-relay uploads, configure the reverse proxy with unlimited request body size and request buffering disabled; see [Nginx Reverse Proxy](../deployment/nginx).
 
-In the Web Console → **Node Management** → **Add Node**. You'll see a three-step wizard.
+Configure the Agent with the final API URL, not an HTTP-to-HTTPS redirect. The Agent deliberately does not follow redirects so its authentication Token cannot be forwarded to an unintended 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 one-line install command is shown with a live countdown. Click copy, paste into the target machine, and run with root privileges. The default command embeds the rendered installer, so the target host does not need to fetch `/api/install/:token` through your reverse proxy. The public install URL is still available as a fallback.
+## Deploy an Agent
 
-### 2. One-line install on the target host
+Open **Node Management → Add Node**:
 
-Use the command generated by the Web Console. It writes the installer to a temporary file, validates the `BACKUPX_AGENT_INSTALL_V1` marker, then runs it with root privileges.
+1. Enter one node name, or up to 50 names in batch mode.
+2. Select systemd, Docker, or foreground mode; architecture; Agent release; command TTL; and download source.
+3. Select **Direct** or **Proxy or bastion**. For the restricted path, set an Agent-specific Master URL, proxy URL, or private CA path.
+4. Copy the generated command to the target host and run it with root privileges.
 
-The script runs automatically and:
+Systemd is recommended for host-file backup and restore because the Agent needs access to arbitrary local paths. A Docker Agent sees only explicitly mounted paths; recreate it with read-only backup-source mounts and separately scoped writable restore destinations before assigning file tasks.
 
-1. Detects OS and architecture (`uname -m`)
-2. Downloads the matching `backupx` binary from GitHub Release (or the ghproxy mirror)
-3. Installs to `/opt/backupx-agent` and creates a `backupx` system user
-4. Writes `/etc/systemd/system/backupx-agent.service` with the token baked into environment variables
-5. Runs `systemctl enable --now backupx-agent`
-6. Polls `/api/v1/agent/self` until the master confirms `status: online` (up to 30 s)
+The URL-based command downloads a one-time installer and verifies its marker before execution. The wizard binds the selected Agent URL, explicit proxy, and private CA to that download command as well as to the installed Agent configuration. If the install endpoint is still unreachable, use the separately displayed embedded command. The embedded command contains the long-lived node Token and must be handled as a secret.
 
-Docker mode uses the same `BACKUPX_AGENT_MASTER`, `BACKUPX_AGENT_TOKEN`, and `BACKUPX_AGENT_TEMP_DIR=/var/lib/backupx-agent/tmp` environment contract. After starting the container, the installer also probes `/api/v1/agent/self`; if the node does not come online, it prints `docker ps` and `docker logs --tail=100 backupx-agent` diagnostics before exiting non-zero.
+The installer:
 
-If you choose the URL-based fallback command and `curl` prints HTML or the shell reports `Syntax error: newline unexpected`, the install URL is being served by the web console instead of the backend. Ensure either `/api/install/` or `/install/` is forwarded to the BackupX backend, or use the embedded command generated by the console.
+1. Detects `linux/amd64` or `linux/arm64`.
+2. Downloads the selected Release archive through the explicit proxy when configured, otherwise using the host's normal direct/environment-proxy route, and verifies its SHA-256 sidecar when the release provides one.
+3. Writes `/etc/backupx-agent/config.yaml` and `/etc/backupx-agent/agent.token` with mode `0600`.
+4. Keeps the Token out of the systemd unit and Docker environment metadata.
+5. Starts the Agent and checks `/api/v1/agent/self` for up to 30 seconds.
+6. Returns non-zero with systemd or Docker diagnostics when the node does not become online.
 
-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.
+Older releases without checksum sidecars remain installable with a warning. New releases should always publish and verify the sidecar.
 
-### 3. Rotate agent tokens at any time
-
-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.
-
-### 4. Batch deployment
-
-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 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
-
-The node table shows the Agent health and command queue state: pending/dispatched depth, running long commands, timeouts, oldest active command age, and the latest Agent-side error. The same queue depth, running-command, and timeout snapshots are exported as Prometheus metrics:
-
-- `backupx_agent_command_queue_depth`
-- `backupx_agent_command_running`
-- `backupx_agent_command_timeout_total`
-
-## Known limitations
-
-- **Encrypted backups are Master-only** — the Agent doesn't hold Master's AES-256 key. Creating or updating a task with `encrypt: true` and a remote node or node pool is rejected up front
-- **Directory browser timeout** — remote dir listing is a synchronous RPC through the queue (15s default)
-- **Dispatched command timeout** — claimed-but-unfinished commands are marked `timeout` after 10 minutes
-
-## CLI reference
+### Installed systemd configuration
 
+```yaml title="/etc/backupx-agent/config.yaml"
+master: "https://backup.example.com"
+tokenFile: "/etc/backupx-agent/agent.token"
+heartbeatInterval: "15s"
+pollInterval: "5s"
+tempDir: "/var/lib/backupx-agent/tmp"
+proxyUrl: ""
+caCertFile: ""
 ```
-backupx agent --help
-  -master string    Master URL
-  -token string     Agent auth token
-  -config string    YAML config path (takes precedence over env)
-  -temp-dir string  Local temp directory (default /tmp/backupx-agent)
-  -insecure-tls     Skip TLS verification (testing only)
-```
-
-## systemd unit
 
 ```ini title="/etc/systemd/system/backupx-agent.service"
 [Unit]
 Description=BackupX Agent
-After=network.target
+After=network-online.target
+Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=10
 
 [Service]
 Type=simple
-User=backupx
-Environment="BACKUPX_AGENT_MASTER=https://master.example.com"
-Environment="BACKUPX_AGENT_TOKEN=your-token"
-ExecStart=/opt/backupx/backupx agent
+ExecStart=/opt/backupx-agent/backupx agent --config /etc/backupx-agent/config.yaml
 Restart=on-failure
 RestartSec=10s
+TimeoutStopSec=30s
+UMask=0077
+LimitNOFILE=65535
 
 [Install]
 WantedBy=multi-user.target
 ```
 
-Enable and start:
+The Agent runs as root because file backup and restore paths may belong to arbitrary system users. Restrict who can create tasks and who can modify the root-owned Agent configuration.
+
+## SSH bastion example
+
+Prefer a SOCKS tunnel when the internal Master uses HTTPS: its hostname and certificate validation remain unchanged.
+
+Create a dedicated SSH account and pre-provision its private key plus a verified `known_hosts` file. Then create:
+
+```sshconfig title="/etc/backupx-agent/ssh_config"
+Host backupx-bastion
+    HostName bastion.example.com
+    User backupx-tunnel
+    IdentityFile /etc/backupx-agent/tunnel_ed25519
+    IdentitiesOnly yes
+    BatchMode yes
+    UserKnownHostsFile /etc/backupx-agent/known_hosts
+    StrictHostKeyChecking yes
+    DynamicForward 127.0.0.1:1080
+    ExitOnForwardFailure yes
+    ServerAliveInterval 30
+    ServerAliveCountMax 3
+```
+
+```ini title="/etc/systemd/system/backupx-agent-tunnel.service"
+[Unit]
+Description=BackupX Agent SSH tunnel
+After=network-online.target
+Wants=network-online.target
+Before=backupx-agent.service
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/ssh -NT -F /etc/backupx-agent/ssh_config backupx-bastion
+Restart=always
+RestartSec=5s
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Add a drop-in so the Agent fails closed when the tunnel is unavailable:
+
+```ini title="/etc/systemd/system/backupx-agent.service.d/tunnel.conf"
+[Unit]
+Requires=backupx-agent-tunnel.service
+After=backupx-agent-tunnel.service
+```
+
+Reload and start both units:
 
 ```bash
-sudo systemctl enable --now backupx-agent
-sudo journalctl -u backupx-agent -f
+sudo systemctl daemon-reload
+sudo systemctl enable --now backupx-agent-tunnel backupx-agent
 ```
+
+In the wizard, keep the internal HTTPS Master URL and set the proxy to `socks5h://127.0.0.1:1080`. Verify the bastion host key out-of-band before enabling the service.
+
+## Central storage data paths
+
+| 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 | Agent streams through the authenticated Master API; Master writes to its local mount |
+
+The relay does not create a second complete temporary copy on the Master. Restore uses the reverse streaming path. Nginx request buffering must be disabled for this behavior to remain streaming.
+
+## Operations
+
+```bash
+sudo systemctl status backupx-agent
+sudo journalctl -u backupx-agent -n 100 --no-pager
+sudo /opt/backupx-agent/backupx agent --config /etc/backupx-agent/config.yaml
+```
+
+Rotate a node Token from its action menu. Update `/etc/backupx-agent/agent.token` on the node and restart the service during the 24-hour overlap window.
+
+Monitor these Prometheus metrics:
+
+- `backupx_agent_command_queue_depth`
+- `backupx_agent_command_running`
+- `backupx_agent_command_timeout_total`
+- `backupx_node_online`
+
+## CLI reference
+
+```text
+backupx agent --help
+  -master string       Master URL
+  -token string        Agent authentication token
+  -token-file string   Read the Agent Token from a file
+  -config string       YAML configuration path
+  -temp-dir string     Local temporary directory
+  -proxy-url string    HTTP(S) or SOCKS5(H) proxy
+  -ca-cert string      PEM CA certificate used to verify the Master
+  -insecure-tls        Skip TLS verification (testing only)
+```
+
+Environment variables: `BACKUPX_AGENT_MASTER`, `BACKUPX_AGENT_TOKEN`, `BACKUPX_AGENT_TOKEN_FILE`, `BACKUPX_AGENT_HEARTBEAT`, `BACKUPX_AGENT_POLL`, `BACKUPX_AGENT_TEMP_DIR`, `BACKUPX_AGENT_PROXY_URL`, `BACKUPX_AGENT_CA_CERT_FILE`, and `BACKUPX_AGENT_INSECURE_TLS`.
+
+## Known limitations
+
+- The Master is single-active because it uses embedded SQLite.
+- Encrypted backups are Master-only because Agents do not hold the Master encryption key.
+- Remote directory browsing is a synchronous queue RPC with a 15-second timeout.
+- Claimed commands that stop reporting progress are timed out according to the Master command monitor.

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

@@ -48,8 +48,9 @@ Images: [`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx) — suppor
 Download from the [Releases page](https://github.com/Awuqing/BackupX/releases) and run the installer:
 
 ```bash
+sha256sum -c backupx-v*-linux-amd64.tar.gz.sha256
 tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
-sudo ./install.sh        # creates system user, installs to /opt/backupx, sets up systemd + nginx
+sudo ./install.sh        # creates system user, installs to /opt/backupx, sets up systemd
 ```
 
 The installer:
@@ -58,7 +59,7 @@ The installer:
 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
+5. Leaves Nginx unchanged unless `INSTALL_NGINX=1` is explicitly requested
 6. Waits for `/api/auth/setup/status`; if startup fails, prints systemd diagnostics and exits non-zero
 
 ## From source
@@ -74,6 +75,8 @@ 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`.
 
+The Nginx template is opt-in because automatically installing a catch-all virtual host can intercept existing sites. Review `deploy/nginx.conf`, then use `sudo INSTALL_NGINX=1 ./deploy/install.sh` only when it matches the host.
+
 ## Verify the install
 
 ```bash

docs-site/docs/intro.md

@@ -21,7 +21,7 @@ description: Overview of BackupX — a self-hosted server backup management plat
 ```
 [Web Console] ─── JWT ──→ [Master (backupx)]
                              │
-                             │ HTTP long-poll (token auth)
+                             │ outbound HTTP polling (token auth)
                              ▼
                          [Agent (backupx agent)]
                              │

docs-site/docs/reference/cli.md

@@ -32,11 +32,14 @@ backupx agent --master http://master:8340 --token <token>
 |------|-------------|
 | `--master <url>` | Master URL |
 | `--token <token>` | Agent auth token |
+| `--token-file <path>` | Read the Agent Token from a file; preferred for services and containers |
 | `--config <path>` | YAML config (takes precedence over env) |
 | `--temp-dir <path>` | Local temp directory (default `/tmp/backupx-agent`) |
+| `--proxy-url <url>` | Explicit HTTP(S) or SOCKS5(H) proxy |
+| `--ca-cert <path>` | PEM CA certificate used to verify the Master |
 | `--insecure-tls` | Skip TLS verification (testing only) |
 
-Environment variables: `BACKUPX_AGENT_MASTER`, `BACKUPX_AGENT_TOKEN`, `BACKUPX_AGENT_HEARTBEAT`, `BACKUPX_AGENT_POLL`, `BACKUPX_AGENT_TEMP_DIR`, `BACKUPX_AGENT_INSECURE_TLS`.
+Environment variables: `BACKUPX_AGENT_MASTER`, `BACKUPX_AGENT_TOKEN`, `BACKUPX_AGENT_TOKEN_FILE`, `BACKUPX_AGENT_HEARTBEAT`, `BACKUPX_AGENT_POLL`, `BACKUPX_AGENT_TEMP_DIR`, `BACKUPX_AGENT_PROXY_URL`, `BACKUPX_AGENT_CA_CERT_FILE`, `BACKUPX_AGENT_INSECURE_TLS`. When no explicit proxy URL is set, the Agent also honors `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`.
 
 ## `backupx backint`
 

docs-site/i18n/zh-CN/code.json

@@ -69,7 +69,7 @@
   "feat.scheduling.title": {"message": "调度与保留策略"},
   "feat.scheduling.desc": {"message": "基于 Cron 的可视化调度编辑器，支持按天数/份数自动保留和空目录清理。"},
   "feat.cluster.title": {"message": "多节点集群"},
-  "feat.cluster.desc": {"message": "Master-Agent 基于 HTTP 长轮询。Agent 在本地执行任务并直接上传到存储 — 无需反向连通性。"},
+  "feat.cluster.desc": {"message": "Master-Agent 采用 Agent 主动出站轮询。支持代理、私有 CA 与 SSH 堡垒机，无需反向连通性。"},
   "feat.security.title": {"message": "默认安全"},
   "feat.security.desc": {"message": "JWT 认证、bcrypt、AES-256-GCM 加密配置、可选备份加密、完整审计日志。"},
   "feat.deploy.title": {"message": "部署轻量"},

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

@@ -1,7 +1,7 @@
 ---
 sidebar_position: 2
 title: 裸机部署
-description: 从预编译包或源码部署 BackupX（systemd + Nginx）。
+description: 从预编译包或源码加固部署 BackupX，Nginx 改为显式启用。
 ---
 
 # 裸机部署
@@ -11,6 +11,8 @@ description: 从预编译包或源码部署 BackupX（systemd + Nginx）。
 ```bash
 # 下载对应平台的压缩包
 curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-linux-amd64.tar.gz
+curl -LO https://github.com/Awuqing/BackupX/releases/latest/download/backupx-linux-amd64.tar.gz.sha256
+sha256sum -c backupx-linux-amd64.tar.gz.sha256
 
 # 解压并安装
 tar xzf backupx-linux-amd64.tar.gz && cd backupx-*-linux-amd64
@@ -23,9 +25,17 @@ sudo ./install.sh
 2. 复制二进制到 `/opt/backupx/bin/backupx`，并把 Web 控制台复制到 `/opt/backupx/web`
 3. 把默认配置安装到 `/etc/backupx/config.yaml`
 4. 安装并启用 `backupx.service` systemd 单元
-5. （可选）生成 Nginx 站点配置 — 参见 [Nginx 反向代理](./nginx)
+5. 默认不修改 Nginx；只有显式设置 `INSTALL_NGINX=1` 时才安装模板
 6. 验证首次初始化接口就绪后才报告安装成功
 
+可执行文件与前端资源由 root 所有，只有 `/opt/backupx/data` 允许 `backupx` 服务账户写入。`/etc/backupx/config.yaml` 以 `root:backupx`、`0640` 权限安装。
+
+仓库提供的 Nginx 模板只是起点，可能与现有默认站点冲突。先审核域名与 TLS 策略，再显式启用：
+
+```bash
+sudo INSTALL_NGINX=1 ./install.sh
+```
+
 如果要部署多节点集群，安装后请编辑 `/etc/backupx/config.yaml`，设置远程 Agent 可访问到的 Master URL：
 
 ```yaml
@@ -70,6 +80,7 @@ ExecStart=/opt/backupx/bin/backupx -config /etc/backupx/config.yaml
 Restart=on-failure
 RestartSec=5
 NoNewPrivileges=true
+UMask=0027
 LimitNOFILE=65535
 
 [Install]
@@ -87,6 +98,8 @@ curl -fsS http://127.0.0.1:8340/api/auth/setup/status
 
 访问 `http://your-server:8340`，可按需切换到 English，然后在“系统初始化 / System setup”页面创建首个管理员。若监听端口不是默认值，请为安装脚本传入对应的 `HEALTH_URL`。
 
+生产环境应通过 HTTPS 暴露 BackupX，或在防火墙限制 `8340` 端口。安装器不会自动修改防火墙。
+
 ## 密码重置
 
 忘记管理员密码时：

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

@@ -15,7 +15,11 @@ server:
   host: "0.0.0.0"             # BACKUPX_SERVER_HOST
   port: 8340                  # BACKUPX_SERVER_PORT
   mode: "release"             # release | debug
-  external_url: ""            # BACKUPX_SERVER_EXTERNAL_URL — Agent 安装脚本使用的 Master 对外 URL
+  external_url: ""            # BACKUPX_SERVER_EXTERNAL_URL — 稳定的 Master 对外 URL
+  trusted_proxies:             # BACKUPX_SERVER_TRUSTED_PROXIES — 准确的代理 IP/CIDR
+    - "127.0.0.1"
+    - "::1"
+  web_root: ""                # BACKUPX_SERVER_WEB_ROOT — 前端构建目录
 
 database:
   path: "./data/backupx.db"   # BACKUPX_DATABASE_PATH — 内嵌 SQLite
@@ -48,6 +52,7 @@ log:
 |--------|----------|
 | `server.port` | `BACKUPX_SERVER_PORT` |
 | `server.external_url` | `BACKUPX_SERVER_EXTERNAL_URL` |
+| `server.trusted_proxies` | `BACKUPX_SERVER_TRUSTED_PROXIES`（环境变量使用逗号分隔） |
 | `security.jwt_expire` | `BACKUPX_SECURITY_JWT_EXPIRE` |
 | `log.level` | `BACKUPX_LOG_LEVEL` |
 | `backup.max_concurrent` | `BACKUPX_BACKUP_MAX_CONCURRENT` |
@@ -64,3 +69,18 @@ server:
 ```
 
 BackupX 会用这个地址渲染一键 Agent 安装脚本和 docker-compose 片段。该地址必须能被所有 Agent 主机访问。只有在 `X-Forwarded-Proto` / `X-Forwarded-Host` 可靠且正好指向 Agent 可访问地址时，才建议留空。
+
+代理或 SSH 堡垒机场景可在安装向导中为单个 Agent 设置运行地址。公开安装链接仍使用 `server.external_url`，生成的 Agent 配置则使用该覆盖地址。
+
+## 可信反向代理
+
+BackupX 只接受 `server.trusted_proxies` 中来源提供的客户端转发头。默认仅允许本机 Nginx。代理运行在其他容器或主机时，加入准确 IP 或网段：
+
+```yaml
+server:
+  trusted_proxies:
+    - "127.0.0.1"
+    - "172.18.0.0/16"
+```
+
+不要配置 `0.0.0.0/0`，因为登录限流、安装令牌限流和审计日志都依赖客户端地址。BackupX 直接暴露且不应信任任何转发头时可设置空列表。

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

@@ -1,81 +1,96 @@
 ---
 sidebar_position: 1
 title: Docker 部署
-description: 生产级 Docker 部署方案，含 compose 配置、宿主目录挂载、环境变量覆盖。
+description: 带健康检查和持久化数据的加固单进程 Docker 部署。
 ---
 
 # Docker 部署
 
-BackupX 官方 Docker 镜像 [`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx) 支持多架构（linux/amd64 + linux/arm64）。
+官方镜像 [`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
+    image: ${BACKUPX_IMAGE:-awuqing/backupx:latest}
     container_name: backupx
     restart: unless-stopped
+    init: true
+    stop_grace_period: 30s
     ports:
-      - "8340:8340"
+      - "${BACKUPX_BIND_ADDRESS:-0.0.0.0}:${BACKUPX_PORT:-8340}:8340"
     volumes:
       - backupx-data:/app/data
-      # 挂载需要备份的宿主机目录：
-      - /var/www:/mnt/www:ro
-      - /etc/nginx:/mnt/nginx-conf:ro
+      # - /var/www:/mnt/www:ro
+      # - /etc/nginx:/mnt/nginx-conf:ro
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    cap_add:
+      - CHOWN
+      - DAC_OVERRIDE
+      - SETGID
+      - SETUID
     environment:
-      - TZ=Asia/Shanghai
-      # 远程 Agent 需要通过公网或可路由地址连接 Master 时必须配置：
-      # - BACKUPX_SERVER_EXTERNAL_URL=https://backup.example.com
-      - BACKUPX_LOG_LEVEL=info
-      - BACKUPX_BACKUP_MAX_CONCURRENT=2
+      TZ: Asia/Shanghai
+      # BACKUPX_SERVER_EXTERNAL_URL: https://backup.example.com
+      BACKUPX_LOG_LEVEL: info
+      BACKUPX_BACKUP_MAX_CONCURRENT: "2"
+    healthcheck:
+      test: ["CMD", "su-exec", "backupx:backupx", "wget", "-q", "-T", "3", "-O", "/dev/null", "http://127.0.0.1:8340/ready"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
 
 volumes:
   backupx-data:
 ```
 
-启动：
-
 ```bash
 docker compose up -d
+docker compose ps
 ```
 
+入口脚本仅以 root 完成旧镜像数据的所有权迁移，随后只运行一个非 root `backupx` 进程；Compose 仅保留初始化所需的所有权与 UID/GID 切换能力。后端同时提供 API 与前端静态文件，默认不挂载 Docker Socket，也不打包 Docker CLI。生产环境应把 `BACKUPX_IMAGE` 固定到明确 Release 标签。
+
 ## 备份宿主机目录
 
-想备份宿主机上的文件，需要将对应路径挂载进容器。在 Web UI 创建文件类型任务时，把源路径指向挂载后的容器内路径（如 `/mnt/www`）。
+按需挂载源目录，并在任务中使用容器内路径。容器中的 `backupx` 用户必须拥有读取权限；恢复目标应使用单独且范围受限的可写挂载。特权路径优先通过远程 Agent 处理；确实需要 Master 以 root 读取时，应显式设置 `user: "0:0"` 并审核每一个挂载。
 
 ## 多节点集群
 
-如果要在其他机器部署 Agent，请在 Master 容器上设置 `BACKUPX_SERVER_EXTERNAL_URL`，值为所有 Agent 都能访问到的 URL：
+设置所有 Agent 可达的稳定地址：
 
 ```yaml
 environment:
-  - BACKUPX_SERVER_EXTERNAL_URL=https://backup.example.com
+  BACKUPX_SERVER_EXTERNAL_URL: https://backup.example.com
 ```
 
-Agent 跨不可信网络访问时建议使用 HTTPS。控制台生成的一键安装脚本和 docker-compose 片段会把这个值写成 `BACKUPX_AGENT_MASTER`。
+跨不可信网络必须使用 HTTPS。代理、私有 CA 和 SSH 堡垒机场景见 [多节点集群](../features/multi-node)。
 
-## 环境变量
+外部反向代理运行在其他容器时，只把准确的 Docker 网桥网段加入 `BACKUPX_SERVER_TRUSTED_PROXIES`，例如 `172.18.0.0/16`，不要信任所有地址。
 
-所有配置项都可以通过 `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
+  TZ: Asia/Shanghai
+  BACKUPX_LOG_LEVEL: debug
+  BACKUPX_BACKUP_MAX_CONCURRENT: "4"
+  BACKUPX_BACKUP_TEMP_DIR: /tmp/backupx
 ```
 
-完整列表见 [配置参考](./configuration)。
+镜像内部端口固定为 `8340`，只通过 `BACKUPX_PORT` 修改宿主机发布端口。
 
-## 升级
-
-在 UI **系统设置 → 检查更新** 页面查看是否有新版，然后在宿主机上：
+## 升级与回退准备
 
 ```bash
-docker compose pull && docker compose up -d
+docker compose pull
+docker compose up -d
+docker compose ps
 ```
 
-无需手工迁移：BackupX 启动时自动迁移 SQLite schema。
+等待状态变为 `healthy` 后再切换流量或移除旧部署。升级前应停止 Master 后做文件级复制，或对整个 `backupx-data` 卷创建原子快照。同一个数据卷必须只运行一个活动 Master；SQLite 不支持多个 Master 容器共享 `/app/data`。

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

@@ -23,13 +23,16 @@ server {
     location /api/ {
         proxy_pass http://127.0.0.1:8340;
         proxy_http_version 1.1;
-        proxy_set_header Host $host;
+        proxy_set_header Host $http_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;
+        proxy_set_header X-Forwarded-Host $http_host;
+        proxy_set_header X-Forwarded-Port $server_port;
 
         # 大文件上传（用于恢复流程）
         client_max_body_size 0;
+        proxy_request_buffering off;
 
         # 实时日志使用 SSE，必须关闭缓冲
         proxy_buffering off;
@@ -39,6 +42,10 @@ server {
 }
 ```
 
+集群使用 Master 中转备份时必须保留 `proxy_request_buffering off`。否则 Nginx 会先把 Agent 上传的完整备份写入代理临时目录，再交给 BackupX，既失去流式传输优势，也可能占满代理磁盘。
+
+如果 Nginx 运行在另一台主机或另一个容器，只把该代理的 IP 或网段加入 `server.trusted_proxies`，不要配置 `0.0.0.0/0`。登录限流、安装令牌限流和审计日志都依赖可信的客户端地址。
+
 ## certbot 配置 HTTPS
 
 ```bash

docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/features/multi-node.md

@@ -1,155 +1,227 @@
 ---
 sidebar_position: 4
 title: 多节点集群
-description: Master-Agent 模式 — 通过 HTTP 长轮询把备份路由到远程服务器。
+description: 通过直连 HTTPS、正向代理或 SSH 堡垒机部署 BackupX Agent。
 ---
 
 # 多节点集群
 
-BackupX 支持 Master-Agent 模式：备份任务可以指定在哪个节点执行，Agent 在本地完成备份并直接上传到存储。所有连接都由 Agent 主动发起，所以远程服务器只需要出站 HTTP 访问权限。
+BackupX 使用一个单活 Master 作为控制面，在每台源服务器运行 Agent。所有连接都由 Agent 主动发起：每 15 秒上报心跳，每 5 秒轮询命令，不需要为 Agent 开放入站端口。
 
-## 架构
+## 架构与边界
 
-```
-[Web 控制台] ─── JWT ──→ [Master (backupx)]
-                              ↑  ↓
-                              │  │ HTTP 长轮询（Token 认证）
-                              │  ↓
-                         [Agent (backupx agent)]   ← 运行在远程服务器
-                              ↓
-                       [70+ 存储后端]
+```text
+[Web 控制台] ────────> [单活 Master + SQLite]
+                              ^
+                              | Agent 主动 HTTP(S) 轮询
+                    +---------+---------+
+                    |         |         |
+                 [Agent B] [Agent C] [Agent D]
+                    |         |         |
+                    +----> 存储目标
 ```
 
-- **协议** — HTTP 长轮询，Agent 主动发起所有连接
-- **心跳** — Agent 每 15s 上报一次；Master 超过 45s 未收到心跳即判为离线
-- **下发** — Master 把 `run_task` 命令写入队列，Agent 轮询拉取
-- **执行** — Agent 复用 BackupRunner（file / mysql / postgresql / sqlite / saphana）并直接上传到存储
-- **安全** — 每个节点独立 Token；Agent 不持有 Master 的 JWT 密钥或 AES-256 加密密钥
+- 每个节点有独立 Agent Token，Agent 不持有 Master 的 JWT 密钥或配置加密密钥。
+- Master 超过 45 秒未收到心跳即把节点标记为离线。
+- Master 持久化命令，Agent 领取后在本机执行。
+- 网络存储通常由 Agent 直传；Master 本地存储可显式启用认证流式中转。
 
-## 把 B/C/D 服务器集中备份到 M
+:::warning Master 只能单活
+内置 SQLite 不是共享多写数据库。同一个数据目录只能运行一个 Master。控制面高可用应采用主备主机、持久卷快照以及稳定 DNS 或虚拟 IP，故障时确保旧 Master 停止后再启动备用实例。不要让多个 Master 副本同时挂载 `/app/data` 或同一个 `backupx.db`。
+:::
 
-Master 作为控制面，每台源服务器安装一个 Agent。任务里的 **源服务器** 决定源路径和数据库工具在哪台机器解析，**存储目标** 决定备份产物最终保留在哪里。
+BackupX 会设置 5 秒 SQLite busy timeout，并为命令队列建立查询索引，降低 Agent 并发轮询及任务更新时的锁竞争。数据库应位于本地文件系统或块存储。采用文件复制备份控制面时，先停止 Master 再复制整个数据目录；运行期间不要只复制 `backupx.db`。
 
-BackupX 会根据目标类型选择数据路径：
+## 选择网络路径
 
-| 目标 | 数据路径 |
-| --- | --- |
-| S3、WebDAV、FTP、云盘或其他网络后端 | Agent 直接流式上传到目标 |
-| 启用 **远程备份经 Master 中转** 的 `local_disk`（例如通过 NFS 挂载的存储服务器 M） | Agent 通过认证后的 Master API 流式中转，由 Master 写入配置目录 |
+| 场景 | Agent Master 地址 | Agent 代理 URL | 说明 |
+| --- | --- | --- | --- |
+| 可路由内网或公网服务 | `https://backup.example.com` | 留空 | 推荐，只需放行出站 TCP 443 |
+| 企业正向代理 | `https://backup.example.com` | `http://proxy.internal:3128` | 支持 HTTP(S) 与 SOCKS5(H) |
+| 通过堡垒机建立 SSH 动态转发 | `https://backup.internal` | `socks5h://127.0.0.1:1080` | 保留 TLS 主机名，并通过隧道解析内网 DNS |
+| SSH 固定本地转发 | `http://127.0.0.1:18340` | 留空 | HTTP 链路位于 SSH 内，只能绑定回环地址 |
 
-中转过程不会在 Master 上额外落一份完整临时文件。把 Master 本地磁盘中的备份恢复到源 Agent 时会走反向流式通道。Agent 与 Master 之间跨越不可信网络时必须配置 HTTPS。
+私有 PKI 场景请填写目标节点上预置的 PEM CA 证书绝对路径。生产环境不要使用 `--insecure-tls`。
 
-典型的 `A → {B,C,D} → M` 拓扑按以下步骤配置：
+未配置显式代理时，Agent 到 Master 的 HTTP 流量会遵循 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY`。systemd 服务通常不会继承交互式 Shell 环境，因此 systemd 部署应在安装向导或 Agent YAML 中明确配置代理。
 
-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` 直传。
+## 准备 Master
 
-## 一键部署步骤
+生成命令前先设置稳定地址：
 
-### 0. 为生产集群设置 Master 对外 URL
-
-生成 Agent 安装命令前，请先确认 Master URL 对所有目标主机稳定可达。
-
-如果 BackupX 部署在 Docker、Nginx、负载均衡或外层反向代理后面，请在 Master 配置 `server.external_url` 或环境变量 `BACKUPX_SERVER_EXTERNAL_URL`：
-
-```yaml title="config.yaml"
+```yaml title="/etc/backupx/config.yaml"
 server:
   external_url: "https://backup.example.com"
+  trusted_proxies:
+    - "127.0.0.1"
+    - "::1"
+    # 代理不在本机时，只加入准确的代理 IP 或网段。
+    # - "172.18.0.0/16"
 ```
 
-该 URL 会写入 systemd 单元、前台运行命令和 docker-compose 片段。如果地址不正确，Agent 可能安装成功但始终离线，因为它会持续轮询一个内网地址或仅浏览器可访问的地址。
+`external_url` 是默认安装入口和 Agent 运行地址。受限节点可以让目标机侧生成的安装 URL 与 Agent 运行地址同时改用隧道或内网地址，浏览器仍继续访问公网地址。
 
-### 1. 打开安装向导
+跨不可信网络必须使用 HTTPS。Master 中转上传还要求反向代理关闭请求缓冲并允许大请求体，详见 [Nginx 反向代理](../deployment/nginx)。
 
-Web 控制台 → **节点管理** → **添加节点**，打开三步向导：
+Agent 必须直接配置最终 API 地址，不能依赖 HTTP 跳转到 HTTPS。Agent 会主动拒绝重定向，避免认证 Token 被转发到非预期主机。
 
-- **第一步 · 节点信息**：填写节点名称；或切换"批量创建"粘贴多行名称（每行一个，最多 50 个）
-- **第二步 · 部署参数**：选择安装模式（`systemd` 推荐、`Docker`、`前台运行` 调试用）、架构（默认自动检测）、Agent 版本（默认跟随 Master 版本）、有效期（5 分钟 / 15 分钟 / 1 小时 / 24 小时）、下载源（`GitHub` 直连或 `ghproxy` 镜像，国内服务器建议后者）
-- **第三步 · 安装命令**：一条一键安装命令 + 实时倒计时。点击复制，粘贴到目标机以 root 权限执行。默认命令会嵌入已渲染的安装脚本，目标机无需再通过反向代理访问 `/api/install/:token`；公开安装 URL 仍作为备用路径保留。
+## 部署 Agent
 
-### 2. 目标机一条命令完成
+打开 **节点管理 → 添加节点**：
 
-请直接使用 Web 控制台生成的命令。该命令会把安装脚本写入临时文件，校验 `BACKUPX_AGENT_INSTALL_V1` 魔数，再以 root 权限执行。
+1. 输入单个节点名，或在批量模式输入最多 50 个名称。
+2. 选择 systemd、Docker 或前台模式，以及架构、Agent Release、命令有效期和下载源。
+3. 选择 **直连** 或 **代理或堡垒机**。受限网络可填写节点专用 Master 地址、代理 URL 或私有 CA 路径。
+4. 把生成的命令复制到目标机，以 root 权限执行。
 
-脚本会自动：
+备份和恢复宿主机文件时推荐 systemd，因为 Agent 需要访问任意本地路径。Docker Agent 只能看到显式挂载的目录；分配文件任务前，应使用只读备份源 volume，并为恢复目标单独配置范围受限的可写挂载。
 
-1. 检测操作系统与架构（`uname -m`）
-2. 从 GitHub Release（或 ghproxy 镜像）下载匹配的 `backupx` 二进制
-3. 安装到 `/opt/backupx-agent`，创建系统用户 `backupx`
-4. 写入 `/etc/systemd/system/backupx-agent.service`（token 已烧入环境变量）
-5. 执行 `systemctl enable --now backupx-agent`
-6. 轮询 `/api/v1/agent/self`，直到 Master 确认 `status: online`（最多 30 秒）
+主命令通过一次性入口下载安装器，并在执行前校验脚本标记。向导会把所选 Agent 地址、显式代理和私有 CA 同时绑定到下载命令与安装后的 Agent 配置。如果目标网络仍无法访问安装入口，使用页面单独展示的嵌入式备用命令。嵌入式命令包含长期节点 Token，必须按密钥管理。
 
-Docker 模式使用同一组环境变量约定：`BACKUPX_AGENT_MASTER`、`BACKUPX_AGENT_TOKEN` 和 `BACKUPX_AGENT_TEMP_DIR=/var/lib/backupx-agent/tmp`。容器启动后，安装脚本同样会探测 `/api/v1/agent/self`；如果节点没有上线，会输出 `docker ps` 与 `docker logs --tail=100 backupx-agent` 排查命令，并以非零状态退出。
+安装器会：
 
-如果使用 URL 备用命令时 `curl` 输出 HTML，或 shell 报 `Syntax error: newline unexpected`，说明安装 URL 被 Web 控制台接管而不是转发到后端。需要确保 `/api/install/` 或 `/install/` 至少一个路径能转发到 BackupX 后端，或改用控制台生成的嵌入式命令。
+1. 检测 `linux/amd64` 或 `linux/arm64`。
+2. 配置显式代理时始终通过该代理下载 Release；否则使用主机的正常直连或环境代理路径，并在该版本提供 SHA-256 旁车文件时进行校验。
+3. 以 `0600` 权限写入 `/etc/backupx-agent/config.yaml` 和 `/etc/backupx-agent/agent.token`。
+4. 不把 Token 写入 systemd unit 或 Docker 环境元数据。
+5. 启动 Agent，并在 30 秒内轮询 `/api/v1/agent/self`。
+6. 节点未上线时返回非零状态，并输出 systemd 或 Docker 排查命令。
 
-脚本是幂等的：升级或重装只需重新生成一条安装命令再跑一次。一次性安装链接在 TTL 到期或被首次消费后立即作废。
+旧版本如果没有校验文件，会显示兼容性警告后继续安装；新版本应始终发布并校验该文件。
 
-### 3. 随时轮换 Agent Token
-
-节点操作列（︙）→ **重新生成 Token**。新 Token 一次性显示，旧 Token 24 小时内仍有效，便于滚动替换无需停机。24 小时后旧 Token 被拒绝。
-
-### 4. 批量部署
-
-第一步选"批量创建"粘贴节点名（每行一个，最多 50 个）。第三步显示每个节点对应的命令表格，底部「导出 .sh」可打包为单个 shell 文件，方便 SSH 循环或 Ansible 任务。
-
-### 5. 把任务路由到该节点
-
-在 **备份任务** 页面新建任务时选择对应源服务器。任务触发时：
-
-- 本机 / 未指定（`nodeId=0`）：Master 进程内直接执行
-- 远程节点：Master 写入命令队列 → Agent 拉取 → Agent 本地执行 → 上传 → 回报
-
-节点列表会展示 Agent 健康与命令队列状态：pending/dispatched 深度、运行中的长任务、超时数、最旧活跃命令年龄和最近 Agent 错误。同样的队列深度、运行中命令数和超时快照会导出为 Prometheus 指标：
-
-- `backupx_agent_command_queue_depth`
-- `backupx_agent_command_running`
-- `backupx_agent_command_timeout_total`
-
-## 已知限制
-
-- **加密备份仅支持 Master 本机执行**：Agent 不持有 Master 的 AES-256 密钥。创建或更新任务时，如果 `encrypt: true` 且选择了远程节点或节点池，会在入口直接拒绝
-- **目录浏览超时**：远程目录浏览通过命令队列做同步 RPC，默认 15s 超时
-- **派发命令超时**：Agent 领取但未完成的命令超过 10 分钟会被置 `timeout`
-
-## CLI 参考
+### systemd 安装结果
 
+```yaml title="/etc/backupx-agent/config.yaml"
+master: "https://backup.example.com"
+tokenFile: "/etc/backupx-agent/agent.token"
+heartbeatInterval: "15s"
+pollInterval: "5s"
+tempDir: "/var/lib/backupx-agent/tmp"
+proxyUrl: ""
+caCertFile: ""
 ```
-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
+After=network-online.target
+Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=10
 
 [Service]
 Type=simple
-User=backupx
-Environment="BACKUPX_AGENT_MASTER=https://master.example.com"
-Environment="BACKUPX_AGENT_TOKEN=your-token"
-ExecStart=/opt/backupx/backupx agent
+ExecStart=/opt/backupx-agent/backupx agent --config /etc/backupx-agent/config.yaml
 Restart=on-failure
 RestartSec=10s
+TimeoutStopSec=30s
+UMask=0077
+LimitNOFILE=65535
 
 [Install]
 WantedBy=multi-user.target
 ```
 
-启用并启动：
+Agent 以 root 运行，因为文件备份和恢复路径可能属于任意系统用户。应严格限制谁能创建任务，以及谁能修改 root 所有的 Agent 配置。
+
+## SSH 堡垒机示例
+
+内网 Master 使用 HTTPS 时优先采用 SOCKS 隧道，这样 Master 主机名与证书校验保持不变。
+
+先创建专用 SSH 账户，预置私钥和已经人工核对指纹的 `known_hosts`，再创建：
+
+```sshconfig title="/etc/backupx-agent/ssh_config"
+Host backupx-bastion
+    HostName bastion.example.com
+    User backupx-tunnel
+    IdentityFile /etc/backupx-agent/tunnel_ed25519
+    IdentitiesOnly yes
+    BatchMode yes
+    UserKnownHostsFile /etc/backupx-agent/known_hosts
+    StrictHostKeyChecking yes
+    DynamicForward 127.0.0.1:1080
+    ExitOnForwardFailure yes
+    ServerAliveInterval 30
+    ServerAliveCountMax 3
+```
+
+```ini title="/etc/systemd/system/backupx-agent-tunnel.service"
+[Unit]
+Description=BackupX Agent SSH tunnel
+After=network-online.target
+Wants=network-online.target
+Before=backupx-agent.service
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/ssh -NT -F /etc/backupx-agent/ssh_config backupx-bastion
+Restart=always
+RestartSec=5s
+
+[Install]
+WantedBy=multi-user.target
+```
+
+再添加依赖覆写，让隧道不可用时 Agent 关闭失败而不是绕过堡垒机：
+
+```ini title="/etc/systemd/system/backupx-agent.service.d/tunnel.conf"
+[Unit]
+Requires=backupx-agent-tunnel.service
+After=backupx-agent-tunnel.service
+```
 
 ```bash
-sudo systemctl enable --now backupx-agent
-sudo journalctl -u backupx-agent -f
+sudo systemctl daemon-reload
+sudo systemctl enable --now backupx-agent-tunnel backupx-agent
 ```
+
+在安装向导中保留内网 HTTPS Master 地址，把代理填写为 `socks5h://127.0.0.1:1080`。启用服务前必须通过独立渠道核对堡垒机 Host Key。
+
+## 集中存储数据路径
+
+| 目标 | 数据路径 |
+| --- | --- |
+| S3、WebDAV、FTP、云盘或其他网络后端 | Agent 直接流式上传到目标 |
+| 启用 **远程备份经 Master 中转** 的 `local_disk` | Agent 通过认证 Master API 流式上传，Master 写入本地挂载 |
+
+中转不会在 Master 上额外创建一份完整临时副本，恢复时走反向流式通道。Nginx 必须关闭请求缓冲，才能保持该特性。
+
+## 运维
+
+```bash
+sudo systemctl status backupx-agent
+sudo journalctl -u backupx-agent -n 100 --no-pager
+sudo /opt/backupx-agent/backupx agent --config /etc/backupx-agent/config.yaml
+```
+
+从节点操作菜单轮换 Token 后，在 24 小时重叠窗口内更新 `/etc/backupx-agent/agent.token` 并重启服务。
+
+建议监控：
+
+- `backupx_agent_command_queue_depth`
+- `backupx_agent_command_running`
+- `backupx_agent_command_timeout_total`
+- `backupx_node_online`
+
+## CLI 参考
+
+```text
+backupx agent --help
+  -master string       Master 地址
+  -token string        Agent Token
+  -token-file string   从文件读取 Agent Token
+  -config string       YAML 配置文件路径
+  -temp-dir string     本地临时目录
+  -proxy-url string    HTTP(S) 或 SOCKS5(H) 代理
+  -ca-cert string      用于校验 Master 的 PEM CA 证书
+  -insecure-tls        跳过 TLS 校验（仅测试）
+```
+
+环境变量：`BACKUPX_AGENT_MASTER`、`BACKUPX_AGENT_TOKEN`、`BACKUPX_AGENT_TOKEN_FILE`、`BACKUPX_AGENT_HEARTBEAT`、`BACKUPX_AGENT_POLL`、`BACKUPX_AGENT_TEMP_DIR`、`BACKUPX_AGENT_PROXY_URL`、`BACKUPX_AGENT_CA_CERT_FILE`、`BACKUPX_AGENT_INSECURE_TLS`。
+
+## 已知限制
+
+- Master 使用内置 SQLite，只支持单活。
+- 加密备份仅支持 Master 本机执行，因为 Agent 不持有 Master 加密密钥。
+- 远程目录浏览是同步队列 RPC，默认超时 15 秒。
+- Agent 领取后长期不更新的命令会由 Master 超时监控处理。

docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/installation.md

@@ -48,8 +48,9 @@ Docker Hub：[`awuqing/backupx`](https://hub.docker.com/r/awuqing/backupx)，支
 从 [Releases 页面](https://github.com/Awuqing/BackupX/releases) 下载对应平台的压缩包，执行安装脚本：
 
 ```bash
+sha256sum -c backupx-v*-linux-amd64.tar.gz.sha256
 tar xzf backupx-v*-linux-amd64.tar.gz && cd backupx-*
-sudo ./install.sh        # 创建系统用户、安装到 /opt/backupx、配置 systemd + Nginx
+sudo ./install.sh        # 创建系统用户、安装到 /opt/backupx、配置 systemd
 ```
 
 安装脚本会自动：
@@ -58,7 +59,7 @@ sudo ./install.sh        # 创建系统用户、安装到 /opt/backupx、配置
 2. 安装二进制到 `/opt/backupx/bin/backupx`，并把 Web 控制台安装到 `/opt/backupx/web`
 3. 生成 `/etc/backupx/config.yaml`（含安全默认值）
 4. 注册并启用 `backupx.service` systemd 单元
-5. （可选）配置 Nginx 反向代理
+5. 默认不修改 Nginx；只有显式设置 `INSTALL_NGINX=1` 时才安装模板
 6. 等待 `/api/auth/setup/status` 就绪；启动失败时输出 systemd 诊断并返回非零状态
 
 ## 从源码构建
@@ -74,6 +75,8 @@ 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`。
 
+自动安装兜底虚拟主机可能接管现有站点，因此 Nginx 模板改为显式启用。请先审核 `deploy/nginx.conf`，确认适合当前主机后再执行 `sudo INSTALL_NGINX=1 ./deploy/install.sh`。
+
 ## 验证安装
 
 ```bash

docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/intro.md

@@ -21,7 +21,7 @@ description: BackupX——自托管服务器备份管理平台概览。
 ```
 [Web 控制台] ─── JWT ──→ [Master (backupx)]
                              │
-                             │ HTTP 长轮询（Token 认证）
+                             │ Agent 主动 HTTP 轮询（Token 认证）
                              ▼
                          [Agent (backupx agent)]
                              │

docs-site/i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/cli.md

@@ -32,11 +32,14 @@ backupx agent --master http://master:8340 --token <token>
 |------|------|
 | `--master <url>` | Master URL |
 | `--token <token>` | Agent 认证令牌 |
+| `--token-file <path>` | 从文件读取 Agent Token，服务与容器部署推荐使用 |
 | `--config <path>` | YAML 配置文件（优先级高于环境变量） |
 | `--temp-dir <path>` | 本地临时目录（默认 `/tmp/backupx-agent`） |
+| `--proxy-url <url>` | 显式 HTTP(S) 或 SOCKS5(H) 代理 |
+| `--ca-cert <path>` | 用于校验 Master 的 PEM CA 证书 |
 | `--insecure-tls` | 跳过 TLS 校验（仅测试用） |
 
-环境变量：`BACKUPX_AGENT_MASTER`、`BACKUPX_AGENT_TOKEN`、`BACKUPX_AGENT_HEARTBEAT`、`BACKUPX_AGENT_POLL`、`BACKUPX_AGENT_TEMP_DIR`、`BACKUPX_AGENT_INSECURE_TLS`。
+环境变量：`BACKUPX_AGENT_MASTER`、`BACKUPX_AGENT_TOKEN`、`BACKUPX_AGENT_TOKEN_FILE`、`BACKUPX_AGENT_HEARTBEAT`、`BACKUPX_AGENT_POLL`、`BACKUPX_AGENT_TEMP_DIR`、`BACKUPX_AGENT_PROXY_URL`、`BACKUPX_AGENT_CA_CERT_FILE`、`BACKUPX_AGENT_INSECURE_TLS`。未设置显式代理时，Agent 同样遵循 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY`。
 
 ## `backupx backint`
 

docs-site/package.json

@@ -15,9 +15,9 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "3.10.0",
-    "@docusaurus/faster": "3.10.0",
-    "@docusaurus/preset-classic": "3.10.0",
+    "@docusaurus/core": "3.10.2",
+    "@docusaurus/faster": "3.10.2",
+    "@docusaurus/preset-classic": "3.10.2",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
@@ -25,9 +25,9 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.10.0",
-    "@docusaurus/tsconfig": "3.10.0",
-    "@docusaurus/types": "3.10.0",
+    "@docusaurus/module-type-aliases": "3.10.2",
+    "@docusaurus/tsconfig": "3.10.2",
+    "@docusaurus/types": "3.10.2",
     "@types/react": "^19.0.0",
     "typescript": "~6.0.2"
   },

docs-site/src/components/HomepageFeatures/index.tsx

@@ -93,7 +93,7 @@ const FEATURES: FeatureItem[] = [
     title: <Translate id="feat.cluster.title">Multi-Node Cluster</Translate>,
     description: (
       <Translate id="feat.cluster.desc">
-        Master-Agent via HTTP long-polling. Agents run tasks locally and upload directly to storage — no reverse connectivity.
+        Outbound-only Master-Agent polling with proxy, private-CA, and SSH-bastion support. No reverse connectivity is required.
       </Translate>
     ),
     icon: <NetworkIcon />,

server/cmd/backupx/agent.go

@@ -24,7 +24,10 @@ func runAgent(args []string) {
 	configPath := fs.String("config", "", "path to agent config YAML (optional)")
 	master := fs.String("master", "", "master URL, e.g. http://master.example.com:8340")
 	token := fs.String("token", "", "agent authentication token")
+	tokenFile := fs.String("token-file", "", "read the agent authentication token from a file")
 	tempDir := fs.String("temp-dir", "", "local temp directory for backup artifacts")
+	proxyURL := fs.String("proxy-url", "", "HTTP(S) or SOCKS5 proxy used to reach the master")
+	caCertFile := fs.String("ca-cert", "", "PEM CA certificate used to verify the master")
 	insecureTLS := fs.Bool("insecure-tls", false, "skip TLS verification (testing only)")
 
 	if err := fs.Parse(args); err != nil {
@@ -36,10 +39,21 @@ func runAgent(args []string) {
 		fmt.Fprintf(os.Stderr, "agent: load config: %v\n", err)
 		os.Exit(2)
 	}
-	cfg.MergeWithFlags(*master, *token, *tempDir)
+	cfg.ApplyOverrides(agent.Overrides{
+		Master:     *master,
+		Token:      *token,
+		TokenFile:  *tokenFile,
+		TempDir:    *tempDir,
+		ProxyURL:   *proxyURL,
+		CACertFile: *caCertFile,
+	})
 	if *insecureTLS {
 		cfg.InsecureSkipTLSVerify = true
 	}
+	if err := cfg.ResolveToken(); err != nil {
+		fmt.Fprintf(os.Stderr, "agent: %v\n", err)
+		os.Exit(2)
+	}
 	if err := cfg.Validate(); err != nil {
 		fmt.Fprintf(os.Stderr, "agent: %v\n", err)
 		os.Exit(2)

server/config.example.yaml

@@ -4,6 +4,9 @@ server:
   port: 8340
   mode: "release"              # debug | release
   external_url: ""             # 可选：Master 对 Agent 可达的 URL，例如 https://backup.example.com
+  trusted_proxies:              # 仅这些代理可提供 X-Forwarded-For；跨容器代理需加入其网段
+    - "127.0.0.1"
+    - "::1"
   web_root: ""                 # 前端静态目录；留空自动探测（./web、/opt/backupx/web 等）。
                                # 命中后后端直接托管 Web 控制台，无需额外 nginx 反向代理。
 

server/internal/agent/agent.go

@@ -28,10 +28,16 @@ type Agent struct {
 
 // New 构造 Agent。
 func New(cfg *Config, version string) (*Agent, error) {
+	if err := cfg.ResolveToken(); err != nil {
+		return nil, err
+	}
 	if err := cfg.Validate(); err != nil {
 		return nil, err
 	}
 	client := NewMasterClient(cfg.Master, cfg.Token, cfg.InsecureSkipTLSVerify)
+	if err := client.ConfigureTransport(cfg.ProxyURL, cfg.CACertFile); err != nil {
+		return nil, fmt.Errorf("configure master connection: %w", err)
+	}
 	executor := NewExecutor(client, cfg.TempDir)
 	return &Agent{
 		cfg:      cfg,
@@ -93,7 +99,6 @@ func (a *Agent) heartbeatLoop(ctx context.Context, interval time.Duration) {
 func (a *Agent) heartbeatOnce(ctx context.Context) error {
 	hostname, _ := os.Hostname()
 	req := HeartbeatRequest{
-		Token:        a.cfg.Token,
 		Hostname:     hostname,
 		IPAddress:    detectLocalIP(),
 		AgentVersion: a.version,

server/internal/agent/client.go

@@ -4,11 +4,14 @@ import (
 	"bytes"
 	"context"
 	"crypto/tls"
+	"crypto/x509"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
 	"net/http"
+	"net/url"
+	"os"
 	"strings"
 	"time"
 )
@@ -22,23 +25,64 @@ type MasterClient struct {
 
 // NewMasterClient 构造 Master 客户端。
 func NewMasterClient(baseURL, token string, insecureTLS bool) *MasterClient {
-	transport := &http.Transport{}
-	if insecureTLS {
-		transport.TLSClientConfig = &tls.Config{InsecureSkipVerify: true}
+	transport := http.DefaultTransport.(*http.Transport).Clone()
+	tlsConfig := &tls.Config{MinVersion: tls.VersionTLS12}
+	if transport.TLSClientConfig != nil {
+		tlsConfig = transport.TLSClientConfig.Clone()
+		tlsConfig.MinVersion = tls.VersionTLS12
 	}
+	// 仅用于用户显式开启的测试模式。生产环境应配置受信 CA。
+	tlsConfig.InsecureSkipVerify = insecureTLS // #nosec G402
+	transport.TLSClientConfig = tlsConfig
 	return &MasterClient{
 		baseURL: strings.TrimRight(baseURL, "/"),
 		token:   token,
 		httpClient: &http.Client{
 			Timeout:   120 * time.Second,
 			Transport: transport,
+			// Agent Token 是自定义认证头。禁止自动重定向，避免代理或错误
+			// 配置把它转发到另一个主机；Master URL 必须直接指向 API。
+			CheckRedirect: func(_ *http.Request, _ []*http.Request) error {
+				return http.ErrUseLastResponse
+			},
 		},
 	}
 }
 
+// ConfigureTransport 应用显式代理和私有 CA。默认 Transport 已保留
+// ProxyFromEnvironment，因此 ProxyURL 留空时 HTTP_PROXY/HTTPS_PROXY/NO_PROXY 生效。
+func (c *MasterClient) ConfigureTransport(proxyURL, caCertFile string) error {
+	transport, ok := c.httpClient.Transport.(*http.Transport)
+	if !ok {
+		return errors.New("agent http transport has unexpected type")
+	}
+	if strings.TrimSpace(proxyURL) != "" {
+		parsedProxy, err := url.Parse(strings.TrimSpace(proxyURL))
+		if err != nil {
+			return fmt.Errorf("parse proxy URL: %w", err)
+		}
+		transport.Proxy = http.ProxyURL(parsedProxy)
+	}
+	if strings.TrimSpace(caCertFile) == "" {
+		return nil
+	}
+	pemData, err := os.ReadFile(strings.TrimSpace(caCertFile))
+	if err != nil {
+		return fmt.Errorf("read CA certificate: %w", err)
+	}
+	roots, err := x509.SystemCertPool()
+	if err != nil || roots == nil {
+		roots = x509.NewCertPool()
+	}
+	if !roots.AppendCertsFromPEM(pemData) {
+		return errors.New("CA certificate file does not contain a valid PEM certificate")
+	}
+	transport.TLSClientConfig.RootCAs = roots
+	return nil
+}
+
 // HeartbeatRequest Agent 上报心跳的请求
 type HeartbeatRequest struct {
-	Token        string `json:"token"`
 	Hostname     string `json:"hostname,omitempty"`
 	IPAddress    string `json:"ipAddress,omitempty"`
 	AgentVersion string `json:"agentVersion,omitempty"`

server/internal/agent/client_test.go

@@ -0,0 +1,93 @@
+package agent
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestMasterClientKeepsEnvironmentProxySupport(t *testing.T) {
+	client := NewMasterClient("https://master.example.com", "token", false)
+	transport := client.httpClient.Transport.(*http.Transport)
+	if transport.Proxy == nil {
+		t.Fatal("default transport proxy function must be preserved")
+	}
+}
+
+func TestMasterClientConfiguresExplicitProxy(t *testing.T) {
+	client := NewMasterClient("https://master.example.com", "token", false)
+	if err := client.ConfigureTransport("socks5h://127.0.0.1:1080", ""); err != nil {
+		t.Fatal(err)
+	}
+	transport := client.httpClient.Transport.(*http.Transport)
+	requestURL, _ := url.Parse("https://master.example.com")
+	proxyURL, err := transport.Proxy(&http.Request{URL: requestURL})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if proxyURL == nil || proxyURL.String() != "socks5h://127.0.0.1:1080" {
+		t.Fatalf("proxy URL = %v", proxyURL)
+	}
+}
+
+func TestMasterClientRejectsInvalidCACertificate(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "invalid.pem")
+	if err := os.WriteFile(path, []byte("not a certificate"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	client := NewMasterClient("https://master.example.com", "token", false)
+	if err := client.ConfigureTransport("", path); err == nil {
+		t.Fatal("expected invalid CA certificate error")
+	}
+}
+
+func TestMasterClientDoesNotForwardTokenThroughRedirects(t *testing.T) {
+	receivedToken := ""
+	target := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		receivedToken = r.Header.Get("X-Agent-Token")
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer target.Close()
+	redirector := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, target.URL, http.StatusTemporaryRedirect)
+	}))
+	defer redirector.Close()
+
+	client := NewMasterClient(redirector.URL, "secret-agent-token", false)
+	if _, err := client.Heartbeat(context.Background(), HeartbeatRequest{}); err == nil {
+		t.Fatal("redirect response should not be accepted as a Master API response")
+	}
+	if receivedToken != "" {
+		t.Fatalf("Agent token leaked through redirect: %q", receivedToken)
+	}
+}
+
+func TestHeartbeatSendsTokenOnlyInAuthenticationHeader(t *testing.T) {
+	requestBody := ""
+	receivedHeader := ""
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, _ := io.ReadAll(r.Body)
+		requestBody = string(body)
+		receivedHeader = r.Header.Get("X-Agent-Token")
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"data":{"status":"ok","nodeId":1,"name":"node"}}`))
+	}))
+	defer server.Close()
+
+	client := NewMasterClient(server.URL, "secret-agent-token", false)
+	if _, err := client.Heartbeat(context.Background(), HeartbeatRequest{Hostname: "node"}); err != nil {
+		t.Fatal(err)
+	}
+	if receivedHeader != "secret-agent-token" {
+		t.Fatalf("authentication header = %q", receivedHeader)
+	}
+	if strings.Contains(requestBody, "secret-agent-token") || strings.Contains(requestBody, `"token"`) {
+		t.Fatalf("heartbeat body exposed the Agent token: %s", requestBody)
+	}
+}

server/internal/agent/config.go

@@ -10,8 +10,10 @@ package agent
 import (
 	"errors"
 	"fmt"
+	"net/url"
 	"os"
 	"strings"
+	"time"
 
 	"gopkg.in/yaml.v3"
 )
@@ -22,16 +24,34 @@ type Config struct {
 	Master string `yaml:"master"`
 	// Token 节点认证令牌（在 Master 创建节点时生成）
 	Token string `yaml:"token"`
+	// TokenFile 从文件读取节点认证令牌；适合 systemd 凭据和容器 secret。
+	// Token 与 TokenFile 同时设置时优先使用 Token。
+	TokenFile string `yaml:"tokenFile"`
 	// HeartbeatInterval 心跳间隔，默认 15s
 	HeartbeatInterval string `yaml:"heartbeatInterval"`
 	// PollInterval 命令轮询间隔，默认 5s
 	PollInterval string `yaml:"pollInterval"`
 	// TempDir 备份临时目录，默认 /var/lib/backupx-agent/tmp
 	TempDir string `yaml:"tempDir"`
+	// ProxyURL Agent 访问 Master 使用的显式代理。留空时遵循
+	// HTTP_PROXY、HTTPS_PROXY 与 NO_PROXY；支持 http(s) 和 socks5(h)。
+	ProxyURL string `yaml:"proxyUrl"`
+	// CACertFile 私有 CA 的 PEM 文件路径，用于安全连接内网 HTTPS Master。
+	CACertFile string `yaml:"caCertFile"`
 	// InsecureSkipTLSVerify 测试环境允许跳过 TLS 证书校验
 	InsecureSkipTLSVerify bool `yaml:"insecureSkipTlsVerify"`
 }
 
+// Overrides 表示命令行显式提供的 Agent 配置覆盖项。
+type Overrides struct {
+	Master     string
+	Token      string
+	TokenFile  string
+	TempDir    string
+	ProxyURL   string
+	CACertFile string
+}
+
 // LoadConfigFile 从 YAML 文件加载 Agent 配置。
 func LoadConfigFile(path string) (*Config, error) {
 	data, err := os.ReadFile(path)
@@ -50,42 +70,109 @@ func LoadConfigFile(path string) (*Config, error) {
 // 支持的环境变量：
 //   - BACKUPX_AGENT_MASTER            Master URL
 //   - BACKUPX_AGENT_TOKEN             节点认证令牌
+//   - BACKUPX_AGENT_TOKEN_FILE        节点认证令牌文件
 //   - BACKUPX_AGENT_HEARTBEAT         心跳间隔（如 15s）
 //   - BACKUPX_AGENT_POLL              命令轮询间隔（如 5s）
 //   - BACKUPX_AGENT_TEMP_DIR          临时目录
+//   - BACKUPX_AGENT_PROXY_URL         显式 HTTP(S)/SOCKS5 代理
+//   - BACKUPX_AGENT_CA_CERT_FILE      私有 CA PEM 文件
 //   - BACKUPX_AGENT_INSECURE_TLS      true / 1 跳过 TLS 校验
 func LoadConfigFromEnv() (*Config, error) {
 	cfg := &Config{
 		Master:                strings.TrimSpace(os.Getenv("BACKUPX_AGENT_MASTER")),
 		Token:                 strings.TrimSpace(os.Getenv("BACKUPX_AGENT_TOKEN")),
+		TokenFile:             strings.TrimSpace(os.Getenv("BACKUPX_AGENT_TOKEN_FILE")),
 		HeartbeatInterval:     strings.TrimSpace(os.Getenv("BACKUPX_AGENT_HEARTBEAT")),
 		PollInterval:          strings.TrimSpace(os.Getenv("BACKUPX_AGENT_POLL")),
 		TempDir:               strings.TrimSpace(os.Getenv("BACKUPX_AGENT_TEMP_DIR")),
+		ProxyURL:              strings.TrimSpace(os.Getenv("BACKUPX_AGENT_PROXY_URL")),
+		CACertFile:            strings.TrimSpace(os.Getenv("BACKUPX_AGENT_CA_CERT_FILE")),
 		InsecureSkipTLSVerify: strings.EqualFold(os.Getenv("BACKUPX_AGENT_INSECURE_TLS"), "true") || os.Getenv("BACKUPX_AGENT_INSECURE_TLS") == "1",
 	}
 	return applyConfigDefaults(cfg)
 }
 
-// MergeWithFlags 把命令行覆盖值合并入配置（非空覆盖）。
-func (c *Config) MergeWithFlags(master, token, tempDir string) {
-	if strings.TrimSpace(master) != "" {
-		c.Master = master
+// ApplyOverrides 把命令行覆盖值合并入配置（非空覆盖）。
+func (c *Config) ApplyOverrides(overrides Overrides) {
+	if strings.TrimSpace(overrides.Master) != "" {
+		c.Master = strings.TrimSpace(overrides.Master)
 	}
-	if strings.TrimSpace(token) != "" {
-		c.Token = token
+	tokenProvided := strings.TrimSpace(overrides.Token) != ""
+	if strings.TrimSpace(overrides.TokenFile) != "" {
+		c.TokenFile = strings.TrimSpace(overrides.TokenFile)
+		if !tokenProvided {
+			// An explicit --token-file must override a token inherited from YAML.
+			c.Token = ""
+		}
 	}
-	if strings.TrimSpace(tempDir) != "" {
-		c.TempDir = tempDir
+	if tokenProvided {
+		c.Token = strings.TrimSpace(overrides.Token)
 	}
+	if strings.TrimSpace(overrides.TempDir) != "" {
+		c.TempDir = strings.TrimSpace(overrides.TempDir)
+	}
+	if strings.TrimSpace(overrides.ProxyURL) != "" {
+		c.ProxyURL = strings.TrimSpace(overrides.ProxyURL)
+	}
+	if strings.TrimSpace(overrides.CACertFile) != "" {
+		c.CACertFile = strings.TrimSpace(overrides.CACertFile)
+	}
+}
+
+// ResolveToken 在所有配置源合并完成后读取 token 文件。
+func (c *Config) ResolveToken() error {
+	if strings.TrimSpace(c.Token) != "" || strings.TrimSpace(c.TokenFile) == "" {
+		c.Token = strings.TrimSpace(c.Token)
+		return nil
+	}
+	data, err := os.ReadFile(strings.TrimSpace(c.TokenFile))
+	if err != nil {
+		return fmt.Errorf("read agent token file: %w", err)
+	}
+	c.Token = strings.TrimSpace(string(data))
+	if c.Token == "" {
+		return errors.New("agent token file is empty")
+	}
+	return nil
 }
 
 // Validate 校验必填字段。
 func (c *Config) Validate() error {
+	masterURL, err := url.Parse(strings.TrimSpace(c.Master))
 	if strings.TrimSpace(c.Master) == "" {
 		return errors.New("master url is required (set via --master, BACKUPX_AGENT_MASTER or config file)")
 	}
+	if err != nil || (masterURL.Scheme != "http" && masterURL.Scheme != "https") || masterURL.Host == "" || masterURL.User != nil || masterURL.RawQuery != "" || masterURL.Fragment != "" {
+		return errors.New("master url must be an absolute http(s) URL without credentials, query or fragment")
+	}
 	if strings.TrimSpace(c.Token) == "" {
-		return errors.New("token is required (set via --token, BACKUPX_AGENT_TOKEN or config file)")
+		return errors.New("token is required (set via --token, --token-file, environment or config file)")
+	}
+	if c.ProxyURL != "" {
+		proxyURL, proxyErr := url.Parse(c.ProxyURL)
+		if proxyErr != nil || proxyURL.Host == "" {
+			return errors.New("proxy url must be an absolute URL")
+		}
+		switch proxyURL.Scheme {
+		case "http", "https", "socks5", "socks5h":
+		default:
+			return errors.New("proxy url scheme must be http, https, socks5 or socks5h")
+		}
+		if proxyURL.RawQuery != "" || proxyURL.Fragment != "" || (proxyURL.Path != "" && proxyURL.Path != "/") {
+			return errors.New("proxy url must not contain a path, query or fragment")
+		}
+	}
+	if c.CACertFile != "" && c.InsecureSkipTLSVerify {
+		return errors.New("ca cert file and insecure TLS cannot be enabled together")
+	}
+	for name, value := range map[string]string{
+		"heartbeat interval": c.HeartbeatInterval,
+		"poll interval":      c.PollInterval,
+	} {
+		duration, durationErr := time.ParseDuration(value)
+		if durationErr != nil || duration <= 0 {
+			return fmt.Errorf("%s must be a positive duration", name)
+		}
 	}
 	return nil
 }
@@ -101,5 +188,9 @@ func applyConfigDefaults(cfg *Config) (*Config, error) {
 		cfg.TempDir = "/var/lib/backupx-agent/tmp"
 	}
 	cfg.Master = strings.TrimRight(strings.TrimSpace(cfg.Master), "/")
+	cfg.Token = strings.TrimSpace(cfg.Token)
+	cfg.TokenFile = strings.TrimSpace(cfg.TokenFile)
+	cfg.ProxyURL = strings.TrimSpace(cfg.ProxyURL)
+	cfg.CACertFile = strings.TrimSpace(cfg.CACertFile)
 	return cfg, nil
 }

server/internal/agent/config_test.go

@@ -11,9 +11,12 @@ func TestLoadConfigFile(t *testing.T) {
 	path := filepath.Join(dir, "agent.yaml")
 	content := `master: http://master.example.com:8340/
 token: abc123
+tokenFile: /run/secrets/backupx_agent_token
 heartbeatInterval: 20s
 pollInterval: 3s
 tempDir: /var/backupx-agent
+proxyUrl: socks5h://127.0.0.1:1080
+caCertFile: /etc/backupx-agent/ca.pem
 insecureSkipTlsVerify: true
 `
 	if err := os.WriteFile(path, []byte(content), 0644); err != nil {
@@ -35,6 +38,9 @@ insecureSkipTlsVerify: true
 	if !cfg.InsecureSkipTLSVerify {
 		t.Errorf("insecure should be true")
 	}
+	if cfg.ProxyURL != "socks5h://127.0.0.1:1080" || cfg.CACertFile != "/etc/backupx-agent/ca.pem" {
+		t.Errorf("connection options not loaded: %+v", cfg)
+	}
 }
 
 func TestLoadConfigDefaults(t *testing.T) {
@@ -64,8 +70,15 @@ func TestConfigValidate(t *testing.T) {
 		{"valid", Config{Master: "http://m", Token: "t"}, false},
 		{"missing master", Config{Token: "t"}, true},
 		{"missing token", Config{Master: "http://m"}, true},
+		{"invalid master scheme", Config{Master: "ssh://m", Token: "t"}, true},
+		{"master credentials rejected", Config{Master: "https://user:pass@m", Token: "t"}, true},
+		{"valid socks proxy", Config{Master: "https://m", Token: "t", ProxyURL: "socks5h://127.0.0.1:1080"}, false},
+		{"invalid proxy", Config{Master: "https://m", Token: "t", ProxyURL: "ftp://proxy"}, true},
+		{"proxy path rejected", Config{Master: "https://m", Token: "t", ProxyURL: "http://proxy/connect"}, true},
+		{"invalid heartbeat", Config{Master: "https://m", Token: "t", HeartbeatInterval: "never"}, true},
 	}
 	for _, c := range cases {
+		_, _ = applyConfigDefaults(&c.cfg)
 		err := c.cfg.Validate()
 		if (err != nil) != c.wantErr {
 			t.Errorf("%s: err=%v wantErr=%v", c.name, err, c.wantErr)
@@ -75,7 +88,7 @@ func TestConfigValidate(t *testing.T) {
 
 func TestMergeWithFlags(t *testing.T) {
 	cfg := &Config{Master: "http://old", Token: "old"}
-	cfg.MergeWithFlags("http://new", "", "/tmp/x")
+	cfg.ApplyOverrides(Overrides{Master: "http://new", TempDir: "/tmp/x", ProxyURL: "http://proxy:3128"})
 	if cfg.Master != "http://new" {
 		t.Errorf("master not overridden: %q", cfg.Master)
 	}
@@ -85,17 +98,50 @@ func TestMergeWithFlags(t *testing.T) {
 	if cfg.TempDir != "/tmp/x" {
 		t.Errorf("tempDir: %q", cfg.TempDir)
 	}
+	if cfg.ProxyURL != "http://proxy:3128" {
+		t.Errorf("proxyUrl: %q", cfg.ProxyURL)
+	}
+}
+
+func TestTokenFileOverrideReplacesConfiguredToken(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "agent.token")
+	if err := os.WriteFile(path, []byte("file-token\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg := &Config{Token: "yaml-token", TokenFile: "/old/token"}
+	cfg.ApplyOverrides(Overrides{TokenFile: "  " + path + "  "})
+	if err := cfg.ResolveToken(); err != nil {
+		t.Fatal(err)
+	}
+	if cfg.Token != "file-token" || cfg.TokenFile != path {
+		t.Fatalf("token file override was not applied: %+v", cfg)
+	}
 }
 
 func TestLoadConfigFromEnv(t *testing.T) {
 	t.Setenv("BACKUPX_AGENT_MASTER", "http://env-master")
 	t.Setenv("BACKUPX_AGENT_TOKEN", "env-token")
+	t.Setenv("BACKUPX_AGENT_PROXY_URL", "http://env-proxy:8080")
 	t.Setenv("BACKUPX_AGENT_INSECURE_TLS", "true")
 	cfg, err := LoadConfigFromEnv()
 	if err != nil {
 		t.Fatal(err)
 	}
-	if cfg.Master != "http://env-master" || cfg.Token != "env-token" || !cfg.InsecureSkipTLSVerify {
+	if cfg.Master != "http://env-master" || cfg.Token != "env-token" || cfg.ProxyURL != "http://env-proxy:8080" || !cfg.InsecureSkipTLSVerify {
 		t.Errorf("env not picked up: %+v", cfg)
 	}
 }
+
+func TestResolveTokenFile(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "agent.token")
+	if err := os.WriteFile(path, []byte(" file-token\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg := &Config{TokenFile: path}
+	if err := cfg.ResolveToken(); err != nil {
+		t.Fatal(err)
+	}
+	if cfg.Token != "file-token" {
+		t.Fatalf("token = %q", cfg.Token)
+	}
+}

server/internal/backup/file_runner.go

@@ -84,7 +84,7 @@ func (r *FileRunner) Run(_ context.Context, task TaskSpec, writer LogWriter) (*R
 
 		walkErr := filepath.Walk(sourcePath, func(currentPath string, currentInfo os.FileInfo, walkErr error) error {
 			if walkErr != nil {
-				writer.WriteLine(fmt.Sprintf("⚠ 无法访问 %s: %v", currentPath, walkErr))
+				writer.WriteLine(fmt.Sprintf("[WARN] 无法访问 %s: %v", currentPath, walkErr))
 				return nil
 			}
 			relPath, err := filepath.Rel(baseParent, currentPath)
@@ -115,7 +115,7 @@ func (r *FileRunner) Run(_ context.Context, task TaskSpec, writer LogWriter) (*R
 
 			if currentInfo.IsDir() {
 				dirCount++
-				writer.WriteLine(fmt.Sprintf("📁 进入目录 %s", archiveName))
+				writer.WriteLine(fmt.Sprintf("[DIR] 进入目录 %s", archiveName))
 			}
 
 			header, err := tar.FileInfoHeader(currentInfo, "")

server/internal/config/config.go

@@ -2,6 +2,8 @@ package config
 
 import (
 	"fmt"
+	"net"
+	"net/url"
 	"strings"
 	"time"
 
@@ -21,6 +23,9 @@ type ServerConfig struct {
 	Port        int    `mapstructure:"port"`
 	Mode        string `mapstructure:"mode"`
 	ExternalURL string `mapstructure:"external_url"`
+	// TrustedProxies 限定可提供 X-Forwarded-For 等头部的反向代理地址。
+	// 默认仅信任本机代理；空列表表示不信任任何代理头。
+	TrustedProxies []string `mapstructure:"trusted_proxies"`
 	// WebRoot 指向前端构建产物目录。留空时后端会按部署惯例自动探测
 	// （./web、./web/dist、/opt/backupx/web 等）。探测命中后后端直接托管
 	// 前端 SPA，无需额外的 nginx 反向代理即可访问 Web 控制台。
@@ -91,6 +96,25 @@ func Load(configPath string) (Config, error) {
 	if cfg.Server.Mode == "" {
 		cfg.Server.Mode = "release"
 	}
+	cfg.Server.ExternalURL = strings.TrimRight(strings.TrimSpace(cfg.Server.ExternalURL), "/")
+	if cfg.Server.ExternalURL != "" {
+		externalURL, parseErr := url.Parse(cfg.Server.ExternalURL)
+		if parseErr != nil || (externalURL.Scheme != "http" && externalURL.Scheme != "https") || externalURL.Host == "" || externalURL.User != nil || externalURL.RawQuery != "" || externalURL.Fragment != "" {
+			return Config{}, fmt.Errorf("server.external_url must be an absolute http(s) URL without credentials, query or fragment")
+		}
+	}
+	if len(cfg.Server.TrustedProxies) == 1 && strings.Contains(cfg.Server.TrustedProxies[0], ",") {
+		cfg.Server.TrustedProxies = strings.Split(cfg.Server.TrustedProxies[0], ",")
+	}
+	for index := range cfg.Server.TrustedProxies {
+		proxy := strings.TrimSpace(cfg.Server.TrustedProxies[index])
+		cfg.Server.TrustedProxies[index] = proxy
+		if net.ParseIP(proxy) == nil {
+			if _, _, parseErr := net.ParseCIDR(proxy); parseErr != nil {
+				return Config{}, fmt.Errorf("server.trusted_proxies contains invalid IP or CIDR %q", proxy)
+			}
+		}
+	}
 	if cfg.Database.Path == "" {
 		cfg.Database.Path = "./data/backupx.db"
 	}
@@ -142,6 +166,7 @@ func applyDefaults(v *viper.Viper) {
 	v.SetDefault("server.port", 8340)
 	v.SetDefault("server.mode", "release")
 	v.SetDefault("server.external_url", "")
+	v.SetDefault("server.trusted_proxies", []string{"127.0.0.1", "::1"})
 	v.SetDefault("server.web_root", "")
 	v.SetDefault("database.path", "./data/backupx.db")
 	v.SetDefault("security.jwt_expire", "24h")

server/internal/config/config_test.go

@@ -21,6 +21,25 @@ func TestLoadUsesDefaultsWithoutConfigFile(t *testing.T) {
 	if cfg.Database.Path != "./data/backupx.db" {
 		t.Fatalf("expected default database path, got %s", cfg.Database.Path)
 	}
+	if len(cfg.Server.TrustedProxies) != 2 {
+		t.Fatalf("expected loopback trusted proxies, got %#v", cfg.Server.TrustedProxies)
+	}
+}
+
+func TestLoadRejectsInvalidExternalURLAndTrustedProxy(t *testing.T) {
+	tests := []string{
+		"server:\n  external_url: \"ssh://master.example.com\"\n",
+		"server:\n  trusted_proxies: [\"not-an-ip\"]\n",
+	}
+	for _, content := range tests {
+		configPath := filepath.Join(t.TempDir(), "config.yaml")
+		if err := os.WriteFile(configPath, []byte(content), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := Load(configPath); err == nil {
+			t.Fatalf("expected invalid configuration to fail: %s", content)
+		}
+	}
 }
 
 func TestLoadReadsServerExternalURLFromFile(t *testing.T) {
@@ -52,3 +71,28 @@ func TestLoadReadsServerExternalURLFromEnv(t *testing.T) {
 		t.Fatalf("expected external URL from env, got %q", cfg.Server.ExternalURL)
 	}
 }
+
+func TestLoadReadsTrustedProxiesFromEnv(t *testing.T) {
+	t.Setenv("BACKUPX_SERVER_TRUSTED_PROXIES", "127.0.0.1,172.18.0.0/16")
+	cfg, err := Load("")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(cfg.Server.TrustedProxies) != 2 || cfg.Server.TrustedProxies[1] != "172.18.0.0/16" {
+		t.Fatalf("trusted proxies = %#v", cfg.Server.TrustedProxies)
+	}
+}
+
+func TestLoadAllowsTrustedProxiesToBeDisabled(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.yaml")
+	if err := os.WriteFile(configPath, []byte("server:\n  trusted_proxies: []\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := Load(configPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(cfg.Server.TrustedProxies) != 0 {
+		t.Fatalf("trusted proxies should be disabled, got %#v", cfg.Server.TrustedProxies)
+	}
+}

server/internal/database/database.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 
 	"backupx/server/internal/config"
 	"backupx/server/internal/model"
@@ -18,7 +19,14 @@ func Open(cfg config.DatabaseConfig, logger *zap.Logger) (*gorm.DB, error) {
 		return nil, fmt.Errorf("create database dir: %w", err)
 	}
 
-	db, err := gorm.Open(sqlite.Open(cfg.Path), &gorm.Config{Logger: gormlogger.Default.LogMode(gormlogger.Silent)})
+	separator := "?"
+	if strings.Contains(cfg.Path, "?") {
+		separator = "&"
+	}
+	// busy_timeout 减少 Agent 轮询、心跳和任务写入同时发生时的瞬时锁错误。
+	// 维持默认回滚日志模式，保证当前嵌入式 SQLite 依赖的数据完整性。
+	dsn := cfg.Path + separator + "_pragma=busy_timeout(5000)"
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{Logger: gormlogger.Default.LogMode(gormlogger.Silent)})
 	if err != nil {
 		return nil, fmt.Errorf("open sqlite: %w", err)
 	}

server/internal/database/database_test.go

@@ -0,0 +1,40 @@
+package database
+
+import (
+	"path/filepath"
+	"testing"
+
+	"backupx/server/internal/config"
+	"backupx/server/internal/logger"
+)
+
+func TestOpenConfiguresSQLiteForSingleMasterConcurrency(t *testing.T) {
+	log, err := logger.New(config.LogConfig{Level: "error"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	db, err := Open(config.DatabaseConfig{Path: filepath.Join(t.TempDir(), "backupx.db")}, log)
+	if err != nil {
+		t.Fatal(err)
+	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = sqlDB.Close() })
+
+	var journalMode string
+	if err := db.Raw("PRAGMA journal_mode").Scan(&journalMode).Error; err != nil {
+		t.Fatal(err)
+	}
+	if journalMode != "delete" {
+		t.Fatalf("journal_mode = %q, want delete", journalMode)
+	}
+	var busyTimeout int
+	if err := db.Raw("PRAGMA busy_timeout").Scan(&busyTimeout).Error; err != nil {
+		t.Fatal(err)
+	}
+	if busyTimeout != 5000 {
+		t.Fatalf("busy_timeout = %d, want 5000", busyTimeout)
+	}
+}

server/internal/http/agent_handler.go

@@ -23,7 +23,7 @@ func NewAgentHandler(agentService *service.AgentService, nodeService *service.No
 	return &AgentHandler{agentService: agentService, nodeService: nodeService, restoreService: restoreService}
 }
 
-// extractToken 从请求头或 JSON body 中提取 Agent Token。
+// extractToken 从认证请求头中提取 Agent Token。
 func extractToken(c *gin.Context) string {
 	if t := strings.TrimSpace(c.GetHeader("X-Agent-Token")); t != "" {
 		return t
@@ -46,10 +46,10 @@ func (h *AgentHandler) Heartbeat(c *gin.Context) {
 		Arch         string `json:"arch"`
 	}
 	_ = c.ShouldBindJSON(&input)
-	// token 优先走 body（向后兼容），否则从 header 读
-	token := input.Token
+	// 新版 Agent 只通过请求头发送 Token；JSON body 仅保留旧版本兼容。
+	token := extractToken(c)
 	if token == "" {
-		token = extractToken(c)
+		token = input.Token
 	}
 	if token == "" {
 		c.JSON(stdhttp.StatusBadRequest, gin.H{"code": "INVALID_INPUT", "message": "missing token"})
@@ -72,7 +72,7 @@ func (h *AgentHandler) Heartbeat(c *gin.Context) {
 	})
 }
 
-// Poll Agent 长轮询获取下一条待执行命令。
+// Poll Agent 获取下一条待执行命令；Agent 按配置间隔主动轮询。
 // 无命令时返回 {command: null}。
 func (h *AgentHandler) Poll(c *gin.Context) {
 	node, err := h.agentService.AuthenticatedNode(c.Request.Context(), extractToken(c))

server/internal/http/forwarded_headers_test.go

@@ -0,0 +1,49 @@
+package http
+
+import (
+	stdhttp "net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestForwardedHeadersMiddlewareRejectsUntrustedHeaders(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	engine := gin.New()
+	engine.Use(ForwardedHeadersMiddleware([]string{"127.0.0.1", "10.0.0.0/8"}))
+	engine.GET("/master-url", func(c *gin.Context) {
+		c.String(stdhttp.StatusOK, resolveMasterURL(c, ""))
+	})
+
+	request := httptest.NewRequest(stdhttp.MethodGet, "http://master.example.com/master-url", nil)
+	request.RemoteAddr = "203.0.113.10:54321"
+	request.Header.Set("X-Forwarded-Host", "attacker.example.com")
+	request.Header.Set("X-Forwarded-Proto", "https")
+	recorder := httptest.NewRecorder()
+	engine.ServeHTTP(recorder, request)
+
+	if recorder.Body.String() != "http://master.example.com" {
+		t.Fatalf("untrusted forwarding headers changed URL: %q", recorder.Body.String())
+	}
+}
+
+func TestForwardedHeadersMiddlewareAcceptsTrustedProxy(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	engine := gin.New()
+	engine.Use(ForwardedHeadersMiddleware([]string{"10.0.0.0/8"}))
+	engine.GET("/master-url", func(c *gin.Context) {
+		c.String(stdhttp.StatusOK, resolveMasterURL(c, ""))
+	})
+
+	request := httptest.NewRequest(stdhttp.MethodGet, "http://backupx:8340/master-url", nil)
+	request.RemoteAddr = "10.10.0.5:43210"
+	request.Header.Set("X-Forwarded-Host", "backup.example.com")
+	request.Header.Set("X-Forwarded-Proto", "https")
+	recorder := httptest.NewRecorder()
+	engine.ServeHTTP(recorder, request)
+
+	if recorder.Body.String() != "https://backup.example.com" {
+		t.Fatalf("trusted forwarding headers were ignored: %q", recorder.Body.String())
+	}
+}

server/internal/http/install_flow_test.go

@@ -115,7 +115,7 @@ func setupInstallFlowRouterWithExternalURL(t *testing.T, externalURL string) (ht
 	return router, setupResp.Data.Token
 }
 
-func TestInstallTokenUsesConfiguredExternalURL(t *testing.T) {
+func TestInstallTokenUsesAgentSpecificURLAndConnectionSettings(t *testing.T) {
 	const externalURL = "https://public.example.com/base"
 	router, jwt := setupInstallFlowRouterWithExternalURL(t, externalURL)
 
@@ -141,11 +141,14 @@ func TestInstallTokenUsesConfiguredExternalURL(t *testing.T) {
 	}
 
 	genBody, _ := json.Marshal(map[string]any{
-		"mode":         "systemd",
-		"arch":         "auto",
-		"agentVersion": "v1.7.0",
-		"downloadSrc":  "github",
-		"ttlSeconds":   900,
+		"mode":           "systemd",
+		"arch":           "auto",
+		"agentVersion":   "v1.7.0",
+		"downloadSrc":    "github",
+		"ttlSeconds":     900,
+		"agentMasterUrl": "http://127.0.0.1:18340",
+		"proxyUrl":       "socks5h://127.0.0.1:1080",
+		"caCertFile":     "/etc/pki/internal-ca.pem",
 	})
 	genReq := httptest.NewRequest(http.MethodPost,
 		"/api/nodes/"+formatUint(batchResp.Data[0].ID)+"/install-tokens", bytes.NewBuffer(genBody))
@@ -156,6 +159,9 @@ func TestInstallTokenUsesConfiguredExternalURL(t *testing.T) {
 	if genRec.Code != 200 {
 		t.Fatalf("install-tokens failed: %d %s", genRec.Code, genRec.Body.String())
 	}
+	if genRec.Header().Get("Cache-Control") != "no-store" {
+		t.Fatalf("install-token response must not be cached: %#v", genRec.Header())
+	}
 	var genResp struct {
 		Data struct {
 			InstallToken string `json:"installToken"`
@@ -167,18 +173,21 @@ func TestInstallTokenUsesConfiguredExternalURL(t *testing.T) {
 	if err := json.Unmarshal(genRec.Body.Bytes(), &genResp); err != nil {
 		t.Fatalf("unmarshal gen: %v", err)
 	}
-	if genResp.Data.URL != externalURL+"/api/install/"+genResp.Data.InstallToken {
-		t.Fatalf("url should use external URL, got %q", genResp.Data.URL)
+	if genResp.Data.URL != "http://127.0.0.1:18340/api/install/"+genResp.Data.InstallToken {
+		t.Fatalf("url should use Agent-specific URL, got %q", genResp.Data.URL)
 	}
-	if genResp.Data.FallbackURL != externalURL+"/install/"+genResp.Data.InstallToken {
-		t.Fatalf("fallbackUrl should use external URL, got %q", genResp.Data.FallbackURL)
+	if genResp.Data.FallbackURL != "http://127.0.0.1:18340/install/"+genResp.Data.InstallToken {
+		t.Fatalf("fallbackUrl should use Agent-specific URL, got %q", genResp.Data.FallbackURL)
 	}
 	decodedScript, err := base64.StdEncoding.DecodeString(genResp.Data.ScriptBase64)
 	if err != nil {
 		t.Fatalf("scriptBase64 should be valid base64: %v", err)
 	}
-	if !strings.Contains(string(decodedScript), `MASTER_URL="`+externalURL+`"`) {
-		t.Fatalf("script should use external MASTER_URL:\n%s", string(decodedScript))
+	if !strings.Contains(string(decodedScript), `MASTER_URL="http://127.0.0.1:18340"`) {
+		t.Fatalf("script should use the Agent-specific Master URL:\n%s", string(decodedScript))
+	}
+	if !strings.Contains(string(decodedScript), `PROXY_URL="socks5h://127.0.0.1:1080"`) || !strings.Contains(string(decodedScript), `CA_CERT_FILE="/etc/pki/internal-ca.pem"`) {
+		t.Fatalf("script should include restricted-network settings:\n%s", string(decodedScript))
 	}
 }
 
@@ -258,8 +267,9 @@ func TestOneClickInstallFlow(t *testing.T) {
 	if scriptRec.Code != 200 {
 		t.Fatalf("script fetch failed: %d %s", scriptRec.Code, scriptRec.Body.String())
 	}
-	if !strings.Contains(scriptRec.Body.String(), "systemctl enable --now backupx-agent") {
-		t.Fatalf("script missing systemctl enable:\n%s", scriptRec.Body.String())
+	if !strings.Contains(scriptRec.Body.String(), "systemctl enable backupx-agent") ||
+		!strings.Contains(scriptRec.Body.String(), "systemctl restart backupx-agent") {
+		t.Fatalf("script missing systemctl enable/restart:\n%s", scriptRec.Body.String())
 	}
 	// Issue #46 防嗅探 headers：text/plain + nosniff + no-store + Content-Disposition
 	if ct := scriptRec.Header().Get("Content-Type"); !strings.HasPrefix(ct, "text/plain") {
@@ -354,7 +364,8 @@ func TestInstallScriptAliasUnderAPI(t *testing.T) {
 	if aliasRec.Code != 200 {
 		t.Fatalf("/api/install alias failed: %d %s", aliasRec.Code, aliasRec.Body.String())
 	}
-	if !strings.Contains(aliasRec.Body.String(), "systemctl enable --now backupx-agent") {
+	if !strings.Contains(aliasRec.Body.String(), "systemctl enable backupx-agent") ||
+		!strings.Contains(aliasRec.Body.String(), "systemctl restart backupx-agent") {
 		t.Errorf("alias should return rendered script, got:\n%s", aliasRec.Body.String())
 	}
 	if ct := aliasRec.Header().Get("Content-Type"); !strings.HasPrefix(ct, "text/plain") {
@@ -557,6 +568,9 @@ func TestInstallFlowComposeSuccessConsumesToken(t *testing.T) {
 	if !strings.Contains(composeRec.Body.String(), "BACKUPX_AGENT_TOKEN") {
 		t.Fatalf("compose missing token env:\n%s", composeRec.Body.String())
 	}
+	if composeRec.Header().Get("Cache-Control") != "no-store" || composeRec.Header().Get("X-Content-Type-Options") != "nosniff" {
+		t.Fatalf("compose response missing secret-safe headers: %#v", composeRec.Header())
+	}
 
 	scriptReq := httptest.NewRequest(http.MethodGet, "/api/install/"+genResp.Data.InstallToken, nil)
 	scriptRec := httptest.NewRecorder()

server/internal/http/install_handler.go

@@ -104,16 +104,22 @@ func (h *InstallHandler) Compose(c *gin.Context) {
 	}
 	h.recordConsumeAudit(c, consumed, "compose")
 	yaml, err := installscript.RenderComposeYaml(installscript.Context{
-		MasterURL:    resolveMasterURL(c, h.externalURL),
+		MasterURL:    installMasterURL(resolveMasterURL(c, h.externalURL), consumed.Record),
 		AgentToken:   consumed.Node.Token,
 		AgentVersion: consumed.Record.AgentVer,
 		Mode:         model.InstallModeDocker,
+		Arch:         consumed.Record.Arch,
 		NodeID:       consumed.Node.ID,
+		ProxyURL:     consumed.Record.ProxyURL,
+		CACertFile:   consumed.Record.CACertFile,
 	})
 	if err != nil {
 		c.String(stdhttp.StatusInternalServerError, "render error\n")
 		return
 	}
+	c.Header("X-Content-Type-Options", "nosniff")
+	c.Header("Cache-Control", "no-store")
+	c.Header("Content-Disposition", `attachment; filename="backupx-agent-compose.yml"`)
 	c.Data(stdhttp.StatusOK, "text/yaml; charset=utf-8", []byte(yaml))
 }
 
@@ -134,7 +140,7 @@ func (h *InstallHandler) recordConsumeAudit(c *gin.Context, consumed *service.Co
 
 func renderInstallScript(masterURL string, node *model.Node, record *model.AgentInstallToken) (string, error) {
 	return installscript.RenderScript(installscript.Context{
-		MasterURL:     masterURL,
+		MasterURL:     installMasterURL(masterURL, record),
 		AgentToken:    node.Token,
 		AgentVersion:  record.AgentVer,
 		Mode:          record.Mode,
@@ -142,9 +148,18 @@ func renderInstallScript(masterURL string, node *model.Node, record *model.Agent
 		DownloadBase:  installscript.DownloadBaseFor(record.DownloadSrc),
 		InstallPrefix: "/opt/backupx-agent",
 		NodeID:        node.ID,
+		ProxyURL:      record.ProxyURL,
+		CACertFile:    record.CACertFile,
 	})
 }
 
+func installMasterURL(fallback string, record *model.AgentInstallToken) string {
+	if record != nil && strings.TrimSpace(record.AgentMasterURL) != "" {
+		return strings.TrimRight(strings.TrimSpace(record.AgentMasterURL), "/")
+	}
+	return fallback
+}
+
 // resolveMasterURL 按优先级推导 Master URL：外部配置 > X-Forwarded-* > Request.Host。
 // 此为包级 helper，供 install_handler 和 node_handler 共用。
 func resolveMasterURL(c *gin.Context, externalURL string) string {

server/internal/http/middleware.go

@@ -3,6 +3,7 @@ package http
 import (
 	"context"
 	stdhttp "net/http"
+	"net/netip"
 	"strings"
 
 	"backupx/server/internal/apperror"
@@ -11,6 +12,46 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// ForwardedHeadersMiddleware 只允许配置中的反向代理提供转发头。
+// Gin 的 trusted_proxies 保护 ClientIP；这里同步保护安装命令使用的
+// X-Forwarded-Host 与 X-Forwarded-Proto，避免直连请求伪造 Agent 地址。
+func ForwardedHeadersMiddleware(trustedProxies []string) gin.HandlerFunc {
+	trustedPrefixes := make([]netip.Prefix, 0, len(trustedProxies))
+	for _, raw := range trustedProxies {
+		raw = strings.TrimSpace(raw)
+		if prefix, err := netip.ParsePrefix(raw); err == nil {
+			trustedPrefixes = append(trustedPrefixes, prefix)
+			continue
+		}
+		if addr, err := netip.ParseAddr(raw); err == nil {
+			trustedPrefixes = append(trustedPrefixes, netip.PrefixFrom(addr, addr.BitLen()))
+		}
+	}
+
+	return func(c *gin.Context) {
+		remote, err := netip.ParseAddrPort(c.Request.RemoteAddr)
+		trusted := false
+		if err == nil {
+			remoteAddr := remote.Addr().Unmap()
+			for _, prefix := range trustedPrefixes {
+				if prefix.Contains(remoteAddr) {
+					trusted = true
+					break
+				}
+			}
+		}
+		if !trusted {
+			for _, header := range []string{
+				"Forwarded", "X-Forwarded-For", "X-Forwarded-Host",
+				"X-Forwarded-Port", "X-Forwarded-Proto", "X-Real-IP",
+			} {
+				c.Request.Header.Del(header)
+			}
+		}
+		c.Next()
+	}
+}
+
 // CORSMiddleware handles Cross-Origin Resource Sharing for the API.
 func CORSMiddleware() gin.HandlerFunc {
 	return func(c *gin.Context) {

server/internal/http/node_handler.go

@@ -204,6 +204,7 @@ func (h *NodeHandler) RotateToken(c *gin.Context) {
 	recordAudit(c, h.auditService, "node", "rotate_token", "node",
 		fmt.Sprintf("%d", id), "",
 		fmt.Sprintf("轮换节点 Token (ID: %d)", id))
+	c.Header("Cache-Control", "no-store")
 	response.Success(c, gin.H{"newToken": tok})
 }
 
@@ -220,11 +221,14 @@ func (h *NodeHandler) CreateInstallToken(c *gin.Context) {
 		return
 	}
 	var input struct {
-		Mode         string `json:"mode"`
-		Arch         string `json:"arch"`
-		AgentVersion string `json:"agentVersion"`
-		DownloadSrc  string `json:"downloadSrc"`
-		TTLSeconds   int    `json:"ttlSeconds"`
+		Mode           string `json:"mode"`
+		Arch           string `json:"arch"`
+		AgentVersion   string `json:"agentVersion"`
+		DownloadSrc    string `json:"downloadSrc"`
+		TTLSeconds     int    `json:"ttlSeconds"`
+		AgentMasterURL string `json:"agentMasterUrl"`
+		ProxyURL       string `json:"proxyUrl"`
+		CACertFile     string `json:"caCertFile"`
 	}
 	if err := c.ShouldBindJSON(&input); err != nil {
 		c.JSON(stdhttp.StatusBadRequest, gin.H{"code": "INVALID_INPUT", "message": err.Error()})
@@ -246,13 +250,16 @@ func (h *NodeHandler) CreateInstallToken(c *gin.Context) {
 
 	out, err := h.installTokenSvc.CreateCommand(c.Request.Context(), service.InstallCommandInput{
 		InstallTokenInput: service.InstallTokenInput{
-			NodeID:       uint(id),
-			Mode:         input.Mode,
-			Arch:         input.Arch,
-			AgentVersion: input.AgentVersion,
-			DownloadSrc:  input.DownloadSrc,
-			TTLSeconds:   input.TTLSeconds,
-			CreatedByID:  h.resolveCurrentUserID(c),
+			NodeID:         uint(id),
+			Mode:           input.Mode,
+			Arch:           input.Arch,
+			AgentVersion:   input.AgentVersion,
+			DownloadSrc:    input.DownloadSrc,
+			TTLSeconds:     input.TTLSeconds,
+			CreatedByID:    h.resolveCurrentUserID(c),
+			AgentMasterURL: input.AgentMasterURL,
+			ProxyURL:       input.ProxyURL,
+			CACertFile:     input.CACertFile,
 		},
 		MasterURL: resolveMasterURL(c, h.externalURL),
 	})
@@ -278,6 +285,7 @@ func (h *NodeHandler) CreateInstallToken(c *gin.Context) {
 		"composeUrl":         out.ComposeURL,
 		"fallbackComposeUrl": out.FallbackComposeURL,
 	}
+	c.Header("Cache-Control", "no-store")
 	response.Success(c, body)
 }
 
@@ -292,18 +300,24 @@ func (h *NodeHandler) PreviewScript(c *gin.Context) {
 		return
 	}
 	src := c.DefaultQuery("downloadSrc", "github")
+	agentMasterURL := c.Query("agentMasterUrl")
+	if agentMasterURL == "" {
+		agentMasterURL = resolveMasterURL(c, h.externalURL)
+	}
 	ctx := installscript.Context{
-		MasterURL:     resolveMasterURL(c, h.externalURL),
+		MasterURL:     agentMasterURL,
 		AgentToken:    "<AGENT_TOKEN>",
 		AgentVersion:  ver,
 		Mode:          mode,
 		Arch:          arch,
 		DownloadBase:  installscript.DownloadBaseFor(src),
 		InstallPrefix: "/opt/backupx-agent",
+		ProxyURL:      c.Query("proxyUrl"),
+		CACertFile:    c.Query("caCertFile"),
 	}
 	script, err := installscript.RenderScript(ctx)
 	if err != nil {
-		response.Error(c, err)
+		response.Error(c, apperror.BadRequest("INSTALL_TOKEN_INVALID", "Agent 连接配置无效", err))
 		return
 	}
 	c.Data(stdhttp.StatusOK, "text/x-shellscript; charset=utf-8", []byte(script))

server/internal/http/router.go

@@ -61,7 +61,11 @@ type RouterDependencies struct {
 func NewRouter(deps RouterDependencies) *gin.Engine {
 	gin.SetMode(deps.Config.Server.Mode)
 	engine := gin.New()
+	if err := engine.SetTrustedProxies(deps.Config.Server.TrustedProxies); err != nil {
+		panic("invalid trusted proxy configuration: " + err.Error())
+	}
 	engine.Use(gin.Recovery())
+	engine.Use(ForwardedHeadersMiddleware(deps.Config.Server.TrustedProxies))
 	engine.Use(CORSMiddleware())
 	engine.Use(requestLogger(deps.Logger))
 

server/internal/installscript/deploy_install_test.go

@@ -6,11 +6,17 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"gopkg.in/yaml.v3"
 )
 
 func TestDeployInstallScriptSyntax(t *testing.T) {
 	scriptPath := filepath.Join("..", "..", "..", "deploy", "install.sh")
-	cmd := exec.Command("sh", "-n", scriptPath)
+	sh, err := exec.LookPath("sh")
+	if err != nil {
+		t.Skip("POSIX sh is not available on this platform")
+	}
+	cmd := exec.Command(sh, "-n", scriptPath)
 	output, err := cmd.CombinedOutput()
 	if err != nil {
 		t.Fatalf("install.sh syntax invalid: %v\n%s", err, output)
@@ -30,9 +36,13 @@ func TestDeployInstallScriptSupportsReleasePackageLayout(t *testing.T) {
 		`BIN_SOURCE="${BIN_SOURCE:-$SCRIPT_DIR/backupx}"`,
 		`WEB_SOURCE="${WEB_SOURCE:-$SCRIPT_DIR/web}"`,
 		`CONFIG_TEMPLATE="${CONFIG_TEMPLATE:-$SCRIPT_DIR/config.example.yaml}"`,
+		`SERVICE_SOURCE_DEFAULT="$SCRIPT_DIR/backupx.service"`,
 		`发布包安装请确认当前目录包含 ./backupx、./web 和 ./install.sh。`,
 		`cat > "/etc/systemd/system/$SERVICE_NAME.service" <<UNIT`,
-		`if [ -d "/etc/nginx/conf.d" ] && [ -f "$NGINX_SOURCE" ]; then`,
+		`if [ "$INSTALL_NGINX" = "1" ]; then`,
+		`[ "$PREFIX" = "/opt/backupx" ] && [ "$ETC_DIR" = "/etc/backupx" ]`,
+		`validate_install_path PREFIX "$PREFIX"`,
+		`拒绝通过符号链接写入受管目录`,
 	} {
 		if !strings.Contains(script, want) {
 			t.Fatalf("install.sh missing %q", want)
@@ -53,9 +63,72 @@ func TestDeployInstallScriptSupportsSourceBuildAndVerifiesFirstSetup(t *testing.
 		`HEALTH_URL="${HEALTH_URL:-http://127.0.0.1:8340/api/auth/setup/status}"`,
 		`systemctl is-active --quiet "$SERVICE_NAME"`,
 		`System setup`,
+		`chown -R root:root "$PREFIX/bin" "$PREFIX/web"`,
+		`find "$PREFIX/web" -type f -exec chmod 0644`,
+		`chown root:"$APP_GROUP" "$ETC_DIR/config.yaml"`,
+		`systemctl restart "$SERVICE_NAME"`,
 	} {
 		if !strings.Contains(script, want) {
 			t.Fatalf("install.sh missing %q", want)
 		}
 	}
 }
+
+func TestDockerDeploymentUsesSingleUnprivilegedProcess(t *testing.T) {
+	root := filepath.Join("..", "..", "..")
+	dockerfileData, err := os.ReadFile(filepath.Join(root, "Dockerfile"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	dockerfile := string(dockerfileData)
+	for _, want := range []string{"su-exec", "BACKUPX_SERVER_WEB_ROOT=/app/web", "HEALTHCHECK"} {
+		if !strings.Contains(dockerfile, want) {
+			t.Fatalf("Dockerfile missing %q", want)
+		}
+	}
+	for _, forbidden := range []string{"docker-cli", "COPY deploy/docker/nginx.conf"} {
+		if strings.Contains(dockerfile, forbidden) {
+			t.Fatalf("Dockerfile still contains %q", forbidden)
+		}
+	}
+
+	composeData, err := os.ReadFile(filepath.Join(root, "docker-compose.yml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var compose map[string]any
+	if err := yaml.Unmarshal(composeData, &compose); err != nil {
+		t.Fatalf("docker-compose.yml is not valid YAML: %v", err)
+	}
+	composeText := string(composeData)
+	for _, want := range []string{"no-new-privileges:true", "cap_drop:", "cap_add:", "DAC_OVERRIDE", "SETGID", "SETUID", "/ready"} {
+		if !strings.Contains(composeText, want) {
+			t.Fatalf("docker-compose.yml missing %q", want)
+		}
+	}
+	if strings.Contains(composeText, "docker.sock") {
+		t.Fatal("docker-compose.yml must not expose the Docker socket")
+	}
+}
+
+func TestReleaseWorkflowPublishesChecksums(t *testing.T) {
+	workflowPath := filepath.Join("..", "..", "..", ".github", "workflows", "release.yml")
+	workflowData, err := os.ReadFile(workflowPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var workflow map[string]any
+	if err := yaml.Unmarshal(workflowData, &workflow); err != nil {
+		t.Fatalf("release workflow is not valid YAML: %v", err)
+	}
+	workflowText := string(workflowData)
+	for _, want := range []string{
+		`cp deploy/backupx.service "${ARCHIVE_NAME}/"`,
+		`sha256sum "${ARCHIVE_NAME}.tar.gz"`,
+		`backupx-${{ matrix.goos }}-${{ matrix.goarch }}.tar.gz.sha256`,
+	} {
+		if !strings.Contains(workflowText, want) {
+			t.Fatalf("release workflow missing %q", want)
+		}
+	}
+}

server/internal/installscript/issue46_test.go

@@ -44,7 +44,7 @@ func TestRenderScriptUsesRootForBareMetalBackups(t *testing.T) {
 	}
 	for _, want := range []string{
 		"/var/lib/backupx-agent/tmp",
-		"install -d -m 0700 /var/lib/backupx-agent /var/lib/backupx-agent/tmp",
+		"install -d -m 0700 \"$CONFIG_DIR\" /var/lib/backupx-agent /var/lib/backupx-agent/tmp",
 	} {
 		if !strings.Contains(got, want) {
 			t.Errorf("script missing %q:\n%s", want, got)

server/internal/installscript/renderer.go

@@ -8,6 +8,7 @@ import (
 	_ "embed"
 	"fmt"
 	"net/url"
+	"path"
 	"strings"
 	"text/template"
 
@@ -30,6 +31,8 @@ type Context struct {
 	DownloadBase  string
 	InstallPrefix string
 	NodeID        uint
+	ProxyURL      string
+	CACertFile    string
 }
 
 // DownloadBaseFor 将下载源枚举转换为具体 URL 前缀。
@@ -84,6 +87,12 @@ func RenderComposeYaml(ctx Context) (string, error) {
 // 这些字段被直接写入 shell 双引号字符串和 YAML 双引号值；不做校验会带来
 // 注入风险（如 MasterURL 含 `"\nCOMMAND:` 可逃逸 YAML 结构）。
 func validateContext(ctx Context) error {
+	if ctx.Mode != model.InstallModeSystemd && ctx.Mode != model.InstallModeDocker && ctx.Mode != model.InstallModeForeground {
+		return fmt.Errorf("unsupported install mode %q", ctx.Mode)
+	}
+	if ctx.Arch != model.InstallArchAmd64 && ctx.Arch != model.InstallArchArm64 && ctx.Arch != model.InstallArchAuto {
+		return fmt.Errorf("unsupported install architecture %q", ctx.Arch)
+	}
 	if err := validateMasterURL(ctx.MasterURL); err != nil {
 		return err
 	}
@@ -93,6 +102,42 @@ func validateContext(ctx Context) error {
 	if err := validateAgentVersion(ctx.AgentVersion); err != nil {
 		return err
 	}
+	if err := validateProxyURL(ctx.ProxyURL); err != nil {
+		return err
+	}
+	if err := validateCACertFile(ctx.CACertFile); err != nil {
+		return err
+	}
+	if !path.IsAbs(ctx.InstallPrefix) || path.Clean(ctx.InstallPrefix) != ctx.InstallPrefix {
+		return fmt.Errorf("install prefix must be a clean absolute path without shell metacharacters")
+	}
+	for _, c := range ctx.InstallPrefix {
+		switch {
+		case c >= '0' && c <= '9':
+		case c >= 'a' && c <= 'z':
+		case c >= 'A' && c <= 'Z':
+		case c == '/' || c == '.' || c == '_' || c == '-' || c == '+':
+		default:
+			return fmt.Errorf("install prefix contains illegal character %q", c)
+		}
+	}
+	if err := validateDownloadBase(ctx.DownloadBase); err != nil {
+		return err
+	}
+	return nil
+}
+
+func validateDownloadBase(raw string) error {
+	if strings.ContainsAny(raw, " \t\r\n\"'`$\\") {
+		return fmt.Errorf("download base contains illegal characters")
+	}
+	u, err := url.Parse(raw)
+	if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" {
+		return fmt.Errorf("download base must be an absolute http(s) URL")
+	}
+	if u.User != nil || u.RawQuery != "" || u.Fragment != "" {
+		return fmt.Errorf("download base must not contain credentials, query or fragment")
+	}
 	return nil
 }
 
@@ -114,6 +159,43 @@ func validateMasterURL(raw string) error {
 	if u.Host == "" {
 		return fmt.Errorf("master URL missing host")
 	}
+	if u.User != nil || u.RawQuery != "" || u.Fragment != "" {
+		return fmt.Errorf("master URL must not contain credentials, query or fragment")
+	}
+	return nil
+}
+
+func validateProxyURL(raw string) error {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return nil
+	}
+	if strings.ContainsAny(raw, " \t\r\n\"'`$\\") {
+		return fmt.Errorf("proxy URL contains illegal characters")
+	}
+	u, err := url.Parse(raw)
+	if err != nil || u.Host == "" {
+		return fmt.Errorf("invalid proxy URL")
+	}
+	switch u.Scheme {
+	case "http", "https", "socks5", "socks5h":
+	default:
+		return fmt.Errorf("proxy URL scheme must be http, https, socks5 or socks5h")
+	}
+	if u.User != nil || u.RawQuery != "" || u.Fragment != "" || (u.Path != "" && u.Path != "/") {
+		return fmt.Errorf("proxy URL must not contain credentials, path, query or fragment")
+	}
+	return nil
+}
+
+func validateCACertFile(file string) error {
+	file = strings.TrimSpace(file)
+	if file == "" {
+		return nil
+	}
+	if !path.IsAbs(file) || path.Clean(file) != file || strings.ContainsAny(file, " \t\r\n\"'`$\\") {
+		return fmt.Errorf("CA certificate path must be a clean absolute path without shell metacharacters")
+	}
 	return nil
 }
 
@@ -160,6 +242,9 @@ func validateAgentVersion(v string) error {
 }
 
 func withDefaults(ctx Context) Context {
+	if ctx.Arch == "" {
+		ctx.Arch = model.InstallArchAuto
+	}
 	if ctx.InstallPrefix == "" {
 		ctx.InstallPrefix = "/opt/backupx-agent"
 	}

server/internal/installscript/renderer_test.go

@@ -2,11 +2,13 @@ package installscript
 
 import (
 	"os"
+	"os/exec"
 	"path/filepath"
 	"strings"
 	"testing"
 
 	"backupx/server/internal/model"
+	"gopkg.in/yaml.v3"
 )
 
 // 使用合法 hex token（32 字节 = 64 字符）以通过 validateAgentToken 校验
@@ -27,11 +29,13 @@ func TestRenderScriptSystemd(t *testing.T) {
 		t.Fatalf("render err: %v", err)
 	}
 	mustContain := []string{
-		"BACKUPX_AGENT_MASTER=${MASTER_URL}",
-		`Environment="BACKUPX_AGENT_TOKEN=${AGENT_TOKEN}"`,
+		`master: "${MASTER_URL}"`,
+		`tokenFile: "${TOKEN_FILE}"`,
+		`ExecStart=${INSTALL_PREFIX}/backupx agent --config ${CONFIG_FILE}`,
 		"/var/lib/backupx-agent/tmp",
 		"systemctl daemon-reload",
-		"systemctl enable --now backupx-agent",
+		"systemctl enable backupx-agent",
+		"systemctl restart backupx-agent",
 		"systemctl status backupx-agent",
 		"X-Agent-Token: ${AGENT_TOKEN}",
 		"MASTER_URL=\"https://master.example.com\"",
@@ -48,6 +52,29 @@ func TestRenderScriptSystemd(t *testing.T) {
 			t.Errorf("systemd script unexpectedly contains %q", s)
 		}
 	}
+	if strings.Contains(got, `Environment="BACKUPX_AGENT_TOKEN=`) {
+		t.Errorf("systemd unit must not expose the agent token in its environment:\n%s", got)
+	}
+}
+
+func TestRenderedInstallScriptSyntax(t *testing.T) {
+	sh, err := exec.LookPath("sh")
+	if err != nil {
+		t.Skip("POSIX sh is not available on this platform")
+	}
+	for _, mode := range []string{model.InstallModeSystemd, model.InstallModeDocker, model.InstallModeForeground} {
+		ctx := testCtx
+		ctx.Mode = mode
+		script, renderErr := RenderScript(ctx)
+		if renderErr != nil {
+			t.Fatal(renderErr)
+		}
+		cmd := exec.Command(sh, "-n")
+		cmd.Stdin = strings.NewReader(script)
+		if output, syntaxErr := cmd.CombinedOutput(); syntaxErr != nil {
+			t.Fatalf("%s installer syntax invalid: %v\n%s", mode, syntaxErr, output)
+		}
+	}
 }
 
 func TestRenderScriptForeground(t *testing.T) {
@@ -90,8 +117,11 @@ func TestRenderScriptDocker(t *testing.T) {
 	if !strings.Contains(got, `"awuqing/backupx:${AGENT_VERSION}" agent`) {
 		t.Errorf("docker script must start image in agent mode:\n%s", got)
 	}
-	if !strings.Contains(got, `-e "BACKUPX_AGENT_TEMP_DIR=/var/lib/backupx-agent/tmp"`) {
-		t.Errorf("docker script missing temp dir env:\n%s", got)
+	if !strings.Contains(got, `-v /etc/backupx-agent:/etc/backupx-agent:ro`) {
+		t.Errorf("docker script missing protected config mount:\n%s", got)
+	}
+	if !strings.Contains(got, `agent --config /etc/backupx-agent/config.yaml`) {
+		t.Errorf("docker script must load the protected config file:\n%s", got)
 	}
 	if !strings.Contains(got, `docker logs --tail=100 backupx-agent`) {
 		t.Errorf("docker script missing diagnostic log command:\n%s", got)
@@ -102,6 +132,9 @@ func TestRenderScriptDocker(t *testing.T) {
 	if strings.Contains(got, "systemctl daemon-reload") {
 		t.Errorf("docker script should not reference systemctl:\n%s", got)
 	}
+	if strings.Contains(got, `-e "BACKUPX_AGENT_TOKEN=`) {
+		t.Errorf("docker inspect must not expose the agent token:\n%s", got)
+	}
 }
 
 func TestDockerEntrypointForwardsAgentSubcommand(t *testing.T) {
@@ -111,12 +144,18 @@ func TestDockerEntrypointForwardsAgentSubcommand(t *testing.T) {
 		t.Fatalf("read docker entrypoint: %v", err)
 	}
 	script := string(got)
-	if !strings.Contains(script, `"${1:-}" = "agent"`) {
-		t.Fatalf("entrypoint must detect the agent subcommand before starting server:\n%s", script)
-	}
 	if !strings.Contains(script, `exec /app/bin/backupx "$@"`) {
 		t.Fatalf("entrypoint must exec backupx with forwarded args:\n%s", script)
 	}
+	if !strings.Contains(script, `exec su-exec backupx:backupx /app/bin/backupx "$@"`) {
+		t.Fatalf("master entrypoint must drop privileges after data migration:\n%s", script)
+	}
+	if !strings.Contains(script, `export HOME=/app`) {
+		t.Fatalf("master entrypoint must set the service user's home directory:\n%s", script)
+	}
+	if strings.Contains(script, "nginx") || strings.Contains(script, "wait -n") {
+		t.Fatalf("entrypoint should run a single foreground process:\n%s", script)
+	}
 }
 
 func TestRenderComposeYaml(t *testing.T) {
@@ -138,9 +177,40 @@ func TestRenderComposeYaml(t *testing.T) {
 	if !strings.Contains(got, `BACKUPX_AGENT_TEMP_DIR: "/var/lib/backupx-agent/tmp"`) {
 		t.Errorf("compose missing temp dir env:\n%s", got)
 	}
+	if !strings.Contains(got, `user: "0:0"`) || !strings.Contains(got, "no-new-privileges:true") {
+		t.Errorf("compose missing root execution declaration or security option:\n%s", got)
+	}
 	if !strings.Contains(got, "/var/lib/backupx-agent:/var/lib/backupx-agent") {
 		t.Errorf("compose missing agent data volume:\n%s", got)
 	}
+	var document map[string]any
+	if err := yaml.Unmarshal([]byte(got), &document); err != nil {
+		t.Fatalf("compose is not valid YAML: %v\n%s", err, got)
+	}
+}
+
+func TestRenderComposeYamlIncludesRestrictedNetworkSettings(t *testing.T) {
+	ctx := testCtx
+	ctx.Mode = model.InstallModeDocker
+	ctx.ProxyURL = "socks5h://127.0.0.1:1080"
+	ctx.CACertFile = "/etc/backupx-agent/ca.pem"
+	got, err := RenderComposeYaml(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{
+		`BACKUPX_AGENT_PROXY_URL: "socks5h://127.0.0.1:1080"`,
+		`BACKUPX_AGENT_CA_CERT_FILE: "/etc/backupx-agent/ca.pem"`,
+		`- /etc/backupx-agent/ca.pem:/etc/backupx-agent/ca.pem:ro`,
+	} {
+		if !strings.Contains(got, want) {
+			t.Errorf("compose missing %q:\n%s", want, got)
+		}
+	}
+	var document map[string]any
+	if err := yaml.Unmarshal([]byte(got), &document); err != nil {
+		t.Fatalf("compose is not valid YAML: %v\n%s", err, got)
+	}
 }
 
 func TestRenderScriptRejectsInjectedMasterURL(t *testing.T) {
@@ -159,6 +229,73 @@ func TestRenderScriptRejectsInjectedMasterURL(t *testing.T) {
 	}
 }
 
+func TestRenderScriptIncludesRestrictedNetworkSettings(t *testing.T) {
+	ctx := testCtx
+	ctx.MasterURL = "http://127.0.0.1:18340"
+	ctx.ProxyURL = "socks5h://127.0.0.1:1080"
+	ctx.CACertFile = "/etc/pki/internal-ca.pem"
+	got, err := RenderScript(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{
+		`PROXY_URL="socks5h://127.0.0.1:1080"`,
+		`CA_CERT_FILE="/etc/pki/internal-ca.pem"`,
+		`proxyUrl: "${PROXY_URL}"`,
+		`caCertFile: "${CA_CERT_FILE}"`,
+		`curl -fsSL --retry 3 --retry-delay 2 --connect-timeout 15 --proxy "$PROXY_URL"`,
+	} {
+		if !strings.Contains(got, want) {
+			t.Errorf("restricted network script missing %q", want)
+		}
+	}
+}
+
+func TestRenderScriptRejectsUnsafeRestrictedNetworkSettings(t *testing.T) {
+	for _, mutate := range []func(*Context){
+		func(ctx *Context) { ctx.ProxyURL = "ftp://proxy.example.com" },
+		func(ctx *Context) { ctx.ProxyURL = "http://user:pass@proxy.example.com" },
+		func(ctx *Context) { ctx.ProxyURL = "http://proxy.example.com/connect" },
+		func(ctx *Context) { ctx.CACertFile = "relative-ca.pem" },
+	} {
+		ctx := testCtx
+		mutate(&ctx)
+		if _, err := RenderScript(ctx); err == nil {
+			t.Fatalf("expected restricted network settings to be rejected: %+v", ctx)
+		}
+	}
+}
+
+func TestRenderScriptRejectsUnsafeDeploymentSettings(t *testing.T) {
+	for _, mutate := range []func(*Context){
+		func(ctx *Context) { ctx.Mode = "unknown" },
+		func(ctx *Context) { ctx.Arch = "386" },
+		func(ctx *Context) { ctx.InstallPrefix = "/opt/backupx;touch/tmp/pwned" },
+		func(ctx *Context) { ctx.DownloadBase = "https://user:pass@example.com/releases" },
+	} {
+		ctx := testCtx
+		mutate(&ctx)
+		if _, err := RenderScript(ctx); err == nil {
+			t.Fatalf("expected unsafe deployment settings to be rejected: %+v", ctx)
+		}
+	}
+}
+
+func TestRenderScriptVerifiesReleaseChecksumWithoutEmoji(t *testing.T) {
+	got, err := RenderScript(testCtx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{"sha256sum -c", `download_file "${URL}.sha256"`, "[OK] 节点已上线", "[WARN]"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("script missing %q", want)
+		}
+	}
+	if strings.ContainsAny(got, "\u2713\u26a0") {
+		t.Fatal("installer output must not use emoji symbols")
+	}
+}
+
 func TestRenderComposeYamlRejectsInjectedMasterURL(t *testing.T) {
 	ctx := testCtx
 	ctx.Mode = model.InstallModeDocker

server/internal/installscript/templates/agent-compose.yml.tmpl

@@ -1,14 +1,22 @@
-# BackupX Agent docker-compose 片段
+# BackupX Agent Compose 片段
 # 生成于 {{.MasterURL}} · 节点 ID {{.NodeID}}
-version: "3.8"
+# 文件包含长期节点 Token，请保存为 0600 权限并在部署完成后限制访问。
 services:
   backupx-agent:
     image: awuqing/backupx:{{.AgentVersion}}
     command: ["agent"]
+    user: "0:0"
     restart: unless-stopped
+    security_opt:
+      - no-new-privileges:true
     environment:
       BACKUPX_AGENT_MASTER: "{{.MasterURL}}"
       BACKUPX_AGENT_TOKEN: "{{.AgentToken}}"
       BACKUPX_AGENT_TEMP_DIR: "/var/lib/backupx-agent/tmp"
-    volumes:
+{{if .ProxyURL}}      BACKUPX_AGENT_PROXY_URL: "{{.ProxyURL}}"
+{{end}}{{if .CACertFile}}      BACKUPX_AGENT_CA_CERT_FILE: "{{.CACertFile}}"
+{{end}}    volumes:
       - /var/lib/backupx-agent:/var/lib/backupx-agent
+{{if .CACertFile}}      - {{.CACertFile}}:{{.CACertFile}}:ro
+{{end}}      # 备份宿主机文件时，必须按需添加只读源目录挂载：
+      # - /srv/data:/srv/data:ro

server/internal/installscript/templates/agent-install.sh.tmpl

@@ -1,12 +1,11 @@
 #!/bin/sh
 # BackupX Agent 一键安装脚本（由 Master 动态渲染）
-# Magic: BACKUPX_AGENT_INSTALL_V1  —— 若 `head -3 脚本` 看不到此行，说明反向代理/CDN 改写了响应
+# Magic: BACKUPX_AGENT_INSTALL_V1 —— 若 `head -3 脚本` 看不到此行，说明反向代理或 CDN 改写了响应
 # 模式: {{.Mode}} | 架构: {{.Arch}} | 版本: {{.AgentVersion}}
 set -eu
+umask 077
 
-# 自举到 bash（文件执行模式下生效；管道模式 $0 不是文件，exec 会静默失败，继续用 sh）。
-# 动机：部分 Debian/Ubuntu 用户通过 `curl | sudo sh` 触发时，dash 对本脚本报语法错误；
-# 若目标机装有 bash，优先切换到 bash 获得更一致的行为。
+# 文件执行模式下优先使用 bash；管道模式继续使用 POSIX sh。
 if [ -z "${BASH_VERSION:-}" ] && command -v bash >/dev/null 2>&1 && [ -f "$0" ]; then
     exec bash "$0" "$@"
 fi
@@ -17,14 +16,56 @@ AGENT_VERSION="{{.AgentVersion}}"
 DOWNLOAD_BASE="{{.DownloadBase}}"
 INSTALL_PREFIX="{{.InstallPrefix}}"
 ARCH="{{.Arch}}"
+PROXY_URL="{{.ProxyURL}}"
+CA_CERT_FILE="{{.CACertFile}}"
+CONFIG_DIR="/etc/backupx-agent"
+CONFIG_FILE="${CONFIG_DIR}/config.yaml"
+TOKEN_FILE="${CONFIG_DIR}/agent.token"
+
+download_file() {
+    source_url="$1"
+    destination="$2"
+    if command -v curl >/dev/null 2>&1; then
+        if [ -n "$PROXY_URL" ]; then
+            curl -fsSL --retry 3 --retry-delay 2 --connect-timeout 15 --proxy "$PROXY_URL" "$source_url" -o "$destination"
+        else
+            curl -fsSL --retry 3 --retry-delay 2 --connect-timeout 15 "$source_url" -o "$destination"
+        fi
+    else
+        wget -q -T 30 -O "$destination" "$source_url"
+    fi
+}
+
+agent_is_online() {
+    if command -v curl >/dev/null 2>&1; then
+        if [ -n "$PROXY_URL" ] && [ -n "$CA_CERT_FILE" ]; then
+            response=$(curl -fsS --max-time 5 --proxy "$PROXY_URL" --cacert "$CA_CERT_FILE" -H "X-Agent-Token: ${AGENT_TOKEN}" "${MASTER_URL}/api/v1/agent/self" 2>/dev/null) || return 1
+        elif [ -n "$PROXY_URL" ]; then
+            response=$(curl -fsS --max-time 5 --proxy "$PROXY_URL" -H "X-Agent-Token: ${AGENT_TOKEN}" "${MASTER_URL}/api/v1/agent/self" 2>/dev/null) || return 1
+        elif [ -n "$CA_CERT_FILE" ]; then
+            response=$(curl -fsS --max-time 5 --cacert "$CA_CERT_FILE" -H "X-Agent-Token: ${AGENT_TOKEN}" "${MASTER_URL}/api/v1/agent/self" 2>/dev/null) || return 1
+        else
+            response=$(curl -fsS --max-time 5 -H "X-Agent-Token: ${AGENT_TOKEN}" "${MASTER_URL}/api/v1/agent/self" 2>/dev/null) || return 1
+        fi
+    else
+        response=$(wget -q -T 5 --max-redirect=0 -O - --header="X-Agent-Token: ${AGENT_TOKEN}" "${MASTER_URL}/api/v1/agent/self" 2>/dev/null) || return 1
+    fi
+    printf '%s' "$response" | grep -q '"status":"online"'
+}
 
 # 1. 前置检查
 [ "$(id -u)" -eq 0 ] || { echo "请使用 root 或 sudo 执行" >&2; exit 1; }
-command -v curl >/dev/null || command -v wget >/dev/null \
+command -v curl >/dev/null 2>&1 || command -v wget >/dev/null 2>&1 \
     || { echo "需要 curl 或 wget" >&2; exit 1; }
-{{if eq .Mode "systemd"}}command -v systemctl >/dev/null || { echo "不支持非 systemd 系统" >&2; exit 1; }
-{{end}}{{if eq .Mode "docker"}}command -v docker >/dev/null || { echo "需要先安装 docker" >&2; exit 1; }
+command -v grep >/dev/null 2>&1 || { echo "需要 grep" >&2; exit 1; }
+if { [ -n "$PROXY_URL" ] || [ -n "$CA_CERT_FILE" ]; } && ! command -v curl >/dev/null 2>&1; then
+    echo "显式代理或自定义 CA 场景需要 curl" >&2
+    exit 1
+fi
+{{if eq .Mode "systemd"}}command -v systemctl >/dev/null 2>&1 || { echo "当前系统不支持 systemd" >&2; exit 1; }
+{{end}}{{if eq .Mode "docker"}}command -v docker >/dev/null 2>&1 || { echo "需要先安装 Docker" >&2; exit 1; }
 {{end}}
+
 # 2. 架构检测
 if [ "$ARCH" = "auto" ]; then
     case "$(uname -m)" in
@@ -34,24 +75,54 @@ if [ "$ARCH" = "auto" ]; then
     esac
 fi
 
+# 3. 安全写入 Agent 配置。systemd unit 与容器元数据中不保存节点 Token。
+install -d -m 0700 "$CONFIG_DIR" /var/lib/backupx-agent /var/lib/backupx-agent/tmp
+printf '%s\n' "$AGENT_TOKEN" > "$TOKEN_FILE"
+chmod 0600 "$TOKEN_FILE"
+if [ -n "$CA_CERT_FILE" ]; then
+    [ -r "$CA_CERT_FILE" ] || { echo "无法读取 CA 证书: $CA_CERT_FILE" >&2; exit 1; }
+    if [ "$CA_CERT_FILE" != "$CONFIG_DIR/ca.pem" ]; then
+        install -m 0644 "$CA_CERT_FILE" "$CONFIG_DIR/ca.pem"
+    fi
+    CA_CERT_FILE="$CONFIG_DIR/ca.pem"
+fi
+cat > "$CONFIG_FILE" <<CONFIG
+master: "${MASTER_URL}"
+tokenFile: "${TOKEN_FILE}"
+heartbeatInterval: "15s"
+pollInterval: "5s"
+tempDir: "/var/lib/backupx-agent/tmp"
+proxyUrl: "${PROXY_URL}"
+caCertFile: "${CA_CERT_FILE}"
+CONFIG
+chmod 0600 "$CONFIG_FILE"
+
 {{if ne .Mode "docker"}}
-# 3. 下载二进制（systemd / foreground 模式）
+# 4. 下载并安装二进制（systemd / foreground 模式）
 ARCHIVE="backupx-${AGENT_VERSION}-linux-${ARCH}.tar.gz"
 URL="${DOWNLOAD_BASE}/${AGENT_VERSION}/${ARCHIVE}"
-TMPDIR="$(mktemp -d)"; trap 'rm -rf "$TMPDIR"' EXIT
+TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR"' EXIT HUP INT TERM
 echo "[1/4] 下载 ${URL}"
-if command -v curl >/dev/null; then
-    curl -fsSL "$URL" -o "$TMPDIR/pkg.tar.gz"
+download_file "$URL" "$TMPDIR/$ARCHIVE"
+if download_file "${URL}.sha256" "$TMPDIR/$ARCHIVE.sha256" 2>/dev/null; then
+    if command -v sha256sum >/dev/null 2>&1; then
+        (cd "$TMPDIR" && sha256sum -c "$ARCHIVE.sha256")
+    elif command -v shasum >/dev/null 2>&1; then
+        (cd "$TMPDIR" && shasum -a 256 -c "$ARCHIVE.sha256")
+    else
+        echo "已下载校验文件，但系统缺少 sha256sum 或 shasum，拒绝未校验安装" >&2
+        exit 1
+    fi
 else
-    wget -qO "$TMPDIR/pkg.tar.gz" "$URL"
+    echo "[WARN] 当前版本未提供 SHA-256 校验文件，继续兼容安装" >&2
 fi
-tar xzf "$TMPDIR/pkg.tar.gz" -C "$TMPDIR"
+tar xzf "$TMPDIR/$ARCHIVE" -C "$TMPDIR"
 
-# 4. 安装二进制 + 数据目录
 echo "[2/4] 安装到 ${INSTALL_PREFIX}"
 install -d -m 0755 "$INSTALL_PREFIX"
-install -d -m 0700 /var/lib/backupx-agent /var/lib/backupx-agent/tmp
-install -m 0755 "$TMPDIR/backupx-${AGENT_VERSION}-linux-${ARCH}/backupx" "$INSTALL_PREFIX/backupx"
+install -m 0755 "$TMPDIR/backupx-${AGENT_VERSION}-linux-${ARCH}/backupx" "$INSTALL_PREFIX/backupx.new"
+mv -f "$INSTALL_PREFIX/backupx.new" "$INSTALL_PREFIX/backupx"
 {{end}}
 
 {{if eq .Mode "systemd"}}
@@ -62,69 +133,78 @@ cat > /etc/systemd/system/backupx-agent.service <<UNIT
 Description=BackupX Agent
 After=network-online.target
 Wants=network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=10
 
 [Service]
 Type=simple
-Environment="BACKUPX_AGENT_MASTER=${MASTER_URL}"
-Environment="BACKUPX_AGENT_TOKEN=${AGENT_TOKEN}"
-ExecStart=${INSTALL_PREFIX}/backupx agent --temp-dir /var/lib/backupx-agent/tmp
+ExecStart=${INSTALL_PREFIX}/backupx agent --config ${CONFIG_FILE}
 Restart=on-failure
 RestartSec=10s
-# Agent 需以 root 运行以读取任意源数据；与单机服务端保持一致的资源/句柄上限。
+TimeoutStopSec=30s
+UMask=0077
+# Agent 以 root 运行，以便读取备份源及执行恢复；节点 Token 仅保存在 0600 文件中。
 LimitNOFILE=65535
 
 [Install]
 WantedBy=multi-user.target
 UNIT
+chmod 0644 /etc/systemd/system/backupx-agent.service
 systemctl daemon-reload
-systemctl enable --now backupx-agent
+if ! systemctl enable backupx-agent || ! systemctl restart backupx-agent; then
+    echo "BackupX Agent 服务启动失败" >&2
+    systemctl status backupx-agent --no-pager >&2 || true
+    journalctl -u backupx-agent -n 100 --no-pager >&2 || true
+    exit 1
+fi
 
 # 6. 等待上线
 echo "[4/4] 等待节点上线"
-for i in $(seq 1 15); do
+i=0
+while [ "$i" -lt 15 ]; do
     sleep 2
-    if curl -fsSL -H "X-Agent-Token: ${AGENT_TOKEN}" "${MASTER_URL}/api/v1/agent/self" 2>/dev/null \
-        | grep -q '"status":"online"'; then
-        echo "✓ 节点已上线"
+    if agent_is_online; then
+        echo "[OK] 节点已上线"
         exit 0
     fi
+    i=$((i + 1))
 done
-echo "⚠ 30s 内未收到上线心跳，请检查防火墙或 journalctl -u backupx-agent"
-echo "提示：systemd 服务名是 backupx-agent，可执行 systemctl status backupx-agent 查看状态。"
+echo "[WARN] 30 秒内未收到上线心跳，请检查网络、代理或 SSH 隧道" >&2
+echo "排查命令: systemctl status backupx-agent" >&2
+echo "排查命令: journalctl -u backupx-agent -n 100 --no-pager" >&2
 exit 2
 {{end}}
 
 {{if eq .Mode "foreground"}}
 # 5. 前台运行
-echo "[3/3] 前台启动 agent（Ctrl+C 退出）"
-export BACKUPX_AGENT_MASTER="${MASTER_URL}"
-export BACKUPX_AGENT_TOKEN="${AGENT_TOKEN}"
-exec "${INSTALL_PREFIX}/backupx" agent --temp-dir /var/lib/backupx-agent/tmp
+echo "[3/3] 前台启动 Agent（Ctrl+C 退出）"
+exec "${INSTALL_PREFIX}/backupx" agent --config "$CONFIG_FILE"
 {{end}}
 
 {{if eq .Mode "docker"}}
-# Docker 模式：直接用镜像启动容器
+# Docker 模式：配置文件只读挂载，避免 Token 出现在 docker inspect 环境变量中。
 echo "[1/2] 拉取镜像 awuqing/backupx:${AGENT_VERSION}"
 docker pull "awuqing/backupx:${AGENT_VERSION}"
 echo "[2/2] 启动容器 backupx-agent"
 docker rm -f backupx-agent >/dev/null 2>&1 || true
-docker run -d --name backupx-agent --restart=unless-stopped \
-    -e "BACKUPX_AGENT_MASTER=${MASTER_URL}" \
-    -e "BACKUPX_AGENT_TOKEN=${AGENT_TOKEN}" \
-    -e "BACKUPX_AGENT_TEMP_DIR=/var/lib/backupx-agent/tmp" \
+docker run -d --name backupx-agent --restart=unless-stopped --user 0:0 \
+    --security-opt no-new-privileges:true \
+    -v /etc/backupx-agent:/etc/backupx-agent:ro \
     -v /var/lib/backupx-agent:/var/lib/backupx-agent \
-    "awuqing/backupx:${AGENT_VERSION}" agent
-echo "✓ 容器已启动，等待节点上线"
-for i in $(seq 1 15); do
+    "awuqing/backupx:${AGENT_VERSION}" agent --config /etc/backupx-agent/config.yaml
+echo "提示: Docker Agent 只能访问显式挂载的目录；备份宿主机路径前请按文档添加只读 -v 挂载。"
+echo "容器已启动，等待节点上线"
+i=0
+while [ "$i" -lt 15 ]; do
     sleep 2
-    if curl -fsSL -H "X-Agent-Token: ${AGENT_TOKEN}" "${MASTER_URL}/api/v1/agent/self" 2>/dev/null \
-        | grep -q '"status":"online"'; then
-        echo "✓ 节点已上线"
+    if agent_is_online; then
+        echo "[OK] 节点已上线"
         exit 0
     fi
+    i=$((i + 1))
 done
-echo "⚠ 30s 内未收到上线心跳，请检查容器状态、网络与 Master URL。"
-echo "排查命令：docker ps -a --filter name=backupx-agent"
-echo "排查命令：docker logs --tail=100 backupx-agent"
+echo "[WARN] 30 秒内未收到上线心跳，请检查容器、代理、隧道与 Master 地址" >&2
+echo "排查命令: docker ps -a --filter name=backupx-agent" >&2
+echo "排查命令: docker logs --tail=100 backupx-agent" >&2
 exit 2
 {{end}}

server/internal/model/agent_command.go

@@ -4,11 +4,11 @@ import "time"
 
 // AgentCommand 状态常量
 const (
-	AgentCommandStatusPending   = "pending"    // 待 Agent 拉取
+	AgentCommandStatusPending    = "pending"    // 待 Agent 拉取
 	AgentCommandStatusDispatched = "dispatched" // Agent 已领取，正在执行
-	AgentCommandStatusSucceeded = "succeeded"  // 执行成功
-	AgentCommandStatusFailed    = "failed"     // 执行失败
-	AgentCommandStatusTimeout   = "timeout"    // 超时未完成
+	AgentCommandStatusSucceeded  = "succeeded"  // 执行成功
+	AgentCommandStatusFailed     = "failed"     // 执行失败
+	AgentCommandStatusTimeout    = "timeout"    // 超时未完成
 )
 
 // AgentCommand 类型常量
@@ -36,20 +36,20 @@ const (
 )
 
 // AgentCommand 代表 Master 发给某个 Agent 节点的待执行命令。
-// 使用简单的数据库队列实现：Agent 通过 token 长轮询拉取本节点 pending 命令，
+// 使用简单的数据库队列实现：Agent 通过 token 定期轮询本节点 pending 命令，
 // 执行后回写状态与结果。Master 侧通过定时检查把超时的命令标记为 timeout。
 type AgentCommand struct {
-	ID             uint       `gorm:"primaryKey" json:"id"`
-	NodeID         uint       `gorm:"column:node_id;index;not null" json:"nodeId"`
-	Type           string     `gorm:"size:32;index;not null" json:"type"`
-	Status         string     `gorm:"size:20;index;not null;default:'pending'" json:"status"`
-	Payload        string     `gorm:"type:text" json:"payload"`        // JSON
-	Result         string     `gorm:"type:text" json:"result"`         // JSON（成功结果）
-	ErrorMessage   string     `gorm:"column:error_message;type:text" json:"errorMessage"`
-	DispatchedAt   *time.Time `gorm:"column:dispatched_at" json:"dispatchedAt,omitempty"`
-	CompletedAt    *time.Time `gorm:"column:completed_at" json:"completedAt,omitempty"`
-	CreatedAt      time.Time  `json:"createdAt"`
-	UpdatedAt      time.Time  `json:"updatedAt"`
+	ID           uint       `gorm:"primaryKey" json:"id"`
+	NodeID       uint       `gorm:"column:node_id;not null;index:idx_agent_commands_node_status,priority:1" json:"nodeId"`
+	Type         string     `gorm:"size:32;index;not null" json:"type"`
+	Status       string     `gorm:"size:20;not null;default:'pending';index:idx_agent_commands_node_status,priority:2;index:idx_agent_commands_status_dispatched,priority:1;index:idx_agent_commands_status_created,priority:1" json:"status"`
+	Payload      string     `gorm:"type:text" json:"payload"` // JSON
+	Result       string     `gorm:"type:text" json:"result"`  // JSON（成功结果）
+	ErrorMessage string     `gorm:"column:error_message;type:text" json:"errorMessage"`
+	DispatchedAt *time.Time `gorm:"column:dispatched_at;index:idx_agent_commands_status_dispatched,priority:2" json:"dispatchedAt,omitempty"`
+	CompletedAt  *time.Time `gorm:"column:completed_at" json:"completedAt,omitempty"`
+	CreatedAt    time.Time  `gorm:"index:idx_agent_commands_status_created,priority:2" json:"createdAt"`
+	UpdatedAt    time.Time  `json:"updatedAt"`
 }
 
 func (AgentCommand) TableName() string {

server/internal/model/agent_install_token.go

@@ -6,17 +6,21 @@ import "time"
 //
 // 生命周期：创建 → 消费（ConsumedAt 非空即作废）→ 超过 ExpiresAt 后被 GC 硬删除。
 type AgentInstallToken struct {
-	ID          uint       `gorm:"primaryKey" json:"id"`
-	Token       string     `gorm:"size:64;uniqueIndex;not null" json:"token"`
-	NodeID      uint       `gorm:"not null;index" json:"nodeId"`
-	Mode        string     `gorm:"size:16;not null" json:"mode"`        // systemd|docker|foreground
-	Arch        string     `gorm:"size:16;not null" json:"arch"`        // amd64|arm64|auto
-	AgentVer    string     `gorm:"size:32;not null" json:"agentVersion"`
-	DownloadSrc string     `gorm:"size:16;not null;default:'github'" json:"downloadSrc"`
-	ExpiresAt   time.Time  `gorm:"not null;index" json:"expiresAt"`
-	ConsumedAt  *time.Time `json:"consumedAt,omitempty"`
-	CreatedByID uint       `gorm:"not null" json:"createdById"`
-	CreatedAt   time.Time  `json:"createdAt"`
+	ID          uint   `gorm:"primaryKey" json:"id"`
+	Token       string `gorm:"size:64;uniqueIndex;not null" json:"token"`
+	NodeID      uint   `gorm:"not null;index" json:"nodeId"`
+	Mode        string `gorm:"size:16;not null" json:"mode"` // systemd|docker|foreground
+	Arch        string `gorm:"size:16;not null" json:"arch"` // amd64|arm64|auto
+	AgentVer    string `gorm:"size:32;not null" json:"agentVersion"`
+	DownloadSrc string `gorm:"size:16;not null;default:'github'" json:"downloadSrc"`
+	// AgentMasterURL 可覆盖公开安装地址，支持代理或 SSH 隧道后的节点专用入口。
+	AgentMasterURL string     `gorm:"size:2048" json:"agentMasterUrl,omitempty"`
+	ProxyURL       string     `gorm:"size:2048" json:"proxyUrl,omitempty"`
+	CACertFile     string     `gorm:"size:512" json:"caCertFile,omitempty"`
+	ExpiresAt      time.Time  `gorm:"not null;index" json:"expiresAt"`
+	ConsumedAt     *time.Time `json:"consumedAt,omitempty"`
+	CreatedByID    uint       `gorm:"not null" json:"createdById"`
+	CreatedAt      time.Time  `json:"createdAt"`
 }
 
 func (AgentInstallToken) TableName() string { return "agent_install_tokens" }

server/internal/repository/agent_command_repository_test.go

@@ -17,12 +17,30 @@ func newTestDB(t *testing.T) *gorm.DB {
 	if err != nil {
 		t.Fatalf("open: %v", err)
 	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("get sql database: %v", err)
+	}
+	t.Cleanup(func() { _ = sqlDB.Close() })
 	if err := db.AutoMigrate(&model.AgentCommand{}); err != nil {
 		t.Fatalf("migrate: %v", err)
 	}
 	return db
 }
 
+func TestAgentCommandQueueIndexes(t *testing.T) {
+	db := newTestDB(t)
+	for _, name := range []string{
+		"idx_agent_commands_node_status",
+		"idx_agent_commands_status_dispatched",
+		"idx_agent_commands_status_created",
+	} {
+		if !db.Migrator().HasIndex(&model.AgentCommand{}, name) {
+			t.Fatalf("missing Agent command queue index %s", name)
+		}
+	}
+}
+
 func TestAgentCommandRepository_ClaimPending(t *testing.T) {
 	db := newTestDB(t)
 	repo := NewAgentCommandRepository(db)

server/internal/repository/agent_install_token_repository_test.go

@@ -20,6 +20,11 @@ func openTestInstallTokenDB(t *testing.T) *gorm.DB {
 	if err != nil {
 		t.Fatalf("open: %v", err)
 	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("get sql database: %v", err)
+	}
+	t.Cleanup(func() { _ = sqlDB.Close() })
 	if err := db.AutoMigrate(&model.AgentInstallToken{}); err != nil {
 		t.Fatalf("migrate: %v", err)
 	}

server/internal/repository/backup_record_repository_test.go

@@ -22,6 +22,11 @@ func newBackupRecordTestRepository(t *testing.T) *GormBackupRecordRepository {
 	if err != nil {
 		t.Fatalf("database.Open returned error: %v", err)
 	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("db.DB returned error: %v", err)
+	}
+	t.Cleanup(func() { _ = sqlDB.Close() })
 	storageTarget := &model.StorageTarget{Name: "local", Type: "local_disk", Enabled: true, ConfigCiphertext: "{}", ConfigVersion: 1, LastTestStatus: "unknown"}
 	if err := db.Create(storageTarget).Error; err != nil {
 		t.Fatalf("seed storage target error: %v", err)

server/internal/repository/backup_task_repository_test.go

@@ -21,6 +21,11 @@ func newBackupTaskTestRepository(t *testing.T) *GormBackupTaskRepository {
 	if err != nil {
 		t.Fatalf("database.Open returned error: %v", err)
 	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("db.DB returned error: %v", err)
+	}
+	t.Cleanup(func() { _ = sqlDB.Close() })
 	if err := db.Create(&model.StorageTarget{Name: "local", Type: "local_disk", Enabled: true, ConfigCiphertext: "{}", ConfigVersion: 1, LastTestStatus: "unknown"}).Error; err != nil {
 		t.Fatalf("seed storage target error: %v", err)
 	}

server/internal/repository/node_repository_test.go

@@ -19,6 +19,11 @@ func openTestNodeDB(t *testing.T) *gorm.DB {
 	if err != nil {
 		t.Fatalf("open sqlite: %v", err)
 	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("get sql database: %v", err)
+	}
+	t.Cleanup(func() { _ = sqlDB.Close() })
 	if err := db.AutoMigrate(&model.Node{}); err != nil {
 		t.Fatalf("migrate: %v", err)
 	}

server/internal/repository/notification_repository_test.go

@@ -21,6 +21,11 @@ func newNotificationTestRepository(t *testing.T) *GormNotificationRepository {
 	if err != nil {
 		t.Fatalf("database.Open returned error: %v", err)
 	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("db.DB returned error: %v", err)
+	}
+	t.Cleanup(func() { _ = sqlDB.Close() })
 	return NewNotificationRepository(db)
 }
 

server/internal/repository/oauth_session_repository_test.go

@@ -22,6 +22,11 @@ func newOAuthSessionTestRepository(t *testing.T) *GormOAuthSessionRepository {
 	if err != nil {
 		t.Fatalf("database.Open returned error: %v", err)
 	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("db.DB returned error: %v", err)
+	}
+	t.Cleanup(func() { _ = sqlDB.Close() })
 	return NewOAuthSessionRepository(db)
 }
 

server/internal/repository/restore_record_repository_test.go

@@ -22,6 +22,11 @@ func newRestoreRecordTestRepository(t *testing.T) (*GormRestoreRecordRepository,
 	if err != nil {
 		t.Fatalf("database.Open returned error: %v", err)
 	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("db.DB returned error: %v", err)
+	}
+	t.Cleanup(func() { _ = sqlDB.Close() })
 	storageTarget := &model.StorageTarget{Name: "local", Type: "local_disk", Enabled: true, ConfigCiphertext: "{}", ConfigVersion: 1, LastTestStatus: "unknown"}
 	if err := db.Create(storageTarget).Error; err != nil {
 		t.Fatalf("seed storage target error: %v", err)

server/internal/repository/storage_target_repository_test.go

@@ -26,6 +26,11 @@ func newStorageTestRepository(t *testing.T) *GormStorageTargetRepository {
 	if err != nil {
 		t.Fatalf("database.Open returned error: %v", err)
 	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("db.DB returned error: %v", err)
+	}
+	t.Cleanup(func() { _ = sqlDB.Close() })
 	return NewStorageTargetRepository(db)
 }
 

server/internal/service/install_token_service.go

@@ -6,6 +6,7 @@ import (
 	"encoding/base64"
 	"encoding/hex"
 	"fmt"
+	"net/url"
 	"strings"
 	"time"
 
@@ -27,13 +28,16 @@ func NewInstallTokenService(repo repository.AgentInstallTokenRepository, nodeRep
 
 // InstallTokenInput 生成一次性安装令牌的输入。
 type InstallTokenInput struct {
-	NodeID       uint
-	Mode         string
-	Arch         string
-	AgentVersion string
-	DownloadSrc  string
-	TTLSeconds   int
-	CreatedByID  uint
+	NodeID         uint
+	Mode           string
+	Arch           string
+	AgentVersion   string
+	DownloadSrc    string
+	TTLSeconds     int
+	CreatedByID    uint
+	AgentMasterURL string
+	ProxyURL       string
+	CACertFile     string
 }
 
 // InstallTokenOutput 生成结果。
@@ -112,14 +116,17 @@ func (s *InstallTokenService) Create(ctx context.Context, in InstallTokenInput)
 	}
 	expiresAt := time.Now().UTC().Add(time.Duration(in.TTLSeconds) * time.Second)
 	record := &model.AgentInstallToken{
-		Token:       token,
-		NodeID:      in.NodeID,
-		Mode:        in.Mode,
-		Arch:        in.Arch,
-		AgentVer:    in.AgentVersion,
-		DownloadSrc: in.DownloadSrc,
-		ExpiresAt:   expiresAt,
-		CreatedByID: in.CreatedByID,
+		Token:          token,
+		NodeID:         in.NodeID,
+		Mode:           in.Mode,
+		Arch:           in.Arch,
+		AgentVer:       in.AgentVersion,
+		DownloadSrc:    in.DownloadSrc,
+		AgentMasterURL: strings.TrimRight(strings.TrimSpace(in.AgentMasterURL), "/"),
+		ProxyURL:       strings.TrimSpace(in.ProxyURL),
+		CACertFile:     strings.TrimSpace(in.CACertFile),
+		ExpiresAt:      expiresAt,
+		CreatedByID:    in.CreatedByID,
 	}
 	if err := s.repo.Create(ctx, record); err != nil {
 		return nil, err
@@ -130,9 +137,15 @@ func (s *InstallTokenService) Create(ctx context.Context, in InstallTokenInput)
 // CreateCommand 创建 install token，并返回 UI 展示安装命令所需的 URL 与嵌入式脚本。
 func (s *InstallTokenService) CreateCommand(ctx context.Context, in InstallCommandInput) (*InstallCommandOutput, error) {
 	masterURL := strings.TrimRight(strings.TrimSpace(in.MasterURL), "/")
-	if masterURL == "" {
-		return nil, apperror.BadRequest("INSTALL_TOKEN_INVALID", "masterURL 必填", nil)
+	deliveryURL, parseErr := url.Parse(masterURL)
+	if masterURL == "" || parseErr != nil || (deliveryURL.Scheme != "http" && deliveryURL.Scheme != "https") || deliveryURL.Host == "" || deliveryURL.User != nil || deliveryURL.RawQuery != "" || deliveryURL.Fragment != "" || strings.ContainsAny(masterURL, " \t\r\n\"'`$\\") {
+		return nil, apperror.BadRequest("INSTALL_TOKEN_INVALID", "masterURL 必须是安全的完整 HTTP(S) 地址", parseErr)
 	}
+	agentMasterURL := strings.TrimRight(strings.TrimSpace(in.AgentMasterURL), "/")
+	if agentMasterURL == "" {
+		agentMasterURL = masterURL
+	}
+	in.AgentMasterURL = agentMasterURL
 	if err := s.validate(in.InstallTokenInput); err != nil {
 		return nil, err
 	}
@@ -144,12 +157,15 @@ func (s *InstallTokenService) CreateCommand(ctx context.Context, in InstallComma
 		return nil, apperror.New(404, "NODE_NOT_FOUND", "节点不存在", nil)
 	}
 	if _, err := renderInstallCommandScript(masterURL, node, &model.AgentInstallToken{
-		Mode:        in.Mode,
-		Arch:        in.Arch,
-		AgentVer:    in.AgentVersion,
-		DownloadSrc: in.DownloadSrc,
+		Mode:           in.Mode,
+		Arch:           in.Arch,
+		AgentVer:       in.AgentVersion,
+		DownloadSrc:    in.DownloadSrc,
+		AgentMasterURL: in.AgentMasterURL,
+		ProxyURL:       in.ProxyURL,
+		CACertFile:     in.CACertFile,
 	}); err != nil {
-		return nil, err
+		return nil, apperror.BadRequest("INSTALL_TOKEN_INVALID", "Agent 连接配置无效", err)
 	}
 	out, err := s.Create(ctx, in.InstallTokenInput)
 	if err != nil {
@@ -164,20 +180,24 @@ func (s *InstallTokenService) CreateCommand(ctx context.Context, in InstallComma
 		ExpiresAt:    out.ExpiresAt,
 		Node:         out.Node,
 		Record:       out.Record,
-		URL:          masterURL + "/api/install/" + out.Token,
-		FallbackURL:  masterURL + "/install/" + out.Token,
+		URL:          agentMasterURL + "/api/install/" + out.Token,
+		FallbackURL:  agentMasterURL + "/install/" + out.Token,
 		ScriptBase64: base64.StdEncoding.EncodeToString([]byte(script)),
 	}
 	if out.Record.Mode == model.InstallModeDocker {
-		result.ComposeURL = masterURL + "/api/install/" + out.Token + "/compose.yml"
-		result.FallbackComposeURL = masterURL + "/install/" + out.Token + "/compose.yml"
+		result.ComposeURL = agentMasterURL + "/api/install/" + out.Token + "/compose.yml"
+		result.FallbackComposeURL = agentMasterURL + "/install/" + out.Token + "/compose.yml"
 	}
 	return result, nil
 }
 
 func renderInstallCommandScript(masterURL string, node *model.Node, record *model.AgentInstallToken) (string, error) {
+	agentMasterURL := strings.TrimRight(strings.TrimSpace(record.AgentMasterURL), "/")
+	if agentMasterURL == "" {
+		agentMasterURL = masterURL
+	}
 	return installscript.RenderScript(installscript.Context{
-		MasterURL:     masterURL,
+		MasterURL:     agentMasterURL,
 		AgentToken:    node.Token,
 		AgentVersion:  record.AgentVer,
 		Mode:          record.Mode,
@@ -185,6 +205,8 @@ func renderInstallCommandScript(masterURL string, node *model.Node, record *mode
 		DownloadBase:  installscript.DownloadBaseFor(record.DownloadSrc),
 		InstallPrefix: "/opt/backupx-agent",
 		NodeID:        node.ID,
+		ProxyURL:      record.ProxyURL,
+		CACertFile:    record.CACertFile,
 	})
 }
 
@@ -259,6 +281,9 @@ func (s *InstallTokenService) validate(in InstallTokenInput) error {
 		return apperror.BadRequest("INSTALL_TOKEN_INVALID",
 			fmt.Sprintf("ttlSeconds 需在 %d-%d", InstallTokenMinTTL, InstallTokenMaxTTL), nil)
 	}
+	if len(in.AgentMasterURL) > 2048 || len(in.ProxyURL) > 2048 || len(in.CACertFile) > 512 {
+		return apperror.BadRequest("INSTALL_TOKEN_INVALID", "连接配置过长", nil)
+	}
 	return nil
 }
 

server/internal/service/install_token_service_test.go

@@ -2,7 +2,9 @@ package service
 
 import (
 	"context"
+	"encoding/base64"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
@@ -177,13 +179,16 @@ func TestInstallTokenServiceCreateCommandBuildsURLsAndScript(t *testing.T) {
 
 	out, err := svc.CreateCommand(context.Background(), InstallCommandInput{
 		InstallTokenInput: InstallTokenInput{
-			NodeID:       node.ID,
-			Mode:         model.InstallModeDocker,
-			Arch:         model.InstallArchAuto,
-			AgentVersion: "v1.7.0",
-			DownloadSrc:  model.InstallSourceGitHub,
-			TTLSeconds:   900,
-			CreatedByID:  1,
+			NodeID:         node.ID,
+			Mode:           model.InstallModeDocker,
+			Arch:           model.InstallArchAuto,
+			AgentVersion:   "v1.7.0",
+			DownloadSrc:    model.InstallSourceGitHub,
+			TTLSeconds:     900,
+			CreatedByID:    1,
+			AgentMasterURL: "http://127.0.0.1:18340",
+			ProxyURL:       "socks5h://127.0.0.1:1080",
+			CACertFile:     "/etc/pki/internal-ca.pem",
 		},
 		MasterURL: "https://public.example.com/base",
 	})
@@ -193,15 +198,66 @@ func TestInstallTokenServiceCreateCommandBuildsURLsAndScript(t *testing.T) {
 	if out.Token == "" || out.ScriptBase64 == "" {
 		t.Fatalf("missing token or script: %+v", out)
 	}
-	if out.URL != "https://public.example.com/base/api/install/"+out.Token {
+	if out.URL != "http://127.0.0.1:18340/api/install/"+out.Token {
 		t.Fatalf("bad url: %s", out.URL)
 	}
-	if out.FallbackURL != "https://public.example.com/base/install/"+out.Token {
+	if out.FallbackURL != "http://127.0.0.1:18340/install/"+out.Token {
 		t.Fatalf("bad fallback url: %s", out.FallbackURL)
 	}
-	if out.ComposeURL != "https://public.example.com/base/api/install/"+out.Token+"/compose.yml" {
+	if out.ComposeURL != "http://127.0.0.1:18340/api/install/"+out.Token+"/compose.yml" {
 		t.Fatalf("bad compose url: %s", out.ComposeURL)
 	}
+	script, err := base64.StdEncoding.DecodeString(out.ScriptBase64)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{
+		`MASTER_URL="http://127.0.0.1:18340"`,
+		`PROXY_URL="socks5h://127.0.0.1:1080"`,
+		`CA_CERT_FILE="/etc/pki/internal-ca.pem"`,
+	} {
+		if !strings.Contains(string(script), want) {
+			t.Fatalf("script missing %q", want)
+		}
+	}
+}
+
+func TestInstallTokenServiceRejectsUnsafeConnectionBeforeCreate(t *testing.T) {
+	db := openInstallTokenTestDB(t)
+	nodeRepo := repository.NewNodeRepository(db)
+	node := &model.Node{Name: "restricted", Token: "deadbeefcafebabe0123456789abcdef0123456789abcdef0123456789abcdef"}
+	if err := nodeRepo.Create(context.Background(), node); err != nil {
+		t.Fatal(err)
+	}
+	tokenRepo := repository.NewAgentInstallTokenRepository(db)
+	svc := NewInstallTokenService(tokenRepo, nodeRepo)
+	_, err := svc.CreateCommand(context.Background(), InstallCommandInput{
+		InstallTokenInput: InstallTokenInput{
+			NodeID: node.ID, Mode: model.InstallModeSystemd, Arch: model.InstallArchAuto,
+			AgentVersion: "v2.4.0", DownloadSrc: model.InstallSourceGitHub, TTLSeconds: 900,
+			ProxyURL: "http://user:pass@proxy.example.com",
+		},
+		MasterURL: "https://public.example.com",
+	})
+	if err == nil {
+		t.Fatal("expected proxy credentials to be rejected")
+	}
+	count, countErr := tokenRepo.CountCreatedSince(context.Background(), node.ID, time.Now().UTC().Add(-time.Hour))
+	if countErr != nil || count != 0 {
+		t.Fatalf("invalid connection created token records: count=%d err=%v", count, countErr)
+	}
+
+	_, err = svc.CreateCommand(context.Background(), InstallCommandInput{
+		InstallTokenInput: InstallTokenInput{
+			NodeID: node.ID, Mode: model.InstallModeSystemd, Arch: model.InstallArchAuto,
+			AgentVersion: "v2.4.0", DownloadSrc: model.InstallSourceGitHub, TTLSeconds: 900,
+			AgentMasterURL: "https://master.internal",
+		},
+		MasterURL: "http://public.example.com/$unsafe",
+	})
+	if err == nil {
+		t.Fatal("expected unsafe public delivery URL to be rejected")
+	}
 }
 
 func TestInstallTokenServiceRateLimit(t *testing.T) {

web/package.json

@@ -11,14 +11,14 @@
   },
   "dependencies": {
     "@arco-design/web-react": "^2.66.0",
-    "axios": "^1.16.0",
-    "echarts": "^6.0.0",
+    "axios": "^1.19.0",
+    "echarts": "^6.1.0",
     "echarts-for-react": "^3.0.6",
     "i18next": "^25.8.14",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-i18next": "^16.5.6",
-    "react-router-dom": "^6.30.0",
+    "react-router-dom": "^6.30.4",
     "zustand": "^5.0.3"
   },
   "devDependencies": {
@@ -31,7 +31,7 @@
     "@vitejs/plugin-react": "^4.3.4",
     "jsdom": "^26.0.0",
     "typescript": "^5.7.3",
-    "vite": "^6.4.2",
-    "vitest": "^3.0.8"
+    "vite": "^6.4.3",
+    "vitest": "^3.2.7"
   }
 }

web/src/pages/nodes/AgentInstallWizard.tsx

@@ -1,11 +1,12 @@
 import React, { useEffect, useRef, useState } from 'react'
 import { Modal, Steps, Button, Space, Message, Spin } from '@arco-design/web-react'
 import { Step1NodeName, type Mode } from './wizard/Step1NodeName'
-import { Step2DeployOptions, type DeployOptions } from './wizard/Step2DeployOptions'
+import { Step2DeployOptions, isReleaseVersion, type DeployOptions } from './wizard/Step2DeployOptions'
 import { Step3CommandPreview } from './wizard/Step3CommandPreview'
 import { BatchCommandTable, type BatchCommandRow } from './BatchCommandTable'
-import type { InstallTokenResult } from '../../types/nodes'
+import type { InstallTokenInput, InstallTokenResult } from '../../types/nodes'
 import { useAgentDeployFlow, type AgentDeployRow } from './useAgentDeployFlow'
+import { validateAgentConnection } from './wizard/AgentConnectionOptions'
 
 const Step = Steps.Step
 
@@ -29,15 +30,19 @@ export function AgentInstallWizard({ visible, onClose, onSuccess, masterVersion,
   const [deploy, setDeploy] = useState<DeployOptions>({
     mode: 'systemd',
     arch: 'auto',
-    agentVersion: masterVersion || '',
+    agentVersion: isReleaseVersion(masterVersion) ? masterVersion || '' : '',
     downloadSrc: 'github',
     ttlSeconds: 900,
+    connectionMode: 'direct',
+    agentMasterUrl: '',
+    proxyUrl: '',
+    caCertFile: '',
   })
 
   // 当父组件异步拿到 masterVersion 后，同步到 deploy.agentVersion（仅初始为空时）
   useEffect(() => {
-    if (masterVersion && !deploy.agentVersion) {
-      setDeploy((prev) => ({ ...prev, agentVersion: masterVersion }))
+    if (isReleaseVersion(masterVersion) && !deploy.agentVersion) {
+      setDeploy((prev) => ({ ...prev, agentVersion: masterVersion as string }))
     }
   }, [masterVersion]) // eslint-disable-line react-hooks/exhaustive-deps
 
@@ -98,17 +103,23 @@ export function AgentInstallWizard({ visible, onClose, onSuccess, masterVersion,
       Message.warning('请填写 Agent 版本号（形如 v1.7.0）')
       return
     }
+    const connectionError = validateAgentConnection(deploy)
+    if (connectionError) {
+      Message.warning(connectionError)
+      return
+    }
+    const installInput = toInstallTokenInput(deploy)
     setSubmitting(true)
     try {
       if (fixedNode) {
-        const result = await deployFlow.submitExistingNode(fixedNode, deploy)
+        const result = await deployFlow.submitExistingNode(fixedNode, installInput)
         applySingleOrTableResult(result.rows, fixedNode)
       } else if (mode === 'single') {
-        const result = await deployFlow.submitNewNodes([singleName.trim()], deploy)
+        const result = await deployFlow.submitNewNodes([singleName.trim()], installInput)
         applySingleOrTableResult(result.rows)
       } else {
         const names = parseBatchNames()
-        const result = await deployFlow.submitNewNodes(names, deploy)
+        const result = await deployFlow.submitNewNodes(names, installInput)
         if (mountedRef.current) setBatchRows(toBatchRows(result.rows))
         if (result.status === 'partialFailed') {
           Message.warning('部分节点安装命令生成失败，可在结果表中查看')
@@ -127,7 +138,7 @@ export function AgentInstallWizard({ visible, onClose, onSuccess, masterVersion,
     if (!singleNodeInfo) return
     setSubmitting(true)
     try {
-      const row = await deployFlow.regenerateNode(singleNodeInfo, deploy)
+      const row = await deployFlow.regenerateNode(singleNodeInfo, toInstallTokenInput(deploy))
       if (row.status === 'ready' && row.installToken) {
         setSingleToken(row.installToken)
       } else {
@@ -143,7 +154,7 @@ export function AgentInstallWizard({ visible, onClose, onSuccess, masterVersion,
   const retryBatchNode = async (row: BatchCommandRow) => {
     setSubmitting(true)
     try {
-      const next = await deployFlow.regenerateNode({ id: row.nodeId, name: row.nodeName }, deploy)
+      const next = await deployFlow.regenerateNode({ id: row.nodeId, name: row.nodeName }, toInstallTokenInput(deploy))
       setBatchRows((rows) => rows.map((item) => (
         item.nodeId === row.nodeId ? toBatchRows([next])[0] : item
       )))
@@ -164,6 +175,9 @@ export function AgentInstallWizard({ visible, onClose, onSuccess, masterVersion,
     arch: deploy.arch,
     agentVersion: deploy.agentVersion,
     downloadSrc: deploy.downloadSrc,
+    agentMasterUrl: deploy.connectionMode === 'restricted' ? deploy.agentMasterUrl.trim() : '',
+    proxyUrl: deploy.connectionMode === 'restricted' ? deploy.proxyUrl.trim() : '',
+    caCertFile: deploy.connectionMode === 'restricted' ? deploy.caCertFile.trim() : '',
   }
 
   // fixedNode 路径下步骤只有 2 步（部署参数 + 安装命令），step 值从 1 开始，
@@ -236,7 +250,6 @@ export function AgentInstallWizard({ visible, onClose, onSuccess, masterVersion,
               nodeId={singleNodeInfo.id}
               nodeName={singleNodeInfo.name}
               token={singleToken}
-              mode={deploy.mode}
               previewParams={previewParams}
               onRegenerate={regenerateSingle}
             />
@@ -268,6 +281,19 @@ export function AgentInstallWizard({ visible, onClose, onSuccess, masterVersion,
   }
 }
 
+function toInstallTokenInput(deploy: DeployOptions): InstallTokenInput {
+  return {
+    mode: deploy.mode,
+    arch: deploy.arch,
+    agentVersion: deploy.agentVersion.trim(),
+    downloadSrc: deploy.downloadSrc,
+    ttlSeconds: deploy.ttlSeconds,
+    agentMasterUrl: deploy.connectionMode === 'restricted' ? deploy.agentMasterUrl.trim() : undefined,
+    proxyUrl: deploy.connectionMode === 'restricted' ? deploy.proxyUrl.trim() : undefined,
+    caCertFile: deploy.connectionMode === 'restricted' ? deploy.caCertFile.trim() : undefined,
+  }
+}
+
 function toBatchRows(rows: AgentDeployRow[]): BatchCommandRow[] {
   return rows.map((row) => ({
     nodeId: row.nodeId,

web/src/pages/nodes/BatchCommandTable.tsx

@@ -81,7 +81,7 @@ export function BatchCommandTable({ rows, onRetryNode }: Props) {
               }
               return (
                 <Text style={{
-                  fontFamily: 'monospace', fontSize: 12, wordBreak: 'break-all',
+                  fontSize: 12, wordBreak: 'break-all',
                   opacity: left === 0 ? 0.4 : 1,
                 }}>
                   {cmd as string}

web/src/pages/nodes/NodesPage.tsx

@@ -121,7 +121,7 @@ export default function NodesPage() {
             <Text type="secondary" style={{ display: 'block', marginBottom: 8 }}>
               新 Token（24 小时内新旧 Token 均可认证，便于滚动替换）：
             </Text>
-            <Text copyable style={{ fontFamily: 'monospace', fontSize: 12, wordBreak: 'break-all' }}>
+            <Text copyable style={{ fontSize: 12, wordBreak: 'break-all' }}>
               {newToken}
             </Text>
           </div>
@@ -138,7 +138,7 @@ export default function NodesPage() {
       render: (name: string, record: NodeSummary) => (
         <Space>
           {record.isLocal ? <IconDesktop style={{ color: 'var(--color-primary-6)' }} /> : <IconCloudDownload />}
-          <Text bold>{name}</Text>
+          <Text>{name}</Text>
           {record.isLocal && <Tag color="arcoblue" size="small" bordered>本机</Tag>}
         </Space>
       ),

web/src/pages/nodes/installCommands.test.ts

@@ -17,21 +17,32 @@ describe('install command builders', () => {
       'https://master.example.com/install/abc',
     )
 
-    expect(cmd).toContain('/tmp/bx-agent-install.sh')
+    expect(cmd).toContain('mktemp /tmp/bx-agent-install.XXXXXX')
     expect(cmd).toContain("'https://master.example.com/install/abc'")
     expect(cmd).toContain('non-script content')
+    expect(cmd).toContain('umask 077')
+    expect(cmd).toContain('rm -f "$tmp"')
   })
 
-  it('keeps URL install command as primary even when embedded script is available', () => {
+  it('keeps the one-time URL as the primary install command', () => {
     const cmd = buildAgentInstallCommand(
       'https://master.example.com/api/install/abc',
       'https://master.example.com/install/abc',
-      'IyEvYmluL3NoCg==',
     )
 
     expect(cmd).toContain('https://master.example.com/api/install/abc')
     expect(cmd).toContain('https://master.example.com/install/abc')
-    expect(cmd).not.toContain('IyEvYmluL3NoCg==')
+  })
+
+  it('binds proxy and private CA settings to installer downloads', () => {
+    const cmd = buildAgentInstallCommand(
+      'https://master.internal/api/install/abc',
+      undefined,
+      { proxyUrl: 'socks5h://127.0.0.1:1080', caCertFile: '/etc/backupx-agent/ca.pem' },
+    )
+
+    expect(cmd).toContain("--proxy 'socks5h://127.0.0.1:1080'")
+    expect(cmd).toContain("--cacert '/etc/backupx-agent/ca.pem'")
   })
 
   it('builds embedded fallback command explicitly', () => {

web/src/pages/nodes/installCommands.ts

@@ -12,16 +12,34 @@ function runScriptCommand(path: string) {
   return `if [ "$(id -u)" -eq 0 ]; then sh ${path}; else sudo sh ${path}; fi`
 }
 
-export function buildAgentInstallCommand(url: string, fallbackUrl?: string, _scriptBase64?: string) {
+export interface InstallFetchOptions {
+  proxyUrl?: string
+  caCertFile?: string
+}
+
+function curlFetch(url: string, destination: string, options: InstallFetchOptions) {
+  const args = ['curl', '-fsS']
+  if (options.proxyUrl?.trim()) {
+    args.push('--proxy', shellQuote(options.proxyUrl.trim()))
+  }
+  if (options.caCertFile?.trim()) {
+    args.push('--cacert', shellQuote(options.caCertFile.trim()))
+  }
+  args.push(shellQuote(url), '-o', destination)
+  return args.join(' ')
+}
+
+export function buildAgentInstallCommand(url: string, fallbackUrl?: string, options: InstallFetchOptions = {}) {
   const primary = url.trim()
   const fallback = (fallbackUrl || legacyInstallUrl(primary)).trim()
   const urls = fallback && fallback !== primary ? [primary, fallback] : [primary]
   const marker = shellQuote(INSTALL_MAGIC_MARKER)
   const fetchScript = urls.length > 1
-    ? `(curl -fsSL ${shellQuote(urls[0])} -o "$tmp" && grep -q ${marker} "$tmp" || curl -fsSL ${shellQuote(urls[1])} -o "$tmp")`
-    : `(curl -fsSL ${shellQuote(urls[0])} -o "$tmp" && grep -q ${marker} "$tmp")`
+    ? `(${curlFetch(urls[0], '"$tmp"', options)} && grep -q ${marker} "$tmp" || ${curlFetch(urls[1], '"$tmp"', options)})`
+    : `(${curlFetch(urls[0], '"$tmp"', options)} && grep -q ${marker} "$tmp")`
 
   return [
+    'umask 077',
     'tmp=$(mktemp)',
     fetchScript,
     `{ grep -q ${marker} "$tmp" || { echo 'BackupX install endpoint returned non-script content; check reverse proxy /api/install or /install forwarding.' >&2; head -5 "$tmp" >&2; false; }; }`,
@@ -29,24 +47,27 @@ export function buildAgentInstallCommand(url: string, fallbackUrl?: string, _scr
   ].join(' && ') + '; rc=$?; rm -f "$tmp"; test $rc -eq 0'
 }
 
-export function buildAgentDownloadCommand(url: string, fallbackUrl?: string, _scriptBase64?: string) {
+export function buildAgentDownloadCommand(url: string, fallbackUrl?: string, options: InstallFetchOptions = {}) {
   const primary = url.trim()
   const fallback = (fallbackUrl || legacyInstallUrl(primary)).trim()
   const marker = shellQuote(INSTALL_MAGIC_MARKER)
   const fetchScript = fallback && fallback !== primary
-    ? `(curl -fsSL ${shellQuote(primary)} -o /tmp/bx-agent-install.sh && grep -q ${marker} /tmp/bx-agent-install.sh || curl -fsSL ${shellQuote(fallback)} -o /tmp/bx-agent-install.sh)`
-    : `(curl -fsSL ${shellQuote(primary)} -o /tmp/bx-agent-install.sh && grep -q ${marker} /tmp/bx-agent-install.sh)`
+    ? `(${curlFetch(primary, '"$tmp"', options)} && grep -q ${marker} "$tmp" || ${curlFetch(fallback, '"$tmp"', options)})`
+    : `(${curlFetch(primary, '"$tmp"', options)} && grep -q ${marker} "$tmp")`
 
   return [
+    'umask 077',
+    'tmp=$(mktemp /tmp/bx-agent-install.XXXXXX)',
     fetchScript,
-    `{ grep -q ${marker} /tmp/bx-agent-install.sh || { echo 'BackupX install endpoint returned non-script content; check reverse proxy /api/install or /install forwarding.' >&2; head -5 /tmp/bx-agent-install.sh >&2; false; }; }`,
-    runScriptCommand('/tmp/bx-agent-install.sh'),
-  ].join(' && ')
+    `{ grep -q ${marker} "$tmp" || { echo 'BackupX install endpoint returned non-script content; check reverse proxy /api/install or /install forwarding.' >&2; head -5 "$tmp" >&2; false; }; }`,
+    runScriptCommand('"$tmp"'),
+  ].join(' && ') + '; rc=$?; rm -f "$tmp"; test $rc -eq 0'
 }
 
 export function buildEmbeddedAgentInstallCommand(scriptBase64: string) {
   const marker = shellQuote(INSTALL_MAGIC_MARKER)
   return [
+    'umask 077',
     'enc=$(mktemp)',
     'tmp=$(mktemp)',
     `printf %s ${shellQuote(scriptBase64.trim())} > "$enc"`,

web/src/pages/nodes/useAgentDeployFlow.test.ts

@@ -76,6 +76,24 @@ describe('createAgentDeployFlow', () => {
     })
   })
 
+  it('uses restricted-network options in batch install commands', async () => {
+    const flow = createAgentDeployFlow({
+      batchCreateNodes: async () => [{ id: 1, name: 'restricted' }],
+      createInstallToken: async () => tokenResult({
+        url: 'https://master.internal/api/install/install-token',
+        fallbackUrl: 'https://master.internal/install/install-token',
+      }),
+    })
+    const result = await flow.submitNewNodes(['restricted'], {
+      ...deployOptions(),
+      proxyUrl: 'socks5h://127.0.0.1:1080',
+      caCertFile: '/etc/backupx-agent/ca.pem',
+    })
+
+    expect(result.rows[0].command).toContain("--proxy 'socks5h://127.0.0.1:1080'")
+    expect(result.rows[0].command).toContain("--cacert '/etc/backupx-agent/ca.pem'")
+  })
+
   it('rejects duplicate names before creating nodes', async () => {
     const flow = createAgentDeployFlow({
       batchCreateNodes: async () => {

web/src/pages/nodes/useAgentDeployFlow.ts

@@ -41,7 +41,7 @@ export function createAgentDeployFlow(deps: AgentDeployFlowDeps) {
   const issueTokenForNode = async (node: AgentDeployNode, input: InstallTokenInput): Promise<AgentDeployRow> => {
     try {
       const token = await deps.createInstallToken(node.id, input)
-      return readyRow(node, token)
+      return readyRow(node, token, input)
     } catch (error) {
       return {
         nodeId: node.id,
@@ -77,12 +77,15 @@ export function useAgentDeployFlow() {
   return useMemo(() => createAgentDeployFlow({ batchCreateNodes, createInstallToken }), [])
 }
 
-function readyRow(node: AgentDeployNode, token: InstallTokenResult): AgentDeployRow {
+function readyRow(node: AgentDeployNode, token: InstallTokenResult, input: InstallTokenInput): AgentDeployRow {
   return {
     nodeId: node.id,
     nodeName: node.name,
     status: 'ready',
-    command: buildAgentInstallCommand(token.url, token.fallbackUrl),
+    command: buildAgentInstallCommand(token.url, token.fallbackUrl, {
+      proxyUrl: input.proxyUrl,
+      caCertFile: input.caCertFile,
+    }),
     expiresAt: token.expiresAt,
     installToken: token,
     embeddedCommand: token.scriptBase64

web/src/pages/nodes/wizard/AgentConnectionOptions.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { validateAgentConnection, type AgentConnectionValue } from './AgentConnectionOptions'
+
+function connection(patch: Partial<AgentConnectionValue> = {}): AgentConnectionValue {
+  return {
+    connectionMode: 'restricted',
+    agentMasterUrl: '',
+    proxyUrl: '',
+    caCertFile: '',
+    ...patch,
+  }
+}
+
+describe('validateAgentConnection', () => {
+  it('accepts direct connectivity without overrides', () => {
+    expect(validateAgentConnection(connection({ connectionMode: 'direct' }))).toBe('')
+  })
+
+  it('accepts an SSH local-forward URL and SOCKS5 proxy', () => {
+    expect(validateAgentConnection(connection({ agentMasterUrl: 'http://127.0.0.1:18340' }))).toBe('')
+    expect(validateAgentConnection(connection({ proxyUrl: 'socks5h://127.0.0.1:1080' }))).toBe('')
+  })
+
+  it('rejects empty restricted settings and relative CA paths', () => {
+    expect(validateAgentConnection(connection())).not.toBe('')
+    expect(validateAgentConnection(connection({ caCertFile: 'internal-ca.pem' }))).not.toBe('')
+  })
+
+  it('rejects credentials and shell-unsafe values before submission', () => {
+    expect(validateAgentConnection(connection({ agentMasterUrl: 'https://user:pass@master.example.com' }))).not.toBe('')
+    expect(validateAgentConnection(connection({ proxyUrl: 'http://user:pass@proxy.example.com' }))).not.toBe('')
+    expect(validateAgentConnection(connection({ caCertFile: '/etc/pki/internal ca.pem' }))).not.toBe('')
+  })
+})

web/src/pages/nodes/wizard/AgentConnectionOptions.tsx

@@ -0,0 +1,110 @@
+import React from 'react'
+import { Form, Input, Radio, Typography } from '@arco-design/web-react'
+
+const { Text } = Typography
+
+export type ConnectionMode = 'direct' | 'restricted'
+
+export interface AgentConnectionValue {
+  connectionMode: ConnectionMode
+  agentMasterUrl: string
+  proxyUrl: string
+  caCertFile: string
+}
+
+interface Props {
+  value: AgentConnectionValue
+  onChange: (value: AgentConnectionValue) => void
+}
+
+export function AgentConnectionOptions({ value, onChange }: Props) {
+  const update = (patch: Partial<AgentConnectionValue>) => onChange({ ...value, ...patch })
+
+  return (
+    <>
+      <Form.Item
+        label="Agent 网络路径"
+        extra={<Text type="secondary">Agent 只需主动访问 Master，不需要从 Master 反向开放节点端口。</Text>}
+      >
+        <Radio.Group
+          type="button"
+          value={value.connectionMode}
+          onChange={(mode) => update({ connectionMode: mode as ConnectionMode })}
+          options={[
+            { label: '直连', value: 'direct' },
+            { label: '代理或堡垒机', value: 'restricted' },
+          ]}
+        />
+      </Form.Item>
+
+      {value.connectionMode === 'restricted' && (
+        <>
+          <Form.Item
+            label="Agent 连接地址"
+            extra={<Text type="secondary">可填写经 SSH 本地转发后的地址；留空则继续使用 Master 对外地址。</Text>}
+          >
+            <Input
+              value={value.agentMasterUrl}
+              placeholder="例如 http://127.0.0.1:18340"
+              onChange={(agentMasterUrl) => update({ agentMasterUrl })}
+            />
+          </Form.Item>
+          <Form.Item
+            label="显式代理 URL"
+            extra={<Text type="secondary">支持 http、https、socks5、socks5h；SSH 动态转发可使用 socks5h://127.0.0.1:1080。</Text>}
+          >
+            <Input
+              value={value.proxyUrl}
+              placeholder="可选，例如 socks5h://127.0.0.1:1080"
+              onChange={(proxyUrl) => update({ proxyUrl })}
+            />
+          </Form.Item>
+          <Form.Item
+            label="私有 CA 证书路径"
+            extra={<Text type="secondary">目标节点上已存在的 PEM 文件绝对路径；安装器会复制到受保护的 Agent 配置目录。</Text>}
+          >
+            <Input
+              value={value.caCertFile}
+              placeholder="可选，例如 /etc/pki/ca-trust/source/anchors/internal-ca.pem"
+              onChange={(caCertFile) => update({ caCertFile })}
+            />
+          </Form.Item>
+        </>
+      )}
+    </>
+  )
+}
+
+export function validateAgentConnection(value: AgentConnectionValue) {
+  if (value.connectionMode === 'direct') return ''
+  const agentMasterUrl = value.agentMasterUrl.trim()
+  const proxyUrl = value.proxyUrl.trim()
+  const caCertFile = value.caCertFile.trim()
+  if (!agentMasterUrl && !proxyUrl && !caCertFile) {
+    return '请至少填写 Agent 连接地址、代理 URL 或私有 CA 路径'
+  }
+  if (agentMasterUrl) {
+    try {
+      const parsed = new URL(agentMasterUrl)
+      if (!['http:', 'https:'].includes(parsed.protocol) || !parsed.host || parsed.username || parsed.password || parsed.search || parsed.hash || /\s/.test(agentMasterUrl)) {
+        return 'Agent 连接地址必须是不含凭据、查询参数和片段的完整 HTTP(S) URL'
+      }
+    } catch {
+      return 'Agent 连接地址必须是完整的 HTTP 或 HTTPS URL'
+    }
+  }
+  if (proxyUrl) {
+    try {
+      const parsed = new URL(proxyUrl)
+      if (!['http:', 'https:', 'socks5:', 'socks5h:'].includes(parsed.protocol) || !parsed.host || parsed.username || parsed.password || (parsed.pathname !== '' && parsed.pathname !== '/') || parsed.search || parsed.hash || /\s/.test(proxyUrl)) {
+        return '代理 URL 仅支持无凭据、无路径的 http、https、socks5 或 socks5h 地址'
+      }
+    } catch {
+      return '代理 URL 仅支持 http、https、socks5 或 socks5h'
+    }
+  }
+  if (caCertFile && (!/^\/(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/.test(caCertFile) || caCertFile.split('/').some((part) => part === '..'))) {
+    return '私有 CA 证书必须使用不含空格或特殊字符的绝对路径'
+  }
+  return ''
+}

web/src/pages/nodes/wizard/InstallCommandBlock.tsx

@@ -0,0 +1,30 @@
+import React, { type ReactNode } from 'react'
+import { Button, Space, Typography } from '@arco-design/web-react'
+import { IconCopy } from '../../../components/icons'
+
+const { Text } = Typography
+
+interface Props {
+  label?: string
+  command: string
+  disabled?: boolean
+  action?: ReactNode
+  onCopy: (command: string) => void
+}
+
+export function InstallCommandBlock({ label, command, disabled, action, onCopy }: Props) {
+  return (
+    <div style={{ background: 'var(--color-fill-2)', padding: '12px 14px', borderRadius: 4, marginBottom: 12 }}>
+      {label && <Text type="secondary" style={{ fontSize: 12, display: 'block', marginBottom: 4 }}>{label}</Text>}
+      <Text style={{ fontSize: 13, wordBreak: 'break-all', opacity: disabled ? 0.4 : 1, userSelect: 'all' }}>
+        {command}
+      </Text>
+      <div style={{ marginTop: 8 }}>
+        <Space>
+          <Button size="small" icon={<IconCopy />} disabled={disabled} onClick={() => onCopy(command)}>复制</Button>
+          {action}
+        </Space>
+      </div>
+    </div>
+  )
+}

web/src/pages/nodes/wizard/Step1NodeName.tsx

@@ -32,7 +32,7 @@ export function Step1NodeName({
       </div>
       {mode === 'single' ? (
         <div>
-          <Text bold style={{ marginBottom: 6, display: 'block' }}>节点名称</Text>
+          <Text style={{ marginBottom: 6, display: 'block' }}>节点名称</Text>
           <Input
             placeholder="如：prod-db-01"
             value={singleName}
@@ -42,13 +42,13 @@ export function Step1NodeName({
         </div>
       ) : (
         <div>
-          <Text bold style={{ marginBottom: 6, display: 'block' }}>节点名称（每行一个，最多 50 个）</Text>
+          <Text style={{ marginBottom: 6, display: 'block' }}>节点名称（每行一个，最多 50 个）</Text>
           <TextArea
             rows={8}
             placeholder={'prod-db-01\nprod-db-02\nprod-web-01'}
             value={batchText}
             onChange={onBatchTextChange}
-            style={{ fontFamily: 'monospace', fontSize: 13 }}
+            style={{ fontSize: 13 }}
           />
           <Text type="secondary" style={{ fontSize: 12, marginTop: 4, display: 'block' }}>
             空行自动忽略；重名会在提交时报错

web/src/pages/nodes/wizard/Step2DeployOptions.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { isReleaseVersion } from './Step2DeployOptions'
+
+describe('isReleaseVersion', () => {
+  it('accepts release tags and rejects source-build versions', () => {
+    expect(isReleaseVersion('v2.4.0')).toBe(true)
+    expect(isReleaseVersion('2.4.0-rc.1')).toBe(true)
+    expect(isReleaseVersion('dev')).toBe(false)
+    expect(isReleaseVersion('00151e4')).toBe(false)
+    expect(isReleaseVersion(null)).toBe(false)
+  })
+})

web/src/pages/nodes/wizard/Step2DeployOptions.tsx

@@ -1,10 +1,11 @@
 import React from 'react'
 import { Form, Radio, Select, Input, Typography } from '@arco-design/web-react'
 import type { InstallMode, InstallArch, InstallSource } from '../../../types/nodes'
+import { AgentConnectionOptions, type AgentConnectionValue } from './AgentConnectionOptions'
 
 const { Text } = Typography
 
-export interface DeployOptions {
+export interface DeployOptions extends AgentConnectionValue {
   mode: InstallMode
   arch: InstallArch
   agentVersion: string
@@ -21,12 +22,17 @@ interface Props {
 
 export function Step2DeployOptions({ masterVersion, value, onChange }: Props) {
   const update = (patch: Partial<DeployOptions>) => onChange({ ...value, ...patch })
-  const versionKnown = !!masterVersion
+  const versionKnown = isReleaseVersion(masterVersion)
   const versionLoading = masterVersion === null
 
   return (
     <Form layout="vertical" size="default">
-      <Form.Item label="安装模式">
+      <Form.Item
+        label="安装模式"
+        extra={value.mode === 'docker'
+          ? <Text type="warning">Docker Agent 只能访问显式挂载的目录；备份源使用只读 volume，恢复目录需单独授权写入，或改用 systemd。</Text>
+          : undefined}
+      >
         <Radio.Group
           type="button"
           value={value.mode}
@@ -56,7 +62,9 @@ export function Step2DeployOptions({ masterVersion, value, onChange }: Props) {
         extra={
           !versionKnown && !versionLoading ? (
             <Text type="warning" style={{ fontSize: 12 }}>
-              未能自动获取 Master 版本，请手动输入（形如 v1.7.0）
+              {masterVersion
+                ? `当前 Master 版本 ${masterVersion} 不是可下载的 Release，请手动输入 Agent Release 标签`
+                : '未能自动获取 Master 版本，请手动输入 Agent Release 标签（形如 v1.7.0）'}
             </Text>
           ) : undefined
         }
@@ -106,6 +114,12 @@ export function Step2DeployOptions({ masterVersion, value, onChange }: Props) {
           ]}
         />
       </Form.Item>
+
+      <AgentConnectionOptions value={value} onChange={(connection) => update(connection)} />
     </Form>
   )
 }
+
+export function isReleaseVersion(version: string | null) {
+  return !!version && /^v?\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)
+}

web/src/pages/nodes/wizard/Step3CommandPreview.tsx

@@ -1,9 +1,10 @@
 import React, { useEffect, useState } from 'react'
 import { Typography, Button, Space, Collapse, Spin, Message, Tag } from '@arco-design/web-react'
-import { IconCopy, IconRefresh } from '../../../components/icons'
+import { IconRefresh } from '../../../components/icons'
 import { fetchScriptPreview } from '../../../services/nodes'
-import type { InstallTokenResult, InstallMode } from '../../../types/nodes'
+import type { InstallTokenResult } from '../../../types/nodes'
 import { buildAgentDownloadCommand, buildAgentInstallCommand, buildEmbeddedAgentInstallCommand } from '../installCommands'
+import { InstallCommandBlock } from './InstallCommandBlock'
 
 const { Text } = Typography
 
@@ -11,12 +12,19 @@ interface Props {
   nodeId: number
   nodeName: string
   token: InstallTokenResult
-  mode: InstallMode
-  previewParams: { mode: string; arch: string; agentVersion: string; downloadSrc: string }
+  previewParams: {
+    mode: string
+    arch: string
+    agentVersion: string
+    downloadSrc: string
+    agentMasterUrl?: string
+    proxyUrl?: string
+    caCertFile?: string
+  }
   onRegenerate: () => void
 }
 
-export function Step3CommandPreview({ nodeId, nodeName, token, mode, previewParams, onRegenerate }: Props) {
+export function Step3CommandPreview({ nodeId, nodeName, token, previewParams, onRegenerate }: Props) {
   const [remaining, setRemaining] = useState(0)
   const [preview, setPreview] = useState<string>('')
   const [loadingPreview, setLoadingPreview] = useState(false)
@@ -30,12 +38,10 @@ export function Step3CommandPreview({ nodeId, nodeName, token, mode, previewPara
   }, [token.expiresAt])
 
   const expired = remaining === 0
-  const command = buildAgentInstallCommand(token.url, token.fallbackUrl)
-  const fallbackCommand = buildAgentDownloadCommand(token.url, token.fallbackUrl)
+  const fetchOptions = { proxyUrl: previewParams.proxyUrl, caCertFile: previewParams.caCertFile }
+  const command = buildAgentInstallCommand(token.url, token.fallbackUrl, fetchOptions)
+  const fallbackCommand = buildAgentDownloadCommand(token.url, token.fallbackUrl, fetchOptions)
   const embeddedCommand = token.scriptBase64 ? buildEmbeddedAgentInstallCommand(token.scriptBase64) : null
-  const dockerComposeCmd = mode === 'docker' && token.composeUrl
-    ? `curl -fsSL ${token.composeUrl} -o docker-compose.yml && docker-compose up -d`
-    : null
 
   const copy = async (s: string) => {
     await navigator.clipboard.writeText(s)
@@ -57,73 +63,28 @@ export function Step3CommandPreview({ nodeId, nodeName, token, mode, previewPara
   return (
     <div>
       <Space style={{ marginBottom: 12 }}>
-        <Text bold>节点：</Text>
+        <Text>节点：</Text>
         <Tag>{nodeName}</Tag>
         <Tag color={expired ? 'gray' : 'green'}>
           {expired ? '已过期' : `有效期 ${Math.floor(remaining / 60)}:${String(remaining % 60).padStart(2, '0')}`}
         </Tag>
       </Space>
 
-      <div style={{ background: 'var(--color-fill-2)', padding: '12px 14px', borderRadius: 6, marginBottom: 12 }}>
-        <Text style={{
-          fontFamily: 'monospace', fontSize: 13, wordBreak: 'break-all',
-          opacity: expired ? 0.4 : 1, userSelect: 'all',
-        }}>
-          {command}
-        </Text>
-        <div style={{ marginTop: 8 }}>
-          <Space>
-            <Button size="small" icon={<IconCopy />} disabled={expired} onClick={() => copy(command)}>复制</Button>
-            {expired && <Button size="small" type="primary" icon={<IconRefresh />} onClick={onRegenerate}>重新生成</Button>}
-          </Space>
-        </div>
-      </div>
+      <InstallCommandBlock
+        command={command}
+        disabled={expired}
+        onCopy={copy}
+        action={expired ? <Button size="small" type="primary" icon={<IconRefresh />} onClick={onRegenerate}>重新生成</Button> : undefined}
+      />
 
-      <div style={{ background: 'var(--color-fill-2)', padding: '12px 14px', borderRadius: 6, marginBottom: 12 }}>
-        <Text type="secondary" style={{ fontSize: 12, display: 'block', marginBottom: 4 }}>
-          或固定下载到 /tmp 后执行：
-        </Text>
-        <Text style={{
-          fontFamily: 'monospace', fontSize: 13, wordBreak: 'break-all',
-          opacity: expired ? 0.4 : 1, userSelect: 'all',
-        }}>
-          {fallbackCommand}
-        </Text>
-        <div style={{ marginTop: 8 }}>
-          <Button size="small" icon={<IconCopy />} disabled={expired} onClick={() => copy(fallbackCommand)}>复制</Button>
-        </div>
-      </div>
-
-      {dockerComposeCmd && (
-        <div style={{ background: 'var(--color-fill-2)', padding: '12px 14px', borderRadius: 6, marginBottom: 12 }}>
-          <Text type="secondary" style={{ fontSize: 12, display: 'block', marginBottom: 4 }}>
-            或使用 docker-compose：
-          </Text>
-          <Text style={{ fontFamily: 'monospace', fontSize: 13, wordBreak: 'break-all', opacity: expired ? 0.4 : 1 }}>
-            {dockerComposeCmd}
-          </Text>
-          <div style={{ marginTop: 8 }}>
-            <Button size="small" icon={<IconCopy />} disabled={expired} onClick={() => copy(dockerComposeCmd)}>复制</Button>
-          </div>
-        </div>
-      )}
+      <InstallCommandBlock label="或先下载到 /tmp 后执行：" command={fallbackCommand} disabled={expired} onCopy={copy} />
 
       {embeddedCommand && (
-        <div style={{ background: 'var(--color-fill-2)', padding: '12px 14px', borderRadius: 6, marginBottom: 12 }}>
-          <Text type="secondary" style={{ fontSize: 12, display: 'block', marginBottom: 4 }}>
-            代理异常时使用嵌入式备用命令：
-          </Text>
-          <Text style={{ fontFamily: 'monospace', fontSize: 13, wordBreak: 'break-all', userSelect: 'all' }}>
-            {embeddedCommand}
-          </Text>
-          <div style={{ marginTop: 8 }}>
-            <Button size="small" icon={<IconCopy />} onClick={() => copy(embeddedCommand)}>复制</Button>
-          </div>
-        </div>
+        <InstallCommandBlock label="安装入口不可达时使用嵌入式备用命令：" command={embeddedCommand} onCopy={copy} />
       )}
 
       <Text type="secondary" style={{ fontSize: 12, display: 'block', marginBottom: 8 }}>
-        主安装命令包含公开 install token，会在 TTL 到期或首次消费后作废；嵌入式备用命令包含完整节点 token，不依赖公开链接消费状态，请仅在目标机执行并妥善保存。
+        主安装命令包含一次性 install token，会在 TTL 到期或首次消费后作废；嵌入式备用命令包含完整节点 Token，不依赖公开入口，请仅在目标机执行并妥善保存。
       </Text>
 
       <Collapse bordered={false} onChange={(_key, keys) => {

web/src/services/nodes.ts

@@ -59,7 +59,15 @@ export async function rotateNodeToken(nodeId: number) {
 
 export async function fetchScriptPreview(
   nodeId: number,
-  params: { mode: string; arch: string; agentVersion: string; downloadSrc: string },
+  params: {
+    mode: string
+    arch: string
+    agentVersion: string
+    downloadSrc: string
+    agentMasterUrl?: string
+    proxyUrl?: string
+    caCertFile?: string
+  },
 ) {
   const response = await http.get<string>(`/nodes/${nodeId}/install-script-preview`, {
     params,

web/src/types/nodes.ts

@@ -51,6 +51,9 @@ export interface InstallTokenInput {
   agentVersion: string
   downloadSrc: InstallSource
   ttlSeconds: number
+  agentMasterUrl?: string
+  proxyUrl?: string
+  caCertFile?: string
 }
 
 export interface InstallTokenResult {