mirror of
https://github.com/Awuqing/BackupX.git
synced 2026-08-16 09:54:00 +08:00
feat: 优化集群部署与堡垒机接入 (#106)
支持受限网络、正向代理、私有 CA 与 SSH 堡垒机部署 Agent。 加固 Docker、systemd、Nginx、安装器、Release 校验与可信代理边界，并完善命令队列索引、前端安装向导及中英文运维文档。
This commit is contained in:
Wu Qing
@@ -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:
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user