fix(cluster): support external master URL

- add server.external_url / BACKUPX_SERVER_EXTERNAL_URL for Agent install URL generation
- pass the configured external Master URL into install script and compose rendering
- document cluster deployment requirements for Docker, bare-metal, and multi-node setups

Fixes #55

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

@@ -25,6 +25,19 @@ sudo ./install.sh
 4. 安装并启用 `backupx.service` systemd 单元
 5. （可选）生成 Nginx 站点配置 — 参见 [Nginx 反向代理](./nginx)
 
+如果要部署多节点集群，安装后请编辑 `/etc/backupx/config.yaml`，设置远程 Agent 可访问到的 Master URL：
+
+```yaml
+server:
+  external_url: "https://backup.example.com"
+```
+
+修改后重启 BackupX：
+
+```bash
+sudo systemctl restart backupx
+```
+
 ## 从源码构建
 
 ```bash

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

@@ -15,13 +15,14 @@ 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
 
 database:
   path: "./data/backupx.db"   # BACKUPX_DATABASE_PATH — 内嵌 SQLite
 
 security:
   jwt_secret: ""              # BACKUPX_SECURITY_JWT_SECRET — 留空自动生成
-  jwt_expires_in: "24h"
+  jwt_expire: "24h"           # BACKUPX_SECURITY_JWT_EXPIRE
   encryption_key: ""          # 用于加密存储配置的 AES-256-GCM 密钥
 
 backup:
@@ -46,7 +47,20 @@ log:
 | 配置项 | 环境变量 |
 |--------|----------|
 | `server.port` | `BACKUPX_SERVER_PORT` |
+| `server.external_url` | `BACKUPX_SERVER_EXTERNAL_URL` |
+| `security.jwt_expire` | `BACKUPX_SECURITY_JWT_EXPIRE` |
 | `log.level` | `BACKUPX_LOG_LEVEL` |
 | `backup.max_concurrent` | `BACKUPX_BACKUP_MAX_CONCURRENT` |
 | `backup.temp_dir` | `BACKUPX_BACKUP_TEMP_DIR` |
 | `backup.bandwidth_limit` | `BACKUPX_BACKUP_BANDWIDTH_LIMIT` |
+
+## Master 对外 URL
+
+当 BackupX 部署在 Docker、Nginx、负载均衡或多层反向代理后面，且后端收到的内部 Host 不是远程 Agent 可访问地址时，请配置 `server.external_url`：
+
+```yaml
+server:
+  external_url: "https://backup.example.com"
+```
+
+BackupX 会用这个地址渲染一键 Agent 安装脚本和 docker-compose 片段。该地址必须能被所有 Agent 主机访问。只有在 `X-Forwarded-Proto` / `X-Forwarded-Host` 可靠且正好指向 Agent 可访问地址时，才建议留空。

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

@@ -25,6 +25,8 @@ services:
       - /etc/nginx:/mnt/nginx-conf:ro
     environment:
       - TZ=Asia/Shanghai
+      # 远程 Agent 需要通过公网或可路由地址连接 Master 时必须配置：
+      # - BACKUPX_SERVER_EXTERNAL_URL=https://backup.example.com
       - BACKUPX_LOG_LEVEL=info
       - BACKUPX_BACKUP_MAX_CONCURRENT=2
 
@@ -42,6 +44,17 @@ docker compose up -d
 
 想备份宿主机上的文件，需要将对应路径挂载进容器。在 Web UI 创建文件类型任务时，把源路径指向挂载后的容器内路径（如 `/mnt/www`）。
 
+## 多节点集群
+
+如果要在其他机器部署 Agent，请在 Master 容器上设置 `BACKUPX_SERVER_EXTERNAL_URL`，值为所有 Agent 都能访问到的 URL：
+
+```yaml
+environment:
+  - BACKUPX_SERVER_EXTERNAL_URL=https://backup.example.com
+```
+
+Agent 跨不可信网络访问时建议使用 HTTPS。控制台生成的一键安装脚本和 docker-compose 片段会把这个值写成 `BACKUPX_AGENT_MASTER`。
+
 ## 环境变量
 
 所有配置项都可以通过 `BACKUPX_` 前缀环境变量覆盖：

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

@@ -28,6 +28,19 @@ BackupX 支持 Master-Agent 模式：备份任务可以指定在哪个节点执
 
 ## 一键部署步骤
 
+### 0. 为生产集群设置 Master 对外 URL
+
+生成 Agent 安装命令前，请先确认 Master URL 对所有目标主机稳定可达。
+
+如果 BackupX 部署在 Docker、Nginx、负载均衡或外层反向代理后面，请在 Master 配置 `server.external_url` 或环境变量 `BACKUPX_SERVER_EXTERNAL_URL`：
+
+```yaml title="config.yaml"
+server:
+  external_url: "https://backup.example.com"
+```
+
+该 URL 会写入 systemd 单元、前台运行命令和 docker-compose 片段。如果地址不正确，Agent 可能安装成功但始终离线，因为它会持续轮询一个内网地址或仅浏览器可访问的地址。
+
 ### 1. 打开安装向导
 
 Web 控制台 → **节点管理** → **添加节点**，打开三步向导：