# CryptoBot — دليل التثبيت الكامل

> **المشروع:** Binance Crypto Trading Bot  
> **Stack:** FastAPI (Python 3.11) + React/Vite (Node 20) + MySQL + Redis  
> **السيرفر:** Ubuntu 20.04 / 22.04  
> **المنافذ المستخدمة:** Backend `8002` | Frontend `3000` | Apache Proxy `8080`

---

## قسم أ: متطلبات السيرفر

| المكوّن | الإصدار المطلوب | الحالة |
|---------|----------------|--------|
| Ubuntu | 20.04 أو 22.04 | مطلوب |
| Python | 3.11+ | يُثبَّت في الخطوة 2 |
| Node.js | 20+ | يُثبَّت في الخطوة 3 |
| MySQL | 8.0 | موجود على port 3306 |
| Redis | 6+ | موجود على port 6379 (Docker) |
| Apache2 | 2.4+ | موجود على 80, 443, 8080 |

### المنافذ المحجوزة على السيرفر (لا تستخدمها)
```
22, 80, 443, 8080, 8000, 8001, 3306, 6379, 5432, 5433, 9000, 9001
```
المنافذ التي سيستخدمها المشروع: **8002** (Backend) و **3000** (Frontend)

---

## قسم ب: خطوات التثبيت

---

### الخطوة 1: رفع الملفات للسيرفر

**من جهازك المحلي (Windows):**
```bash
# رفع Backend
scp -r C:\Users\User\Documents\claude\crypto-bot\backend root@YOUR_SERVER_IP:/var/www/html/crypto-bot/

# رفع ملفات الـ Deployment
scp C:\Users\User\Documents\claude\crypto-bot\apache-cryptobot.conf root@YOUR_SERVER_IP:/var/www/html/crypto-bot/

# رفع Frontend (من مجلده المنفصل)
scp -r C:\Users\User\crypto-bot\frontend root@YOUR_SERVER_IP:/var/www/html/crypto-bot/
```

أو باستخدام rsync (أسرع):
```bash
rsync -avz --exclude='node_modules' --exclude='venv' --exclude='__pycache__' \
  /c/Users/User/Documents/claude/crypto-bot/ \
  root@YOUR_SERVER_IP:/var/www/html/crypto-bot/
```

**التحقق على السيرفر:**
```bash
ls /var/www/html/crypto-bot/
# يجب أن ترى: backend/  frontend/  apache-cryptobot.conf  INSTALL.md
```

---

### الخطوة 2: تثبيت Python 3.11

```bash
# إضافة PPA
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update

# تثبيت Python 3.11
sudo apt install python3.11 python3.11-venv python3.11-pip -y

# التحقق
python3.11 --version
# يجب أن يظهر: Python 3.11.x
```

---

### الخطوة 3: تثبيت Node.js 20

```bash
# إضافة NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# تثبيت Node.js
sudo apt install nodejs -y

# التحقق
node --version   # يجب أن يظهر: v20.x.x
npm --version    # يجب أن يظهر: 10.x.x
```

---

### الخطوة 4: إعداد قاعدة البيانات

```bash
# الدخول لـ MySQL كـ root
sudo mysql -u root -p
```

داخل MySQL:
```sql
-- إنشاء قاعدة البيانات
CREATE DATABASE IF NOT EXISTS cryptobot
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

-- إنشاء مستخدم مخصص
CREATE USER IF NOT EXISTS 'cryptobot_user'@'localhost'
  IDENTIFIED BY 'STRONG_PASSWORD_HERE';

-- منح الصلاحيات
GRANT ALL PRIVILEGES ON cryptobot.* TO 'cryptobot_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

تشغيل سكريبت الجداول:
```bash
sudo mysql -u cryptobot_user -p cryptobot \
  < /var/www/html/crypto-bot/backend/init_db.sql

# تحقق من إنشاء الجداول
sudo mysql -u cryptobot_user -p cryptobot -e "SHOW TABLES;"
```

---

### الخطوة 5: إعداد Backend

```bash
cd /var/www/html/crypto-bot/backend

# إنشاء virtual environment
python3.11 -m venv venv

# تفعيل البيئة
source venv/bin/activate

# تحديث pip
pip install --upgrade pip

# تثبيت المكتبات
pip install -r requirements.txt
```

إعداد ملف البيئة:
```bash
# نسخ الملف النموذجي
cp .env.example .env

# تعديل القيم
nano .env
```

القيم المطلوب تعديلها في `.env`:
```env
# قاعدة البيانات
DATABASE_URL=mysql+aiomysql://cryptobot_user:STRONG_PASSWORD_HERE@localhost:3306/cryptobot

# Binance API (من https://www.binance.com/en/my/settings/api-management)
BINANCE_API_KEY=your_actual_api_key_here
BINANCE_SECRET_KEY=your_actual_secret_key_here

# Telegram Bot (من @BotFather على تيليغرام)
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

