Laravel Backup Kit

بکاپ رمزنگاری‌شده و پایش‌شونده‌ی دیتابیس برای Laravel، روی هر ذخیره‌ساز سازگار با S3 (پیش‌فرض: ArvanCloud). ساخته‌شده روی spatie/laravel-backup.

پکیج را نصب می‌کنید، چند متغیر .env می‌گذارید و بقیه خودکار است: بکاپ شبانه، آرشیو AES-256، چیدمان تاریخ‌دار، تاریخچه‌ی اجراها، heartbeat به مانیتور مرکزی، هشدار و صفحه‌ی عیب‌یابی storage.

فهرست

• امکانات
• نیازمندی‌ها
• نصب سریع
• پیکربندی
• نحوه‌ی کار
• دستورها
• زمان‌بندی
• وضعیت سلامت و heartbeat
• بکاپ ساعتی جدول‌های حیاتی (hot backup)
• هشدار ایمیلی
• صفحه‌ی تست storage
• Retention
• Restore
• بکاپ پیش از دیپلوی (Deployer)
• امنیت
• عیب‌یابی
• مهاجرت از پیاده‌سازی داخلی پروژه
• توسعه و تست
• مجوز

امکانات

• بکاپ شبانه‌ی فقط دیتابیس (فایل‌های پروژه هرگز بکاپ نمی‌شوند) در قالب zip با رمزنگاری AES-256.
• چیدمان تاریخ‌دار روی باکت: <project>/YYYY/MM/DD/<timestamp>.zip؛ چند پروژه می‌توانند یک باکت مشترک داشته باشند.
• تاریخچه‌ی اجراها در جدول backup_runs برای هر backup، cleanup و hot.
• وضعیت سلامت پنج‌حالته (SUCCESS، FAILED، STORAGE_ERROR، NEVER_RUN، STALE) و دستور backup:status با exit code مناسب cron و alerting.
• Heartbeat اختیاری به مانیتور مرکزی؛ بعد از هر شکست هم بلافاصله ارسال می‌شود.
• Hot backup ساعتی فقط برای جدول‌های حیاتی (اختیاری).
• ایمیل هشدار اختیاری، لاگ اختصاصی backup و پیام‌های خطای sanitize‌شده (بدون secret).
• صفحه‌ی تست storage برای عیب‌یابی اتصال به باکت.
• زمان‌بندی و پیکربندی خودکار؛ هر دو قابل خاموش‌شدن‌اند.

نیازمندی‌ها

• PHP ^8.3 با اکستنشن zip
• Laravel ^12.40 یا ^13.0
• spatie/laravel-backup ^10.3 و league/flysystem-aws-s3-v3 (همراه پکیج نصب می‌شوند)
• باینری dump دیتابیس روی سرور (مثلاً mysqldump یا mariadb-dump) روی PATH یا از طریق DB_DUMP_BINARY_PATH
• Scheduler لاراول فعال: * * * * * php /path/to/artisan schedule:run >> /dev/null 2>&1

نصب سریع

composer require utab/laravel-backup-kit
php artisan backup-kit:install
php artisan migrate

backup-kit:install فایل‌های config/backup-kit.php و config/backup.php (تنظیمات آماده‌ی Spatie) را publish می‌کند. فایل‌های موجود دست‌نخورده می‌مانند، مگر با --force. معادل دستی:

php artisan vendor:publish --tag=backup-kit-config
php artisan vendor:publish --tag=backup-kit-spatie-config
php artisan vendor:publish --tag=backup-kit-migrations   # فقط اگر migration را خودتان نگه می‌دارید

حداقل متغیرهای .env:

BACKUP_PROJECT=my-project              # پوشه‌ی ریشه‌ی این پروژه روی باکت (پیش‌فرض: APP_NAME)، در باکت مشترک یکتا باشد
BACKUP_ARCHIVE_PASSWORD=               # رمز AES-256 آرشیو، الزامی
ARVAN_ACCESS_KEY=
ARVAN_SECRET_KEY=
ARVAN_BUCKET=
ARVAN_ENDPOINT=https://s3.ir-central1.arvanstorage.ir   # بدون نام باکت در host

بعد از تنظیم، نصب را بررسی کنید:

php artisan backup:status          # دیسک reachable است؟
php artisan backup:run --only-db   # اولین بکاپ دستی
php artisan backup:status          # باید SUCCESS شود

