۱. انواع خطا و نحوه خواندن آن‌ها

خطاهای موتور در سه قالب نمایش داده می‌شوند. تشخیص قالب خطا، نیمی از راه عیب‌یابی است:

نکته: در ناحیه مدیریت، نمایش خطاهای PHP فعال است تا عیب‌یابی ساده‌تر شود؛ رفتار طبیعی است و به معنای خرابی نیست. در محیط عمومی، نمایش خطا معمولاً توسط هاست خاموش است و خطای PHP به شکل صفحه سفید دیده می‌شود.

۲. خطای ماژول

پیام: «امکان اجرای وب‌سایت موتور وجود ندارد. ماژول‌های ضروری … در دسترس نیست.»

این صفحه فقط در نخستین اجرای موتور (پیش از ایجاد فایل تنظیمات) نمایش داده می‌شود و فهرست ماژول‌های گمشده را نام می‌برد. فهرست کامل نیازمندی‌ها و تفکیک ضروری/شرطی: راهنمای «راه‌اندازی»، بخش ۲. دو ماژول شرطی — curl و Zip — در این صفحه بررسی نمی‌شوند و نبودشان در جای خود (نصب پوسته، درگاه پرداخت) با پیام جداگانه مشخص می‌شود. نبود ماژول GD هم با کارنشدن کد امنیتی و بندانگشتی خود را نشان می‌دهد.

رفع خطا بر اساس نوع میزبانی

هاست اشتراکی (cPanel): وارد کنترل‌پنل شوید؛ از بخش Select PHP Version (یا PHP Options) تیک ماژول‌های مورد نیاز را بزنید. تغییرات معمولاً بلافاصله اعمال می‌شود.

هاست اشتراکی (DirectAdmin): از مسیر PHP Settings → Extensions ماژول‌ها را فعال کنید.

سرور مجازی یا اختصاصی لینوکس: بسته‌های ماژول را با مدیر بسته توزیع نصب کنید:

# Ubuntu / Debian
sudo apt install php8.2-curl php8.2-gd php8.2-sqlite3 php8.2-mbstring
sudo systemctl restart apache2        # یا php8.2-fpm

# CentOS / AlmaLinux / Rocky
sudo dnf install php-curl php-gd php-pdo php-mbstring
sudo systemctl restart php-fpm

ماژول نصب است ولی غیرفعال: فایل php.ini را ویرایش و علامت ; را از ابتدای سطر مربوطه حذف کنید:

extension=curl
extension=gd
extension=pdo_sqlite
extension=mbstring

سپس وب‌سرور را ری‌استارت کنید.

بدون دسترسی به هیچ‌کدام: از پشتیبانی شرکت هاستینگ درخواست نصب یا فعال‌سازی ماژول‌ها را داشته باشید.

بررسی نتیجه

پس از اعمال تغییرات، فعال بودن ماژول‌ها را با یکی از دو روش بررسی کنید:

• فایلی حاوی کد زیر بسازید، آن را روی سایت بارگذاری و در مرورگر باز کنید؛ و در خروجی، نام ماژول‌ها را جستجو کنید. پس از بررسی، فایل را حذف کنید.

<?php phpinfo();

• در خط فرمان سرور: php -m — فهرست ماژول‌های فعال را چاپ می‌کند.

نکته درباره GD: برای ساخت تصویر کد امنیتی، GD باید همراه کتابخانه FreeType کامپایل شده باشد؛ و برای پشتیبانی از تصاویر AVIF، همراه libavif. نبود FreeType رایج‌ترین علت «نمایان نشدن تصویر کد امنیتی» است.

۳. خطاهای نصب و پیکربندی سرور

صفحه اصلی باز می‌شود اما همه نشانی‌های دیگر خطای 404 می‌دهند

علت: ارجاع درخواست‌ها به index.php انجام نمی‌شود؛ یعنی ماژول mod_rewrite خاموش است یا وب‌سرور اجازه اجرای .htaccess (AllowOverride) نمی‌دهد.

راه‌حل: در سرور اختصاصی:

sudo a2enmod rewrite
# در پیکربندی VirtualHost:  AllowOverride All
sudo systemctl restart apache2

در هاست اشتراکی معمولاً نیازی به اقدام نیست؛ اگر مشکل داشتید با پشتیبانی هاست مطرح کنید.

تنظیمات ذخیره نمی‌شود، تصویر آپلود نمی‌شود یا عملیات فایل شکست می‌خورد

علت: نبود مجوز نوشتن PHP روی پوشه‌ها و فایل‌ها.