# Redis (موجود بالفعل)
REDIS_URL=redis://localhost:6379/0

# إعدادات التطبيق
SECRET_KEY=generate_a_random_64_char_string_here
DEBUG=False
```

توليد `SECRET_KEY` عشوائي:
```bash
python3.11 -c "import secrets; print(secrets.token_hex(32))"
```

---

### الخطوة 6: اختبار Backend

```bash
cd /var/www/html/crypto-bot/backend
source venv/bin/activate

# تشغيل مؤقت للاختبار
uvicorn app.main:app --host 0.0.0.0 --port 8002

# في terminal آخر، اختبر:
curl http://localhost:8002/api/v1/bot/status
# المتوقع: {"status": "stopped", "mode": "SIMULATION"}

# أو افتح في المتصفح:
# http://YOUR_SERVER_IP:8002/docs  (Swagger UI)

# اضغط Ctrl+C للإيقاف بعد الاختبار
```

---

### الخطوة 7: تشغيل Backend كـ Systemd Service

إنشاء ملف الـ service:
```bash
sudo nano /etc/systemd/system/cryptobot-backend.service
```

المحتوى:
```ini
[Unit]
Description=CryptoBot FastAPI Backend
After=network.target mysql.service

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/html/crypto-bot/backend
Environment="PATH=/var/www/html/crypto-bot/backend/venv/bin"
EnvironmentFile=/var/www/html/crypto-bot/backend/.env
ExecStart=/var/www/html/crypto-bot/backend/venv/bin/uvicorn \
    app.main:app \
    --host 0.0.0.0 \
    --port 8002 \
    --workers 1
Restart=always
RestartSec=3
StandardOutput=journal
StandardError=journal

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

تفعيل وتشغيل الـ service:
```bash
# منح الصلاحيات لـ www-data
sudo chown -R www-data:www-data /var/www/html/crypto-bot/

# تحميل الإعدادات الجديدة
sudo systemctl daemon-reload

# تفعيل التشغيل التلقائي عند إعادة التشغيل
sudo systemctl enable cryptobot-backend

# تشغيل الـ service
sudo systemctl start cryptobot-backend

# التحقق من الحالة
sudo systemctl status cryptobot-backend
```

---

### الخطوة 8: إعداد Frontend

```bash
cd /var/www/html/crypto-bot/frontend

# تثبيت الحزم
npm install

# بناء نسخة الإنتاج (Vite يبني في مجلد dist/)
npm run build

# التحقق من نتيجة البناء
ls dist/
# يجب أن ترى: index.html  assets/
```

تثبيت serve لخدمة الـ build:
```bash
sudo npm install -g serve
```

اختبار يدوي:
```bash
serve -s dist -l 3000

# في terminal آخر:
curl -I http://localhost:3000
# المتوقع: HTTP/1.1 200 OK

# اضغط Ctrl+C بعد الاختبار
```

---

### الخطوة 9: تشغيل Frontend كـ Systemd Service

```bash
sudo nano /etc/systemd/system/cryptobot-frontend.service
```

المحتوى:
```ini
[Unit]
Description=CryptoBot React Frontend
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/html/crypto-bot/frontend
ExecStart=/usr/bin/serve -s dist -l 3000
Restart=always
RestartSec=3
StandardOutput=journal
StandardError=journal

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

تفعيل وتشغيل:
```bash
sudo systemctl daemon-reload
sudo systemctl enable cryptobot-frontend
sudo systemctl start cryptobot-frontend
sudo systemctl status cryptobot-frontend
```

---

### الخطوة 10: إعداد Apache Reverse Proxy

تفعيل الـ modules المطلوبة:
```bash
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_wstunnel
sudo a2enmod headers
sudo a2enmod rewrite

# التحقق من تفعيل الـ modules
apache2ctl -M | grep -E "proxy|headers|rewrite"
```

نسخ وتفعيل ملف الإعداد:
```bash
# نسخ ملف الإعداد
sudo cp /var/www/html/crypto-bot/apache-cryptobot.conf \
        /etc/apache2/sites-available/cryptobot.conf

# تعديل اسم الدومين (اختياري)
sudo nano /etc/apache2/sites-available/cryptobot.conf
# غيّر: ServerName cryptobot.yourdomain.com
# إلى:  ServerName YOUR_ACTUAL_DOMAIN_OR_IP

# تفعيل الموقع
sudo a2ensite cryptobot

# اختبار صحة الإعداد
sudo apache2ctl configtest
# يجب أن يظهر: Syntax OK

# إعادة تحميل Apache
sudo systemctl reload apache2
```

---

### الخطوة 11: التحقق النهائي

```bash
# 1. تحقق من حالة الـ services
sudo systemctl status cryptobot-backend cryptobot-frontend

# 2. تحقق من Backend مباشرة
curl http://localhost:8002/api/v1/bot/status
# المتوقع: {"status":"stopped","mode":"SIMULATION",...}

