مستنداتبخش برنامه نویسانراهنمای عیب‌یابی و حل خطاهای رایج

راهنمای عیب‌یابی و پرسش‌های متداول (Troubleshooting & FAQ)

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

۱. خطای CORS در درخواست‌های بین سرویس‌ها

اگر با خطای Access-Control-Allow-Origin در مرورگر مواجه شدید، مقادیر متغیرهای STORE_CORS و AUTH_CORS را در .env چک کنید:

.env

env

STORE_CORS=http://localhost:8000,https://store.yourdomain.com
ADMIN_CORS=http://localhost:9000,https://api.yourdomain.com
AUTH_CORS=http://localhost:8000,http://localhost:9000,https://store.yourdomain.com

۲. عدم نمایش محصولات در فرانت‌اند (Publishable API Key)

علت اصلی عدم نمایش محصولات

پس از ساخت Publishable Key در پنل Medusa (آدرس http://localhost:9000/app)، حتماً باید وارد کلید شده و در تب Sales Channels، آن را به Default Sales Channel متصل نمایید.

۳. عدم رندر سواچ‌های رنگی یا مشکل فیلتر رنگ

دقت کنید عنوان کلید اپشن رنگ در Medusa حتماً color یا Color باشد. برای ترجمه نام آن به زبان‌های مختلف (انگلیسی، فارسی، عربی، آلمانی و ...) از Strapi استفاده کنید تا کلید اصلی رزرو شده تغییر نکند.

۴. اتمام RAM و Crash کردن سرور هنگام Build داکر

از دستورات استقرار فازبندی شده (Phased Deployment) استفاده کنید و در صورت نیاز حافظه مجازی Swap روی لینوکس فعال نمایید:

ایجاد 4GB Swap حافظه روی Ubuntu

bash

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

۵. افزودن استایل‌های جدید در سرور زنده (پروداکشن)

برای افزودن یا حذف استایل‌ها در پروداکشن، هیچ نیازی به لاگین SSH به سرور یا اجرای دستورات ترمینال نیست. کافی است وارد پنل ادمین Strapi > منوی Storefront Management شوید، استایل مورد نظر را انتخاب کرده و دکمه Update Storefront را بزنید. گیت‌هاب اکشن به صورت خودکار استایل را دانلود کرده، کامیت می‌زند و روی سرور شما مستقر می‌کند.

جریان کاری خودکار

bash

پنل استراپی (Storefront Management) -> گیت‌هاب اکشن -> بیلد و دیپلوی خودکار روی VPS

۶. خطای دسترسی داکر (docker.sock Permission Denied)

روی سرور تازه لینوکس ممکن است با خطای عدم دسترسی به داکر روبرو شوید. کاربر لینوکس خود را به گروه docker اضافه کنید:

رفع خطای دسترسی داکر

bash

sudo groupadd docker 2>/dev/null || true
sudo usermod -aG docker $USER
newgrp docker
docker ps

۷. لوپ لاگین یا صفحه سفید پنل ادمین Medusa

لوپ لاگین: مطمئن شوید MEDUSA_NODE_ENV=production است. در صورت استفاده از IP و HTTP ساده (پروفایل A)، مقدار MEDUSA_ALLOW_HTTP_COOKIES=true را بگذارید. برای HTTPS مقدار را false قرار دهید.

صفحه سفید: هرگز در داکر از MEDUSA_NODE_ENV=development استفاده نکنید؛ زیرا پنل ادمین به صورت پروداکشن بیلد شده است.

تنظیمات محیطی مدوسا

env

MEDUSA_NODE_ENV=production
MEDUSA_ALLOW_HTTP_COOKIES=false # یا true برای پروفایل A با HTTP ساده