راه‌حل: برای data و images و themes و ریشه سایت، مجوز نوشتن تنظیم شود (معمولاً 755 برای پوشه‌ها و 644 برای فایل‌ها). اگر پایگاه داده یا فایلی را بیرون از ناحیه مدیریت (مثلاً با FTP) ویرایش و آپلود کرده‌اید، مالکیت فایل ممکن است با کاربر اجرای PHP یکی نباشد؛ فایل را از طریق «مدیریت پرونده» دوباره بارگذاری کنید یا مالکیت را اصلاح کنید.

صفحه سفید در همان ابتدای نصب

• نسخه PHP قدیمی: حداقل نسخه 7.3 است؛ از کنترل‌پنل ارتقا دهید.
• فایل ناقص بارگذاری شده: انتقال index.php نیمه‌کاره مانده یا در حالت متنی (به‌جای باینری) آپلود شده است. اندازه فایل را با نسخه اصلی مقایسه و دوباره بارگذاری کنید.

تصویر کد امنیتی نمایش داده نمی‌شود

علت: ماژول GD غیرفعال است یا همراه FreeType کامپایل نشده (بخش ۲).

مدیریت باز نمی‌شود یا بخش‌های آن بی‌عملکردند

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

راه‌حل: دسترسی سرور به static.websitemotor.com را بررسی کنید؛ در صورت محدودیت پایدار، فایل اسکریپت را روی سایت خود جایگزین نشانی بارگذاری‌شده کنید.

۴. خطاهای پوسته

«پوسته‌ای تنظیم نشده است.»

علت: هنوز هیچ پوسته‌ای نصب و فعال نشده است، یا پوسته فعال حذف شده است. برای نمایش محتوای سایت، نصب و فعال‌کردن پوسته ضروری است.

راه‌حل: از طریق بخش «پوسته» در ناحیه مدیریت، پوسته دلخواه را از مخزن انتخاب یا فایل فشرده آن را بارگذاری کنید. اگر پوسته را با FTP در پوشه themes بارگذاری کرده‌اید، از بخش «پوسته» فعالش کنید؛ ویرایش مستقیم فایل data/setting.json و تنظیم ردیف theme برابر نام پوسته هم امکان‌پذیر است. تعدادی پوسته در مخزن وب‌سایت موتور موجود است.

«خطا در دسترسی به پرونده پوسته» — پرونده پوسته یافت نشد!

پیام، نام فایل یافت‌نشده را نشان می‌دهد.

خطاهای نصب پوسته

۵. خطا در پردازش پرونده تنظیمات

پیام: «پرونده setting.json خراب است.»

علت: فایل data/setting.json — که همه تنظیمات سایت در آن است — ساختار JSON معتبر ندارد؛ معمولاً به‌سبب ویرایش دستی نادرست (کامای اضافی، نقل‌قول ناقص، قطع شدن در حین ذخیره).

راه‌حل به ترتیب:

1. اگر پشتیبان دارید، آخرین نسخه سالم را بازگردانید.
2. فایل را با یک اعتبارسنج JSON بررسی و خطای ساختاری را اصلاح کنید.
3. در نبود پشتیبان: محتوای فایل را بررسی کنید — بخش‌های خراب (مثل اسکریپت یک روش پرداخت که ویرایشش JSON را شکسته) را اصلاح یا حذف کنید. حذف یک کلید، فقط همان تنظیم را به پیش‌فرض برمی‌گرداند و محتوا دست‌نخورده می‌ماند.

⚠ هشدار: تغییر نام کامل این فایل، باعث اجرای فرآیند راه‌اندازی مجدد می‌شود و کاربران قبلی حذف می‌شوند — فقط به‌عنوان آخرین راهکار فراموشی رمز و با احتیاط (راهنمای «ناحیه مدیریت»، بخش ۱). آن را با «خراب بودن» اشتباه نگیرید: در خرابی، نام فایل را تغییر ندهید؛ محتوایش را اصلاح کنید.

۶. ایمیل بازنشانی ارسال نشد

پیام: «ایمیل بازنشانی ارسال نشد.» (در صفحه ورود به مدیریت، پس از درخواست بازنشانی رمز)

علت: موتور برای ارسال ایمیل از تابع mail() هاست استفاده می‌کند و SMTP ندارد. کارنکردن این تابع — به‌دلیل پیکربندی هاست، محدودیت ارسال، یا رسیدن به پوشه هرزنامه — رایج است. اگر ایمیل را دریافت نکرده‌اید، ابتدا پوشه هرزنامه (Spam) را بررسی کنید. در غیر این صورت، رمز با یکی از سه راهکار زیر بازنشانی می‌شود:

راه اول — ویرایش پایگاه کاربران از طریق ناحیه مدیریت

