# نصب پنل CalcGard روی هاست

## ۱. پیش‌نیاز

- دامنه یا زیردامنه با SSL معتبر؛ API دستگاه، آدرس HTTP را قبول نمی‌کند.
- PHP 8.1 یا جدیدتر
- MySQL 8 یا MariaDB 10.5 یا جدیدتر
- افزونه‌های `PDO MySQL`، `OpenSSL`، `JSON` و `mbstring`
- امکان Rewrite در Apache یا تنظیم معادل آن در Nginx

## ۲. آپلود

محتویات پوشه `web` را روی هاست آپلود کنید. امن‌ترین چینش این است که Document Root دامنه/زیردامنه مستقیماً روی پوشه `web/public` باشد. در این حالت فایل تنظیمات و سورس PHP از وب قابل دریافت نیستند.

اگر کنترل Document Root ندارید، کل پوشه `web` را در یک مسیر قرار دهید؛ فایل `.htaccess` درخواست‌ها را به `public` هدایت و دسترسی به `config.php`، دیتابیس و storage را مسدود می‌کند. روی Nginx حتماً همین محدودیت‌ها را دستی اعمال کنید.

## ۳. دیتابیس

از کنترل‌پنل هاست یک دیتابیس و کاربر اختصاصی بسازید. کاربر باید روی همان دیتابیس مجوزهای `CREATE`, `ALTER`, `SELECT`, `INSERT`, `UPDATE`, `DELETE` و `INDEX` داشته باشد.

## ۴. نصب تحت وب

آدرس پنل را در مرورگر باز کنید. فرم نصب نمایش داده می‌شود:

1. آدرس دقیق HTTPS پنل را وارد کنید؛ اگر پنل داخل زیرپوشه است همان زیرپوشه نیز باید در URL باشد.
2. اطلاعات MySQL را وارد کنید.
3. یک نام کاربری و رمز حداقل ۱۰ کاراکتری برای مدیر کل بسازید.
4. «نصب امن CalcGard» را بزنید.

نصب‌کننده جداول را ایجاد، `web/config.php` را با کلید رمزنگاری تصادفی تولید و فایل `storage/installed.lock` را ثبت می‌کند.

## ۵. دسترسی فایل‌ها

- پوشه `storage` باید برای PHP قابل نوشتن باشد؛ معمولاً `0750` یا `0770` کافی است.
- فایل `config.php` بهتر است `0600` یا در هاست اشتراکی `0640` باشد.
- هرگز `config.php`، نسخه پشتیبان دیتابیس یا keystore اندروید را داخل پوشه public قرار ندهید.

## ۶. آزمایش سلامت

آدرس زیر باید JSON نسخه را نمایش دهد:

```text
https://YOUR-DOMAIN/health
```

سپس وارد پنل شوید، یک کسب‌وکار بسازید و API Key نمایش‌داده‌شده را ذخیره کنید. کلید کامل بعداً قابل مشاهده نیست و فقط می‌توان آن را تعویض کرد.

پس از اولین ورود، از «حساب کاربری» رمز اولیه را تغییر دهید. مشتری هر کسب‌وکار نیز می‌تواند رمز خودش را بدون دسترسی به حساب‌های دیگر تغییر دهد.

## ۷. پشتیبان‌گیری و به‌روزرسانی

- روزانه از دیتابیس و `config.php` نسخه پشتیبان رمزگذاری‌شده بگیرید.
- هنگام به‌روزرسانی، `config.php` و پوشه `storage` را جایگزین نکنید.
- قبل از هر تغییر، نسخه staging را آزمایش کنید.

## رفع اشکال سریع

- خطای 404 همه مسیرها: Rewrite یا AllowOverride هاست فعال نیست.
- خطای اتصال دیتابیس: نام دیتابیس در هاست‌های اشتراکی معمولاً پیشوند نام کاربری دارد.
- خطای نصب درباره نوشتن فایل: مجوز پوشه `web` و `storage` را بررسی کنید.
- وب‌هوک ارسال نمی‌شود: URL باید HTTPS عمومی باشد؛ آدرس localhost و شبکه خصوصی عمداً رد می‌شود.