آموزش نصب نمایندگی پنل دامنه

پیش‌نیازهای نصب پنل نمایندگی

پیش از شروع نصب، مطمئن شوید به امکانات و اطلاعات زیر دسترسی دارید:

• دسترسی به کنترل‌پنل هاست مانند cPanel یا DirectAdmin
• دسترسی به File Manager یا FTP
• دامنه یا ساب‌دامنه متصل‌شده به هاست
• امکان ساخت دیتابیس MySQL
• دسترسی به phpMyAdmin
• امکان فعال‌سازی گواهی SSL
• دسترسی به تنظیمات API در پنل اصلی نمایندگی
• فایل کامل پکیج نصب پنل نمایندگی

دانلود و آماده‌سازی فایل‌های نصب

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

پکیج نصب معمولاً شامل دو فایل اصلی است:

1. front.zip برای نصب و تنظیم بخش ظاهری یا فرانت‌اند پنل
2. source.zip برای نصب سورس، تنظیمات بک‌اند و اتصال به پایگاه داده

دانلود فایل نصب پنل نمایندگی

مرحله اول: تنظیمات بخش Front پنل نمایندگی

در این مرحله باید فایل‌های مربوط به رابط کاربری پنل را در مسیر عمومی هاست قرار دهید.

آپلود فایل front.zip در public_html

1. وارد کنترل‌پنل هاست خود شوید.
2. بخش File Manager را باز کنید.
3. وارد پوشه public_html شوید.
4. فایل front.zip را داخل این مسیر آپلود کنید. (محتوی درون این پوشه مستقیم در روت اصلی هاست باشد یعنی پوشه public_html)
5. پس از تکمیل آپلود، فایل را انتخاب کرده و روی گزینه Extract کلیک کنید.

تغییر نام فایل index.html-new

اگر پنل را برای اولین‌بار نصب می‌کنید، در پوشه public_html فایل زیر را پیدا کنید:

index.html-new

نام این فایل را به مقدار زیر تغییر دهید:

index.html

تنظیم window.BASE_URL در فایل index.html

فایل index.html را با ویرایشگر فایل هاست باز کرده و عبارت window.BASE_URL را پیدا کنید. سپس دامنه یا ساب‌دامنه پنل خود را به‌شکل زیر وارد نمایید:

window.BASE_URL = 'https://panel.yourdomain.xyz/api/v3';

به‌جای panel.yourdomain.xyz باید آدرس واقعی پنل نمایندگی خود را قرار دهید.

تغییر نام پوشه api-new

در نصب اولیه، پوشه‌ای با نام api-new وجود دارد. نام این پوشه را از:

api-new

به نام زیر تغییر دهید:

api

بررسی فایل‌های index.php

در فایل‌های نصب، معمولاً دو فایل با نام index.php وجود دارد:

• یک فایل در کنار index.html و در مسیر اصلی public_html
• یک فایل دیگر در پوشه api

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

Please check setting

برای برطرف کردن این خطا، فایل index.php را با ویرایشگر باز کرده و کد مربوط به بارگذاری فایل app.php را بررسی کنید:

<?php
$app = require dirname(__DIR__, 2) . '/source/bootstrap/app.php';

با توجه به محل قرارگیری پوشه source، ممکن است لازم باشد عدد موجود در تابع dirname را کم یا زیاد کنید. برای مثال:

<?php
$app = require dirname(__DIR__, 1) . '/source/bootstrap/app.php';

مرحله دوم: نصب و تنظیم فایل Source

پس از تکمیل تنظیمات فرانت‌اند، باید بخش سورس و بک‌اند پنل را نصب کنید. فایل source.zip نباید مستقیماً در مسیر عمومی سایت قرار بگیرد.

محل صحیح آپلود source.zip

فایل source.zip را در مسیر اصلی حساب هاست و یک سطح قبل از پوشه public_html آپلود کنید. ساختار پیشنهادی باید مشابه نمونه زیر باشد:

/home/username/source
/home/username/public_html

پس از آپلود فایل، آن را از حالت فشرده خارج کنید و مطمئن شوید پوشه source در کنار public_html قرار گرفته است.

تغییر نام فایل .env.new

وارد پوشه source شوید و فایل زیر را پیدا کنید:

.env.new

نام این فایل را به مقدار زیر تغییر دهید:

.env

اگر فایل‌های مخفی را مشاهده نمی‌کنید، در تنظیمات File Manager گزینه Show Hidden Files را فعال کنید.

ثبت آدرس پنل در APP_URL

فایل .env را با ویرایشگر باز کرده و در مقابل متغیر APP_URL، آدرس کامل دامنه یا ساب‌دامنه پنل را وارد کنید:

APP_URL=https://panel.yourdomain.xyz

