Skip to content

Latest commit

 

History

History
266 lines (202 loc) · 17.7 KB

backup-and-restore.fa.md

File metadata and controls

266 lines (202 loc) · 17.7 KB

راهنمای بکاپ و بازیابی پاسارگارد

English guide

ابتدا محیط سازگار با بکاپ را بازیابی کنید و بعد از سالم‌شدن پنل، ارتقا دهید. نصب جدیدترین پنل و دیتابیس همیشه برای بازیابی یک بکاپ قدیمی مناسب نیست.

وقتی سرور قبلی کاملاً از دست رفته است

بکاپ تهیه‌شده با اسکریپت جدید را روی سرور لینوکسی جدید قرار دهید؛ مثلاً /root/backup_20261004120000.zip. دسترسی به سرور قبلی، نصب پنل جدید یا ساخت مدیر جدید لازم نیست. فقط اسکریپت مدیریت را نصب کنید:

sudo bash -c "$(curl -fsSL https://github.com/PasarGuard/scripts/raw/main/pasarguard.sh)" @ install-script

ابتدا فایل و مشخصات محیط قبلی را بررسی کنید، سپس بازیابی را انجام دهید:

sudo pasarguard restore /root/backup_20261004120000.zip --check
sudo pasarguard restore /root/backup_20261004120000.zip --fresh

برای بررسی بکاپ SQLite، ابزار sqlite3 باید نصب باشد. در Debian/Ubuntu:

sudo apt-get update
sudo apt-get install -y sqlite3

--check به Docker نیاز ندارد، SQL وارد نمی‌کند و سرویس‌ها و تنظیمات مقصد را تغییر نمی‌دهد. فایل را موقتاً کنار آرشیو باز می‌کند، checksum و کامل‌بودن dump یا سلامت snapshot را بررسی می‌کند و staging را حذف می‌کند. این بررسی جای آزمایش کامل بازیابی را نمی‌گیرد.

بعد از تأیید --fresh، نسخه‌های ثبت‌شده آماده می‌شوند. هر ایمیج ثبت‌شده با همان نامی که در فایل Compose آرشیو آمده (مثلاً pasarguard/panel:latest) tag می‌شود و خود فایل Compose بدون تغییر نصب می‌شود. نام ایمیج‌ها در کل سرور مشترک است؛ اگر نامی از قبل به ایمیج دیگری اشاره کند، به ایمیج ثبت‌شده منتقل می‌شود و اسکریپت این را اعلام می‌کند. ابتدا فقط دیتابیس اجرا می‌شود و پس از آماده‌شدن، بکاپ وارد می‌شود؛ پنل و migrationها در این مرحله خاموش هستند. اگر سرویس دیتابیس healthcheck نداشته باشد، آماده‌بودن با اتصال TCP داخل کانتینر سنجیده می‌شود. پس از بازیابی داده‌ها و تنظیمات، پنل با ایمیج اصلی اجرا می‌شود. برای SQLite، snapshot قبل از راه‌اندازی هر سرویس پنل بررسی و بازگردانی می‌شود.

مقصد باید خالی باشد: پوشه برنامه و داده‌ها نباید نصب دیگری داشته باشند؛ پروژه Compose نباید کانتینر موجود داشته باشد؛ دیتابیس یا volume موجود بازنویسی نمی‌شود. پوشه برنامه می‌تواند فقط پوشه backup/ را داشته باشد. قالب‌های رسمی محلی SQLite، MySQL، MariaDB، PostgreSQL و TimescaleDB پشتیبانی می‌شوند. دیتابیس راه‌دور و volumeهای external به آماده‌سازی دستی نیاز دارند.

برای نصب سفارشی، نام و مسیرهای نمایش‌داده‌شده در --check را مشخص کنید:

sudo env APP_NAME=my-panel APP_DIR=/opt/my-panel DATA_DIR=/var/lib/my-panel \
  pasarguard restore /root/backup.zip --fresh

معماری مقصد باید با ایمیج‌ها سازگار باشد. زمان بازیابی به حجم داده، دیسک، شبکه و دریافت ایمیج‌ها بستگی دارد و زمان ثابتی تضمین نمی‌شود.

چه چیزهایی در بکاپ ذخیره می‌شود؟