اگر از قبل config/backup.php دارید و می‌خواهید نگهش دارید: source.files.include باید خالی باشد، password و encryption => 'aes256' تنظیم شود، destination.disks شامل BACKUP_DISK باشد و backup.name همان BACKUP_PROJECT باشد. ساده‌ترین راه شروع از stub پکیج است.

پیکربندی

همه‌ی تنظیمات پکیج در config/backup-kit.php است و تقریباً همه از .env خوانده می‌شوند. تنظیمات Spatie (retention، health checkها، notifications) در config/backup.php می‌مانند.

متغیرهای محیطی

ذخیره‌سازی و هویت پروژه

Dump دیتابیس

زمان‌بندی، مانیتور و hot backup

صفحه‌ی تست، لاگ، retention و اعلان

تنظیم خودکار (auto-configure)

پکیج در boot این سه مورد را تعریف می‌کند، هرکدام فقط اگر اپ خودش تعریفش نکرده باشد:

• دیسک S3 با نام BACKUP_DISK که از متغیرهای ARVAN_* تغذیه می‌شود.
• کانال لاگ backup (روزانه، فایل storage/logs/backup-YYYY-MM-DD.log).
• تنظیمات dump روی اتصال‌های دیتابیس لیست‌شده در backup.source.databases (single-transaction، timeout، exclude tables، مسیر باینری). رمز دیتابیس از طریق فایل defaults موقت به mysqldump می‌رسد و روی خط فرمان نمی‌آید.

هرکدام با backup-kit.auto_configure.{disk,log_channel,dump}.enabled خاموش می‌شود. تعریف‌ها داخل فایل config هستند، پس php artisan config:cache آن‌ها را هم cache می‌کند. برای سفارشی‌سازی (مثلاً دیسک غیر Arvan) کافی است دیسک را خودتان در config/filesystems.php تعریف کنید.

نحوه‌ی کار

php artisan backup:run --only-db   (زمان‌بندی‌شده، ۰۲:۳۰)
        │
        ▼
dump.sql ──► ZIP (AES-256 + BACKUP_ARCHIVE_PASSWORD) ──► verify
        │
        ▼
<ARVAN_BUCKET>/<BACKUP_PROJECT>/YYYY/MM/DD/<timestamp>.zip
        │
        ├── backup_runs (DB)  ──► SUCCESS / FAILED / STORAGE_ERROR / NEVER_RUN / STALE
        └── heartbeat ──► BACKUP_MONITOR_URL (اختیاری)

• مسیر تاریخ‌دار هنگام زمان‌بندی با --destination-path به backup:run داده می‌شود. Listener MoveBackupToDatedFolder روی رویداد BackupWasSuccessful هر آرشیو flat را (از جمله اجراهای دستی) به Y/m/d منتقل می‌کند؛ idempotent است و فایل موجود را overwrite نمی‌کند.
• Listener RecordBackupRunEvents بعد از جابه‌جایی، اجرا را در backup_runs ثبت و heartbeat را ارسال می‌کند. خطای ثبت یا مانیتور هرگز pipeline بکاپ را نمی‌شکند.
• پیام خطا قبل از ذخیره یا لاگ از BackupErrorSanitizer عبور می‌کند.

دستورها

دستورهای خود Spatie هم کار می‌کنند: backup:run، backup:clean، backup:list و backup:monitor.

php artisan backup:run --only-db
php artisan backup:list
php artisan backup:clean

# destination-path کاملاً جای نام پروژه می‌نشیند: پیشوند پروژه را خودتان بدهید
php artisan backup:run --only-db --destination-path="my-project/manual/$(date +%Y/%m/%d)"

زمان‌بندی

مگر با BACKUP_SCHEDULE_ENABLED=false، چهار ورودی روی scheduler اپ ثبت می‌شود. همه با withoutOverlapping() و بر اساس timezone اپ اجرا می‌شوند:

مقدار نامعتبر هرگز scheduler را خراب نمی‌کند: ساعت بدفرمت به پیش‌فرض برمی‌گردد، ساعت‌های hot به بازه‌ی ۰ تا ۲۳ محدود می‌شوند و فاصله‌ی heartbeat به ۱ تا ۵۹ دقیقه. اگر BACKUP_HOT_FROM_HOUR بزرگ‌تر از BACKUP_HOT_TO_HOUR باشد، ورودی hot کلاً اجرا نمی‌شود (بازه‌ی شبانه‌روزی پشتیبانی نمی‌شود).

