راهنمای نصب و استفاده
از انتخاب لودر تا رفع اشکال؛ همه چیز برای اینکه فایل‌های محافظت‌شده روی سرور مشتری درست اجرا شوند.
۱. شروع سریع (سه قدم)
- پروژه را ZIP کنید:
zip -r project.zip .(ساختار پوشه‌ها مهم است). - در صفحه اصلی آپلود کنید و در صورت نیاز دامنه مشتری را در «قفل دامنه» بنویسید.
- خروجی را روی سرور مشتری بگذارید و لودر مناسب را از صفحه لودرها نصب کنید.
هیچ تغییری در کد پروژه لازم نیست: autoload، composer، WordPress و قالب‌ها بدون تغییر کار می‌کنند.
۲. نصب روی ویندوز
XAMPP
- نسخه و رشته‌ای بودن را ببینید:
C:\xampp\php\php.exe -vوphp -i | findstr Thread - DLL متناظر را در
C:\xampp\php\ext\کپی کنید. - در
C:\xampp\php\php.iniخطextension=ioncuberرا اضافه کنید. - از کنترل‌پنل XAMPP، Apache را Stop و Start کنید.
- تست:
C:\xampp\php\php.exe -m | findstr ioncuber
Laragon / IIS / PHP خام
- اگر
php.iniجدا دارید، همان مسیرLoaded Configuration Fileازphp --iniرا ویرایش کنید. - برای IIS/FastCGI بعد از تغییر،
iisresetبزنید. - اگر TS/NTS اشتباه باشد، در لاگ Apache این خط را می‌بینید:
Unable to load dynamic library.
۳. نصب روی لینوکس
# 1) نسخه PHP و TS/NTS php -v php -i | grep -i "thread safety" # 2) مسیر افزونه‌ها EXT=$(php -r 'echo ini_get("extension_dir");') # 3) کپی لودر (نام فایل را با نسخه واقعی عوض کنید) cp ioncuber-php8.2.30-x64-nts-linux.so $EXT/ # 4) فعال‌سازی در php.ini مربوط به SAPI مورد استفاده # CLI: /etc/php/8.2/cli/php.ini FPM: /etc/php/8.2/fpm/php.ini echo "extension=ioncuber.so" >> /etc/php/8.2/fpm/php.ini # 5) ری‌استارت systemctl restart php8.2-fpm systemctl reload apache2 # 6) تأیید php -m | grep -i ioncuber
در cPanel/Plesk اگر امکان ویرایش php.ini ندارید، از بخش PHP Selector / MultiPHP INI Editor گزینه «Extension» یا فایل .user.ini استفاده کنید و مقدار
extension=ioncuber.so را اضافه کنید.داکر: فایل
.so را در ایمیج کپی کنید و docker-php-ext-enable ioncuber یا echo "extension=ioncuber.so" > /usr/local/etc/php/conf.d/ioncuber.ini را اجرا کنید.۴. تأیید و تست
php -m | grep -i ioncuber
php -r "print_r(ioncuber_loader_info());"
php -i | grep -i ioncuber
در خروجی باید نسخه لودر، لیست کلیدهای پشتیبانی‌شده و وضعیت allow_cli/strict_host را ببینید.
ابزار تشخیص: فایل
ioncuber-check.php را از صفحه لودرها دانلود کنید،
روی سرور مشتری بگذارید و باز کنید؛ نسخه PHP، TS/NTS، معماری، مسیر ext و کادر لازم php.ini را
خودش تشخیص می‌دهد. با CLI: php ioncuber-check.php
۵. تنظیمات php.ini
| تنظیم | پیش‌فرض | توضیح |
|---|---|---|
ioncuber.enabled | 1 | خاموش/روشن کردن کل لودر (برای دیباگ). |
ioncuber.allow_cli | 1 | اجرای فایل‌های قفل‌شده با دامنه از طریق CLI (کرون‌جاب/queue). |
ioncuber.strict_host | 0 | اگر هاست درخواست قابل تشخیص نباشد، فایل قفل‌شده اجرا نشود. |
۶. قفل دامنه چطور کار می‌کند؟
- در زمان محافظت، لیست دامنه‌ها داخل هدر فایل امضا می‌شود (AAD) و قابل تغییر نیست.
- لودر مقدار
HTTP_HOST(یاSERVER_NAME) را با لیست مقایسه می‌کند؛ دامنه اصلی و همه زیردامنه‌ها مجازند. - در صورت عدم تطابق، صفحه «این دامنه لایسنس ندارد» نمایش داده می‌شود.
- برای مشتری‌های multi-domain، همه دامنه‌ها را با کاما بنویسید:
a.com,b.com,*.c.com
۷. رفع اشکال
| علامت | علت | راه‌حل |
|---|---|---|
| فایل محافظت‌شده صفحه نصب نشان می‌دهد | لودر در همان PHP لود نشده است | خروجی php -m و php --ini را چک کنید؛ ممکن است CLI و FPM دو php.ini جدا داشته باشند. |
| Unable to load dynamic library | نسخه PHP یا TS/NTS یا معماری اشتباه | دقیقاً همان نسخه‌ای را دانلود کنید که php -v و php -i | grep -i thread نشان می‌دهد. |
| پیام «unknown loader key» | لودر قدیمی‌تر از کلید فعلی است | لودر را از صفحه لودرها دوباره دانلود کنید (بیلدهای جدید همه کلیدها را دارند) یا با کلید فعال قبلی محافظت کنید. |
| پیام «could not be decoded» | فایل دست‌کاری/دوباره آپلود شده یا ناقص منتقل شده است | فایل را دوباره از خروجی سرویس روی سرور بگذارید (FTP باید binary باشد). |
| صفحه «دامنه لایسنس ندارد» | دامنه واقعی در لیست قفل نیست | پروژه را با لیست دامنه درست دوباره محافظت کنید (زیردامنه‌ها خودکار مجازند). |
| سایت سفید یا ۵۰۰ می‌شود | خطای واقعی داخل پیلود یا ناسازگاری نسخه PHP | لاگ PHP را ببینید؛ در صورت نیاز ioncuber.enabled=0 بگذارید تا کد اصلی خطا بدهد. |
۸. استفاده از CLI و API
# محافظت از یک پروژه روی سرور خودتان node bin/ioncuber-pack.mjs ./my-project -o out.zip \ --domain "example.com" --skip "vendor/**" # API curl -X POST --data-binary @project.zip \ -H "Content-Type: application/zip" \ "http://127.0.0.1:3088/api/pack?domain=example.com" # وضعیت و دانلود curl "http://127.0.0.1:3088/api/jobs/<id>" curl -O "http://127.0.0.1:3088/download/<id>"
۹. نکات امنیتی (صادقانه)
- این روش سورس را رمزنگاری می‌کند، ولی «غیرقابل شکستن مطلق» نیست؛ هر محافظت PHP در نهایت روی سروری اجرا می‌شود که در اختیار مشتری است.
- در حالت پیش‌فرض (کد کامپایل‌شده) هیچ متن سورسی روی سرور مشتری وجود ندارد؛ حالت سورس‌محور برای ۷.۴ و ۸.۰ است.
- قبل از تحویل، خروجی را روی همان نسخهٔ PHP سرور مقصد تست کنید و از خروجی و فایل کلید بکاپ بگیرید.
- برای پروژه‌های حساس، «لودر اختصاصی» بسازید و در صورت نیاز لایسنس آنلاین (دامنه + انقضا) را فعال کنید؛ توضیح کامل در صفحهٔ امنیت.
- SHA-256 هر لودر در صفحهٔ لودرها منتشر می‌شود؛ فایل دانلودشده را با آن مقایسه کنید.