.env، Compose، فایل‌های برنامه/گواهی‌ها در پوشه داده، snapshot یا dump دیتابیس و این دو فایل ذخیره می‌شوند:

  • backup-runtime.tsv: زمان UTC، نوع و نسخه واقعی دیتابیس، نسخه schema در صورت دسترسی، نام/مسیرهای نصب و digest و شناسه ایمیج کانتینرهای واقعی.
  • backup-files.sha256: checksum فایل‌ها، از جمله تنظیمات و شناسنامه. فایلی که نامش backslash، CR یا LF دارد در آن ثبت نمی‌شود و هنگام بکاپ گزارش می‌شود.

نسخه ایمیج از کانتینر واقعی، حتی کانتینر خاموش، ثبت می‌شود؛ صرفاً latest یا lts در Compose ملاک نیست. اگر سرویسی قابل شناسایی نباشد، unavailable نمایش داده می‌شود. restore معمولی ممکن است، اما --fresh نسخه‌ای حدس نمی‌زند. ایمیج اصلی که با docker load بارگذاری شده هم قابل استفاده است.

DNS، cron سیستم‌عامل، سرویس تمدید گواهی خارج از پوشه‌های برنامه، تنظیمات کل سرور و نودهای مستقل، جزو این آرشیو نیستند. فایل خام دیتابیس در حال اجرا، جایگزین dump یا snapshot معتبر نیست.

تهیه و نگهداری بکاپ

sudo pasarguard backup
sudo pasarguard backup-service

فایل‌های محلی در /opt/pasarguard/backup/ ساخته می‌شوند. فرمان فعلی پس از تهیه موفق بکاپ جدید، آرشیوهای محلی قبلی را حذف می‌کند؛ چند نسل تاریخ‌دار را در محل جداگانه خارج از سرور نگه دارید. بکاپ روی همان سرور برای نابودی کامل آن کافی نیست.

برای ارسال خودکار تلگرام از منوی backup-service استفاده کنید. نام متغیرها:

BACKUP_SERVICE_ENABLED=true
BACKUP_TELEGRAM_BOT_KEY="123456789:example-token"
BACKUP_TELEGRAM_CHAT_ID="-1001234567890"
BACKUP_PROXY_ENABLED=false
# BACKUP_PROXY_URL="socks5://127.0.0.1:1080"

فاصله‌های متداول: ۵، ۱۵، ۳۰، ۶۰، ۱۲۰، ۳۶۰ و ۱۴۴۰ دقیقه. همه بخش‌ها را دریافت کنید و روی نسخه دانلودشده --check اجرا کنید. ارسال موفق، اثبات import موفق نیست.

آرشیوها رمز و کلید خصوصی دارند و اسکریپت ZIP را رمزنگاری نمی‌کند؛ دسترسی امن یا رمزنگاری نسخه خارج از سرور را فراهم کنید. checksum خرابی را تشخیص می‌دهد و هویت ارسال‌کننده ناشناس را تأیید نمی‌کند. فایل‌های .env و Compose بلافاصله پس از بازگردانی فقط برای مالک قابل خواندن می‌شوند.

SQLite با .backup آنلاین snapshot می‌گیرد و quick_check اجرا می‌شود. PostgreSQL/TimescaleDB در صورت دسترسی، همه دیتابیس‌های کاربری و globals را ذخیره می‌کنند؛ در fallback فقط دیتابیس تنظیم‌شده ذخیره می‌شود. dump برای MySQL/MariaDB با قفل پیش‌فرض جدول‌ها گرفته می‌شود، نه یک snapshot تراکنشی؛ پس تا پایان dump نوشتن پنل منتظر می‌ماند. زمان snapshot دیتابیس‌های مختلف و کپی فایل‌ها یکسان نیست؛ هنگام تغییر schema/DDL بکاپ نگیرید.

بازیابی روی نصب موجود

sudo pasarguard restore /root/backup.zip
# یا انتخاب از پوشه پیش‌فرض:
sudo pasarguard restore

مسیر مستقیم انتخاب شماره را حذف می‌کند و می‌تواند خارج از پوشه پیش‌فرض باشد. --file /path/to/backup.zip معادل آن است. --yes تأیید تعاملی را حذف می‌کند، اما بررسی‌های سلامت همچنان انجام می‌شوند.

برای دیتابیس سروری، Compose و مشخصات اتصال مقصد حفظ می‌شوند. بکاپ از خانواده دیگری از موتورهای دیتابیس (مثلاً بکاپ SQLite روی نصب PostgreSQL) پیش از هر تغییری رد می‌شود؛ MySQL و MariaDB یک خانواده‌اند. وقتی نسخه مبدا مشخص باشد، ورود MySQL به MariaDB یا برعکس و بازیابی روی نسخه قدیمی‌تر، قبل از SQL متوقف می‌شود. مقایسه نسخه، سازگاری همه SQLهای اختصاصی را تضمین نمی‌کند.

