راهنمای استقرار و عملیات موتوشاب (Motoshub Ops Guide)

این سند برای تیم DevOps و فروش تهیه شده است: نیازمندی‌های سرور برای هر مشتری، خط‌لوله‌ی استقرار، پایش زنده‌ی مصرف منابع، استراتژی احراز هویت میان PHP و Django، و وضعیت ORM. همه‌ی اعداد از اندازه‌گیری واقعی روی استک در حال اجرا به‌دست آمده‌اند.

---

۱) پشته‌ی اجرایی (Runtime Stack)

• PHP 8.4.11، افزونه‌ها: pdo_mysql, mysqli, mbstring, exif, pcntl, bcmath, gd, sockets, zip, soap, intl, ftp + OPcache (فعال، ۱۲۸MB).
• MariaDB 10.5.29 — همه‌ی تنظیمات روی پیش‌فرض ایمیج (بدون tuning).
• nginx: client_max_body_size 20M, fastcgi_read_timeout 300.
• وابستگی‌های Composer سنگین: Smarty + Twig (دو موتور قالب)، illuminate/database|events|support|container|pagination (اجزای Eloquent لاراول)، Symfony (cache/console/http-foundation)، Guzzle، Monolog، PhpSpreadsheet، Shieldon (WAF)، swagger-php، firebase/php-jwt، php-di، wideimage، morilog/jalali. درخت vendor ≈ ۲۰۵MB.

سرویس‌های خارجی که کد فرض می‌کند

---

۲) مصرف منابع واقعی (اندازه‌گیری‌شده)

docker stats --no-stream (استک بی‌بار)

هر worker از php-fpm (اندازه‌گیری VmRSS زیر بار)

• master: ~۳۲ MB
• هر worker استخر www: ~۵۵–۵۷ MB حتی برای یک صفحه‌ی ساده.
• علت این کف بالا: ۵۱ پلاگین فعال، init.php هرکدام در هر درخواست اجرا می‌شود (Oxwall پلاگین‌های فعال را eager-load می‌کند؛ lazy loading ندارد) + بارگذاری Smarty/Twig/Illuminate/Symfony/Guzzle/Shieldon.

فرمول بدترین حالت RAM کانتینر app

RAM app  =  master  +  pm.max_children × RSS هر worker

• تنظیم فعلی (اندازه‌گیری‌شده): 31 + 5 × 57 ≈ 316 MB سقف پایدار.
• بدترین حالت مطلق (هر درخواست سنگین: resize تصویر با gd/wideimage، خروجی PhpSpreadsheet، رندر بزرگ فید تا memory_limit):

31 + 5 × 256 MB  =  1.31 GB

چرا RAM سرور شما زیاد مصرف می‌شود (تشخیص دقیق)

• کف هر worker بالا و ثابت است (~۵۵MB) چون ۵۱ پلاگین هر درخواست بوت می‌شوند — این یک مالیات ثابت است، نه وابسته به بار.
• pm.max_children ضریب است. مقدار shipped برابر ۵ است (سقف ~۳۱۶MB)؛ اما اپراتورها معمولاً برای همزمانی آن را بالا می‌برند: در max_children=20 تنها PHP = 20×57 ≈ 1.14GB، در ۴۰ → 2.3GB. این مکانیزم گم‌شدن RAM است.
• نکته‌ی مهم پیکربندی: فایل tune‌شده‌ی docker/php/www.conf (که pm.max_children=10 + status page + slowlog دارد) هرگز داخل ایمیج کپی نمی‌شود — Dockerfile فقط docker/php-fpm.conf را کپی می‌کند. پس کانتینر روی www.conf استاندارد (max_children=5) اجرا می‌شود و هر tuning در docker/php/www.conf بی‌اثر است. باید این کپی در Dockerfile اضافه شود.
• memory_limit=256MB هر درخواست یعنی رگبار درخواست‌های سنگین می‌تواند هرکدام ۴–۵ برابر worker بی‌بار متورم شود پیش از reap.
• OPcache فعال است (خوب) — مشکل OPcache نیست؛ مشکل heap هر پروسه × تعداد worker است.
• MariaDB حتی بی‌بار ~۱۶۰MB ثابت اضافه می‌کند (buffer pool پیش‌فرض ۱۲۸MB)؛ داده‌ی واقعی این را بالا می‌برد.

