راه‌اندازی Multi-Worker

حالت Multi-Worker پاسارگارد پنل را به سرویس‌های جدا تقسیم می‌کند تا ترافیک API و کارهای پس‌زمینه مستقل اجرا شوند. این کار کارایی را بهتر می‌کند و مانع از مسدود شدن داشبورد توسط کارهای طولانی می‌شود.

در مثال‌های زیر، فایل‌های docker-compose.yml و .env در مسیر /opt/pasarguard قرار دارند و داده‌ها در /var/lib/pasarguard ذخیره می‌شوند.

Multi-Worker چه چیزهایی را اجرا می‌کند

نقش	کاربرد
`backend`	API HTTP + داشبورد + اجرای مهاجرت‌ها
`node`	عملیات مربوط به نودها، لاگ‌ها و وظایف وابسته به نود
`scheduler`	کارهای زمان‌بندی‌شده، نوتیفیکیشن‌ها و پردازش صف‌ها

چه زمانی استفاده کنیم

تعداد نود/کاربر زیاد دارید و پاسخ‌گویی بهتر می‌خواهید.
می‌خواهید کارهای زمان‌بندی‌شده از ترافیک API جدا باشند.
می‌خواهید تعداد workerهای API را جداگانه افزایش دهید.

پیش‌نیازها

NATS برای هماهنگی بین workerها الزامی است.
همه سرویس‌ها باید از یک پایگاه داده مشترک استفاده کنند.
همه workerها باید مسیر /var/lib/pasarguard را مشترک داشته باشند (قالب‌ها، گواهی‌ها، فایل‌های زمان اجرا).

حالت Multi-Worker نیازمند NATS_ENABLED=True است. اگر NATS غیرفعال باشد، workerهای node/scheduler نمی‌توانند با backend هماهنگ شوند.

مرحله ۱: آماده‌سازی `.env`

این حداقل تنظیمات است. بخش پایگاه داده را از تب انتخابی خود اضافه کنید.

# NATS
NATS_ENABLED = True
NATS_URL = "nats://127.0.0.1:4222"

# Web server
# UVICORN_PORT = 8000

# Optional: Uvicorn processes inside the backend container
# UVICORN_WORKERS = 2

# Database connection (set per database section)
# SQLALCHEMY_DATABASE_URL = "..."

# Pooling (per worker process)
# SQLALCHEMY_POOL_SIZE = 10
# SQLALCHEMY_MAX_OVERFLOW = 30

ROLE در docker-compose.yml برای هر سرویس تعیین می‌شود. هنگام استفاده از فایل‌های Multi-Worker، آن را در .env تنظیم نکنید.

مرحله ۲: انتخاب پایگاه داده

docker-compose.yml

