mirror of https://github.com/Awuqing/BackupX.git synced 2026-08-12 16:03:59 +08:00

Files

Wu Qing bdd16dafa8 docs: 完善部署与运维文档 (#107 )

新增中英文升级恢复、安全加固、监控告警与故障排查手册，校正安装部署、CLI 与 API 参考，并修复安全密钥环境变量注入及其回归测试。

2026-08-09 13:51:38 +08:00

3.5 KiB

Raw Blame History

sidebar_position, title, description

sidebar_position	title	description
1	Docker Deployment	Hardened single-process Docker deployment with health checks and persistent data.

Docker Deployment

The official awuqing/backupx image supports linux/amd64 and linux/arm64.

Compose file

services:
  backupx:
    image: ${BACKUPX_IMAGE:-awuqing/backupx:latest}
    container_name: backupx
    restart: unless-stopped
    init: true
    stop_grace_period: 30s
    ports:
      - "${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
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - SETGID
      - SETUID
    environment:
      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:

docker compose up -d
docker compose ps

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.

Host-directory backups

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.

Multi-node cluster

Set the stable URL that Agents can reach:

environment:
  BACKUPX_SERVER_EXTERNAL_URL: https://backup.example.com

Use HTTPS across untrusted networks. Proxy, private-CA, and SSH-bastion deployments are covered in Multi-Node Cluster.

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.

Environment overrides

environment:
  TZ: Asia/Shanghai
  BACKUPX_LOG_LEVEL: debug
  BACKUPX_BACKUP_MAX_CONCURRENT: "4"
  BACKUPX_BACKUP_TEMP_DIR: /tmp/backupx

The image's internal port is fixed at 8340; change only the published host port with BACKUPX_PORT.

Upgrade prerequisites

docker compose pull
docker compose up -d
docker compose ps

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.

Use a release tag or digest instead of latest, and keep the matching pre-upgrade data snapshot. The complete upgrade, rollback, and disaster-recovery procedure is in Upgrade and Recovery.

3.5 KiB Raw Blame History