اگر زمان‌بندی را خودتان می‌خواهید (BACKUP_SCHEDULE_ENABLED=false):

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('backup:run', ['--only-db'])->dailyAt('02:30')->withoutOverlapping();
Schedule::command('backup:clean')->dailyAt('04:00')->withoutOverlapping();
Schedule::command('backup:report')->everyFifteenMinutes();

وضعیت سلامت و heartbeat

اولویت: STORAGE_ERROR ← FAILED ← STALE ← NEVER_RUN ← SUCCESS. فقط اجراهای نوع backup در وضعیت اصلی حساب می‌شوند؛ اجراهای cleanup و hot آن را خراب نمی‌کنند.

اگر BACKUP_MONITOR_URL تنظیم باشد، پکیج heartbeat را هر چند دقیقه، بعد از هر رویداد پایانی بکاپ و بلافاصله بعد از هر شکست hot ارسال می‌کند:

POST {BACKUP_MONITOR_URL} با هدر Authorization: Bearer {BACKUP_MONITOR_TOKEN} و بدنه‌ی JSON:

{
  "project": "my-project",
  "environment": "production",
  "status": "SUCCESS",
  "detail": "Last backup completed successfully.",
  "checked_at": "2026-10-06T15:00:00+03:30",
  "last_run_at": "2026-10-06T02:30:04+03:30",
  "last_success_at": "2026-10-06T02:30:58+03:30",
  "last_backup_path": "my-project/2026/10/06/2026-10-06-02-30-00.zip",
  "last_backup_size_bytes": 12345678,
  "disk": "arvan-backup",
  "consecutive_failures": 0,
  "hot": {
    "status": "success",
    "last_run_at": "2026-10-06T15:00:03+03:30",
    "last_success_at": "2026-10-06T15:00:03+03:30",
    "last_path": "hot-my-project/2026/10/06/2026-10-06-15-00-03-hot.zip",
    "last_size_bytes": 54210,
    "consecutive_failures": 0
  },
  "meta": { "php": "8.4.0", "laravel": "13.0.0" }
}

برای دیدن payload بدون ارسال: php artisan backup:report --dry-run. کلاینت مانیتور هرگز exception پرتاب نمی‌کند؛ خرابی مانیتور فقط یک warning در لاگ backup است.

بکاپ ساعتی جدول‌های حیاتی (hot backup)

برای داده‌ی جایگزین‌ناپذیر (سفارش‌ها، کیف پول، کاربران، نقش‌ها و دسترسی‌ها و...)، فول‌دامپ شبانه RPO یک روزه دارد. Hot backup هر ساعت در بازه‌ی کاری فقط همین جدول‌ها را dump می‌کند؛ آرشیو بسیار کوچک است و RPO داده‌ی حیاتی به یک ساعت می‌رسد. این قابلیت تا وقتی جدول‌ها را تنظیم نکنید خاموش است:

BACKUP_HOT_TABLES=orders,wallet_transactions,users

hot-<BACKUP_PROJECT>/YYYY/MM/DD/<timestamp>-hot.zip     ← AES-256، روی همان دیسک

• چرا hot-<project>/ در ریشه؟ Retention پکیج Spatie لیست allFiles(<project>) را prefix-match می‌کند. اگر آرشیو hot داخل <project>/ یا <project>-hot/ بود، keep-daily ممکن بود یک zip کوچک hot را به‌جای فول‌دامپ نگه دارد. پیشوند hot- این تداخل را می‌شکند.
• Retention جدا: بعد از هر اجرای موفق، آرشیوهای قدیمی‌تر از BACKUP_HOT_KEEP_DAYS حذف می‌شوند.
• ثبت: در backup_runs با type = 'hot'؛ وضعیت اصلی بکاپ را تغییر نمی‌دهد. وضعیت مستقل آن در بلوک hot heartbeat است: disabled | never_run | success | failed | storage_error | stale. وضعیت stale وابسته به بازه‌ی کاری است: داخل بازه، آخرین موفقیت باید کمتر از ۲ ساعت قبل باشد؛ بیرون بازه کافی است آخرین اسلات دیروز اجرا شده باشد.
• هشدار: شکست در لاگ ثبت می‌شود، heartbeat فوری می‌رود و (اگر ایمیل فعال باشد) فقط در اولین شکستِ هر دنباله ایمیل می‌رسد؛ اولین موفقیت بعدی دنباله را ریست می‌کند.
• اتصال: از اولین اتصال backup.source.databases (یا database.default) استفاده می‌شود و فایل داخل zip با نام db-dumps/<db>-hot.sql ذخیره می‌شود.
• اگر BACKUP_ARCHIVE_PASSWORD تنظیم نباشد، آرشیو hot بدون رمز نوشته می‌شود و یک warning در لاگ می‌آید.

