ifnex/DEPLOYMENT.md

راهنمای استقرار IFNEX

آخرین بروزرسانی: 2026-09-03

---

محیط‌ها

محیط	دامنه	نقش
Production	api.ifnex.vernahost.ir (دامنه اختصاصی آینده: system.ifnex.ir)	API لاراول
Production	ifnex.vernahost.ir (دامنه اختصاصی آینده: ifnex.ir)	وب‌سایت وردپرس
Local	localhost:8000	توسعه

---

پیش‌نیازها

• SSH دسترسی به سرور
• HestiaCP (مدیریت سرور)
• Git روی سرور
• Composer روی سرور (اختیاری — بهتره locallly نصب کنی)

---

۱. استقرار لاراول

۱.۱ کلون مخزن روی سرور

cd /home/USER/web/api.ifnex.vernahost.ir/public_html
git clone https://www.git.vernahost.ir/gitmodir110/ifnex.git .

اگر پوشه لاراول زیرمسیر 04_Laravel/ هست:

cd /home/USER/web/api.ifnex.vernahost.ir/public_html
git clone https://www.git.vernahost.ir/gitmodir110/ifnex.git tmp-ifnex
cp -r tmp-ifnex/04_Laravel/* .
cp -r tmp-ifnex/04_Laravel/.* . 2>/dev/null
rm -rf tmp-ifnex

۱.۲ نصب وابستگی‌ها

cd /home/USER/web/api.ifnex.vernahost.ir/public_html
composer install --no-dev --optimize-autoloader

۱.۳ تنظیم .env

cp .env.example .env
nano .env

مقادیر مهم:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://system.ifnex.ir

DB_HOST=localhost
DB_DATABASE=ifnex_db
DB_USERNAME=ifnex_user
DB_PASSWORD=STRONG_PASSWORD

# مهم: هر دو کلید باید با مقادیر وردپرس یکسان باشند و پیش از استقرار
# با یک رشته تصادفی جایگزین شوند (مثلاً: openssl rand -hex 32)
IFNEX_API_KEY=change-this-secret-key
IFNEX_BRIDGE_API_KEY=change-this-secret-key

CORS_ALLOWED_ORIGINS=https://ifnex.ir

# Payment Gateway
ZARINPAL_SANDBOX=false
ZARINPAL_MERCHANT_ID=YOUR_REAL_MERCHANT_ID
ZARINPAL_CALLBACK_URL=https://system.ifnex.ir/api/v1/payment/callback
ZARINPAL_FRONTEND_FAILURE_URL=https://ifnex.ir/wallet

# Kavenegar — کلید نهایی از پنل ادمین تنظیم می‌شود، نه از این فایل
KAVENEGAR_API_KEY=
KAVENEGAR_SENDER=

🔐 نکتهٔ امنیتی: مقدار change-this-secret-key عمداً انتخاب شده است، چون BridgeAuthController دقیقاً همین مقدار را رد می‌کند و خطای ۵۰۰ می‌دهد — یعنی اگر جایگزینی فراموش شود، سیستم بی‌سروصدا کار نمی‌کند. هر مقدار دیگری (حتی مواردی که شبیه placeholder باشند) به‌عنوان یک کلید معتبر پذیرفته می‌شود.

⚠️ اگر کلیدی قبلاً در این مخزن یا در .env اشتراکی ثبت شده، آن را لو‌رفته فرض کنید و حتماً چرخش دهید.

📱 نکتهٔ ZARINPAL_FRONTEND_SUCCESS_URL: این کلید در کد خوانده نمی‌شود. ریدایرکت بعد از پرداخت موفق از طریق frontend_callback که وردپرس در هر درخواست پرداخت ارسال می‌کند تعیین می‌شود؛ فقط ZARINPAL_FRONTEND_FAILURE_URL به‌عنوان fallback استفاده می‌شود.

📱 نکتهٔ SMS: سرویس پیامک از تنظیمات پنل ادمین (Filament → تنظیمات سیستم → SystemSetting) خوانده می‌شود: kavenegar_api_key و سوییچ‌های kavenegar_send_* برای هر نوع اعلان. مقداردهی این متغیرها در .env کافی نیست.

۱.۴ دیتابیس

# ایجاد دیتابیس (اگر وجود نداره)
mysql -u root -p -e "CREATE DATABASE ifnex_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# اجرای migrations
php artisan migrate --force

# اجرای seeders (فقط بار اول)
php artisan db:seed --force

۱.۵ پیکربندی نهایی

php artisan storage:link
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan filament:clear-cached-components

۱.۶ آپلود تعهدنامه‌ها و دیسک امن

فایل‌های آپلودی مشتری (تعهدنامه‌های امضاشده) روی دیسک secure در storage/app/secure ذخیره می‌شوند و URL عمومی ندارند — فقط از طریق روت‌های محافظت‌شده (/api/v1/customer/... و /admin/shipments/...) سرو می‌شوند:

# مسیر دیسک امن باید قابل نوشتن باشد
mkdir -p storage/app/secure && chmod -R 775 storage

محدودیت آپلود PHP سرور باید با اعتبارسنجی اپلیکیشن (۵ مگابایت) همخوان باشد — در php.ini مربوط به PHP-FPM:

upload_max_filesize = 8M
post_max_size = 8M

---

۲. استقرار وردپرس (پلاگین و قالب)

۲.۱ آپلود فایل‌ها

# قالب IFNEX
cd /home/USER/web/ifnex.vernahost.ir/public_html/wp-content/themes/
# فایل‌های قالب را اینجا آپلود/بروزرسانی کن

# پلاگین IFNEX Bridge
cd /home/USER/web/ifnex.vernahost.ir/public_html/wp-content/plugins/
# فایل‌های پلاگین را اینجا آپلود/بروزرسانی کن

۲.۲ تنظیم پلاگین

در پیشخوان وردپرس → تنظیمات → IFNEX Bridge:

تنظیم	مقدار
API URL	https://api.ifnex.vernahost.ir/api/v1
API Key (عمومی)	برای APIهای عمومی مثل Tracking (همان IFNEX_API_KEY در .env لاراول)
Bridge API Key	کلید مشترک بین وردپرس و لاراول (همان IFNEX_BRIDGE_API_KEY در .env لاراول)

⚠️ مهم: Bridge API Key باید در لاراول (.env) و وردپرس (پنل تنظیمات پلاگین) دقیقاً یکسان باشد. در غیر این صورت، کاربران وردپرس نمی‌توانند توکن Sanctum دریافت کنند.

۲.۳ صفحات مورد نیاز در وردپرس

این صفحات باید با شورت‌کدهای مشخص ساخته شوند:

آدرس	شورت‌کد	توضیح
/my-account/	[ifnex_customer_dashboard]	پنل جامع مشتری
/my-orders/	[ifnex_orders_list]	لیست سفارشات
/new-order/	[ifnex_order_form]	فرم ثبت سفارش
/order-detail/	[ifnex_order_detail]	جزئیات سفارش
/order-payment/	[ifnex_order_payment]	صفحه پرداخت
/wallet/	[ifnex_wallet_charge]	شارژ کیف پول
/tracking/	[ifnex_tracking_form]	رهگیری مرسوله

---

۳. بروزرسانی (بعد از تغییرات جدید)

۳.۱ لاراول

cd /home/USER/web/api.ifnex.vernahost.ir/public_html

# خاموش کردن موقت سایت
php artisan down

# بکاپ
cp .env .env.backup

# دریافت تغییرات
git fetch --all
git pull origin main

# وابستگی‌ها (اگه composer.json تغییر کرده)
composer install --no-dev --optimize-autoloader

# مایگریشن‌های جدید
php artisan migrate --force

# پاک‌سازی کش
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear
php artisan filament:clear-cached-components

# کش مجدد
php artisan config:cache
php artisan route:cache
php artisan view:cache

# روشن کردن سایت
php artisan up

۳.۲ وردپرس

cd /home/USER/web/ifnex.vernahost.ir/public_html/wp-content/plugins/ifnex-bridge
git pull origin main

اگر پلاگین از طریق گیت کلون نشده، فایل‌ها را دستی آپلود کن.

---

۴. تنظیمات Cron

crontab -e

# به‌روزرسانی نرخ ارز
0 0 * * * cd /home/USER/web/api.ifnex.vernahost.ir/public_html && php artisan ifnex:update-rates --source=freecurrencyapi >> /dev/null 2>&1

---

۵. عیب‌یابی

بررسی لاگ‌ها

# لاگ لاراول
tail -f /home/USER/web/api.ifnex.vernahost.ir/public_html/storage/logs/laravel.log

# لاگ HestiaCP
tail -f /var/log/hestia.log

کلیر کش

php artisan optimize:clear

بررسی وضعیت

php artisan about
php artisan route:list --path=api/v1

---

۶. نکات امنیتی

• .env هرگز در گیت کامیت نشود (در .gitignore باشد)
• APP_DEBUG=false در Production
• CORS_ALLOWED_ORIGINS فقط دامنه وردپرس
• IFNEX_API_KEY یک کلید قوی و تصادفی باشد
• IFNEX_BRIDGE_API_KEY یک کلید قوی و تصادفی باشد (متفاوت از API Key)
• SSL/HTTPS فعال باشد
• دسترسی پوشه storage و bootstrap/cache قابل نوشتن باشد (۷۷۵)
• درگاه Zarinpal در Production باید SANDBOX=false و MERCHANT_ID واقعی باشد

---

© 2026 VernaSoft Group. Internal use only.