آدرس باید با https:// شروع شود و در این قسمت نیازی به افزودن مسیر /api/v3 نیست.

مرحله سوم: ساخت دیتابیس و اتصال پنل نمایندگی

برای ذخیره اطلاعات پنل، باید یک پایگاه داده MySQL ایجاد کرده و فایل SQL موجود در پکیج را داخل آن وارد کنید.

ایجاد دیتابیس MySQL

1. وارد بخش مدیریت دیتابیس در کنترل‌پنل هاست شوید.
2. یک دیتابیس جدید ایجاد کنید.
3. برای دیتابیس، یک نام کاربری و رمز عبور قوی بسازید.
4. کاربر دیتابیس را به دیتابیس متصل کنید.
5. تمام دسترسی‌های موردنیاز یا All Privileges را فعال نمایید.

ثبت اطلاعات دیتابیس در فایل .env

اطلاعات دیتابیس ساخته‌شده را در فایل .env و مقابل متغیرهای زیر وارد کنید:

DB_DATABASE=database_name
DB_USERNAME=database_username
DB_PASSWORD=database_password

به‌جای مقادیر نمونه، نام دیتابیس، نام کاربری دیتابیس و رمز عبور واقعی را بنویسید.

ایمپورت فایل database.sql در phpMyAdmin

در پوشه source فایلی با نام database.sql وجود دارد. برای ساخت جداول پنل مراحل زیر را انجام دهید:

1. وارد phpMyAdmin شوید.
2. دیتابیس ساخته‌شده را از ستون کناری انتخاب کنید.
3. وارد زبانه Import شوید.
4. فایل database.sql را انتخاب کنید.
5. روی دکمه Import یا Go کلیک نمایید.
6. پس از پایان عملیات، ساخته‌شدن جداول را بررسی کنید.

مرحله چهارم: دریافت و ثبت SPA Token نمایندگی

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

1. وارد پنل اصلی نمایندگی شوید.
2. به مسیر تنظیمات نمایندگی ← API بروید.
3. گزینه ساخت یا ایجاد SPA Token را انتخاب کنید.
4. توکن نمایش‌داده‌شده را بلافاصله کپی و در محل امنی ذخیره نمایید.

پس از دریافت توکن، فایل .env را باز کرده و آن را در مقابل متغیر RESELLER_TOKEN قرار دهید:

RESELLER_TOKEN=your_spa_token

مقدار your_spa_token را با توکن واقعی خود جایگزین کنید.

مرحله پنجم: فعال‌سازی گواهی SSL برای دامنه پنل

برای حفظ امنیت اطلاعات کاربران و برقراری صحیح ارتباط API، باید گواهی SSL را برای دامنه یا ساب‌دامنه پنل فعال کنید.

پس از فعال‌سازی SSL، آدرس پنل باید با پروتکل امن https:// باز شود:

https://panel.yourdomain.xyz

اگر پنل همچنان با HTTP باز می‌شود، تنظیمات ریدایرکت HTTPS، گواهی SSL و اتصال دامنه به هاست را بررسی کنید.

تنظیم پنل نمایندگی روی وب‌سرور Nginx

اگر وب‌سرور هاست شما Nginx باشد، فایل .htaccess به‌صورت مستقیم خوانده نمی‌شود. بنابراین ممکن است صفحه اصلی، مسیرهای داخلی یا درخواست‌های API به‌درستی بارگذاری نشوند.

در این شرایط باید قوانین Rewrite موجود در فایل‌های .htaccess پوشه‌های public_html و api به ساختار قابل‌استفاده در Nginx تبدیل و در تنظیمات سرور ثبت شوند.

تنظیم درگاه پرداخت پنل نمایندگی

پس از نصب کامل پنل و اطمینان از برقراری ارتباط با API، تنظیمات درگاه پرداخت را مطابق راهنمای اختصاصی آن انجام دهید.

مشاهده آموزش تنظیم درگاه پرداخت پنل نمایندگی

رفع خطاهای رایج نصب پنل نمایندگی

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

رفع خطای ۵۰۰ در پنل نمایندگی

خطای ۵۰۰ Internal Server Error معمولاً به تنظیمات PHP، مسیر اشتباه فایل‌های سورس، سطح دسترسی فایل‌ها یا اطلاعات نادرست دیتابیس مربوط است.

برای عیب‌یابی خطای ۵۰۰ موارد زیر را بررسی کنید:

• صحیح‌بودن مسیر پوشه source
• درست‌بودن مقدار dirname در فایل‌های index.php
• صحیح‌بودن اطلاعات دیتابیس در فایل .env
• اتصال کاربر دیتابیس به دیتابیس و فعال‌بودن دسترسی‌ها
• سازگاری نسخه PHP هاست با سورس پنل
• وجود فایل bootstrap/app.php در پوشه source
• سطح دسترسی صحیح فایل‌ها و پوشه‌ها
• گزارش خطاهای ثبت‌شده در Error Log هاست

