T3ST3ST3R0N · Oct 10, 2026 · Oct 9, 2026 · Oct 10, 2026 · coderabbitai · Oct 9, 2026
diff --git a/docs/backup-and-restore.fa.md b/docs/backup-and-restore.fa.md
@@ -123,13 +123,18 @@ sudo pasarguard restore
 `--file /path/to/backup.zip` معادل آن است. `--yes` تأیید تعاملی را حذف می‌کند،
 اما بررسی‌های سلامت همچنان انجام می‌شوند.
 
-برای دیتابیس سروری، Compose و مشخصات اتصال مقصد حفظ می‌شوند. وقتی نسخه مبدا
+برای دیتابیس سروری، Compose و مشخصات اتصال مقصد حفظ می‌شوند. بکاپ از خانواده دیگری از
+موتورهای دیتابیس (مثلاً بکاپ SQLite روی نصب PostgreSQL) پیش از هر تغییری رد می‌شود؛
+MySQL و MariaDB یک خانواده‌اند. وقتی نسخه مبدا
 مشخص باشد، ورود MySQL به MariaDB یا برعکس و بازیابی روی نسخه قدیمی‌تر، قبل از
 SQL متوقف می‌شود. مقایسه نسخه، سازگاری همه SQLهای اختصاصی را تضمین نمی‌کند.
 
 قبل از بازنویسی نصب موجود، بکاپ مستقل بگیرید. import SQL و بازیابی چند دیتابیس
 rollback یکپارچه ندارند؛ ممکن است یک دیتابیس موفق و بعدی ناموفق باشد. برای
-SQLite، snapshot ایمنی و برای فایل‌های برنامه، کپی پیش از جایگزینی تهیه می‌شود.
+SQLite، snapshot ایمنی و برای فایل‌های برنامه و داده، کپی پیش از جایگزینی تهیه
+می‌شود؛ اگر این کپی شکست بخورد، بازیابی متوقف می‌شود. فضای دیتابیس و فایل‌های
+Xray داخل پوشه داده دست‌نخورده می‌مانند و کپی نمی‌شوند. آرشیو دارای symbolic link
+یا hard link پیش از استخراج رد می‌شود.
 
 اگر `--fresh` پس از آماده‌سازی نصب شکست خورد، پنل اجرا نمی‌شود و داده‌ها برای
 بررسی باقی می‌مانند. پس از اصلاح علت در لاگ، اگر Compose و تنظیمات مقصد ساخته

diff --git a/docs/backup-and-restore.md b/docs/backup-and-restore.md
@@ -145,14 +145,19 @@ still applies. Use `pasarguard restore --help` for the options.
 
 Ordinary restore preserves the destination Compose file for server databases
 and the provisioned destination database credentials/connection URL. It validates
-payloads before stopping application writers. When source-version information is
-available, it refuses MySQL-to-MariaDB/MariaDB-to-MySQL imports and database
+payloads before stopping application writers. It refuses a backup from another
+database engine family (for example a SQLite backup onto a PostgreSQL
+installation) before changing anything. When source-version information is
+available, it also refuses MySQL-to-MariaDB/MariaDB-to-MySQL imports and database
 version downgrades before executing the import. Restore to the original engine
 and version when diagnosing an old backup. An allowed version comparison is not
 a guarantee that every vendor-specific SQL statement is compatible.
 
-Application/data files are saved before replacement, and SQLite receives a
-pre-restore safety snapshot. Server SQL imports are **not transactional recovery
+Application/data files are saved before replacement (the restore stops if that
+copy fails; database storage and Xray binaries inside the data directory are
+left in place rather than copied), and SQLite receives a pre-restore safety
+snapshot. Archives containing symbolic or hard links are refused before
+extraction. Server SQL imports are **not transactional recovery
 of the whole host**: an import can fail after changing data, and multi-database
 restores can finish earlier databases before a later one fails. Take a separate
 current backup before replacing an existing installation. Fresh recovery leaves

diff --git a/lib/common.sh b/lib/common.sh
@@ -93,6 +93,20 @@ sqlite_absolute_database_url() {
     printf '%s:////%s\n' "$driver" "${path#/}"
 }
 
