DEV Community

Dal
Dal

Posted on

Zero-Downtime Hot Backups & Safe Migration for Proxy Panels (3X-UI, Marzban, Hiddify)

#devops #linux #sqlite #docker

Zero-Downtime Hot Backups & Safe Migration for Proxy Management Panels

When managing distributed network proxy servers and VPN orchestration panels (such as 3X-UI, Marzban, PasarGuard, Remnawave, or Hiddify), the database is under relentless write load. Client upload and download metrics, bandwidth quotas, and session lifetimes update every fraction of a second.

Standard backup methods—such as ad-hoc cp commands or archiving directories while services run—often cause database corruption due to uncommitted WAL pages, or require service downtime that disrupts active user tunnels.

This tutorial explores how to implement atomic online hot backups, safe schema verification, and sub-minute server migration using the open-source Khoosheh engine.

The Technical Problem: SQLite WAL Inconsistencies

Most modern panels use SQLite configured with PRAGMA journal_mode=WAL;. In WAL mode:

  1. Modifying transactions append pages to the -wal file instead of altering the main .db database.
  2. The -shm shared-memory file maintains index mappings.
  3. If an archive tool copies .db while transactions are occurring, the resulting backup will be out-of-sync or corrupt.

The Atomic Solution: PRAGMA wal_checkpoint(TRUNCATE)

To safely take a snapshot without locking tables or interrupting active clients, we invoke an atomic checkpoint:

PRAGMA wal_checkpoint(TRUNCATE);
PRAGMA integrity_check;
Enter fullscreen mode Exit fullscreen mode

This flushes all active journal frames into the database file, truncates the WAL log to zero bytes, and ensures zero data loss of user bandwidth statistics.

Multi-Panel Auto-Discovery Architecture

The Khoosheh backup engine automates this pipeline through intelligent discovery:

Panel Type Target Files & Databases Backup Mechanism
3X-UI / X-UI (Sanaei, Alireza, etc.) /etc/x-ui/x-ui.db Native Python SQLite streaming hot backup
Marzban (Gozar) marzban.db, .env, Docker MySQL dumps Atomic checkpoint & containerized dump
PasarGuard Client databases, sub_bridge, TLS certs Volume snapshot & structured packaging
Remnawave SQLite config & PostgreSQL container pg_dump stream & config extraction
Hiddify Manager hiddifypanel.db, current-config.json Live DB checkpoint & SSL certificate preservation

Step-by-Step Implementation Guide

1. One-Line Deployment

On Debian or Ubuntu servers:

curl -sSL https://raw.githubusercontent.com/dalroot/khoosheh/main/install.sh | bash
Enter fullscreen mode Exit fullscreen mode

The systemd daemon launches automatically on port 2099 (HTTP) and 2098 (HTTPS), preventing port conflicts with standard proxy ports (such as 443, 80, 2053, or 8443).

2. Access the Dashboard

Navigate to:

http://YOUR_SERVER_IP:2099
Enter fullscreen mode Exit fullscreen mode

Configure administrative credentials during the initial setup wizard. Installed panels are automatically detected on login.

3. Telegram Automation & AES-256 Encryption

Under the Settings panel:

  • Configure your Telegram Bot token and Admin ID.
  • Set an optional AES-256 (7z) encryption passphrase for all archives.
  • Enable automated daily digests and scheduled distribution (e.g., every 6 hours).

4. Zero-Downtime Migration (< 60s Downtime)

To migrate to a new server or node:

  1. Deploy Khoosheh on the destination server.
  2. Upload the encrypted archive to the Smart Restore Wizard.
  3. Khoosheh automatically saves a .pre_restore_<timestamp>.bak rollback safety copy, verifies database integrity, clears stale -wal cache, and restarts dependent services cleanly.

Benchmark Results

  • Migration Downtime: < 60 seconds (zero tunnel disconnects).
  • Traffic Loss: 0% (exact preservation of upload/download bytes).
  • Restore Speed: Initial restoration of multi-gigabyte logs completed in < 5 minutes.

Open Source & Contributions

Khoosheh is open-source under the MIT License. PRs, issue reports, and community benchmarks are welcomed:

Top comments (0)