---

۳) مشخصات سرور برای هر مشتری (بدبینانه)

فرض‌ها: بدون swap (سقف سخت RAM)، ~۲۰٪ headroom، هر worker ۷۰MB (بدبینانه برای جذب spike تصویر/اکسپورت)، OS+Docker ~۵۰۰MB.

هشدارهای بدبینانه:

• اگر Elasticsearch/RabbitMQ فعال شوند: +۱GB برای ES و +۲۵۶MB برای هر RabbitMQ. پروفایل متوسط باید +۱.۵GB بودجه بگیرد.
• worker cron یک ایمیج PHP کامل دوم است: هنگام استقرار ~۵۵–۹۰MB اضافه کنید.
• اگر کسی max_children را بدون RAM متناسب بالا ببرد، OOM-kill تقریباً حتمی است: شعاع انفجار واقعی max_children × 256MB است (۲۰ worker × ۲۵۶MB = ۵.۱GB).
• ow_log بدون rotation رشد نامحدود دارد — روی استوریج پایش‌شده نگه دارید.

جمله‌ی نهایی: این اپ memory-bound است، نه CPU-bound. هرگز روی <۲GB اجرا نکنید. RAM را این‌طور اندازه بگیرید:

500MB (OS) + buffer_pool + (max_children × 70MB) + 20% headroom

---

۴) خط‌لوله‌ی استقرار برای مشتری (تمیز و مرحله‌به‌مرحله)

پیش‌نیازها روی سرور مشتری

• Docker + Docker Compose، دسترسی به میرورهای build (Nexus) یا ایمیج از پیش build‌شده.
• دامنه/ساب‌دامین با رکورد A به IP سرور.

مراحل

# ۱) کد
git clone <repo> motoshub && cd motoshub
git checkout motonext            # شاخه‌ی زنده

# ۲) تنظیمات محیط
cp .env.example .env
#   ویرایش .env: DB_*، SITE_URL، PROJECT_NAME، OW_PASSWORD_PEPPER (کلید امضای JWT)

# ۳) بالا آوردن استک
docker compose up -d --build     # app + db + web (+ cron در prod)

# ۴) نصب/آپدیت اکسوال و پلاگین‌ها
#   نصب تازه از طریق ماژول init یا صفحه‌ی نصب؛
#   سایت موجود: از پنل مدیریت، آپدیت‌های در انتظار پلاگین‌ها را اجرا کنید
#   (اکسوال با دیدن بامپ build در plugin.xml، update.php ها را خودکار اجرا می‌کند).

