# سند ۳۴ — نصب روی سرور و هاست اشتراکی (cPanel)

**نسخه:** 1.12.0 · **تاریخ:** ۲۰۲۶-۰۹-۲۶ · **خلاصه‌ی سریع:** `INSTALL.md` (داخل بسته) · **بسته:** `node scripts/release.mjs [--with-deps]`

این سند سه مسیر نصب را کامل توضیح می‌دهد. همه‌ی مسیرها به یک نصب‌گر می‌رسند:

| مسیر | برای چه کسی | زمان |
|---|---|---|
| **A. cPanel (Passenger)** | هاست اشتراکی با «Setup Node.js App» | ~۵ دقیقه |
| **B. سرور اختصاصی/VPS** | Docker یا Node مستقیم | ~۵ دقیقه |
| **C. لوکال/توسعه** | اجرای خانگی/آزمایشی | ~۱ دقیقه |

---

## ۰. معماری نصب (چطور کار می‌کند)

```
node server/index.js  ← (cPanel: همین فایل به‌عنوان Application startup file)
   ├── config/settings.json  ← تنظیمات بدون env (اولویت: env > فایل > پیش‌فرض)
   ├── SQLite در ALPHABET_DATA_DIR (پیش‌فرض server/data — نیازی به سرور DB نیست)
   └── اولین اجرا بدون ادمین → نصب‌گر فعال:
        https://دامنه/install  →  ویزارد ۳ گامی  →  قفل دائمی (410)
```

- **نصب‌گر وب** (`/install`): بررسی محیط (Node ≥۱۸ · SQLite · نوشتنی‌بودن پوشه‌ها) → ساخت حساب مدیر (+ SMTP اختیاری) → نوشتن `config/settings.json` با `installed:true` → از آن لحظه `/api/install/run` همیشه **410** برمی‌گرداند (الگوی WordPress).
- **نصب‌گر CLI** (معادل، برای ترمینال/اسکریپت):
  ```bash
  node scripts/install.mjs --email admin@example.com --password 'رمز۸کاراکتری'
  # بازیابی دست گم‌شده‌ی ادمین (فقط از خودِ سرور):
  node scripts/install.mjs --recover --email admin2@example.com --password 'رمز۸کاراکتری'
  ```
- **کلید نصب (اختیاری، توصیه‌شده در هاست اشتراکی):** `ALPHABET_INSTALL_KEY` را در env/فایل تنظیمات بگذار تا ویزارد فقط با آن کلید نصب کند — پنجره‌ی بین «آپلود» و «نصب» را می‌بندد.

---

## A. نصب روی cPanel

### A-۰. پیش‌نیازهای هاست

| پیش‌نیاز | چک |
|---|---|
| **Setup Node.js App** در cPanel (CloudLinux + Passenger) | cPanel → بخش Software |
| **Node.js ≥ ۱۸** (۲۰ پیشنهادی) | در فهرست نسخه‌های Node |
| فضای ~۵۰MB (کد) یا ~۲۰۰MB (با وابستگی‌ها) | |
| **دسترسی هاست شما اجازه‌ی اجرای پروسه‌ی Node می‌دهد** | اگر «Setup Node.js App» نیست → هاست Node ندارد → مسیر B |

> ⚠️ **اگر هاست‌تان اصلاً Node ندارد** (فقط PHP)، این اپ روی آن اجرا نمی‌شود — نیازمند بازنویسی به PHP است که توصیه نمی‌شود. یک VPS ارزان (۲-۳ یورو/ماه) یا هاست Node-دار بگیرید.

### A-۱. گرفتن بسته

دو حالت — **حالت ۲ برای وقتی است که SSH/Terminal یا «Run NPM Install» کار نمی‌کند:**

**حالت ۱ — بسته‌ی سبک + نصب وابستگی روی هاست:**
```bash
# روی سیستم خودت (لینوکس/مک/ویندوز با Node ۲۰):
node scripts/release.mjs          # → releases/alphabetplay-1.12.0.zip
```
سپس در cPanel بعد از ساخت اپ، دکمه‌ی **Run NPM Install** را بزن (یا در Terminal: `npm ci --omit=dev`).

**حالت ۲ — بسته‌ی آماده با وابستگی‌ها (بدون هیچ کامپایل روی هاست):**
```bash
# روی یک لینوکس x64 با همان نسخه‌ی Node که در cPanel انتخاب می‌کنی (مثلاً ۲۰):
node scripts/release.mjs --with-deps   # → releases/alphabetplay-1.12.0-with-deps.zip (۶.۷MB)
```
> **مهم:** `better-sqlite3` ماژول بومی است — بسته‌ی `-with-deps` را با **همان نسخه‌ی Node‌ِ** بساز که در cPanel انتخاب می‌کنی (شماره‌ی اصلی؛ ۲۰ با ۲۰). نسخه‌ها ناسازگار باشند اپ با خطای `NODE_MODULE_VERSION` بالا نمی‌آید.

### A-۲. آپلود

1. cPanel → **File Manager** → پوشه‌ی خانه‌ی اکانت (بالای `public_html` — کد اپ نباید داخل public_html باشد).
2. Upload → فایل zip → راست‌کلیک → **Extract**.
3. (اختیاری) پوشه را به `alphabetplay` کوتاه کن.

### A-۳. ساخت اپلیکیشن

cPanel → **Setup Node.js App** → **Create Application**:

| فیلد | مقدار |
|---|---|
| Node.js version | 20 (یا نسخه‌ی بسته) |
| Application mode | Production |
| Application root | `alphabetplay` |
| Application URL | دامنه/ساب‌دامنه (مثلاً `play.example.com`) |
| Application startup file | **`server/index.js`** |

