多 Worker 模式

Multi-Worker 模式运行多个 PasarGuard 进程，使 API 流量与后台任务共同扩展，而不是争抢同一个事件循环。

自 PasarGuard v5.3.0 起，推荐的 Multi-Worker 运行方式是使用单个 all-in-one 服务，并将 UVICORN_WORKERS 设置为大于 1，通过 NATS 进行协调。旧的拆分角色方案（ROLE=backend / node / scheduler）已被弃用，将在 v7.0.0 中移除——如果你仍在使用该方案，请参见下方的「旧版拆分角色配置（v5.3.0 之前）」部分。

以下示例中，docker-compose.yml 与 .env 位于 /opt/pasarguard，数据存放在 /var/lib/pasarguard。

工作原理

ROLE=all-in-one（默认值）会在同一进程中运行 HTTP API、面板、节点 worker 与定时任务。
设置 UVICORN_WORKERS 可在 Uvicorn 的进程管理器下运行多个该 all-in-one 应用的操作系统进程，而无需运行独立的服务。
当有多个进程需要共享状态时——即 UVICORN_WORKERS > 1，或使用已弃用的拆分 ROLE——NATS 会负责协调 leader 选举（用于定时任务）以及跨进程的节点/用户同步。此时如果没有 NATS，PasarGuard 将拒绝启动。

何时使用

节点/用户数量较多，需要比单进程更高的吞吐量。
只需提高 UVICORN_WORKERS 即可扩展 API/worker 容量。
需要定时任务与节点同步在多个进程之间也能正确工作。

要求

当 UVICORN_WORKERS > 1 时，需要 NATS。
所有 worker 进程必须共享 /var/lib/pasarguard（模板、证书、运行时文件）。
数据库连接池设置是按每个 worker 计算的，而非全局——例如 4 个 worker、每个连接池大小为 10，最多可打开 40 个基础连接。

只要 UVICORN_WORKERS 大于 1，Multi-Worker 模式就要求 NATS_ENABLED=True。如果 NATS 未启用，PasarGuard 将无法启动。

步骤 1：准备 `.env`

以下为最小配置，请根据所选数据库补充对应的数据库配置块。

# Process role — keep the default (all-in-one runs API + node worker + scheduler)
# ROLE = "all-in-one"

# Uvicorn worker processes
# Set this to the number of CPU cores on your server for best performance
UVICORN_WORKERS = 4

# NATS — required when UVICORN_WORKERS > 1
NATS_ENABLED = True
NATS_URL = "nats://127.0.0.1:4222"

# Web server
# UVICORN_PORT = 8000

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

# Pooling (per worker process — see Requirements above)
# SQLALCHEMY_POOL_SIZE = 10
# SQLALCHEMY_MAX_OVERFLOW = 30

步骤 2：选择数据库

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
        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

    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
        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

    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: always
        env_file: .env
        network_mode: host
        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

    mysql:
        image: mysql:lts
        network_mode: host
        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=127.0.0.1
            - --character_set_server=utf8mb4
            - --collation_server=utf8mb4_unicode_ci
            - --skip-log-bin
            - --host-cache-size=0
            - --innodb-open-files=1024
            - --innodb-buffer-pool-size=256M
            - --general_log=0
            - --slow_query_log=1
            - --slow_query_log_file=/var/lib/mysql/slow.log
            - --long_query_time=2
        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

    phpmyadmin:
        container_name: phpmyadmin
        image: phpmyadmin:latest
        restart: always
        env_file: .env
        network_mode: host
        environment:
            PMA_HOST: 127.0.0.1
            APACHE_PORT: 8010
            UPLOAD_LIMIT: 1024M
        depends_on:
            mysql:
                condition: service_healthy

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
        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

    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:

步骤 3：启动服务

cd /opt/pasarguard
sudo docker compose up -d

查看状态：

sudo docker compose ps

查看 backend 服务日志：

sudo docker compose logs -f pasarguard

旧版拆分角色配置（v5.3.0 之前）

将 ROLE=backend / node / scheduler 拆分为多个独立服务的方式自 v5.3.0 起已被弃用，将在 PasarGuard v7.0.0 中移除。新部署请使用上方的「工作原理」中介绍的 all-in-one 方案；如果你仍在使用拆分角色，请规划迁移。

在 v5.3.0 之前，Multi-Worker 意味着将 PasarGuard 拆分为三个独立服务，每个服务运行相同的镜像，但使用不同的 ROLE：

角色	作用
`backend`	HTTP API + 面板 + 数据库迁移
`node`	节点操作、日志与节点相关任务
`scheduler`	定时任务、通知与队列处理

在这种模式下始终需要 NATS（与 UVICORN_WORKERS 无关），并且必须为每个服务单独设置 ROLE。

多 Worker 模式

工作原理

何时使用

要求

步骤 1：准备 .env

步骤 2：选择数据库

步骤 3：启动服务

旧版拆分角色配置（v5.3.0 之前）

显示旧版 backend / node / scheduler 配置

On this page

步骤 1：准备 `.env`