services:
    nats:
        image: nats:2.10-alpine
        restart: unless-stopped
        command: ["-js"]
        ports:
            - "4222:4222"
        volumes:
            - nats-data:/data
        healthcheck:
            test: ["CMD", "nc", "-z", "localhost", "4222"]
            interval: 2s
            timeout: 2s
            retries: 10
            start_period: 30s

    pasarguard:
        container_name: pasarguard
        image: pasarguard/panel:latest
        restart: unless-stopped
        env_file: .env
        network_mode: host
        environment:
            ROLE: backend
        depends_on:
            nats:
                condition: service_healthy
            pgbouncer:
                condition: service_healthy
        volumes:
            - /var/lib/pasarguard:/var/lib/pasarguard
        healthcheck:
            test: ["CMD", "/code/healthcheck.sh"]
            interval: 5s
            timeout: 5s
            retries: 10
            start_period: 60s

    node-worker:
        container_name: node-worker
        image: pasarguard/panel:latest
        restart: unless-stopped
        env_file: .env
        network_mode: host
        environment:
            ROLE: node
        depends_on:
            pasarguard:
                condition: service_healthy
        volumes:
            - /var/lib/pasarguard:/var/lib/pasarguard

    scheduler:
        container_name: scheduler
        image: pasarguard/panel:latest
        restart: unless-stopped
        env_file: .env
        network_mode: host
        environment:
            ROLE: scheduler
        depends_on:
            pasarguard:
                condition: service_healthy
        volumes:
            - /var/lib/pasarguard:/var/lib/pasarguard

    timescaledb:
        image: timescale/timescaledb:latest-pg17
        restart: always
        command: >
            postgres -c max_connections=${PG_MAX_CONNECTIONS:-400}
                     -c shared_buffers=${PG_SHARED_BUFFERS:-512MB}
                     -c work_mem=${PG_WORK_MEM:-32MB}
        environment:
            POSTGRES_DB: ${DB_NAME}
            POSTGRES_USER: ${DB_USER}
            POSTGRES_PASSWORD: ${DB_PASSWORD}
        ports:
            - "127.0.0.1:5432:5432"
        volumes:
            - /var/lib/postgresql/pasarguard:/var/lib/postgresql/data
        healthcheck:
            test: ["CMD-SHELL", "pg_isready -q -d ${DB_NAME} -U ${DB_USER}"]
            interval: 10s
            timeout: 5s
            retries: 5
        networks:
            - pg_backend
    pgbouncer:
        image: edoburu/pgbouncer:latest
        restart: always
        environment:
            DB_HOST: timescaledb
            DB_PORT: 5432
            DB_USER: ${DB_USER}
            DB_PASSWORD: ${DB_PASSWORD}
            DB_NAME: ${DB_NAME}
            LISTEN_PORT: 6432
            POOL_MODE: transaction
            MAX_CLIENT_CONN: ${PG_MAX_CLIENT_CONN:-700}
            DEFAULT_POOL_SIZE: ${PG_DEFAULT_POOL_SIZE:-50}
            RESERVE_POOL_SIZE: ${PG_RESERVE_POOL_SIZE:-50}
            AUTH_TYPE: scram-sha-256
            LOG_CONNECTIONS: 0
            LOG_DISCONNECTIONS: 0
            LOG_POOLER_ERRORS: 0
            VERBOSE: 0
        ports:
            - "127.0.0.1:6432:6432"
        depends_on:
            timescaledb:
                condition: service_healthy
        healthcheck:
            test: ["CMD-SHELL", "pgrep -f pgbouncer > /dev/null"]
            interval: 10s
            timeout: 5s
            retries: 5
            start_period: 10s
        networks:
            - pg_backend

    pgadmin:
        image: dpage/pgadmin4:latest
        container_name: pgadmin
        restart: unless-stopped
        network_mode: host
        environment:
            PGADMIN_DEFAULT_EMAIL: ${PGADMIN_EMAIL}
            PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD}
            PGADMIN_LISTEN_ADDRESS: 127.0.0.1
            PGADMIN_LISTEN_PORT: 8010
        volumes:
            - pgadmin:/var/lib/pgadmin
        depends_on:
            timescaledb:
                condition: service_healthy

volumes:
    pgadmin:
    nats-data:
networks:
    pg_backend:
        driver: bridge

docker-compose.yml