هشدار ایمیلی

ایمیل اختیاری است و با تنظیم BACKUP_NOTIFICATION_MAIL_TO روشن می‌شود. آن‌وقت اعلان‌های شکست Spatie (BackupHasFailed، CleanupHasFailed، UnhealthyBackupWasFound) و اعلان HotBackupFailed پکیج به آن آدرس می‌روند. بدون این متغیر، heartbeat تنها منبع حقیقت است. فرستنده از MAIL_FROM_ADDRESS و MAIL_FROM_NAME خوانده می‌شود.

صفحه‌ی تست storage

GET /backup-storage-test سه پروب روی دیسک بکاپ اجرا می‌کند و خطای دقیقِ sanitize‌شده را نشان می‌دهد:

1. کامل‌بودن تنظیمات دیسک (برای دیسک s3: key، secret، endpoint و bucket)
2. files() روی پوشه‌ی پروژه (احراز هویت و خواندن)
3. round-trip put / get / delete (دسترسی نوشتن)

خروجی HTML است؛ با Accept: application/json پاسخ JSON می‌دهد. در موفقیت 200 و در شکست 503 برمی‌گرداند.

• Local: بدون توکن باز است.
• غیر Local: فقط با ?token= برابر BACKUP_DEBUG_TOKEN (در نبود آن BACKUP_MONITOR_TOKEN)؛ در غیر این صورت 404. اگر هیچ توکنی تنظیم نشده باشد، همیشه 404.
• access key و secret هرگز چاپ نمی‌شوند؛ فقط set (N chars) یا MISSING دیده می‌شود. برای دیسک‌های غیر s3 فقط وجود تعریف دیسک بررسی می‌شود.

curl -H "Accept: application/json" "https://example.com/backup-storage-test?token=$BACKUP_DEBUG_TOKEN"

مسیر، middleware و روشن/خاموش‌بودن route در config/backup-kit.php است:

'routes' => [
    'storage_test' => [
        'enabled' => env('BACKUP_STORAGE_TEST_ENABLED', true),
        'path' => env('BACKUP_STORAGE_TEST_PATH', 'backup-storage-test'),
        'middleware' => ['web'],
    ],
],

نام route برابر backup-kit.storage-test است.

Retention

Cleanup با DefaultStrategy پکیج Spatie انجام می‌شود و جدیدترین بکاپ همیشه نگه داشته می‌شود. بازه‌ها با متغیرهای BACKUP_KEEP_* و BACKUP_MAX_STORAGE_MB (جدول بالا) تنظیم می‌شوند. Cleanup روی پوشه‌ی پروژه recursive کار می‌کند، پس فایل‌های داخل Y/m/d و pre-deploy/ هم پوشش داده می‌شوند. آرشیوهای hot retention جدا دارند (BACKUP_HOT_KEEP_DAYS).

Restore

جدول‌های DB_DUMP_EXCLUDE_TABLES در dump نیستند و بعد از restore ساخته نمی‌شوند؛ باید با migration یا دستی دوباره ساخته شوند.

۱. آرشیو را پیدا و دانلود کنید:

php artisan backup:list
aws --endpoint-url "$ARVAN_ENDPOINT" s3 ls "s3://$ARVAN_BUCKET/my-project/" --recursive
aws --endpoint-url "$ARVAN_ENDPOINT" s3 cp \
  "s3://$ARVAN_BUCKET/my-project/2026/10/06/2026-10-06-02-30-00.zip" backup.zip

۲. رمزگشایی: unzip معمولی AES-256 را نمی‌فهمد؛ از 7-Zip (لینوکس: 7zz یا p7zip) یا PHP استفاده کنید:

7z x -p"$BACKUP_ARCHIVE_PASSWORD" backup.zip -o./restore-tmp

$zip = new ZipArchive;
$zip->open('backup.zip', ZipArchive::RDONLY);
$zip->setPassword(getenv('BACKUP_ARCHIVE_PASSWORD'));
$zip->extractTo('./restore-tmp');
$zip->close();

۳. دیتابیس را روی یک دیتابیس جدید یا staging بازیابی کنید، نه مستقیم روی production:

mysql -h <host> -u <user> -p <database> < ./restore-tmp/db-dumps/mysql-<database>.sql