+# rsync excludes for DATA_DIR, shared by backup and restore so they cannot drift
+# apart: database server storage (backed up as SQL dumps instead) and downloaded
+# Xray binaries. Backup skips them and restore's `rsync --delete` leaves them in
+# place. The leading slash anchors each pattern to the top of DATA_DIR, so a
+# nested directory with the same name is still part of the data.
+# shellcheck disable=SC2034 # used by pasarguard-backup.sh and pasarguard-restore.sh
+PASARGUARD_DATA_DIR_EXCLUDES=(
+    --exclude=/xray-core
+    --exclude=/mysql
+    --exclude=/mariadb
+    --exclude=/postgresql
+    --exclude=/timescaledb
+)
+
 # Ensure a secret-bearing file (e.g. .env, TLS private key) is only readable by
 # its owner. Creates the file with 0600 if it is missing so callers can harden
 # it *before* writing secrets; tightens it to 0600 if it already exists. A

diff --git a/lib/pasarguard-backup.sh b/lib/pasarguard-backup.sh
@@ -1889,7 +1889,7 @@ backup_command() {
     colorized_echo blue "Copying data directory..."
     # Ensure destination directory exists and is empty (already cleaned above, but be explicit)
     if [ -d "$DATA_DIR" ]; then
-        local rsync_args=(-av --exclude 'xray-core' --exclude 'mysql' --exclude 'mariadb' --exclude 'postgresql' --exclude 'timescaledb')
+        local rsync_args=(-av "${PASARGUARD_DATA_DIR_EXCLUDES[@]}")
         local normalized_data_dir=""
         normalized_data_dir=$(normalize_posix_path "$DATA_DIR")
 

diff --git a/lib/pasarguard-restore.sh b/lib/pasarguard-restore.sh
@@ -1,5 +1,17 @@
 #!/usr/bin/env bash
 
+# True when the archive lists a symbolic or hard link member (or cannot be
+# listed). Checked before extraction; backups never contain links.
+archive_has_links() {
+    local archive="$1" kind="$2" listing=""
+    case "$kind" in
+        zip) listing=$(unzip -Z "$archive" 2>/dev/null) || return 0 ;;
+        tar) listing=$(tar -tvzf "$archive" 2>/dev/null) || return 0 ;;
+        *) return 0 ;;
+    esac
+    grep -q '^[lh]' <<<"$listing"
+}
+
 # Reject archives whose members would escape the extraction directory — an
 # absolute path or a '..' component (zip-slip / tar path traversal). Backups
 # are later rsynced into $DATA_DIR/$APP_DIR as root, so a tampered archive must
@@ -701,6 +713,24 @@ pg_restore_all_user_databases() {
     [ "$total" -gt 0 ] && [ "$ok" -eq "$total" ]
 }
 
