# 📦 راهنمای نصب و راه‌اندازی پنل‌وینو (PanelVino)

---

## 🛠️ نصب روی هاست سی‌پنل (آسان‌نصب تحت وب — بدون SSH)

از نسخه‌ی **۱۶٫۱** پنل‌وینو یک **جادوگر آسان‌نصب فارسی** دارد که همه‌چیز را خودکار انجام می‌دهد؛ فقط فایل‌ها را آپلود و یک صفحه را باز کنید:

### قدم ۱ — آپلود فایل‌ها
۱. از سی‌پنل، **File Manager** را باز کنید و به پوشه‌ی موردنظر بروید (مثلاً ریشه‌ی یک ساب‌دامین مثل `home/user/panel`).
۲. **بسته‌ی آماده‌ی نصب** `panelvino-v*-cpanel.zip` (پوشه‌ی `release/` — با `bash scripts/build-dist.sh` ساخته می‌شود) را آپلود و **در همان پوشه Extract** کنید. این بسته فقط فایل‌های اجرایی را دارد (بدون node_modules، بدون داده‌ی دمو) — مسیر نهایی مثلاً `/home/USER/panel`.
> 💡 این بسته `package-lock.json` و وابستگی‌های بهینه دارد؛ نصب روی هاست معمولاً کمتر از یک دقیقه طول می‌کشد.

### قدم ۲ — ساخت اپلیکیشن Node در سی‌پنل
از بخش **Software ← Setup Node.js App**:
| فیلد | مقدار |
|---|---|
| Node.js version | **۲۰** (حداقل ۱۸) |
| Application mode | Production |
| Application root | پوشه‌ی آپلود (مثلاً `panel`) |
| Application URL | دامنه/ساب‌دامین پنل (مثلاً `panel.yoursite.com`) |
| **Application startup file** | **`app.js`** ✓ (همین فایل آماده در ریشه است) |

روی **Create** بزنید. سپس از همان صفحه دکمه‌ی **Run NPM Install** را بزنید (یا اگر ترمینال دارید: `npm install --omit=dev`).

### قدم ۳ — باز کردن جادوگر ✨
دامنه‌ی پنل را در مرورگر باز کنید (مثلاً `https://panel.yoursite.com`) — به‌صورت خودکار به **`/setup`** هدایت می‌شوید و جادوگر فارسی نمایش داده می‌شود:
1. **🔍 بررسی خودکار محیط** — نسخه‌ی Node، قابل‌نوشتن‌بودن `data/` و `.env`، سلامت SQLite (اگر موردی ⛔ بود، معمولاً با درست‌کردن پرمیشن پوشه‌ی `data` به `755/777` رفع می‌شود)
2. **🏪 برند و مدیر** — نام پنل، ایمیل و رمز مدیر، دامنه‌ی پنل
3. **🤖 ربات تلگرام** (اختیاری — قابل رد شدن و تنظیم بعدی)
4. **🚀 نصب خودکار** — سکرت‌های JWT/PANEL_SECRET قوی ساخته و در `.env` ذخیره می‌شوند، دیتابیس آماده و به‌صورت پیش‌فرض با **«شروع تمیز»** (حذف داده‌های نمایشی دمو، حفظ پلن‌ها و گروه‌های آماده) تحویل داده می‌شود؛ سپس سرویس خودش ری‌استارت و به صفحه‌ی ورود هدایت می‌شوید.

> 🔐 بعد از نصب، صفحه‌ی `/setup` برای همیشه **قفل (۴۱۰)** می‌شود. برای نصب دوباره، فایل `data/.install-lock` را حذف و سرویس را ری‌استارت کنید.
> 💡 اگر قسمت «Run NPM Install» نبود: از **Terminal** سی‌پنل دستور `cd panel && npm install --omit=dev` را بزنید، یا از هاست خود بخواهید wkhtmltopdf/نصب نود را انجام دهد.
> 📁 دیتابیس SQLite در `data/panel.db` است — برای بکاپ، کپی از همین پوشه‌ی `data` کافی است (بکاپ‌گیری ابری رمزنگاری‌شده هم داخل پنل فعال است ☁️).

---

راهنمای کامل نصب روی سرور واقعی (Production) و توسعه محلی (Development).

> 🧊 **نصب تازه (فاز ۷):** بوت اول روی دیتابیس خالی، خودش همه‌ی مهاجرت‌ها را اجرا و دادهٔ دمو (فروشنده `demo@panel.local`، نماینده `agent_demo`، ۷ پلن نمونه و نود تست) را seed می‌کند — این مسیر با `scripts/test-coldstart.sh` در CI پوشش داده شده است. دیتابیس در `journal_mode=DELETE` کار می‌کند (سازگار با بکاپ فایلی/اسنپ‌شات). استقرار یک‌دستوری: `docker compose up -d panel` (ولوم `/app/data` برای دیتابیس و سکرت‌ها).

