ifnex/DEPLOYMENT.md

📦 راهنمای دپلوی IFNEX Logistics Platform

راهنمای کامل انتقال پروژه از محیط توسعه (XAMPP) به سرور Production

نسخه: 1.0.0
تاریخ: 2026-08-10
نویسنده: تیم توسعه IFNEX

---

📋 فهرست مطالب

1. پیش‌نیازهای سرور
2. ساختار پروژه
3. دپلوی Laravel (Backend)
4. دپلوی WordPress (Frontend)
5. اتصال دو سیستم (Bridge)
6. تنظیمات امنیتی
7. Cron Jobs
8. Backup Strategy
9. چک‌لیست نهایی
10. Troubleshooting

---

۱. پیش‌نیازهای سرور

حداقل نیازمندی‌ها

مورد	حداقل	پیشنهادی
PHP	8.2	8.3
MySQL	8.0	8.0+
RAM	2GB	4GB
Disk	20GB SSD	50GB NVMe
Web Server	Apache 2.4 / Nginx 1.24	Nginx

افزونه‌های PHP مورد نیاز

php -m | grep -E "pdo_mysql|mbstring|openssl|tokenizer|xml|ctype|json|bcmath|gd|zip|curl|intl"

لیست کامل:

• pdo_mysql - اتصال به MySQL
• mbstring - پشتیبانی UTF-8 (فارسی)
• openssl - رمزنگاری
• tokenizer - Laravel
• xml - Laravel
• ctype - Laravel
• json - Laravel
• bcmath - محاسبات مالی
• gd یا imagick - پردازش تصویر
• zip - Composer
• curl - درخواست‌های HTTP
• intl - تاریخ شمسی (Jalali)

نصب Composer و Node

# Composer
curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer

# بررسی نسخه
composer --version

---

۲. ساختار پروژه

IFNEX-Logistics/
├── 01_WordPress/          # (قدیمی - قابل حذف بعد از مهاجرت)
├── 03_WordPress/          # ✅ وردپرس اصلی (Frontend مشتری)
│   └── wp-content/
│       ├── plugins/
│       │   └── ifnex-bridge/    # ✅ پلاگین اتصال به Laravel
│       └── themes/
│           └── ifnex/           # ✅ قالب اختصاصی
├── 04_Laravel/            # ✅ Laravel (Backend + پنل ادمین)
│   ├── app/
│   ├── database/
│   ├── public/            # Document root برای Laravel
│   └── routes/
└── DEPLOYMENT.md          # این فایل

Document Roots روی سرور

دامنه	مسیر
ifnex.com	/var/www/IFNEX/03_WordPress
api.ifnex.com یا ifnex.com/api	/var/www/IFNEX/04_Laravel/public

---

۳. دپلوی Laravel (Backend)

گام ۱: آپلود فایل‌ها

# از سیستم محلی به سرور
scp -r 04_Laravel user@server:/var/www/IFNEX/

# یا با rsync (پیشنهادی)
rsync -avz --exclude 'vendor' --exclude 'node_modules' \
  04_Laravel/ user@server:/var/www/IFNEX/04_Laravel/

گام ۲: نصب Dependencies

cd /var/www/IFNEX/04_Laravel

# نصب بدون dev packages (برای production)
composer install --optimize-autoloader --no-dev --no-interaction

گام ۳: تنظیم .env

فایل .env را برای production تنظیم کن:

# ─── تنظیمات پایه ───────────────────────────
APP_NAME="IFNEX Logistics"
APP_ENV=production
APP_KEY=base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
APP_DEBUG=false
APP_URL=https://api.ifnex.com

# ─── دیتابیس ─────────────────────────────────
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=ifnex_laravel
DB_USERNAME=ifnex_user
DB_PASSWORD=StrongPassword@123

# ─── Session و Cache ─────────────────────────
SESSION_DRIVER=database
CACHE_STORE=redis
QUEUE_CONNECTION=database