اگر کاربری با سطح مدیر به بخش مدیریت پرونده برسد، می‌تواند با زدن کلید ویرایش در ردیف فایل data/users.sqlite، رمز دیگری جایگزین رمز فراموش‌شده کند. برای این منظور عبارت زیر را در فرم بالای صفحه ویرایش وارد و کلید Run را بزنید. شماره کاربری — که در جدول ستون اول است — را جایگزین عدد ۲ کنید:

UPDATE users SET user_pass='827ccb0eea8a706c4c34a16891f84e7b' WHERE user_id=2;

با این کار رمز 12345 به‌عنوان رمز ورود جدید برای کاربر تعیین‌شده ثبت می‌شود. عبارت بالا، درهم‌ساخت (hash) رمز 12345 است. موتور رمزها را با درهم‌سازی MD5 و بدون افزوده ذخیره می‌کند؛ بنابراین برای رمزهای ساده‌تر می‌توان به جداول بازیابی MD5 نیز مراجعه کرد. پس از ورود، رمز را فوراً عوض کنید.

راه دوم — ویرایش پایگاه بدون دسترسی به ناحیه مدیریت

با دسترسی FTP، فایل data/users.sqlite را دریافت و مشابه روش قبل ویرایش و باز بارگذاری کنید. مثلاً در ویندوز با نرم‌افزارهایی از نوع SQLite مثل SQLite Database Browser، یا در اندروید با برنامه‌های مشابه SQLite Editor.

راه سوم — راه‌اندازی مجدد سایت

نام فایل data/setting.json را موقتاً تغییر دهید (مثلاً setting-original.json). با مراجعه به نشانی سایت، فرآیند راه‌اندازی — تعیین نام سایت و رمز عبور — از نو انجام می‌شود. پس از تعیین رمز جدید، فایل setting.json جدیدی که ساخته شده را حذف و نام فایل اصلی را بازگردانید. با این کار محتوای سایت دست‌نخورده می‌ماند و فقط کاربران قبلی حذف و کاربر جدیدی که سایت را راه‌اندازی کرده، جایگزین می‌شود.

⚠ هشدار: در فاصله‌ای که setting.json تغییر نام یافته، هر بازدیدکننده‌ای می‌تواند فرم راه‌اندازی را تکمیل و مدیر سایت شود. این کار را در کوتاه‌ترین زمان و خارج از ساعت‌های پر بازدید انجام دهید.

نکته: پس از بازیابی دسترسی، به فلسفه ذخیره MD5 توجه کنید (راهنمای «ناحیه مدیریت»، بخش ۱۵): رمزهای طولانی و تصادفی انتخاب کنید.

۷. خطاهای دسترسی به محتوا

«خطای دسترسی — مشاهده این مطلب تنها برای اعضای سایت مجاز است.» (کد 403)

مطلب مورد نظر پیش‌نویس است و برای عموم قابل مشاهده نیست؛ نشانی آن را اعضای سایت می‌بینند و اعضا همان صفحه را همراه نوار هشدار قرمز شناور «این مطلب پیش‌نویس است و برای عموم قابل مشاهده نیست.» مشاهده می‌کنند. خطا نیست — وضعیت انتشار مطلب است.

صفحه «404 — یافت نشد!»