+# Copy DATA_DIR aside before a restore replaces it. Database storage and Xray
+# binaries are skipped: the restore leaves them in place.
+save_data_dir_safety_copy() {
+    local destination="$1" log="$2"
+    rsync -a "${PASARGUARD_DATA_DIR_EXCLUDES[@]}" "$DATA_DIR/" "$destination/" 2>>"$log"
+}
+
+# Map an engine name or a SQLAlchemy URL to its engine family: sqlite, mysql
+# (MySQL and MariaDB) or postgresql (PostgreSQL and TimescaleDB). Prints nothing
+# for anything else.
+database_engine_family() {
+    case "$1" in
+        sqlite*) echo sqlite ;;
+        mysql* | mariadb*) echo mysql ;;
+        postgresql* | timescaledb*) echo postgresql ;;
+    esac
+}
+
 # Read recovery metadata as data, without evaluating archived shell input.
 backup_runtime_value() {
     local stage="$1" key="$2"
@@ -764,6 +794,8 @@ print_backup_runtime() {
 # Reject cross-engine imports and version downgrades before the first SQL
 # statement. Upgrades within one engine still use its normal logical restore
 # path (and the existing TimescaleDB compatibility conversion).
+# Returns 0 when compatible, 1 when refused (with the reason printed) and 2
+# when the destination version could not be read.
 check_restore_database_version() {
     local stage="$1" engine="$2" container="$3" log="$4"
     local source_version="" target_version="" client="mysql" user="" password=""
@@ -777,13 +809,22 @@ check_restore_database_version() {
     case "$engine" in
         mysql|mariadb)
             if docker exec "$container" mariadb --version >/dev/null 2>&1; then client=mariadb; fi
-            if [ -n "$current_mysql_root_password" ]; then
-                user=root; password="$current_mysql_root_password"
-            else
-                user="${current_db_user:-$db_user}"; password="${current_db_password:-$db_password}"
-            fi
-            target_version=$(docker exec -e MYSQL_PWD="$password" "$container" "$client" \
-                -u "$user" -N -s -e 'SELECT VERSION();' 2>>"$log") || return 1
+            # Same credential order as the import: current root, backup root,
+            # backup app user, current app user.
+            local credentials=() i=0
+            [ -z "${current_mysql_root_password:-}" ] || credentials+=(root "$current_mysql_root_password")
+            [ -z "${MYSQL_ROOT_PASSWORD:-}" ] || credentials+=(root "$MYSQL_ROOT_PASSWORD")
+            [ -z "${db_user:-}" ] || credentials+=("$db_user" "${db_password:-}")
+            [ -z "${current_db_user:-}" ] || credentials+=("$current_db_user" "${current_db_password:-}")
+            for ((i = 0; i < ${#credentials[@]}; i += 2)); do
+                user="${credentials[i]}"; password="${credentials[i + 1]}"
+                if target_version=$(docker exec -e MYSQL_PWD="$password" "$container" "$client" \
+                    -u "$user" -N -s -e 'SELECT VERSION();' 2>>"$log"); then
+                    break
+                fi
+                target_version=""
+            done
+            [ -n "$target_version" ] || return 2
             if { [[ "$source_version" == *MariaDB* ]] && [[ "$target_version" != *MariaDB* ]]; } || \
                 { [[ "$source_version" != *MariaDB* ]] && [[ "$target_version" == *MariaDB* ]]; }; then
                 colorized_echo red "Backup engine ($source_version) differs from destination ($target_version). Restore with the original engine, or use --fresh on an empty server."
@@ -793,11 +834,11 @@ check_restore_database_version() {
         postgresql|timescaledb)
             user="${current_db_user:-${db_user:-postgres}}"; password="${current_db_password:-$db_password}"
             target_version=$(docker exec -e PGPASSWORD="$password" "$container" psql -X -U "$user" -d postgres -At \
-                -c 'SHOW server_version;' 2>>"$log") || return 1
+                -c 'SHOW server_version;' 2>>"$log") || return 2
             ;;
         *) return 0 ;;
     esac
-    [[ "$target_version" =~ ^([0-9]+)\.([0-9]+) ]] || return 1
+    [[ "$target_version" =~ ^([0-9]+)\.([0-9]+) ]] || return 2
     local target_major="${BASH_REMATCH[1]}" target_minor="${BASH_REMATCH[2]}"
     if [ "$source_major" -gt "$target_major" ] || \
         { [[ "$engine" =~ ^(mysql|mariadb)$ ]] && [ "$source_major" -eq "$target_major" ] && [ "$source_minor" -gt "$target_minor" ]; }; then
@@ -1457,6 +1498,12 @@ restore_command() {
             rm -rf "$temp_restore_dir"
             exit 1
         fi
+        if archive_has_links "$archive_to_extract" zip; then
+            colorized_echo red "ERROR: The backup archive contains symbolic or hard links. Repackage it with regular files before restoring."
+            echo "Link members detected in $archive_to_extract" >>"$log_file"
+            rm -rf "$temp_restore_dir"
+            exit 1
+        fi
         if ! unzip -oq "$archive_to_extract" -d "$temp_restore_dir" 2>>"$log_file"; then
             colorized_echo red "Failed to extract backup file."
             echo "Failed to extract $archive_to_extract" >>"$log_file"
@@ -1476,6 +1523,12 @@ restore_command() {
             rm -rf "$temp_restore_dir"
             exit 1
         fi
+        if archive_has_links "$archive_to_extract" tar; then
+            colorized_echo red "ERROR: The backup archive contains symbolic or hard links. Repackage it with regular files before restoring."
+            echo "Link members detected in $archive_to_extract" >>"$log_file"
+            rm -rf "$temp_restore_dir"
+            exit 1
+        fi
         if ! tar -xzf "$archive_to_extract" -C "$temp_restore_dir" 2>>"$log_file"; then
             colorized_echo red "Failed to extract backup file."
             echo "Failed to extract $archive_to_extract" >>"$log_file"
@@ -1719,6 +1772,17 @@ restore_command() {
         colorized_echo green "Backup validation passed. No services or destination data were changed. This check does not perform a database import."
         return 0
     fi
+    # Ordinary restore keeps the destination's database server. A backup from
+    # another engine family would replace its configuration instead (for SQLite,
+    # the restored .env and Compose file drop the database service).
+    if [ "$fresh_restore" = false ] && [ -n "$current_sqlalchemy_url" ]; then
+        local destination_engine=""
+        destination_engine=$(database_engine_family "$current_sqlalchemy_url")
+        if [ -n "$destination_engine" ] && [ "$(database_engine_family "$db_type")" != "$destination_engine" ]; then
+            colorized_echo red "Backup engine ($db_type) differs from destination ($destination_engine). Restore with the original engine, or use --fresh on an empty server."
+            cleanup_and_exit_restore_error 1
+        fi
+    fi
     if [ "$fresh_restore" = true ]; then
         if [ "$db_type" != sqlite ] && ! is_local_db_host "$db_host"; then
             colorized_echo red "--fresh requires a local database from the official Compose templates."
@@ -1785,10 +1849,12 @@ restore_command() {
             colorized_echo red "Destination database could not be started for compatibility checks."
             cleanup_and_exit_restore_error 1
         fi
-        if ! check_restore_database_version "$temp_restore_dir" "$db_type" "$container_name" "$log_file"; then
-            colorized_echo red "Could not validate database version compatibility. Check destination credentials and the restore log."
-            cleanup_and_exit_restore_error 1
+        local version_check=0
+        check_restore_database_version "$temp_restore_dir" "$db_type" "$container_name" "$log_file" || version_check=$?
+        if [ "$version_check" -eq 2 ]; then
+            colorized_echo red "Could not read the destination database version. Check destination credentials and the restore log."
         fi
+        [ "$version_check" -eq 0 ] || cleanup_and_exit_restore_error 1
     fi
 
     # Stop pasarguard services before restore for clean state
@@ -2178,11 +2244,19 @@ restore_command() {
             install_package rsync
         fi
         mkdir -p "$DATA_DIR"
+        # rsync --delete below relies on these excludes to keep database storage.
+        if [ "${#PASARGUARD_DATA_DIR_EXCLUDES[@]}" -eq 0 ]; then
+            colorized_echo red "The data directory exclude list is missing (mismatched script libraries). Refusing to sync the data directory."
+            cleanup_and_exit_restore_error 1
+        fi
         if [ "$fresh_restore" = false ] && [ "$(ls -A "$DATA_DIR" 2>/dev/null)" ]; then
             colorized_echo blue "Backing up current data directory before restore..."
-            cp -r "$DATA_DIR" "$DATA_DIR.backup.$(date +%Y%m%d%H%M%S)" 2>>"$log_file" || true
+            if ! save_data_dir_safety_copy "$DATA_DIR.backup.$(date +%Y%m%d%H%M%S)" "$log_file"; then
+                colorized_echo red "Failed to save the current data directory before replacement."
+                cleanup_and_exit_restore_error 1
+            fi
         fi
-        if ! rsync -a --delete --exclude mysql --exclude mariadb --exclude postgresql --exclude timescaledb "$extracted_data_dir/" "$DATA_DIR/" 2>>"$log_file"; then
+        if ! rsync -a --delete "${PASARGUARD_DATA_DIR_EXCLUDES[@]}" "$extracted_data_dir/" "$DATA_DIR/" 2>>"$log_file"; then
             colorized_echo red "Failed to restore data directory."
             echo "Failed to restore data directory from $extracted_data_dir to $DATA_DIR" >>"$log_file"
             cleanup_and_exit_restore_error 1

diff --git a/tests/unit_restore_archive_safety.sh b/tests/unit_restore_archive_safety.sh
@@ -56,6 +56,24 @@ else
     echo "(skipped zip cases: zip/unzip unavailable)"
 fi
 
+# Symbolic and hard links are rejected from the listing, before extraction.
+mkdir -p links
+echo target > links/target.txt
+ln -s target.txt links/symlink
+tar -czf symlink.tgz -C links .
+rm links/symlink && ln links/target.txt links/hardlink
+tar -czf hardlink.tgz -C links .
+assert_true  "archive_has_links: tar symlink found" archive_has_links symlink.tgz tar
+assert_true  "archive_has_links: tar hard link found" archive_has_links hardlink.tgz tar
+assert_false "archive_has_links: clean tar passes" archive_has_links safe.tgz tar
+if command -v zip >/dev/null 2>&1 && command -v unzip >/dev/null 2>&1; then
+    rm links/hardlink && ln -s target.txt links/symlink
+    (cd links && zip -qry "$WORK_DIR/symlink.zip" .)
+    assert_true  "archive_has_links: zip symlink found" archive_has_links symlink.zip zip
+    assert_false "archive_has_links: clean zip passes" archive_has_links safe.zip zip
+fi
+assert_true "archive_has_links: unreadable archive treated as unsafe" archive_has_links /no/such.tgz tar
+
 # Unknown kind and unreadable archive are treated as unsafe.
 assert_false "archive_entries_are_safe: unknown kind rejected" archive_entries_are_safe safe.tgz bogus
 assert_false "archive_entries_are_safe: missing archive rejected" archive_entries_are_safe /no/such.tgz tar