# ۵) پاک‌سازی کش
rm -rf ow_smarty/template_c/* ow_static/tmp/*

# ۶) راستی‌آزمایی
curl -i https://<domain>/                 # 200
curl -i https://<domain>/api/v1/docs/json # 200، خروجی OpenAPI

اصلاحات لازم پیش از production (بدهی فنی شناسایی‌شده)

• Dockerfile: کپی docker/php/www.conf را اضافه کنید تا tuning استخر (max_children، status page، slowlog) واقعاً اعمال شود.
• docker/nexus.pem روی هیچ شاخه‌ای نیست و مرحله‌ی build را می‌شکند — یا گواهی Nexus را به مخزن/CI بیفزایید یا آن خط Dockerfile را مشروط کنید.
• rotation لاگ برای ow_log تنظیم کنید.
• SSL (Let's Encrypt) روی nginx.

---

۵) پایش زنده‌ی مصرف (چطور live چک کنم؟)

سطح کانتینر (روی هاست production)

docker stats                    # زنده CPU/MEM هر کانتینر
docker stats --no-stream        # snapshot یک‌باره برای اسکریپت

داخل کانتینر PHP

docker compose exec app top                      # اگر procps نصب باشد
# fallback بدون top/ps (این ایمیج ندارد):
docker compose exec app sh -c 'for p in $(ls /proc|grep -E "^[0-9]+$"); do \
  grep -qa "pool www" /proc/$p/cmdline 2>/dev/null && \
  echo "$p $(grep VmRSS /proc/$p/status|awk "{print \$2}")kB"; done'

صفحه‌ی وضعیت php-fpm (پس از رفع کپی www.conf)

curl -s "https://<domain>/status?full"   # worker های active/idle/total، صف، peak
curl -s https://<domain>/ping            # → pong

MariaDB

docker compose exec db mysql -uroot -p<pass> -e "SHOW FULL PROCESSLIST;"
docker compose exec db mysql -uroot -p<pass> -e "SHOW ENGINE INNODB STATUS\G"
docker compose exec db mysql -uroot -p<pass> -e \
  "SET GLOBAL slow_query_log=ON; SET GLOBAL long_query_time=1; \
   SET GLOBAL slow_query_log_file='/var/lib/mysql/slow.log';"   # فعال‌سازی بدون restart
# روند رشد دیتابیس:
docker compose exec db mysql -uroot -p<pass> -e \
  "SELECT table_schema, ROUND(SUM(data_length+index_length)/1024/1024,1) MB \
   FROM information_schema.tables GROUP BY table_schema;"

گزینه‌های always-on (با overhead خودشان)

---

۶) مدیریت احراز هویت میان PHP و Django (استراتژی — بدون تغییر کد)

وضعیت فعلی: API (لایه‌ی جدید) با JWT (الگوریتم HS256) کار می‌کند. توکن با hash('sha256', OW_PASSWORD_PEPPER) امضا می‌شود و claims دارد: { iat, exp, sub: userId }. ورود از POST /api/v1/auth/login توکن یک‌ساعته می‌دهد.

معماری هدف شما: api.shub.ir (Gateway) جلوی api1 (PHP/Oxwall) و api2 (Django).

گزینه‌ی توصیه‌شده (کم‌ریسک، بدون تغییر کد فعلی): کلید متقارن مشترک

• همان راز را به هر دو بدهید. OW_PASSWORD_PEPPER در PHP همان رازی باشد که Django برای امضا/اعتبارسنجی JWT استفاده می‌کند. کلید نهایی = sha256(pepper).
• Django با همان الگوریتم و claims اعتبارسنجی کند (HS256، بررسی exp، خواندن sub به‌عنوان userId). کتابخانه: PyJWT — jwt.decode(token, key, algorithms=['HS256']) که key = sha256(pepper).hexdigest() (باید دقیقاً همان hex که PHP می‌سازد باشد).
• Gateway توکن را pass-through کند — هدر Authorization: Bearer <token> را دست‌نخورده به api1 و api2 بفرستد. هر دو سرویس مستقل همان توکن را می‌پذیرند.
• هویت کاربر مشترک: sub همان userId جدول ow_base_user است. Django باید به همان دیتابیس (یا یک نگاشت) دسترسی داشته باشد تا userId را به کاربرش وصل کند.

مزیت: هیچ تغییری در کد PHP لازم نیست؛ فقط راز مشترک + پیاده‌سازی decode در Django.

محدودیت‌ها (صادقانه):

• کلید متقارن یعنی هر دو سرویس می‌توانند توکن صادر کنند. اگر می‌خواهید فقط یک صادرکننده باشد، به RS256 (کلید نامتقارن) بروید: صادرکننده (مثلاً Gateway یا یک Identity Provider) با کلید خصوصی امضا می‌کند، PHP و Django با کلید عمومی فقط verify می‌کنند. این تغییر کد لازم دارد (JWTService باید RS256 بپذیرد) — فعلاً انجام ندهید، ولی مسیر درست بلندمدت است.
• ابطال توکن: JWT بی‌حالت است؛ برای logout/ban فوری، یک لیست سیاه کوتاه‌مدت (Redis) در Gateway لازم است.

گزینه‌ی بلندمدت (تمیزتر): Identity Provider مرکزی (Keycloak)

همه (فرانت، Gateway، PHP، Django) توکن را از یک IdP می‌گیرند و با کلید عمومی verify می‌کنند. تک‌نقطه‌ی حقیقت برای هویت، پشتیبانی refresh/revoke استاندارد. برای مقیاس چندسرویسی درست است، ولی راه‌اندازی جدا می‌خواهد.

---

۷) وضعیت ORM (آیا Laravel Eloquent است؟)

پاسخ دقیق: بله و نه — بستگی به لایه دارد. دو لایه‌ی دسترسی به داده روی یک MariaDB مشترک (shub_db، پیشوند ow_):

• لایه‌ی قدیمی Oxwall (DAO): ow_plugins/*/bol/*_dao.php که از OW_BaseDao ارث می‌برند. Eloquent نیست — خودش SQL می‌سازد (SELECT * FROM ow_photo WHERE id = ?) و از OW_Example فیلتر می‌گیرد. نمونه: PHOTO_BOL_PhotoDao::getInstance()->findById($id).
• لایه‌ی جدید REST API v1: ow_plugins/*/src/Models/*.php و src/Repositories/*.php. واقعاً Eloquent است — مدل پایه Bridge\Models\BaseModel از Illuminate\Database\Eloquent\Model ارث می‌برد؛ ۷۴ مدل در ۲۶ پلاگین. نمونه: Photo::query()->with('album')->find($id) و Photo::create([...]).

نکته‌ی صادقانه: این Laravel نیست. در composer.json هیچ laravel/framework نیست؛ فقط اجزای مستقل Illuminate (illuminate/database v13.16.1 و چند بسته). Eloquent دستی و از طریق یک «Bridge» سفارشی راه‌اندازی شده (bridge/src/Kernel.php با Capsule::bootEloquent()). پس عبارت درست: «API جدید از کامپوننت ORM لاراول (Eloquent) استفاده می‌کند، اما اپ یک اپ لاراولی نیست؛ یک اپ Oxwall است که Eloquent به آن اضافه شده.»

ORM یعنی چه؟ ابزاری که ردیف‌های جدول را به شیء PHP تبدیل می‌کند تا به‌جای SQL با متدهای شیء کار کنید. Eloquent ORM لاراول با الگوی Active Record است: هر کلاس مدل = یک جدول، هر شیء = یک ردیف که خودش می‌داند چطور ذخیره/به‌روزرسانی/حذف شود.

ریسک مهم — نوشتن دوگانه: هر دو لایه به همان جدول‌ها می‌نویسند. نوشتن با Eloquent، رویدادها و پاک‌سازی کشِ لایه‌ی قدیمی را دور می‌زند:

• OW_BaseDao::save() رویداد امنیتی/کش/اعلان trigger می‌کند؛ Photo::create()/update() این‌ها را اجرا نمی‌کند.
• نوشتن API کش Oxwall را پاک نمی‌کند ⇒ ممکن است UI قدیمی داده‌ی کهنه نشان دهد.
• کاهش‌یافته: BaseModel::$timestamps=false است، پس Eloquent created_at/updated_at نمی‌نویسد (که اسکیمای اکسوال ندارد) — از رایج‌ترین crash جلوگیری می‌کند.

جمع‌بندی برای مستندات: لایه‌ی API یک بازنویسی مشروع مبتنی بر Eloquent روی لایه‌ی DAO قدیمی است، هر دو روی یک MariaDB. Eloquent است، نه Laravel. خطر اصلی، مسیر نوشتن دوگانه است؛ هر جدولی که هر دو لایه می‌نویسند نیاز به دقت (یا یک نویسنده‌ی معتبر واحد) دارد.

---

تهیه‌شده پس از مطالعه‌ی کامل سورس و اندازه‌گیری زنده روی استک Docker.