سپس **Create**. (اپ ما `PORT` را از Passenger می‌خواند — نیازی به تنظیم پورت نیست.)

### A-۴. تنظیمات (اختیاری اما تمیز)

در همان صفحه، **Environment variables** (یا فایل `config/settings.json` در پوشه‌ی اپ با File Manager):

| متغیر | پیشنهاد |
|---|---|
| `ALPHABET_INSTALL_KEY` | یک رمز تصادفی — تا فقط تو بتوانی /install را تمام کنی |
| `ALPHABET_FRAME_GUARD` | `deny` (تولید) |
| `ALPHABET_BACKUP` | `1` |

بعد از تغییر، **Restart** فراموش نشود.

### A-۵. نصب ویزارد

مرورگر: `https://دامنه/install`

1. بررسی محیط — همه باید سبز باشند (قرمز بودن = جزئیات را ببین و با هاست در میان بگذار).
2. حساب مدیر (ایمیل + رمز ≥۸ کاراکتر) + SMTP اختیاری.
3. تمام → ورود از `/admin.html` · اپ کودک از `/`.

**SSL:** cPanel → SSL/TLS Status → AutoSSL برای دامنه (باید — اپ کودک-محور است و مرورگرهای جدید سخت می‌گیرند).

### A-۶. بکاپ روی cPanel (Cron)

پروسه‌ی Passenger ممکن است در سکوت کشته شود؛ برای اطمینان یک Cron روزانه (cPanel → Cron Jobs، ساعت ۳ بامداد):

```
cd /home/USER/alphabetplay && /opt/alt/node-v20/bin/node scripts/backup.mjs
```
(مسیر node دقیق را از cPanel → Setup Node.js App ببین؛ فایل بکاپ در `data-backups` کنار اپ می‌نشیند. برای نسخه‌ی سومِ قاعده‌ی ۳-۲-۱، هفته‌ای یک‌بار پوشه‌ی `data-backups` را با بکاپ خود cPanel یا دستی دانلود کن — **restic روی هاست اشتراکی معمولاً موجود نیست**.)

### A-۷. محدودیت‌های صادقانه‌ی هاست اشتراکی

| محدودیت | اثر | کار |
|---|---|---|
| پروسه در سکوت spindown می‌شود | اولین درخواست بعد از بی‌کاری ~۲-۵ث کندتر | قابل‌قبول؛ پینگ دوره‌ای (uptimerobot) اگر مهم بود |
| بدون restic | بکاپ ریموت خودکار نیست | Cron + دانلود هفتگی (A-6) |
| منابع CPU/RAM اشتراکی | ~۱۰۰ کاربر هم‌زمان سقف واقعی است | برای پایلوت فراتر از انتظار؛ رشد → VPS |
| یک پروسه = محدودسازها در حافظه | ری‌استارت پنجره‌ها را صفر می‌کند | تک‌اپ اینجا؛ نگرانی نیست |
| SMTP هاست (Exim) | ما از آن استفاده نمی‌کنیم | Resend/Mailgun بده یا بدون ایمیل زندگی کن (کانال AP- ادمین هست) |

---

## B. سرور اختصاصی/VPS

### B-1. با Docker (پیشنهادی — سند ۲۸)

```bash
git clone <repo> alphabetplay && cd alphabetplay
cp .env.example .env 2>/dev/null || true   # رازها را در .env بگذار (gitignore است)
docker compose up -d
docker compose exec app node scripts/install.mjs --email you@example.com --password 'your-pass'
```
TLS خودکار با Caddy (دامنه را در `Caddyfile` بگذار). بکاپ/retention/پایش با env فعال می‌شوند (جدول کامل سند ۲۸ §۶).

### B-2. بدون Docker

```bash
node@server:~$ unzip alphabetplay-1.12.0-with-deps.zip && cd alphabetplay-1.12.0
node@server:~$ node scripts/install.mjs --email you@example.com --password 'your-pass'
node@server:~$ ALPHABET_FRAME_GUARD=deny node server/index.js   # پشت Nginx/Caddy
```
(یا systemd unit ساده — الگو در سند ۲۸.)

---

## C. لوکال/توسعه

```bash
npm install
node scripts/install.mjs --email dev@local --password 'dev-pass-8'
npm start   # → http://localhost:8080
```

---

## عیب‌یابی

| نشانه | علت رایج | راه‌حل |
|---|---|---|
| **503 بعد از ساخت اپ** | startup file اشتباه / وابستگی ناقص / نسخه‌ی Node ناسازگار | `server/index.js` · Run NPM Install · هم‌نسخه‌سازی بسته |
| `NODE_MODULE_VERSION` در لاگ | بسته با Node دیگری ساخته شده | در cPanel همان نسخه‌ی اصلی را انتخاب کن یا بسته‌ی سبک + NPM Install |
| `/install` صفحه‌ی «از قبل نصب شده» می‌دهد ولی رمز نداری | نصب قبلی | `node scripts/install.mjs --recover …` از Terminal |
| بررسیِ «پوشه‌ی داده قرمز» | home فقط‌خواندنی (نادر) | `ALPHABET_DATA_DIR` را به مسیر نوشتنی در فایل تنظیمات بده → Restart |
| تغییرات تنظیمات اعمال نشد | env هاست بر فایل برنده است / Restart نشده | Restart از cPanel؛ کلید تکراری را از env حذف کن |
| اپ بعد از مدتی 502/503 می‌شود | Idle spindown | عادی — رفرش؛ یا uptime pinger |

**لاگ‌ها:** cPanel → Setup Node.js App → لاگ اپ (`passenger.log`).