۴. بعد از restore، تعداد ردیف‌های جدول‌های کلیدی را بررسی کنید و مطمئن شوید اپ بالا می‌آید (php artisan about).

Restore از hot backup: ابتدا فول‌دامپ شب را restore کنید، سپس آخرین آرشیو hot را با همان روش باز کنید و db-dumps/<db>-hot.sql را import کنید. این کار روی جدول‌های موجود overwrite می‌کند (mysqldump به‌صورت پیش‌فرض DROP TABLE IF EXISTS دارد، پس schema هم درست می‌شود).

بکاپ پیش از دیپلوی (Deployer)

پکیج هیچ کدی برای Deployer ندارد و deployer/deployer وابستگی آن نیست. اگر دیپلوی شما با Deployer انجام می‌شود، این تسک قبل از migration یک dump تازه از release فعلی (current، یعنی کد و .env که می‌دانید کار می‌کند) روی باکت می‌گذارد تا یک migration خراب هرگز بدون snapshot اجرا نشود:

<?php

namespace Deployer;

desc('Pre-deploy database backup (deploy aborts on failure)');
task('backup:pre-deploy', function () {
    if (getenv('DEPLOY_SKIP_BACKUP')) {
        writeln('<comment>DEPLOY_SKIP_BACKUP set, skipping pre-deploy backup</comment>');

        return;
    }

    // --destination-path replaces the backup name entirely, so the project
    // prefix must be part of it: {{application}} has to equal BACKUP_PROJECT.
    run('cd {{current_path}} && {{bin/php}} artisan backup:run --only-db --destination-path="{{application}}/pre-deploy/$(date +%Y/%m/%d)"');
});

before('artisan:migrate', 'backup:pre-deploy');

• آرشیو در <project>/pre-deploy/YYYY/MM/DD/ می‌نشیند و زیر retention عادی است.
• اگر بکاپ شکست بخورد، دستور run خطا می‌دهد و دیپلوی متوقف می‌شود.
• دور زدن فقط برای اورژانس: DEPLOY_SKIP_BACKUP=1. در اولین دیپلوی هم release current وجود ندارد و باید از همین متغیر استفاده کنید.

امنیت

• credentialها فقط از .env خوانده می‌شوند و هیچ‌جا چاپ نمی‌شوند.
• پیام خطا قبل از ذخیره در backup_runs.error_summary یا لاگ: فقط خط اول، کوتاه‌شده، با حذف password= / token= / secret= / key= و mask کردن secretهای جاری config (دیتابیس، S3، رمز آرشیو، توکن مانیتور؛ حداقل ۸ کاراکتر).
• رمز دیتابیس از طریق فایل defaults موقت به mysqldump می‌رسد و در argv یا لیست پردازه‌ها دیده نمی‌شود.
• رمز آرشیو را در یک secret store نگه دارید. هر آرشیو با رمزِ زمان ساختش رمز می‌شود؛ هنگام تغییر رمز، رمز قبلی را تا حذف شدن آرشیوهای قدیمی نگه دارید، وگرنه آن‌ها قابل بازیابی نیستند.
• توکن صفحه‌ی تست storage در URL می‌آید و ممکن است در access logها بماند؛ آن را دوره‌ای عوض کنید یا اگر لازم نیست BACKUP_STORAGE_TEST_ENABLED=false بگذارید.
• کلید S3 را فقط به باکت (و در صورت امکان پیشوند) بکاپ محدود کنید؛ دسترسی list، put، get و delete کافی است (delete برای cleanup لازم است).
• آدرس مانیتور را فقط HTTPS بدهید؛ توکن به‌صورت Bearer ارسال می‌شود.

عیب‌یابی

مهاجرت از پیاده‌سازی داخلی پروژه

اگر پروژه‌ای همین pipeline را به‌صورت کد داخلی دارد، با نصب پکیج این جایگزینی‌ها لازم است:

Migration پکیج idempotent است: اگر جدول backup_runs از قبل وجود داشته باشد، دست‌نخورده می‌ماند. کد داخلی (provider، commandها، listenerها، controller و route) را بعد از اطمینان از کارکرد پکیج حذف کنید.

توسعه و تست

composer install
composer test    # Pest روی Orchestra Testbench؛ نیازی به S3 یا شبکه ندارد
composer lint    # Laravel Pint در حالت --test

تست‌ها دیسک و HTTP را با Storage::fake و Http::fake شبیه‌سازی می‌کنند.

مجوز

MIT. متن کامل در فایل LICENSE.