• نشانی درخواستی به هیچ مطلب، دسته یا برچسبی تعلق ندارد، یا محتوا نشانی یکتای خالی (ذخیره‌شده با #) دارد و عمداً روی سایت نامرئی است.
• اگر پوسته فایل 404.html نداشته باشد، موتور صفحه پیش‌فرض ساده خود را نشان می‌دهد — این هم رفتار عادی است، نه خرابی.
• اگر نشانی درست است ولی 404 می‌گیرید: نشانی یکتای مطلب را در ویرایش مطلب بررسی کنید؛ به خاطر داشته باشید نشانی نمی‌تواند فقط عدد باشد یا با عدد آغاز شود، و «نشانی کوتاه عددی» (مثل /123) فقط هدایت‌گر است.

پیوندهای داخلی یا تصاویر مطالب کار نمی‌کنند

پس از تغییر نشانی یکتای مطلب، پیوندهای قدیمی 404 می‌شوند — نشانی کوتاه عددی همان مطلب هنوز کار می‌کند. تصاویر گمشده را از بخش «مدیریت تصاویر» بررسی کنید؛ اگر تصویر با FTP حذف شده، بندانگشتی آن (-thumb.jpg) هم باقی مانده و باید دستی پاک شود.

۸. خطاهای فرم‌های عمومی

پاسخ همه فرم‌ها (تماس، دیدگاه، رأی) به‌صورت متنی است: OK... برای موفقیت و ERROR|پیام فارسی برای خطا. اگر پیام خطا در صفحه نمایش داده نشد، طرح پوسته جای نمایش آن را نداشته یا خطای جاوااسکریپت رخ داده است — با کنسول مرورگر بررسی کنید (بخش ۱۱). فهرست کامل پیام‌ها با علت و راه‌حل: پیوست. رایج‌ترین‌ها:

اگر فرم تماس پیام موفقیت داد ولی ایمیلی دریافت نشد، علت در سمت mail() هاست است — خود پیام در گزارش وقایع (wotor.log) ثبت شده است؛ ارسال ایمیل را با پشتیبانی هاست بررسی کنید.

۹. خطاهای فروشگاه و پرداخت

صفحه رسید — سه حالت

خطاهای رایج درون رسید ناموفق

«خطای محدودیت سفارش — امکان ایجاد سفارش بیشتر برای شما وجود ندارد.»

برای جلوگیری از سفارش‌های هرز، هر نشانی IP حداکثر ۳ سفارش پرداخت‌نشده در روز می‌تواند بسازد. برای آزمایش مکرر خرید، سفارش‌های ناتمام را از بخش «سفارش‌ها» حذف کنید یا وضعیت آن‌ها را تغییر دهید.

«شماره رسید معتبر نیست یا حذف شده است.» / «شماره سفارش معتبر نیست یا حذف شده است.»

شماره رسید اشتباه تایپ شده یا سفارش حذف شده است. شماره رسید، شناسه سفارش به‌همراه ۶ رقم امنیتی است و حذف حتی یک رقم آن را نامعتبر می‌کند.

۱۰. خطاهای ناحیه مدیریت

ورود

• «اطلاعات ورود صحیح نیست.» — ایمیل یا رمز اشتباه است؛ رمز به بزرگی/کوچکی حروف و ارقام فارسی/انگلیسی حساس است.
• «شناسه بازنشانی منقضی شده یا روی این مرورگر معتبر نیست.» — پیوند بازنشانی مبتنی بر همان مرورگری است که درخواست داده و یک‌بارمصرف است؛ دوباره درخواست دهید.
• «ورود شما به بخش مدیریت نامعتبر یا منقضی شده است.» — درخواست POST بدون بارگذاری قبلی فرم (نشست منقضی). صفحه را تازه‌سازی کنید.

مجوزها

پیام‌های «این دسترسی محدود به مدیر سایت است.»، «دسترسی شما برای … کافی نیست.» و «شما مجاز به ویرایش/حذف این مطلب نیستید.» بازتاب جدول نقش‌هاست (راهنمای «ناحیه مدیریت»، بخش ۲): سردبیر به تنظیمات سایت و ابزارهای فایل دسترسی ندارد؛ نویسنده فقط مطالب خودش را ویرایش و حذف می‌کند و در مدیریت پرونده فقط تصاویر را مدیریت می‌کند.

مدیریت پرونده

• «مسیر معتبر نیست.» — مسیر حاوی کاراکتر غیرمجاز یا ../ است.
• «پرونده‌ای با این نام وجود دارد.» — بارگذاری با نام تکراری؛ ابتدا نام را عوض یا فایل قبلی را حذف کنید.
• «خطا در تغییر نام» / «نام جدید از قبل وجود دارد» — نام جدید حاوی کاراکتر غیرمجاز یا تکراری است.
• «پرونده فشرده دارای فایل خارج از مسیر و غیر مجاز است.» — بسته ZIP نامعتبر است و استخراج متوقف شد.
• اگر پایگاهی را بیرون از ناحیه مدیریت ویرایش و آپلود کرده‌اید و عملیات نوشتن شکست می‌خورد: مجوز نوشتن/مالکیت فایل را اصلاح کنید (بخش ۳).

ویرایشگر پایگاه داده

• پیام BAD_SQL — کوئری به قالب استاندارد موتور نمی‌خورد (باید شامل FROM یا INTO یا UPDATE یا TABLE با نام جدول باشد).
• پیام‌های SQLite (مثل no such table یا database is locked) — نام جدول/ستون اشتباه است، یا فایل هم‌زمان توسط فرآیند دیگری قفل شده؛ کمی بعد دوباره تلاش کنید.
• ویرایش اشتباه پایگاه‌ها می‌تواند محتوا را خراب کند — پیش از هر دستور تغییردهنده، پشتیبان بگیرید.

به روز رسانی انجام نشد

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

• می‌توانید به روز رسانی را به طور دستی انجام دهید.
• برای به روز رسانی موتور کافی است فایل index.php جدید را از سایت websitemotor.com دریافت کرده و آن را روی سایت خودتان جایگزین کنید.

نکته: پیش از به‌روزرسانی پشتیبان بگیرید.
راهنمای تهیه نسخه پشتیبان را ببینید.

۱۱. ابزارهای عیب‌یابی

گزارش وقایع — data/wotor.log

بسیاری از رویدادها — ورودها، ایجاد و حذف مطالب و کاربران، سفارش‌ها، تراکنش‌های موفق و ناموفق، پیام‌های فرم تماس — با زمان و آی‌پی در این فایل ثبت می‌شوند و ۲۵ ردیف آخر آن در پیشخوان مدیریت دیده می‌شود. برای عیب‌یابی تراکنش یا بررسی اینکه «آیا پیام فرم تماس ثبت شده؟» اولین جای مراجعه همین‌جاست. نام این فایل‌ها عمداً به این شکل است (wotor از websitemotor، هم‌آوا با روتور و استاتور؛ countor از counter) — غلط املایی نیست و فایل‌ها را با همین نام‌ها جستجو کنید.

کنسول و تب Network مرورگر

برای مشکلات فرم‌ها و بخش‌های AJAX (دیدگاه‌ها، رأی، فرم تماس، سبد خرید): کلید F12 را بزنید. در تب Console خطاهای جاوااسکریپت را می‌بینید — رایج‌ترین علت، حذف عناصر الزامی (مثل #comments-container) یا تداخل اسکریپت‌هاست. در تب Network، درخواست POST را انتخاب و پاسخ سرور را ببینید: هر پاسخ با OK یا ERROR| آغاز می‌شود و پیام دقیق سرور همان‌جاست.

نمایش خطاهای PHP

در ناحیه مدیریت، خطاهای PHP نمایان‌اند؛ برای دیدن خطای یک صفحه عمومی، همان نشانی را پس از ورود به مدیریت باز کنید یا موقتاً در ابتدای index.php این دو سطر را اضافه کنید و پس از عیب‌یابی حذف کنید:

ini_set('display_errors','1'); error_reporting(E_ALL);

بررسی ماژول‌ها و نسخه PHP

با فایل حاوی phpinfo() یا دستور php -m (بخش ۲).

مقایسه با پوسته نمونه

اگر بخشی از پوسته کار نمی‌کند، همان بخش را با پوسته نمونه مقایسه کنید: ترتیب اسکریپت‌ها، صفت‌های الزامی (votes، captchano، post_id) و نام کلاس‌ها. شرح کامل: راهنمای «طراحی پوسته»، بخش ۱۱.

۱۲. چک‌لیست عیب‌یابی سریع

وقتی مشکل روشن نیست، به همین ترتیب پیش بروید:

1. کنسول مرورگر (F12): خطای جاوااسکریپت یا پاسخ ERROR| در تب Network؟
2. گزارش وقایع: پیشخوان مدیریت یا data/wotor.log — رویداد مربوط ثبت شده؟
3. پیش‌نیازها: PHP ≥ 7.3 و ماژول‌های ضروری فعال؟ (بخش ۲)
4. مجوز نوشتن: پوشه‌های data و images و themes قابل نوشتن‌اند؟
5. پس از تغییر اخیر: پوسته یا افزونه یا ویرایش دستی فایل؟ پشتیبان آخر را بازگردانید.
6. حافظه نهان: تغییرات CSS/JS با Ctrl+F5 یا کلید theme_dev بررسی شود.
7. جداسازی: پوسته نمونه را موقتاً فعال کنید — اگر مشکل رفع شد، مشکل از پوسته است؛ اگر ماند، از موتور یا سرور.
8. جستجوی پیام: متن دقیق پیام را در پیوست همین راهنما یا در راهنمای مربوط پیدا کنید.

پیوست — جدول مرجع پیام‌های ERROR|

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

ورود و بازنشانی رمز

کپچا

دیدگاه‌ها و رأی‌ها

مطالب و دسته‌ها و برچسب‌ها (در مدیریت)

کاربران (در مدیریت)

مدیریت پرونده (در مدیریت)

پوسته‌ها (در مدیریت)

نکته: پاسخ موفق فرم‌های عمومی با OK آغاز می‌شود (OK. برای تماس؛ OK\nداده‌ها برای رأی و دریافت دیدگاه‌ها؛ OK|پیام برای ثبت دیدگاه). پیام‌های وضعیت سفارش (رسید موفق/ناموفق/ناتمام) به‌صورت صفحه مستقل‌اند و بخش ۹ همین راهنما را ببینید.