ابتدا محیط سازگار با بکاپ را بازیابی کنید و بعد از سالمشدن پنل، ارتقا دهید. نصب جدیدترین پنل و دیتابیس همیشه برای بازیابی یک بکاپ قدیمی مناسب نیست.
بکاپ تهیهشده با اسکریپت جدید را روی سرور لینوکسی جدید قرار دهید؛ مثلاً
/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 میتواند ناسازگاری را پنهان کند.
نسخه افزونه در 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 --freshBACKUP_TMPDIR نیز مسیر staging تهیه بکاپ را تعیین میکند.
پیش از خرابی سرور، ایمیجهای واقعی را در فایل جداگانه ذخیره کنید:
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 --freshimage 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 را بررسی کنید |