services:
    nats:
        image: nats:2.10-alpine
        restart: unless-stopped
        command: ["-js"]
        ports:
            - "4222:4222"
        volumes:
            - nats-data:/data
        healthcheck:
            test: ["CMD", "nc", "-z", "localhost", "4222"]
            interval: 2s
            timeout: 2s
            retries: 10
            start_period: 30s

    pasarguard:
        container_name: pasarguard
        image: pasarguard/panel:latest
        restart: unless-stopped
        env_file: .env
        network_mode: host
        environment:
            ROLE: backend
        depends_on:
            nats:
                condition: service_healthy
            pgbouncer:
                condition: service_healthy
        volumes:
            - /var/lib/pasarguard:/var/lib/pasarguard
        healthcheck:
            test: ["CMD", "/code/healthcheck.sh"]
            interval: 5s
            timeout: 5s
            retries: 10
            start_period: 60s

    node-worker:
        container_name: node-worker
        image: pasarguard/panel:latest
        restart: unless-stopped
        env_file: .env
        network_mode: host
        environment:
            ROLE: node
        depends_on:
            pasarguard:
                condition: service_healthy
        volumes:
            - /var/lib/pasarguard:/var/lib/pasarguard

    scheduler:
        container_name: scheduler
        image: pasarguard/panel:latest
        restart: unless-stopped
        env_file: .env
        network_mode: host
        environment:
            ROLE: scheduler
        depends_on:
            pasarguard:
                condition: service_healthy
        volumes:
            - /var/lib/pasarguard:/var/lib/pasarguard

    postgresql:
        image: postgres:latest
        restart: always
        command: >
            postgres -c max_connections=${PG_MAX_CONNECTIONS:-400}
                     -c shared_buffers=${PG_SHARED_BUFFERS:-512MB}
                     -c work_mem=${PG_WORK_MEM:-32MB}
        environment:
            POSTGRES_DB: ${DB_NAME}
            POSTGRES_USER: ${DB_USER}
            POSTGRES_PASSWORD: ${DB_PASSWORD}
        ports:
            - "127.0.0.1:5432:5432"
        volumes:
            - /var/lib/postgresql/pasarguard:/var/lib/postgresql
        healthcheck:
            test: ["CMD-SHELL", "pg_isready -q -d ${DB_NAME} -U ${DB_USER}"]
            interval: 10s
            timeout: 5s
            retries: 5
        networks:
            - pg_backend
    pgbouncer:
        image: edoburu/pgbouncer:latest
        restart: always
        environment:
            DB_HOST: postgresql
            DB_PORT: 5432
            DB_USER: ${DB_USER}
            DB_PASSWORD: ${DB_PASSWORD}
            DB_NAME: ${DB_NAME}
            LISTEN_PORT: 6432
            POOL_MODE: transaction
            MAX_CLIENT_CONN: ${PG_MAX_CLIENT_CONN:-700}
            DEFAULT_POOL_SIZE: ${PG_DEFAULT_POOL_SIZE:-50}
            RESERVE_POOL_SIZE: ${PG_RESERVE_POOL_SIZE:-50}
            AUTH_TYPE: scram-sha-256
            LOG_CONNECTIONS: 0
            LOG_DISCONNECTIONS: 0
            LOG_POOLER_ERRORS: 0
            VERBOSE: 0
        ports:
            - "127.0.0.1:6432:6432"
        depends_on:
            postgresql:
                condition: service_healthy
        healthcheck:
            test: ["CMD-SHELL", "pgrep -f pgbouncer > /dev/null"]
            interval: 10s
            timeout: 5s
            retries: 5
            start_period: 10s
        networks:
            - pg_backend

    pgadmin:
        image: dpage/pgadmin4:latest
        container_name: pgadmin
        restart: unless-stopped
        network_mode: host
        environment:
            PGADMIN_DEFAULT_EMAIL: ${PGADMIN_EMAIL}
            PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD}
            PGADMIN_LISTEN_ADDRESS: 127.0.0.1
            PGADMIN_LISTEN_PORT: 8010
        volumes:
            - pgadmin:/var/lib/pgadmin
        depends_on:
            postgresql:
                condition: service_healthy

volumes:
    pgadmin:
    nats-data:
networks:
    pg_backend:
        driver: bridge

docker-compose.yml

services:
    nats:
        image: nats:2.10-alpine
        restart: unless-stopped
        command: ["-js"]
        ports:
            - "4222:4222"
        volumes:
            - nats-data:/data
        healthcheck:
            test: ["CMD", "nc", "-z", "localhost", "4222"]
            interval: 2s
            timeout: 2s
            retries: 10
            start_period: 30s

    pasarguard:
        container_name: pasarguard
        image: pasarguard/panel:latest
        restart: unless-stopped
        env_file: .env
        network_mode: host
        environment:
            ROLE: backend
        depends_on:
            nats:
                condition: service_healthy
            mysql:
                condition: service_healthy
        volumes:
            - /var/lib/pasarguard:/var/lib/pasarguard
        healthcheck:
            test: ["CMD", "/code/healthcheck.sh"]
            interval: 5s
            timeout: 5s
            retries: 10
            start_period: 60s

    node-worker:
        container_name: node-worker
        image: pasarguard/panel:latest
        restart: unless-stopped
        env_file: .env
        network_mode: host
        environment:
            ROLE: node
        depends_on:
            pasarguard:
                condition: service_healthy
        volumes:
            - /var/lib/pasarguard:/var/lib/pasarguard

    scheduler:
        container_name: scheduler
        image: pasarguard/panel:latest
        restart: unless-stopped
        env_file: .env
        network_mode: host
        environment:
            ROLE: scheduler
        depends_on:
            pasarguard:
                condition: service_healthy
        volumes:
            - /var/lib/pasarguard:/var/lib/pasarguard

    mysql:
        image: mysql:lts
        restart: always
        environment:
            MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
            MYSQL_ROOT_HOST: "%"
            MYSQL_DATABASE: ${DB_NAME}
            MYSQL_USER: ${DB_USER}
            MYSQL_PASSWORD: ${DB_PASSWORD}
        command:
            - --mysqlx=OFF
            - --bind-address=0.0.0.0
            - --character_set_server=utf8mb4
            - --collation_server=utf8mb4_unicode_ci
            - --log-bin=mysql-bin
            - --skip-log-bin
            - --binlog_expire_logs_seconds=1209600
            - --host-cache-size=0
            - --innodb-open-files=1024
            - --innodb-buffer-pool-size=256M
            - --innodb-log-file-size=64M
            - --innodb-log-files-in-group=2
            - --general_log=0
            - --slow_query_log=1
            - --slow_query_log_file=/var/lib/mysql/slow.log
            - --long_query_time=2
        ports:
            - "127.0.0.1:3306:3306"
        volumes:
            - /var/lib/mysql/pasarguard:/var/lib/mysql
        healthcheck:
            test:
                [
                    "CMD",
                    "mysqladmin",
                    "ping",
                    "-h",
                    "127.0.0.1",
                    "-u",
                    "${DB_USER}",
                    "--password=${DB_PASSWORD}",
                ]
            start_period: 5s
            interval: 5s
            timeout: 5s
            retries: 55