---

> 🧊 **نصب تازه (فاز ۷):** بوت اول روی دیتابیس خالی خودش مهاجرت‌ها را اجرا و دادهٔ دمو (فروشنده/نماینده/پلن‌ها/نود نمونه) را seed می‌کند — با `scripts/test-coldstart.sh` در CI پوشش دارد. دیتابیس SQLite در `journal_mode=DELETE` کار می‌کند (سازگار با اسنپ‌شات/بکاپ فایلی)؛ برای مقیاس خیلی بالا اسکفولد `db-pg.js` (آزمایشی) هست. استقرار یک‌دستوری با `docker compose up -d panel` (ولوم `/app/data` برای دیتابیس و سکرت‌ها).

## ۱) پیش‌نیازها

| مورد | حداقل | توضیح |
|---|---|---|
| **Node.js** | 18+ (پیشنهاد 20) | همراه با npm |
| **سیستم‌عامل** | لینوکس (Ubuntu 20.04+) | برای پنل و نود |
| **RAM** | 512MB (پنل) / 256MB (نود) | خود Xray بسیار کم‌مصرف است |
| **پورت‌ها** | 3000 (پنل) + پورت اینباندها (مثلاً 18443) | فایروال را باز کنید |

```bash
# بررسی نسخه
node -v    # باید v18 به بالا باشد
```

---

## ۲) نصب پنل (سرور مرکزی)

```bash
# کلون/کپی پروژه
cd /home/user/connectix-clone

# نصب وابستگی‌ها (۷ پکیج: express, better-sqlite3, jsonwebtoken, qrcode, web-push + build tools)
npm install --no-audit --no-fund

# بیلد استایل‌ها (Tailwind → public/app.css)
npx tailwindcss -i css/input.css -o public/app.css --minify

# اجرا
PORT=3000 node src/server.js
```

خروجی مورد انتظار:
```
[seed] demo data created → login: demo@panel.local / demo1234
PanelVino running on 0.0.0.0:3000
```

**ورود اولیه:** `demo@panel.local` / `demo1234` — حتماً بعد از ورود از بخش «تنظیمات» رمز را عوض کنید. ✅

> 💾 در اولین اجرا دیتابیس `data/panel.db` به‌همراه ۲۰ جدول و داده‌ی دمو (پلن‌ها، گروه‌ها، کوپن WELCOME10 و…) به‌صورت خودکار ساخته و seed می‌شود. کلید JWT در `data/.jwt-secret` و کلیدهای Web Push در `data/.vapid.json` ذخیره می‌شوند — این دو فایل را در `.gitignore` نگه دارید.

### اجرای دائمی با systemd (پیشنهاد Production)

```ini
# /etc/systemd/system/panelvino.service
[Unit]
Description=PanelVino VPN Seller Panel
After=network-online.target

[Service]
WorkingDirectory=/home/user/connectix-clone
ExecStart=/usr/bin/node src/server.js
Environment=PORT=3000
Restart=always
RestartSec=3
User=root

[Install]
WantedBy=multi-user.target
```

```bash
systemctl daemon-reload
systemctl enable --now panelvino
```

---

## ۳) نصب ایجنت روی هر نود (سرور VPN)

نودها همان سرورهایی هستند که ترافیک VPN کاربران از آن‌ها عبور می‌کند.

### گام ۱ — ساخت نود در پنل
در پنل → بخش **«سرورها»** → «افزودن نود» → یک **agent_token** دریافت می‌کنید.

### گام ۲ — اجرای ایجنت روی سرور نود

```bash
cd /home/user/connectix-clone
PANEL_URL=http://IP-PANEL:3000 \
NODE_TOKEN=<agent_token که از پنل گرفتید> \
node agent/agent.js
```

ایجنت به‌صورت خودکار:
1. **Xray-core** را دانلود و نصب می‌کند (نسخه فعلی 26.3.27) ✅
2. اگر WARP فعال باشد، در Cloudflare **ثبت‌نام واقعی** می‌کند ✅
3. کانفیگ xray را بر اساس اینباندها می‌سازد و اجرا می‌کند ✅
4. هر چند ثانیه Heartbeat + متریک‌های سیستم (CPU/RAM/دیسک) می‌فرستد ✅

### متغیرهای محیطی ایجنت

