مستندات

میزبانی شخصی

استقرار

اجرای آواتارک روی سرور خودتان با Docker: تنظیمات، HTTPS، ایمیل، CDN، پشتیبان‌گیری و به‌روزرسانی.

مخزن یک استک آماده‌ی تولید دارد: nginx، PHP-FPM، صف (queue worker)، زمان‌بند (scheduler)، MySQL و Redis، که با Docker Compose به هم وصل شده‌اند. یک سرور لینوکسی با Docker، یک دامنه و یک حساب SMTP برای ایمیل لازم دارید.

این راهنما با فایل‌های داخل مخزن (Dockerfile، docker-compose.yml، پوشه‌ی docker/ و .env.production.example) یکی است. یک‌بار آن‌ها را بخوانید؛ کوتاه‌اند.

۱. اولین راه‌اندازی

git clone https://github.com/avatarak/avatarak.git && cd avatarak
cp .env.production.example .env

فایل .env را ویرایش کنید. هرچه با !!! علامت خورده باید عوض شود: آدرس عمومی (APP_URL)، گذرواژه‌های دیتابیس و تنظیمات SMTP. کلید برنامه را بسازید:

docker compose run --rm app php artisan key:generate --show      # نتیجه را در APP_KEY بگذارید
docker compose up -d --build
docker compose exec app php artisan admin:create you@example.com

کانتینر برنامه در هر راه‌اندازی مایگریشن‌ها را اجرا می‌کند و تنظیمات را کش می‌کند. استک روی پورت 8080 گوش می‌دهد (WEB_PORT در .env).

۲. HTTPS

جلوی پورت 8080 چیزی بگذارید که TLS را تمام کند. ساده‌ترینش Caddy است که گواهی را خودش می‌گیرد:

avatarak.ir {
    reverse_proxy 127.0.0.1:8080
}

Nginx با certbot، Traefik، لود بالانسر ابری یا Cloudflare هم همین‌قدر خوب‌اند. تا وقتی برنامه فقط از طریق همان پروکسی در دسترس است، TRUSTED_PROXIES=* را در .env نگه دارید؛ همین باعث می‌شود لینک‌ها، QRها و کوکی‌ها https باشند و آدرس واقعی بازدیدکننده ثبت شود. اگر پورت 8080 به اینترنت هم باز است، به‌جایش آدرس پروکسی را بنویسید (TRUSTED_PROXIES=10.0.0.0/8) یا پورت را ببندید.

۳. ایمیل

کد ورود و پیام تأیید ایمیل واقعی هستند و از طریق صف فرستاده می‌شوند. MAIL_* را در .env پر کنید و بعد امتحان کنید:

docker compose exec app php artisan mail:test you@example.com

این دستور یک پیام را همان لحظه می‌فرستد و اگر مشکلی باشد می‌گوید چیست. از دامنه‌ی ارسالی با SPF و DKIM استفاده کنید، وگرنه پیام‌ها به اسپم می‌روند. صف را با docker compose logs -f queue ببینید.

۴. تلگرام و گیت‌هاب (اختیاری)

خط‌های TELEGRAM_* و GITHUB_* را در .env پر کنید و docker compose up -d بزنید. روی سرور واقعی از وب‌هوک استفاده کنید، نه poll:

docker compose exec app php artisan telegram:webhook

جزئیات در حساب‌های تأییدشده است.

۵. CDN

آواتار پرترافیک‌ترین آدرس است و برای کش شدن ساخته شده: کوکی ندارد، ETag و Cache-Control دارد و CORS باز است. سه لایه وجود دارد:

  • مرورگر عکس را AVATAR_MAX_AGE ثانیه نگه می‌دارد (پیش‌فرض یک ساعت).
  • nginx همراه پروژه ۶۰ ثانیه یک نسخه نگه می‌دارد، پس یک موج درخواست یکسان یک‌بار به PHP می‌رسد.
  • CDN (کلودفلر، آروان‌کلاود، Bunny و…) جلوی دامنه بیشترین بار را می‌گیرد. با AVATAR_S_MAXAGE (ثانیه؛ در نمونه 600) از طریق s-maxage عمر جدا برای کش‌های مشترک بگذارید.

عکس عوض‌شده همان آدرس را دارد، پس CDN ممکن است تا AVATAR_S_MAXAGE ثانیه عکس قدیمی را نشان بدهد. برای همین عدد دقیقه است، نه روز؛ اگر لازم شد آدرس را دستی purge کنید. تصویرهای پیش‌فرضِ ساخته‌شده هرگز s-maxage نمی‌گیرند.

