mirror of
https://github.com/Awuqing/BackupX.git
synced 2026-09-06 07:56:41 +08:00
feat: 优化集群部署与堡垒机接入 (#106)
支持受限网络、正向代理、私有 CA 与 SSH 堡垒机部署 Agent。 加固 Docker、systemd、Nginx、安装器、Release 校验与可信代理边界，并完善命令队列索引、前端安装向导及中英文运维文档。
This commit is contained in:
Wu Qing
+15
-2
@@ -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` 端口。安装器不会自动修改防火墙。
|
||||
|
||||
## 密码重置
|
||||
|
||||
忘记管理员密码时：
|
||||
|
||||
+21
-1
@@ -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 直接暴露且不应信任任何转发头时可设置空列表。
|
||||
|
||||
@@ -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`。
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user