قبل از بازنویسی نصب موجود، بکاپ مستقل بگیرید. import SQL و بازیابی چند دیتابیس rollback یکپارچه ندارند؛ ممکن است یک دیتابیس موفق و بعدی ناموفق باشد. برای SQLite، snapshot ایمنی و برای فایل‌های برنامه و داده، کپی پیش از جایگزینی تهیه می‌شود؛ اگر این کپی شکست بخورد، بازیابی متوقف می‌شود. فضای دیتابیس و فایل‌های Xray داخل پوشه داده دست‌نخورده می‌مانند و کپی نمی‌شوند. آرشیو دارای symbolic link یا hard link پیش از استخراج رد می‌شود.

اگر --fresh پس از آماده‌سازی نصب شکست خورد، پنل اجرا نمی‌شود و داده‌ها برای بررسی باقی می‌مانند. پس از اصلاح علت در لاگ، اگر Compose و تنظیمات مقصد ساخته شده‌اند، همان فرمان --fresh را دوباره اجرا کنید: تلاش قبلی به‌صورت restore معمولی روی همان نصب ادامه پیدا می‌کند (بکاپ دیگری پذیرفته نمی‌شود) و از پوشه‌های برنامه و داده نیمه‌کاره آن کپی پیش از جایگزینی نمی‌گیرد. restore معمولی با همان بکاپ هم کار می‌کند، اما پیش از آن از این پوشه‌ها کپی می‌گیرد.

بکاپ قدیمی بدون شناسنامه

--check ساختار بکاپ قدیمی ZIP/tar.gz را نیز بررسی می‌کند و اعلام می‌کند که inventory چک‌سام ندارد. آرشیوی که backup-runtime.tsv دارد ولی backup-files.sha256 ندارد رد می‌شود، چون هر بکاپ دارای شناسنامه inventory را هم می‌نویسد. --fresh نمی‌تواند نسخه دقیق پنل را از latest یا schema حدس بزند و برای این بکاپ‌ها متوقف می‌شود.

۱. یک کپی را باز کنید و Compose و header فایل SQL را بررسی کنید: -- Server version یا -- Dumped from database version می‌تواند نسخه را نشان دهد.

۲. همان موتور و نسخه دیتابیس و نسخه اصلی پنل، در صورت مشخص‌بودن، را آماده کنید؛ tag دقیق یا digest را در Compose مقصد ثبت کنید.

۳. فایل اصلی دست‌نخورده را با restore معمولی بازگردانی کنید. پس از بررسی عملکرد، بکاپ جدید بگیرید و بعد ارتقا دهید.

فایل ناقص، کلید گم‌شده یا نسخه ناشناخته با حدس‌زدن قابل تضمین نیست. جایگزینی کورکورانه collation/DEFINER یا اجبار نسخه Alembic می‌تواند ناسازگاری را پنهان کند.

TimescaleDB

نسخه افزونه در manifest هر دیتابیس یا db_backup.timescaledb-version ثبت می‌شود. برای تفاوت نسخه، restore معمولی ابتدا تبدیل را در کانتینر موقت انجام می‌دهد. ایمیج سازگاری باید نسخه مبدا و مسیر ارتقای آن را داشته باشد. این قابلیت، downgrade دلخواه PostgreSQL را ممکن نمی‌کند.

اگر نسخه دقیق افزونه در بکاپ قدیمی ثبت نشده، اما آن را می‌دانید:

sudo env TIMESCALEDB_BACKUP_VERSION=2.27.2 \
  pasarguard restore /root/legacy-backup.zip

نمونه برای مقصد PostgreSQL 17 و TimescaleDB 2.28:

sudo env TIMESCALEDB_COMPAT_IMAGE=timescale/timescaledb-ha:pg17-ts2.28-all \
  pasarguard restore /root/backup.zip

نسخه‌ها نمونه هستند؛ مقادیر واقعی مبدا/مقصد را استفاده کنید. شکست تبدیل قبل از import dump ناسازگار باعث توقف می‌شود؛ دیتابیس‌های قبلاً بازیابی‌شده خودکار rollback نمی‌شوند.

فایل چندبخشی و فضای دیسک