# 3. تحقق من Frontend مباشرة
curl -I http://localhost:3000
# المتوقع: HTTP/1.1 200 OK

# 4. تحقق من Apache Proxy
curl http://localhost:8080/api/v1/bot/status
# المتوقع: نفس استجابة Backend

# 5. تحقق من WebSocket endpoint
curl -I http://localhost:8080/ws/
# المتوقع: 200 أو 426 (Upgrade Required — طبيعي لـ WS)

# 6. افتح الواجهة في المتصفح
# http://YOUR_SERVER_IP:8080
```

---

## قسم ج: استكشاف الأخطاء

### جدول المشاكل الشائعة

| المشكلة | التشخيص | الحل |
|---------|---------|------|
| Backend لا يبدأ | `sudo journalctl -u cryptobot-backend -n 50` | تحقق من `.env` و `requirements.txt` |
| خطأ في الاتصال بـ MySQL | `journalctl -u cryptobot-backend \| grep mysql` | تحقق من `DATABASE_URL` في `.env` |
| Port 8002 مستخدم | `sudo lsof -i :8002` | `sudo kill -9 PID` ثم أعد التشغيل |
| خطأ CCXT / Binance | `journalctl -u cryptobot-backend \| grep ccxt` | تحقق من `BINANCE_API_KEY` و `BINANCE_SECRET_KEY` |
| WebSocket لا يتصل | `sudo a2enmod proxy_wstunnel && sudo systemctl reload apache2` | تأكد من تفعيل proxy_wstunnel |
| Frontend يظهر صفحة بيضاء | `curl http://localhost:3000` | تحقق من أن `npm run build` اكتمل بنجاح |
| Apache يعطي 502 Bad Gateway | `curl http://localhost:8002/` | تأكد أن Backend يعمل أولاً |
| صلاحيات الملفات | `sudo journalctl -u cryptobot-backend \| grep Permission` | `sudo chown -R www-data:www-data /var/www/html/crypto-bot/` |

### أوامر تشخيص مفيدة

```bash
# مشاهدة لوج Backend في الوقت الحقيقي
sudo journalctl -u cryptobot-backend -f

# مشاهدة لوج Frontend
sudo journalctl -u cryptobot-frontend -f

# لوج Apache
sudo tail -f /var/log/apache2/cryptobot-error.log
sudo tail -f /var/log/apache2/cryptobot-access.log

# التحقق من المنافذ المفتوحة
sudo ss -tlnp | grep -E "3000|8002|8080"

# التحقق من Redis
redis-cli ping
# المتوقع: PONG

# التحقق من MySQL
mysql -u cryptobot_user -p -e "SELECT 1" cryptobot
```

---

## قسم د: أوامر الإدارة اليومية

### إيقاف وتشغيل الخدمات

```bash
# إيقاف
sudo systemctl stop cryptobot-backend cryptobot-frontend

# تشغيل
sudo systemctl start cryptobot-backend cryptobot-frontend

# إعادة تشغيل
sudo systemctl restart cryptobot-backend cryptobot-frontend

# حالة تفصيلية
sudo systemctl status cryptobot-backend -l
```

### تحديث المشروع

```bash
# 1. رفع الملفات الجديدة من الجهاز المحلي
rsync -avz --exclude='node_modules' --exclude='venv' \
  /c/Users/User/Documents/claude/crypto-bot/backend/ \
  root@YOUR_SERVER_IP:/var/www/html/crypto-bot/backend/

# 2. على السيرفر — تحديث Backend
cd /var/www/html/crypto-bot/backend
source venv/bin/activate
pip install -r requirements.txt
sudo systemctl restart cryptobot-backend

# 3. تحديث Frontend
cd /var/www/html/crypto-bot/frontend
npm install
npm run build
sudo systemctl restart cryptobot-frontend
```

### مراقبة الاستخدام

```bash
# استخدام CPU و RAM
htop

# مساحة القرص
df -h /var/www/html/crypto-bot/

# حجم لوجات الـ journal
sudo journalctl --disk-usage

# تنظيف اللوجات القديمة (أكثر من 7 أيام)
sudo journalctl --vacuum-time=7d
```

---

## ملاحظات مهمة

1. **لا تستخدم** المنافذ 80، 443، 8080، 8000، 8001 للـ Backend أو Frontend — محجوزة.
2. **احتفظ بنسخة احتياطية** من ملف `.env` في مكان آمن (لا ترفعه لـ git).
3. **Binance API Keys** في وضع الاختبار استخدم testnet أولاً: `https://testnet.binance.vision/`
4. **وضع الـ Simulation** هو الوضع الافتراضي — لن يتم تنفيذ صفقات حقيقية حتى تغير `TRADING_MODE=LIVE` في `.env`.
5. **Redis** يجب أن يعمل قبل تشغيل Backend — تحقق دائماً بـ `redis-cli ping`.

---

*دليل التثبيت — CryptoBot v1.0 — 2026*