دو نکته‌ی عملی. فرمت (WebP یا JPEG) به هدر Accept بستگی دارد (Vary: Accept)، پس تنظیمی از CDN را انتخاب کنید که Vary را رعایت می‌کند، یا فقط JPEG را کش کنید. و /admin، /account و /login را کش نکنید: پویا و خصوصی‌اند.

دامنه‌ی اختصاصی و HTTPS

دامنه‌ی مشتری‌ها هرکدام گواهی لازم دارند. با Caddy خودکار است (on-demand TLS): Caddy قبل از گرفتن گواهی از برنامه می‌پرسد که واقعاً به آن دامنه سرویس می‌دهد یا نه.

{
    on_demand_tls { ask http://127.0.0.1:8080/_internal/domain-check?key=YOUR_DOMAIN_CHECK_KEY }
}
avatarak.ir { reverse_proxy 127.0.0.1:8080 }
https:// {
    tls { on_demand }
    reverse_proxy 127.0.0.1:8080
}

DOMAIN_CHECK_KEY (یک رشته‌ی تصادفی بلند) و CUSTOM_DOMAIN_TARGET (مثلاً domains.avatarak.ir، یک نام DNS که به سرور شما اشاره می‌کند) را در .env بگذارید. بدون کلید، آدرس بررسی خاموش است و هیچ گواهی صادر نمی‌شود. فقط دامنه‌های تأییدشده‌ای را تأیید می‌کند که صاحبشان هنوز پلنِ دارای دامنه‌ی اختصاصی دارد و مسدود نیست.

۶. پشتیبان‌گیری

docker compose exec app php artisan backup:run

فایل storage/app/backups/avatarak-YYYY-MM-DD_HHMMSS.zip را می‌سازد: یک نسخه‌ی دیتابیس به‌علاوه‌ی همه‌ی عکس‌ها و تصویرهای بندانگشتی، و جدیدترین BACKUP_KEEP تا (۱۴) را نگه می‌دارد. زمان‌بند هر شب ساعت ۰۲:۳۰ آن را اجرا می‌کند. BACKUP_DISK را روی یک دیسک سازگار با S3 بگذارید تا نسخه‌ها بیرون از سرور هم باشند؛ پشتیبانی که روی همان ماشین است با از دست رفتن آن ماشین از بین می‌رود.

برای بازیابی روی یک نصب تازه: فایل را باز کنید، database.sql را وارد کنید (mysql avatarak < database.sql) و پوشه‌ی files/ را داخل storage/app/ کپی کنید. یک‌بار بازیابی را امتحان کنید، قبل از اینکه لازمش شود.

۷. به‌روزرسانی

git pull
docker compose up -d --build

مایگریشن‌ها خودکار اجرا می‌شوند و صف و زمان‌بند با کد جدید دوباره بالا می‌آیند. قبلش یک backup:run بزنید.

پایش

/up تا وقتی پردازش زنده است 200 می‌دهد. /up/ready علاوه بر آن دیتابیس، کش و ذخیره‌سازی فایل را هم بررسی می‌کند و در صورت مشکل 503 می‌دهد و فقط نام بخش خراب را می‌نویسد. مانیتور آنلاین بودن را روی /up/ready بگذارید. داشبورد مدیریت هم برای تنظیمات اشتباهِ سرور واقعی هشدار نشان می‌دهد.

فهرست قبل از انتشار

  • LEGAL_ENTITY و LEGAL_CONTACT_EMAIL پر شده‌اند و یک وکیل /terms و /privacy را خوانده (متن‌ها در resources/legal/ هستند).
  • ADMIN_REQUIRE_2FA=true است و همه‌ی مدیران ورود دومرحله‌ای را فعال کرده‌اند.
  • APP_DEBUG=false، یک APP_URL واقعی با https و یک APP_KEY یکتا (از آن نسخه نگه دارید؛ گم شدنش نشست‌ها را باطل می‌کند).
  • mail:test موفق است و ایمیل ثبت‌نام در یک صندوق واقعی می‌رسد.
  • backup:run کار می‌کند و یک نسخه جایی غیر از سرور هست.
  • کانتینرهای صف و زمان‌بند بالا هستند (docker compose ps).
  • فقط پورت‌های ۸۰ و ۴۴۳ به اینترنت باز است.