# ─── Sanctum ─────────────────────────────────
SANCTUM_STATEFUL_DOMAINS=ifnex.com,www.ifnex.com
SESSION_DOMAIN=.ifnex.com

# ─── IFNEX Bridge ────────────────────────────
# ⚠️ مهم: این کلید باید با وردپرس یکسان باشد
IFNEX_BRIDGE_API_KEY=your-very-strong-random-key-here

# ─── Zarinpal ────────────────────────────────
ZARINPAL_MERCHANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ZARINPAL_SANDBOX=false

# ─── Mail ────────────────────────────────────
MAIL_MAILER=smtp
MAIL_HOST=smtp.ifnex.com
MAIL_PORT=587
MAIL_USERNAME=noreply@ifnex.com
MAIL_PASSWORD=xxxxx
MAIL_ENCRYPTION=tls

تولید کلید امن:

php artisan key:generate --show
openssl rand -hex 32   # برای BRIDGE_API_KEY

گام ۴: ساخت دیتابیس

mysql -u root -p

CREATE DATABASE ifnex_laravel CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'ifnex_user'@'localhost' IDENTIFIED BY 'StrongPassword@123';
GRANT ALL PRIVILEGES ON ifnex_laravel.* TO 'ifnex_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

گام ۵: Import دیتابیس از توسعه

# از سیستم محلی (XAMPP)
mysqldump -u root ifnex_laravel > ifnex_backup.sql

# آپلود به سرور
scp ifnex_backup.sql user@server:/tmp/

# Import روی سرور
mysql -u ifnex_user -p ifnex_laravel < /tmp/ifnex_backup.sql

گام ۶: Migrations و Cache

cd /var/www/IFNEX/04_Laravel

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

# Seed داده‌های اولیه (نرخ ارز، zones، ...)
php artisan db:seed --class=SampleShippingRatesSeeder --force

# ساخت cache ها برای سرعت
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache

# Permissions
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

گام ۷: تنظیم Nginx

فایل /etc/nginx/sites-available/ifnex-api:

server {
    listen 80;
    server_name api.ifnex.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.ifnex.com;

    root /var/www/IFNEX/04_Laravel/public;
    index index.php;

    # SSL
    ssl_certificate /etc/letsencrypt/live/api.ifnex.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.ifnex.com/privkey.pem;

    # Security headers
    add_header X-Frame-Options SAMEORIGIN;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";

    # Upload limits
    client_max_body_size 50M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # مسدود کردن فایل‌های حساس
    location ~ /\.(env|git) {
        deny all;
    }
}

فعال‌سازی:

ln -s /etc/nginx/sites-available/ifnex-api /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

گام ۸: SSL رایگان با Let's Encrypt

apt install certbot python3-certbot-nginx
certbot --nginx -d api.ifnex.com

---

۴. دپلوی WordPress (Frontend)

گام ۱: آپلود فایل‌ها

rsync -avz --exclude 'wp-content/uploads' \
  03_WordPress/ user@server:/var/www/IFNEX/03_WordPress/

گام ۲: تنظیم wp-config.php

<?php
// ─── دیتابیس ─────────────────────────────
define('DB_NAME', 'ifnex_wp');
define('DB_USER', 'ifnex_wp_user');
define('DB_PASSWORD', 'StrongPassword@456');
define('DB_HOST', 'localhost');
define('DB_CHARSET', 'utf8mb4');

// ─── کلیدهای امنیتی ──────────────────────
// از https://api.wordpress.org/secret-key/1.1/salt/ بگیرید
define('AUTH_KEY',         'xxxxx');
define('SECURE_AUTH_KEY',  'xxxxx');
define('LOGGED_IN_KEY',    'xxxxx');
define('NONCE_KEY',        'xxxxx');

// ─── Production ──────────────────────────
define('WP_DEBUG', false);
define('WP_DEBUG_LOG', false);
define('WP_DEBUG_DISPLAY', false);
define('SCRIPT_DEBUG', false);