همه .part01.zip، .part02.zip و ... را کنار هم بگذارید و مسیر یکی را به restore بدهید. ابزار بخش اول و ترتیب را بررسی و ترکیب می‌کند. هر بخش ZIP مستقل نیست. برای .z01، .z02 و ... فایل نهایی .zip نیز لازم است؛ مسیر .zip یا .zNN قابل استفاده است. نبود بخش میانی باعث توقف می‌شود.

برای ترکیب فایل، استخراج، import و کپی ایمنی فضای کافی لازم است. staging پیش‌فرض کنار آرشیو است؛ برای انتخاب دیسک دیگر:

sudo env RESTORE_TMPDIR=/srv/recovery-staging \
  pasarguard restore /root/backup.zip --fresh

BACKUP_TMPDIR نیز مسیر staging تهیه بکاپ را تعیین می‌کند.

وقتی دسترسی به رجیستری Docker ندارید

پیش از خرابی سرور، ایمیج‌های واقعی را در فایل جداگانه ذخیره کنید:

sudo docker image save -o /root/pasarguard-recovery-images.tar \
  $(sudo docker compose -f /opt/pasarguard/docker-compose.yml -p pasarguard ps -a -q \
    | xargs -r sudo docker inspect --format '{{.Image}}' | sort -u)

این فایل و بسته آفلاین اسکریپت را همراه بکاپ خارج از سرور نگه دارید. روی مقصد که Docker نصب است:

sudo docker image load -i /root/pasarguard-recovery-images.tar
sudo pasarguard restore /root/backup.zip --fresh

image ID اصلی حتی اگر digest رجیستری برنگشته باشد پذیرفته می‌شود. بکاپ دیتابیس شامل ایمیج‌ها، بسته Docker یا بسته اسکریپت نیست؛ بدون آماده‌کردن وابستگی‌ها، بازیابی کاملاً آفلاین تضمین نمی‌شود.

بررسی بعد از بازیابی

  • sudo pasarguard status و sudo pasarguard logs؛ migrationها باید موفق باشند.
  • ورود مدیر، تعداد کاربران، محدودیت/مصرف، اشتراک و اتصال واقعی یک کلاینت.
  • اتصال نودها و کلیدها/گواهی‌ها؛ بکاپ مستر جای بکاپ نود مستقل نیست.
  • اصلاح DNS، فایروال و پورت‌ها در صورت تغییر IP؛ گواهی مختص IP قبلی نیاز به صدور مجدد دارد. تمدید خودکار گواهی را روی مقصد دوباره برقرار کنید.
  • فعال‌بودن بکاپ خارج از سرور و cron؛ cron سیستم‌عامل از آرشیو بازگردانی نمی‌شود.
  • تهیه بکاپ جدید پیش از ارتقا. --fresh ایمیج‌های مبدا را با همان tagهای Compose (مثلاً latest) اجرا می‌کند، پس pasarguard update بعدی ایمیج‌های جدید همان tagها را دریافت می‌کند؛ نسخه ارتقا را آگاهانه انتخاب کنید.

خطاها و محل لاگ

sudo cat /opt/pasarguard/backup/pasarguard_restore_error.log

اگر ساخت پوشه مقصد ممکن باشد، لاگ آنجا ذخیره می‌شود. شکست --check تشخیص را روی خروجی چاپ می‌کند و نصب مقصد ایجاد نمی‌کند. قبل از اشتراک‌گذاری، رمز، توکن و connection string کامل را حذف کنید.

پیام اقدام
checksum نامعتبر یا بخش گم‌شده همه فایل‌های اصلی را دریافت کنید؛ inventory را برای دورزدن خطا تغییر ندهید
ایمیج دقیق موجود نیست ایمیج اصلی را load کنید یا نصب سازگار برای restore معمولی آماده کنید
پوشه/کانتینر/volume موجود restore معمولی یا سرور خالی؛ داده لازم را حذف نکنید
موتور متفاوت یا مقصد قدیمی‌تر ابتدا موتور و نسخه مبدا، سپس ارتقا
شکست تبدیل TimescaleDB نسخه افزونه، ایمیج سازگاری و دسترسی رجیستری را بررسی کنید
Unknown collation یا syntax موتور، سرور و ابزار dump را تطبیق دهید؛ SQL را کورکورانه تغییر ندهید
Access denied رمز واقعی مقصد را با .env تطبیق دهید؛ تغییر .env رمز volume موجود را تغییر نمی‌دهد
دیتابیس آماده نمی‌شود لاگ کانتینر و فضای دیسک را بررسی کنید
migration پنل شکست می‌خورد نسخه اصلی پنل و Alembic را بررسی کنید