volumes:
    nats-data:

docker-compose.yml

services:
    nats:
        image: nats:2.10-alpine
        restart: unless-stopped
        command: ["-js"]
        ports:
            - "4222:4222"
        volumes:
            - nats-data:/data
        healthcheck:
            test: ["CMD", "nc", "-z", "localhost", "4222"]
            interval: 2s
            timeout: 2s
            retries: 10
            start_period: 30s

    pasarguard:
        container_name: pasarguard
        image: pasarguard/panel:latest
        restart: unless-stopped
        env_file: .env
        network_mode: host
        environment:
            ROLE: backend
        depends_on:
            nats:
                condition: service_healthy
            mariadb:
                condition: service_healthy
        volumes:
            - /var/lib/pasarguard:/var/lib/pasarguard
        healthcheck:
            test: ["CMD", "/code/healthcheck.sh"]
            interval: 5s
            timeout: 5s
            retries: 10
            start_period: 60s

    node-worker:
        container_name: node-worker
        image: pasarguard/panel:latest
        restart: unless-stopped
        env_file: .env
        network_mode: host
        environment:
            ROLE: node
        depends_on:
            pasarguard:
                condition: service_healthy
        volumes:
            - /var/lib/pasarguard:/var/lib/pasarguard

    scheduler:
        container_name: scheduler
        image: pasarguard/panel:latest
        restart: unless-stopped
        env_file: .env
        network_mode: host
        environment:
            ROLE: scheduler
        depends_on:
            pasarguard:
                condition: service_healthy
        volumes:
            - /var/lib/pasarguard:/var/lib/pasarguard

    mariadb:
        image: mariadb:lts
        restart: always
        environment:
            MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
            MYSQL_ROOT_HOST: "%"
            MYSQL_DATABASE: ${DB_NAME}
            MYSQL_USER: ${DB_USER}
            MYSQL_PASSWORD: ${DB_PASSWORD}
        command:
            - --bind-address=0.0.0.0
            - --character_set_server=utf8mb4
            - --collation_server=utf8mb4_unicode_ci
            - --host-cache-size=0
            - --innodb-open-files=1024
            - --innodb-buffer-pool-size=256M
            - --binlog_expire_logs_seconds=1209600
            - --innodb-log-file-size=64M
            - --innodb-doublewrite=0
            - --general_log=0
            - --slow_query_log=1
            - --slow_query_log_file=/var/lib/mysql/slow.log
            - --long_query_time=2
            - --innodb_snapshot_isolation=0
        ports:
            - "127.0.0.1:3306:3306"
        volumes:
            - /var/lib/mysql/pasarguard:/var/lib/mysql
        healthcheck:
            test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
            start_period: 10s
            start_interval: 3s
            interval: 10s
            timeout: 5s
            retries: 3

volumes:
    nats-data:

مرحله ۳: اجرای سرویس‌ها

cd /opt/pasarguard
sudo docker compose up -d

برای بررسی وضعیت:

sudo docker compose ps

مشاهده لاگ‌های سرویس backend:

sudo docker compose logs -f pasarguard

راه‌اندازی Multi-Worker

Multi-Worker چه چیزهایی را اجرا می‌کند

چه زمانی استفاده کنیم

پیش‌نیازها

مرحله ۱: آماده‌سازی .env

مرحله ۲: انتخاب پایگاه داده

مرحله ۳: اجرای سرویس‌ها

On this page

مرحله ۱: آماده‌سازی `.env`