Seyyed_arc/docs/RQ_WORKER_SETUP.md

راهنمای نصب و راه‌اندازی RQ Worker

فهرست مطالب

1. مقدمه
2. RQ Worker چیست؟
3. نصب و راه‌اندازی
4. مدیریت سرویس
5. بررسی و مانیتورینگ
6. عیب‌یابی
7. ساخت سرویس 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

# بررسی وضعیت Redis
systemctl status redis

# یا
redis-cli ping
# باید پاسخ "PONG" بدهد

اگر Redis فعال نیست:

# نصب 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

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 مراجعه کنید.

مرحله 4: فعال‌سازی سرویس

# 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: بررسی لاگ‌ها

# مشاهده لاگ‌های 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

---

مدیریت سرویس

دستورات پایه

# راه‌اندازی
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

# 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

# وضعیت سرویس
sudo systemctl status hesabix-rq-worker

# بررسی فعال بودن
systemctl is-active hesabix-rq-worker
# باید "active" باشد

# بررسی فعال بودن در startup
systemctl is-enabled hesabix-rq-worker
# باید "enabled" باشد

روش 2: بررسی از طریق Process

# بررسی process
ps aux | grep rq_worker

# یا
pgrep -af rq_worker

روش 3: بررسی از طریق Redis

# اتصال به 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

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)

راه‌حل:

# بررسی لاگ‌های خطا
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.

راه‌حل:

# بررسی 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 خطا نشان می‌دهد

راه‌حل:

# بررسی لاگ‌های خطا
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 بالایی مصرف می‌کند

راه‌حل:

# بررسی تعداد 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

راه‌حل:

# بررسی مالکیت فایل‌ها
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 ذخیره می‌شود:

[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 ای فعال شود

ایجاد دستی سرویس

# ایجاد فایل سرویس
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 (برای کارایی بیشتر):

# ایجاد سرویس‌های متعدد
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 را متوقف کنم؟

پاسخ:

sudo systemctl stop hesabix-rq-worker

Q4: اگر Worker متوقف شود، Jobs چه می‌شوند؟

پاسخ:

• Jobs در Redis Queue باقی می‌مانند
• وقتی Worker دوباره شروع شود، Jobs را پردازش می‌کند
• Jobs ناموفق در rq:failed ذخیره می‌شوند

Q5: چگونه Jobs ناموفق را دوباره اجرا کنم؟

پاسخ:

# از طریق 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:

queues = [
    QUEUE_EMAIL,  # فقط email
    # یا
    QUEUE_HIGH_PRIORITY,  # فقط high priority
]

---

منابع بیشتر

• RQ Documentation
• Systemd Service Files
• Redis Documentation
• Python RQ GitHub

---

پشتیبانی

در صورت بروز مشکل:

1. لاگ‌ها را بررسی کنید
2. مستندات را مطالعه کنید
3. با تیم توسعه تماس بگیرید

---

آخرین به‌روزرسانی: 2025-11-28