// ─── Performance ─────────────────────────
define('WP_CACHE', true);

define('ABSPATH', __DIR__ . '/');
require_once ABSPATH . 'wp-settings.php';

گام ۳: Import دیتابیس وردپرس

mysqldump -u root ifnexwp > ifnexwp_backup.sql
scp ifnexwp_backup.sql user@server:/tmp/
mysql -u ifnex_wp_user -p ifnex_wp < /tmp/ifnexwp_backup.sql

اصلاح URLها در دیتابیس:

UPDATE wp_options SET option_value = 'https://ifnex.com' 
WHERE option_name IN ('siteurl', 'home');

UPDATE wp_posts SET post_content = REPLACE(post_content, 
  'http://localhost/IFNEX-Logistics/03_WordPress', 'https://ifnex.com');

گام ۴: تنظیم Nginx برای وردپرس

فایل /etc/nginx/sites-available/ifnex-wp:

server {
    listen 443 ssl http2;
    server_name ifnex.com www.ifnex.com;

    root /var/www/IFNEX/03_WordPress;
    index index.php;

    ssl_certificate /etc/letsencrypt/live/ifnex.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ifnex.com/privkey.pem;

    client_max_body_size 50M;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # کش فایل‌های استاتیک
    location ~* \.(jpg|jpeg|png|gif|css|js|svg|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    location ~ /\.(env|git) {
        deny all;
    }
}

گام ۵: Permissions

chown -R www-data:www-data /var/www/IFNEX/03_WordPress
find /var/www/IFNEX/03_WordPress -type d -exec chmod 755 {} \;
find /var/www/IFNEX/03_WordPress -type f -exec chmod 644 {} \;
chmod -R 775 /var/www/IFNEX/03_WordPress/wp-content/uploads

---

۵. اتصال دو سیستم (Bridge)

گام ۱: تنظیم پلاگین IFNEX Bridge

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

فیلد	مقدار
API URL	https://api.ifnex.com/api/v1
API Key	(کلید عمومی از Laravel)
Bridge API Key	(همان مقدار .env لاراول)

گام ۲: بررسی اتصال

در وردپرس یک صفحه تست بساز با شورت‌کد:

[ifnex_wallet_balance]

اگر موجودی نمایش داده شد، اتصال برقرار است. ✅

گام ۳: Sync کاربران

cd /var/www/IFNEX/04_Laravel
php artisan ifnex:sync-wp-users \
  --wp-db-name=ifnex_wp \
  --wp-db-user=ifnex_wp_user \
  --wp-db-pass=StrongPassword@456

---

۶. تنظیمات امنیتی

چک‌لیست امنیتی

• APP_DEBUG=false در Laravel
• WP_DEBUG=false در WordPress
• SSL فعال روی هر دو دامنه
• فایل‌های .env و .git مسدود شده‌اند
• رمزهای قوی برای دیتابیس
• IFNEX_BRIDGE_API_KEY قوی و تصادفی
• حذف فایل‌های debug از production:

  rm -f debug-payment.php check-*.php test-*.php
  

• محدودیت دسترسی به /admin (اختیاری: IP whitelist)

Firewall (UFW)

ufw allow 22/tcp    # SSH
ufw allow 80/tcp    # HTTP
ufw allow 443/tcp   # HTTPS
ufw enable

---

۷. Cron Jobs

Laravel Scheduler

crontab -e

* * * * * cd /var/www/IFNEX/04_Laravel && php artisan schedule:run >> /dev/null 2>&1

Cron آپدیت نرخ ارز (هر ساعت)

اگر از scheduler استفاده نمی‌کنید:

0 * * * * cd /var/www/IFNEX/04_Laravel && php artisan ifnex:update-rates >> /dev/null 2>&1

Cron Backup روزانه (ساعت ۲ بامداد)

0 2 * * * /var/www/IFNEX/scripts/backup.sh >> /var/log/ifnex-backup.log 2>&1

---

۸. Backup Strategy

اسکریپت backup.sh

فایل /var/www/IFNEX/scripts/backup.sh:

#!/bin/bash
# ─── IFNEX Backup Script ───────────────────

BACKUP_DIR="/var/backups/ifnex"
DATE=$(date +%Y%m%d_%H%M%S)
RETENTION_DAYS=7

mkdir -p $BACKUP_DIR

# Backup دیتابیس Laravel
mysqldump -u ifnex_user -p'StrongPassword@123' ifnex_laravel \
  | gzip > $BACKUP_DIR/laravel_$DATE.sql.gz

# Backup دیتابیس WordPress
mysqldump -u ifnex_wp_user -p'StrongPassword@456' ifnex_wp \
  | gzip > $BACKUP_DIR/wordpress_$DATE.sql.gz

# Backup فایل‌های آپلود وردپرس
tar -czf $BACKUP_DIR/uploads_$DATE.tar.gz \
  -C /var/www/IFNEX/03_WordPress/wp-content uploads

# حذف backup های قدیمی
find $BACKUP_DIR -name "*.gz" -mtime +$RETENTION_DAYS -delete

echo "✅ Backup completed: $DATE"

اجرا:

chmod +x /var/www/IFNEX/scripts/backup.sh

---

۹. چک‌لیست نهایی

قبل از Go-Live

Laravel:

• php artisan migrate --force بدون خطا
• php artisan config:cache موفق
• ورود به /admin با ادمین
• داشبورد بدون خطا لود می‌شود
• ویجت‌های نرخ ارز نمایش داده می‌شوند

WordPress:

• صفحه اصلی بدون خطا
• ورود مشتری کار می‌کند
• /new-order/ فرم را نمایش می‌دهد
• /my-orders/ لیست سفارشات را نشان می‌دهد
• تست کامل: ثبت سفارش → پرداخت → تغییر status

اتصال:

• Bridge API Key یکسان در هر دو طرف
• تست پرداخت از کیف پول موفق
• Tracking event ثبت می‌شود

بعد از Go-Live

• مانیتورینگ لاگ‌ها:

  tail -f /var/www/IFNEX/04_Laravel/storage/logs/laravel.log
  

• بررسی cron jobs: crontab -l
• تست backup و restore

---

۱۰. Troubleshooting

مشکل: خطای 500 در Laravel

# بررسی لاگ
tail -100 storage/logs/laravel.log

# پاک کردن cache
php artisan config:clear
php artisan cache:clear

# بررسی permissions
chmod -R 775 storage bootstrap/cache

مشکل: وردپرس به Laravel وصل نمی‌شود

# تست اتصال از سرور وردپرس
curl -X POST https://api.ifnex.com/api/v1/bridge/login \
  -H "Content-Type: application/json" \
  -d '{"bridge_api_key":"YOUR_KEY","wp_user_id":1,"wp_user_email":"test@test.com"}'

مشکل: خطای "توکن احراز هویت یافت نشد"

1. بررسی کنید کاربر در Laravel وجود دارد (sync شده)
2. توکن‌های قدیمی را پاک کنید:

   DELETE FROM wp_usermeta WHERE meta_key LIKE 'ifnex_laravel%';
   

3. دوباره لاگین کنید

مشکل: SSL certificate error

certbot renew --dry-run
certbot renew

مشکل: خطای CORS

در config/cors.php لاراول:

'paths' => ['api/*', 'sanctum/csrf-cookie'],
'allowed_origins' => ['https://ifnex.com', 'https://www.ifnex.com'],

---

📞 پشتیبانی

در صورت بروز مشکل:

• ایمیل: dev@ifnex.com
• مستندات Laravel: https://laravel.com/docs
• مستندات WordPress: https://wordpress.org/documentation/

---

پایان راهنمای دپلوی
🎉 موفق باشید!