forked from hesabix/arc
596 lines
15 KiB
Markdown
Executable file
596 lines
15 KiB
Markdown
Executable file
# راهنمای نصب و راه‌اندازی RQ Worker
|
|
|
|
## فهرست مطالب
|
|
|
|
1. [مقدمه](#مقدمه)
|
|
2. [RQ Worker چیست؟](#rq-worker-چیست)
|
|
3. [نصب و راه‌اندازی](#نصب-و-راه‌اندازی)
|
|
4. [مدیریت سرویس](#مدیریت-سرویس)
|
|
5. [بررسی و مانیتورینگ](#بررسی-و-مانیتورینگ)
|
|
6. [عیب‌یابی](#عیب‌یابی)
|
|
7. [ساخت سرویس Systemd](#ساخت-سرویس-systemd)
|
|
8. [سوالات متداول](#سوالات-متداول)
|
|
|
|
---
|
|
|
|
## مقدمه
|
|
|
|
RQ (Redis Queue) Worker یک سرویس Background است که برای اجرای کارهای زمان‌بر و غیرهمزمان (Asynchronous) در پس‌زمینه استفاده می‌شود. این سرویس باعث می‌شود که API Server مسدود نشود و کارهای سنگین در پس‌زمینه اجرا شوند.
|
|
|
|
---
|
|
|
|
## RQ Worker چیست؟
|
|
|
|
### تعریف
|
|
|
|
**RQ Worker** یک پردازش‌گر Background است که:
|
|
- کارهای زمان‌بر را از Redis Queue دریافت می‌کند
|
|
- آنها را به ترتیب اولویت اجرا می‌کند
|
|
- نتیجه را در Redis ذخیره می‌کند
|
|
- امکان Retry برای کارهای ناموفق را فراهم می‌کند
|
|
|
|
### کاربردهای RQ Worker
|
|
|
|
1. **ارسال ایمیل** (`email` queue)
|
|
- ارسال ایمیل‌های تایید
|
|
- اطلاع‌رسانی‌ها
|
|
- گزارش‌های دوره‌ای
|
|
|
|
2. **تولید گزارش** (`reports` queue)
|
|
- گزارش‌های PDF/Excel
|
|
- گزارش‌های حسابداری
|
|
- آمار و تحلیل‌ها
|
|
|
|
3. **Export داده‌ها** (`exports` queue)
|
|
- Export به Excel
|
|
- Export به CSV
|
|
- Export داده‌های حجیم
|
|
|
|
4. **کارهای با اولویت بالا** (`high` queue)
|
|
- کارهای فوری
|
|
- پردازش‌های مهم
|
|
|
|
5. **کارهای عادی** (`default` queue)
|
|
- کارهای معمولی
|
|
- پردازش‌های استاندارد
|
|
|
|
6. **کارهای با اولویت پایین** (`low` queue)
|
|
- کارهای غیرضروری
|
|
- پاک‌سازی و بهینه‌سازی
|
|
|
|
### مزایا
|
|
|
|
- ✅ جلوگیری از Block شدن API
|
|
- ✅ اجرای همزمان چند کار
|
|
- ✅ اولویت‌بندی کارها
|
|
- ✅ Retry خودکار برای کارهای ناموفق
|
|
- ✅ مانیتورینگ و Logging
|
|
- ✅ مقیاس‌پذیری (چند Worker)
|
|
|
|
---
|
|
|
|
## نصب و راه‌اندازی
|
|
|
|
### پیش‌نیازها
|
|
|
|
1. **Redis** باید نصب و فعال باشد
|
|
2. **Python 3.8+** و Virtual Environment
|
|
3. **RQ Package** در requirements
|
|
4. **دسترسی به Redis** از Worker
|
|
|
|
### مرحله 1: بررسی Redis
|
|
|
|
```bash
|
|
# بررسی وضعیت Redis
|
|
systemctl status redis
|
|
|
|
# یا
|
|
redis-cli ping
|
|
# باید پاسخ "PONG" بدهد
|
|
```
|
|
|
|
اگر Redis فعال نیست:
|
|
|
|
```bash
|
|
# نصب Redis (Ubuntu/Debian)
|
|
sudo apt-get update
|
|
sudo apt-get install redis-server
|
|
|
|
# راه‌اندازی Redis
|
|
sudo systemctl start redis
|
|
sudo systemctl enable redis
|
|
|
|
# بررسی
|
|
redis-cli ping
|
|
```
|
|
|
|
### مرحله 2: بررسی Dependencies
|
|
|
|
```bash
|
|
cd /var/www/ark/hesabixAPI
|
|
source venv/bin/activate
|
|
|
|
# بررسی نصب RQ
|
|
pip list | grep rq
|
|
|
|
# اگر نصب نیست:
|
|
pip install rq redis
|
|
```
|
|
|
|
### مرحله 3: ساخت سرویس Systemd
|
|
|
|
فایل سرویس قبلاً ایجاد شده است: `/etc/systemd/system/hesabix-rq-worker.service`
|
|
|
|
اگر نیاز به ساخت مجدد دارید، به بخش [ساخت سرویس Systemd](#ساخت-سرویس-systemd) مراجعه کنید.
|
|
|
|
### مرحله 4: فعال‌سازی سرویس
|
|
|
|
```bash
|
|
# Reload systemd
|
|
sudo systemctl daemon-reload
|
|
|
|
# فعال کردن startup خودکار
|
|
sudo systemctl enable hesabix-rq-worker
|
|
|
|
# راه‌اندازی سرویس
|
|
sudo systemctl start hesabix-rq-worker
|
|
|
|
# بررسی وضعیت
|
|
sudo systemctl status hesabix-rq-worker
|
|
```
|
|
|
|
### مرحله 5: بررسی لاگ‌ها
|
|
|
|
```bash
|
|
# مشاهده لاگ‌های real-time
|
|
sudo journalctl -u hesabix-rq-worker -f
|
|
|
|
# مشاهده آخرین لاگ‌ها
|
|
sudo journalctl -u hesabix-rq-worker -n 50
|
|
|
|
# مشاهده لاگ‌های امروز
|
|
sudo journalctl -u hesabix-rq-worker --since today
|
|
```
|
|
|
|
---
|
|
|
|
## مدیریت سرویس
|
|
|
|
### دستورات پایه
|
|
|
|
```bash
|
|
# راه‌اندازی
|
|
sudo systemctl start hesabix-rq-worker
|
|
|
|
# متوقف کردن
|
|
sudo systemctl stop hesabix-rq-worker
|
|
|
|
# راه‌اندازی مجدد
|
|
sudo systemctl restart hesabix-rq-worker
|
|
|
|
# مشاهده وضعیت
|
|
sudo systemctl status hesabix-rq-worker
|
|
|
|
# فعال کردن startup خودکار
|
|
sudo systemctl enable hesabix-rq-worker
|
|
|
|
# غیرفعال کردن startup خودکار
|
|
sudo systemctl disable hesabix-rq-worker
|
|
```
|
|
|
|
### مشاهده Logs
|
|
|
|
```bash
|
|
# Real-time logs
|
|
sudo journalctl -u hesabix-rq-worker -f
|
|
|
|
# آخرین 100 خط
|
|
sudo journalctl -u hesabix-rq-worker -n 100
|
|
|
|
# Logs با timestamp
|
|
sudo journalctl -u hesabix-rq-worker --since "1 hour ago"
|
|
|
|
# Logs با grep
|
|
sudo journalctl -u hesabix-rq-worker | grep ERROR
|
|
|
|
# Export logs به فایل
|
|
sudo journalctl -u hesabix-rq-worker > /tmp/rq-worker.log
|
|
```
|
|
|
|
---
|
|
|
|
## بررسی و مانیتورینگ
|
|
|
|
### روش 1: بررسی از طریق Systemd
|
|
|
|
```bash
|
|
# وضعیت سرویس
|
|
sudo systemctl status hesabix-rq-worker
|
|
|
|
# بررسی فعال بودن
|
|
systemctl is-active hesabix-rq-worker
|
|
# باید "active" باشد
|
|
|
|
# بررسی فعال بودن در startup
|
|
systemctl is-enabled hesabix-rq-worker
|
|
# باید "enabled" باشد
|
|
```
|
|
|
|
### روش 2: بررسی از طریق Process
|
|
|
|
```bash
|
|
# بررسی process
|
|
ps aux | grep rq_worker
|
|
|
|
# یا
|
|
pgrep -af rq_worker
|
|
```
|
|
|
|
### روش 3: بررسی از طریق Redis
|
|
|
|
```bash
|
|
# اتصال به Redis
|
|
redis-cli
|
|
|
|
# مشاهده Workers
|
|
KEYS rq:*
|
|
SMEMBERS rq:workers
|
|
|
|
# مشاهده Queues
|
|
KEYS rq:queue:*
|
|
LLEN rq:queue:default
|
|
LLEN rq:queue:high
|
|
LLEN rq:queue:email
|
|
|
|
# مشاهده Jobs
|
|
KEYS rq:job:*
|
|
|
|
# خروج
|
|
exit
|
|
```
|
|
|
|
### روش 4: بررسی از طریق Monitoring UI
|
|
|
|
در صفحه **مانیتورینگ سیستم**:
|
|
1. به تب **سرویس‌ها** بروید
|
|
2. وضعیت **Workers** باید "online" باشد
|
|
3. تعداد Workers و اطلاعات Queues نمایش داده می‌شود
|
|
|
|
### روش 5: تست دستی Worker
|
|
|
|
```bash
|
|
cd /var/www/ark/hesabixAPI
|
|
source venv/bin/activate
|
|
|
|
# اجرای دستی Worker
|
|
python rq_worker.py
|
|
```
|
|
|
|
اگر Worker به درستی کار کند، باید پیامی شبیه این ببینید:
|
|
```
|
|
Starting RQ worker for queues: high, default, email, reports, exports, low
|
|
```
|
|
|
|
---
|
|
|
|
## عیب‌یابی
|
|
|
|
### مشکل 1: Worker شروع نمی‌شود
|
|
|
|
**علائم:**
|
|
```
|
|
● hesabix-rq-worker.service - Hesabix RQ Worker
|
|
Loaded: loaded (/etc/systemd/system/hesabix-rq-worker.service)
|
|
Active: failed (Result: exit-code)
|
|
```
|
|
|
|
**راه‌حل:**
|
|
|
|
```bash
|
|
# بررسی لاگ‌های خطا
|
|
sudo journalctl -u hesabix-rq-worker -n 50
|
|
|
|
# بررسی دسترسی فایل
|
|
ls -la /var/www/ark/hesabixAPI/rq_worker.py
|
|
ls -la /var/www/ark/hesabixAPI/venv/bin/python
|
|
|
|
# بررسی دسترسی کاربر
|
|
sudo -u www-data ls -la /var/www/ark/hesabixAPI/rq_worker.py
|
|
|
|
# تست دستی
|
|
sudo -u www-data /var/www/ark/hesabixAPI/venv/bin/python /var/www/ark/hesabixAPI/rq_worker.py
|
|
```
|
|
|
|
### مشکل 2: Redis Connection Error
|
|
|
|
**علائم:**
|
|
```
|
|
Error: Redis connection not available. Please check Redis configuration.
|
|
```
|
|
|
|
**راه‌حل:**
|
|
|
|
```bash
|
|
# بررسی Redis
|
|
systemctl status redis
|
|
redis-cli ping
|
|
|
|
# بررسی تنظیمات Redis در سیستم
|
|
# در تنظیمات سیستم → Redis Configuration
|
|
|
|
# تست Connection از Python
|
|
cd /var/www/ark/hesabixAPI
|
|
source venv/bin/activate
|
|
python -c "from app.core.queue import get_redis_connection; conn = get_redis_connection(); print('OK' if conn else 'FAILED')"
|
|
```
|
|
|
|
### مشکل 3: Worker متوقف می‌شود (Crash)
|
|
|
|
**علائم:**
|
|
- Worker مدام restart می‌شود
|
|
- Logs خطا نشان می‌دهد
|
|
|
|
**راه‌حل:**
|
|
|
|
```bash
|
|
# بررسی لاگ‌های خطا
|
|
sudo journalctl -u hesabix-rq-worker -n 200 | grep -i error
|
|
|
|
# بررسی Memory
|
|
free -h
|
|
|
|
# بررسی Disk Space
|
|
df -h
|
|
|
|
# بررسی Jobs ناموفق
|
|
redis-cli
|
|
> SMEMBERS rq:failed
|
|
```
|
|
|
|
### مشکل 4: Worker کند است
|
|
|
|
**علائم:**
|
|
- Jobs مدت زمان زیادی در Queue می‌مانند
|
|
- Worker CPU/Memory بالایی مصرف می‌کند
|
|
|
|
**راه‌حل:**
|
|
|
|
```bash
|
|
# بررسی تعداد Jobs در Queue
|
|
redis-cli
|
|
> LLEN rq:queue:default
|
|
> LLEN rq:queue:high
|
|
|
|
# بررسی تعداد Workers
|
|
SMEMBERS rq:workers
|
|
|
|
# اگر تعداد Workers کم است، چند Worker دیگر اضافه کنید
|
|
# (راهنمای اضافه کردن چند Worker در زیر آمده است)
|
|
```
|
|
|
|
### مشکل 5: Permission Denied
|
|
|
|
**علائم:**
|
|
```
|
|
PermissionError: [Errno 13] Permission denied
|
|
```
|
|
|
|
**راه‌حل:**
|
|
|
|
```bash
|
|
# بررسی مالکیت فایل‌ها
|
|
ls -la /var/www/ark/hesabixAPI/
|
|
|
|
# تنظیم مالکیت
|
|
sudo chown -R www-data:www-data /var/www/ark/hesabixAPI/
|
|
|
|
# بررسی دسترسی
|
|
sudo -u www-data ls -la /var/www/ark/hesabixAPI/
|
|
```
|
|
|
|
---
|
|
|
|
## ساخت سرویس Systemd
|
|
|
|
### فایل سرویس Systemd
|
|
|
|
فایل سرویس در مسیر `/etc/systemd/system/hesabix-rq-worker.service` ذخیره می‌شود:
|
|
|
|
```ini
|
|
[Unit]
|
|
Description=Hesabix RQ Worker (Background Jobs)
|
|
Documentation=https://github.com/miguelgrinberg/python-rq
|
|
After=network.target redis.service mysql.service
|
|
Wants=redis.service
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=www-data
|
|
Group=www-data
|
|
WorkingDirectory=/var/www/ark/hesabixAPI
|
|
Environment=PATH=/var/www/ark/hesabixAPI/venv/bin:/usr/local/bin:/usr/bin:/bin
|
|
Environment=PYTHONUNBUFFERED=1
|
|
ExecStart=/var/www/ark/hesabixAPI/venv/bin/python /var/www/ark/hesabixAPI/rq_worker.py
|
|
Restart=always
|
|
RestartSec=10
|
|
StandardOutput=journal
|
|
StandardError=journal
|
|
|
|
# Security settings
|
|
NoNewPrivileges=true
|
|
PrivateTmp=true
|
|
ProtectSystem=strict
|
|
ProtectHome=true
|
|
ReadWritePaths=/var/www/ark/hesabixAPI
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
### توضیحات بخش‌های فایل
|
|
|
|
#### [Unit]
|
|
- **Description**: توضیحات سرویس
|
|
- **After**: سرویس‌هایی که باید قبل از این سرویس شروع شوند
|
|
- **Wants**: سرویس‌های اختیاری (اگر نباشند، سرویس شروع می‌شود)
|
|
|
|
#### [Service]
|
|
- **Type=simple**: نوع سرویس (simple برای script های معمولی)
|
|
- **User/Group**: کاربر و گروه که سرویس با آن اجرا می‌شود
|
|
- **WorkingDirectory**: مسیر کاری
|
|
- **Environment**: متغیرهای محیطی
|
|
- **ExecStart**: دستور اجرای سرویس
|
|
- **Restart=always**: همیشه restart شود در صورت crash
|
|
- **RestartSec=10**: 10 ثانیه صبر قبل از restart
|
|
- **StandardOutput/Error**: خروجی به journal برود
|
|
|
|
#### [Install]
|
|
- **WantedBy**: سرویس در چه target ای فعال شود
|
|
|
|
### ایجاد دستی سرویس
|
|
|
|
```bash
|
|
# ایجاد فایل سرویس
|
|
sudo nano /etc/systemd/system/hesabix-rq-worker.service
|
|
|
|
# یا استفاده از cat
|
|
sudo tee /etc/systemd/system/hesabix-rq-worker.service > /dev/null <<'EOF'
|
|
[Unit]
|
|
Description=Hesabix RQ Worker (Background Jobs)
|
|
After=network.target redis.service mysql.service
|
|
Wants=redis.service
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=www-data
|
|
Group=www-data
|
|
WorkingDirectory=/var/www/ark/hesabixAPI
|
|
Environment=PATH=/var/www/ark/hesabixAPI/venv/bin
|
|
Environment=PYTHONUNBUFFERED=1
|
|
ExecStart=/var/www/ark/hesabixAPI/venv/bin/python /var/www/ark/hesabixAPI/rq_worker.py
|
|
Restart=always
|
|
RestartSec=10
|
|
StandardOutput=journal
|
|
StandardError=journal
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
EOF
|
|
|
|
# تنظیم دسترسی
|
|
sudo chmod 644 /etc/systemd/system/hesabix-rq-worker.service
|
|
|
|
# Reload systemd
|
|
sudo systemctl daemon-reload
|
|
|
|
# فعال کردن
|
|
sudo systemctl enable hesabix-rq-worker
|
|
sudo systemctl start hesabix-rq-worker
|
|
```
|
|
|
|
### اجرای چند Worker
|
|
|
|
برای اجرای چند Worker (برای کارایی بیشتر):
|
|
|
|
```bash
|
|
# ایجاد سرویس‌های متعدد
|
|
sudo cp /etc/systemd/system/hesabix-rq-worker.service /etc/systemd/system/hesabix-rq-worker-1.service
|
|
sudo cp /etc/systemd/system/hesabix-rq-worker.service /etc/systemd/system/hesabix-rq-worker-2.service
|
|
|
|
# تغییر Description و نام سرویس
|
|
sudo sed -i 's/Hesabix RQ Worker/Hesabix RQ Worker 1/g' /etc/systemd/system/hesabix-rq-worker-1.service
|
|
sudo sed -i 's/hesabix-rq-worker/hesabix-rq-worker-1/g' /etc/systemd/system/hesabix-rq-worker-1.service
|
|
|
|
# راه‌اندازی
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable hesabix-rq-worker-1 hesabix-rq-worker-2
|
|
sudo systemctl start hesabix-rq-worker-1 hesabix-rq-worker-2
|
|
```
|
|
|
|
یا استفاده از **Supervisor** برای مدیریت چند Worker.
|
|
|
|
---
|
|
|
|
## سوالات متداول
|
|
|
|
### Q1: چه تعداد Worker نیاز دارم؟
|
|
|
|
**پاسخ:**
|
|
- برای شروع: **1 Worker** کافی است
|
|
- برای بار متوسط: **2-3 Worker**
|
|
- برای بار بالا: **5-10 Worker**
|
|
- **توجه**: تعداد Worker نباید بیشتر از تعداد CPU Cores باشد
|
|
|
|
### Q2: Worker چقدر Memory مصرف می‌کند؟
|
|
|
|
**پاسخ:**
|
|
- هر Worker معمولاً **50-200 MB** Memory مصرف می‌کند
|
|
- بستگی به نوع Jobs دارد
|
|
|
|
### Q3: چگونه Worker را متوقف کنم؟
|
|
|
|
**پاسخ:**
|
|
```bash
|
|
sudo systemctl stop hesabix-rq-worker
|
|
```
|
|
|
|
### Q4: اگر Worker متوقف شود، Jobs چه می‌شوند؟
|
|
|
|
**پاسخ:**
|
|
- Jobs در Redis Queue باقی می‌مانند
|
|
- وقتی Worker دوباره شروع شود، Jobs را پردازش می‌کند
|
|
- Jobs ناموفق در `rq:failed` ذخیره می‌شوند
|
|
|
|
### Q5: چگونه Jobs ناموفق را دوباره اجرا کنم؟
|
|
|
|
**پاسخ:**
|
|
```python
|
|
# از طریق Python
|
|
from rq import Queue, Worker
|
|
from app.core.queue import get_redis_connection
|
|
|
|
redis_conn = get_redis_connection()
|
|
failed_queue = Queue('failed', connection=redis_conn)
|
|
|
|
# مشاهده Jobs ناموفق
|
|
failed_jobs = failed_queue.get_jobs()
|
|
|
|
# Retry یک Job
|
|
job = failed_queue.get_job(job_id)
|
|
job.retry()
|
|
```
|
|
|
|
### Q6: چگونه Worker را برای Queue خاص تنظیم کنم؟
|
|
|
|
**پاسخ:**
|
|
ویرایش فایل `rq_worker.py`:
|
|
```python
|
|
queues = [
|
|
QUEUE_EMAIL, # فقط email
|
|
# یا
|
|
QUEUE_HIGH_PRIORITY, # فقط high priority
|
|
]
|
|
```
|
|
|
|
---
|
|
|
|
## منابع بیشتر
|
|
|
|
- [RQ Documentation](https://python-rq.org/)
|
|
- [Systemd Service Files](https://www.freedesktop.org/software/systemd/man/systemd.service.html)
|
|
- [Redis Documentation](https://redis.io/documentation)
|
|
- [Python RQ GitHub](https://github.com/rq/rq)
|
|
|
|
---
|
|
|
|
## پشتیبانی
|
|
|
|
در صورت بروز مشکل:
|
|
1. لاگ‌ها را بررسی کنید
|
|
2. مستندات را مطالعه کنید
|
|
3. با تیم توسعه تماس بگیرید
|
|
|
|
---
|
|
|
|
**آخرین به‌روزرسانی:** 2025-11-28
|
|
|