| متغیر | پیش‌فرض | کاربرد |
|---|---|---|
| `PANEL_URL` | — | آدرس پنل (الزامی) |
| `NODE_TOKEN` | — | توکن نود (الزامی) |
| `AGENT_STATE_DIR` | `/tmp/pv-agent` | مسیر ذخیره xray و warp.json |
| `POLL_MS` | 8000 | فاصله دریافت کانفیگ (میلی‌ثانیه) |
| `IP_CHECK_FIRST_MS` | — | تأخیر اولین چک IP |
| `IP_CHECK_MS` | 600000 | فاصله چک سلامت IP |

### اجرای دائمی ایجنت با systemd

```ini
# /etc/systemd/system/panelvino-agent.service
[Unit]
Description=PanelVino Node Agent
After=network-online.target

[Service]
WorkingDirectory=/home/user/connectix-clone
ExecStart=/usr/bin/node agent/agent.js
Environment=PANEL_URL=http://IP-PANEL:3000
Environment=NODE_TOKEN=PUT_TOKEN_HERE
Environment=AGENT_STATE_DIR=/var/lib/pv-agent
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
```

---

## ۴) ساخت اینباند (ورودی اتصال)

در پنل → سرورها → نود موردنظر → «اینباندها» → افزودن:

| پروتکل | شبکه | توضیح |
|---|---|---|
| **VLESS** | WS / TCP | متر (شمارش ترافیک) به‌صورت واقعی ✅ |
| **Trojan** | WS / TCP | متر واقعی با SHA224 ✅ |
| **Shadowsocks** | TCP | رمز مشترک — بدون متر (محدودیت AEAD) ⚠️ |

پورت را طوری انتخاب کنید که با فایروال تداخل نداشته باشد. پورت عمومی ← متر ← xray (پورت+10000).

---

## ۵) فعال‌سازی WARP (خروجی از پشت Cloudflare)

روی هر نود → دکمه **🌀 WARP** → تمام ترافیک خروجی نود از IP کلادفلر خارج می‌شود (برای دور زدن تحریم/فیلتر IP مقصد).
اگر نود بخواهد IP ثابت داشته باشد، WARP را خاموش کنید.

---

## ۶) ربات تلگرام

1. از @BotFather یک بات بسازید → توکن را بگیرید
2. پنل → تنظیمات → «توکن ربات» → ذخیره → «فعال‌سازی وب‌هوک»
3. پنل باید HTTPS داشته باشد (مسیر مخفی: `/api/telegram/webhook/:sellerId/:secret`)

> بدون HTTPS می‌توانید از «شبیه‌ساز ربات» داخل پنل برای تست استفاده کنید.

---

## ۷) درگاه‌های پرداخت

پنل → تنظیمات → درگاه:

| درگاه | وضعیت | کلید موردنیاز |
|---|---|---|
| **sandbox** 🧪 | تست کامل ✅ | — |
| **zarinpal** | پیاده‌شده ✅ | merchant_id (UUID) |
| **idpay** | پیاده‌شده ✅ | X-API-KEY |
| **zibal** | پیاده‌شده ✅ | merchant |

کال‌بک‌ها:
```
/api/gateway/callback/zarinpal   (GET)
/api/gateway/callback/idpay      (POST form)
/api/gateway/callback/zibal      (GET)
```

---

## ۸) چک‌لیست امنیت Production 🔒

- [ ] رمز `demo@panel.local` را عوض کنید یا کاربر دمو را حذف کنید
- [ ] `data/.jwt-secret` و `data/.vapid.json` خصوصی بمانند (chmod 600)
- [ ] پنل را پشت HTTPS (nginx + certbot) قرار دهید
- [ ] فایروال: فقط پورت 3000 و پورت اینباندها باز باشد
- [ ] بکاپ دوره‌ای از `data/` (دیتابیس + اسناد)
- [ ] توکن API را از بخش تنظیمات بازتولید کنید

---

## ۹) تست سلامت پس از نصب

```bash
# پنل بالاست؟
curl -s http://127.0.0.1:3000/ | head -c 100

# لاگین کار می‌کند؟
curl -s -X POST http://127.0.0.1:3000/api/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"demo@panel.local","password":"demo1234"}'

# ایجنت وصل است؟ (چک CPU/heartbeat در پنل → سرورها)
```

---

## 🔧 عیب‌یابی

| مشکل | علت محتمل | راه‌حل |
|---|---|---|
| `Cannot find module` | وابستگی‌ها نصب نیست | `npm install` |
| صفحه بدون استایل | app.css بیلد نشده | `npx tailwindcss ...` |
| ایجنت وصل نمی‌شود | PANEL_URL یا توکن اشتباه | تولید مجدد توکن در پنل |
| WARP فعال نمی‌شود | دسترسی به api.cloudflareclient.com | چک سیاست شبکه نود |
| ربات آپدیت نمی‌گیرد | وب‌هوک ست نشده | HTTPS + «فعال‌سازی وب‌هوک» |