رفع خطای ۴۰۴ و مشکل htaccess

خطای ۴۰۴ Not Found معمولاً زمانی نمایش داده می‌شود که قوانین بازنویسی آدرس‌ها به‌درستی اجرا نشده باشند.

اگر وب‌سرور هاست شما Apache یا LiteSpeed است، محتوای فایل‌های .htaccess در مسیرهای مربوط را بررسی کرده و در صورت نیاز از قوانین زیر استفاده کنید:

<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews
    </IfModule>

    RewriteEngine On

    # Redirect Trailing Slashes If Not A Folder...
    # RewriteCond %{REQUEST_FILENAME} !-d
    # RewriteRule ^(.*)/$ /$1 [L,R=301]

    # Load Main Page...
    RewriteCond %{REQUEST_URI} ^/$
    RewriteRule ^$ index.html [L]

    # Handle API Requests...
    RewriteCond %{REQUEST_URI} ^/(api|storage) [NC]
    RewriteRule ^(.*)$ index.php [L]

    # Handle Front Controller...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_URI} !^/(api|storage)
    RewriteRule ^(.*)$ index.html [L]
</IfModule>

رفع خطای Please check setting

نمایش پیام Please check setting معمولاً به این معناست که فایل index.php نمی‌تواند فایل اصلی برنامه را در پوشه source پیدا کند.

برای رفع این مشکل:

1. محل قرارگیری پوشه source را بررسی کنید.
2. مطمئن شوید پوشه source یک سطح قبل از public_html قرار دارد.
3. مسیر نوشته‌شده در فایل index.php را بررسی کنید.
4. مقدار عددی تابع dirname را متناسب با ساختار پوشه‌ها تنظیم نمایید.
5. پس از ذخیره تغییرات، کش مرورگر و کش سرور را پاک کنید.

پنل باز می‌شود اما اطلاعات نمایش داده نمی‌شوند

اگر ظاهر پنل بارگذاری می‌شود اما اطلاعات کاربران یا سرویس‌ها نمایش داده نمی‌شوند، موارد زیر را کنترل کنید:

• وجود مسیر /api/v3 در مقدار window.BASE_URL
• صحیح‌بودن دامنه ثبت‌شده در APP_URL
• معتبر بودن مقدار RESELLER_TOKEN
• فعال‌بودن SSL و بازشدن دامنه با HTTPS
• عدم مسدودشدن درخواست‌های API توسط فایروال یا تنظیمات امنیتی هاست
• بررسی خطاهای Console و Network در ابزار توسعه‌دهنده مرورگر

چک‌لیست نهایی راه‌اندازی پنل نمایندگی

قبل از تحویل پنل به کاربران، موارد زیر را یک‌بار بررسی کنید:

• فایل‌های Front در مسیر public_html قرار گرفته‌اند.
• نام فایل index.html-new به index.html تغییر کرده است.
• نام پوشه api-new به api تغییر کرده است.
• مقدار window.BASE_URL همراه با مسیر /api/v3 ثبت شده است.
• پوشه source خارج از public_html قرار دارد.
• فایل .env.new به .env تغییر نام داده شده است.
• آدرس پنل در متغیر APP_URL ثبت شده است.
• اطلاعات دیتابیس در فایل .env صحیح هستند.
• فایل database.sql با موفقیت ایمپورت شده است.
• SPA Token در متغیر RESELLER_TOKEN قرار گرفته است.
• گواهی SSL دامنه فعال است.
• صفحه اصلی و مسیرهای داخلی بدون خطای ۴۰۴ یا ۵۰۰ باز می‌شوند.

سؤالات متداول نصب پنل نمایندگی

جمع‌بندی آموزش نصب پنل نمایندگی

برای راه‌اندازی پنل نمایندگی روی دامنه اختصاصی باید فایل‌های Front را در مسیر public_html و پوشه Source را خارج از مسیر عمومی سایت قرار دهید. پس از آن، تنظیم دامنه، اتصال دیتابیس، ایمپورت فایل SQL، ثبت SPA Token و فعال‌سازی SSL ضروری است.

اگر مراحل نصب به‌ترتیب انجام شوند و مسیر فایل‌ها، اطلاعات دیتابیس و تنظیمات API صحیح باشند، پنل نمایندگی بدون خطا روی دامنه اختصاصی شما اجرا خواهد شد. در صورت مشاهده خطا نیز ابتدا Error Log هاست، فایل .env، قوانین Rewrite و مسیر پوشه source را بررسی کنید.