Skálázás

Alapértelmezés szerint az IntraCord API container egyetlen uvicorn workert futtat. Production forgalomnál – különösen sok egyidejű hanghívás és hosszú élettartamú WebSocket esetén – több worker ajánlott. Az IntraCord ezt beépítetten támogatja: az nginx a least_conn stratégia alapján osztja el a terhelést N független uvicorn process között.

Ez az oldal bemutatja a multi-worker konfiguráció működését, a worker-szám kiválasztását telepítéskor, valamint módosítását futó stackben.

!

A multi-worker módhoz IntraCord v1.29.0 vagy újabb szükséges. A korábbi release-ek uvicorn --workers módot és eltérő remote deployment elrendezést használtak. Régebbi stack esetén először frissítsen.

Hogyan működik

Az API containerben FASTAPI_WORKERS számú külön uvicorn process indul, mindegyik saját portra bindolva (8000, 8001, 8002, …). Az nginx egyetlen IntraCord_api upstreamet biztosít az összes worker-porttal, és az új requesteket a legkevesebb aktív kapcsolattal rendelkező workerhez irányítja.

                       ┌───────────────────────────────────┐
                       │ api container                     │
                       │  uvicorn worker 0  → :8000        │
 browser ──► nginx ──► │  uvicorn worker 1  → :8001        │
   (443)    (least_conn)  uvicorn worker 2  → :8002        │
                       │  uvicorn worker 3  → :8003        │
                       └───────────────────────────────────┘

i

Ez szándékosan nem uvicorn --workers N (beépített pre-fork mód). Pre-fork esetén a Linux kernel az accept() híváson keresztül osztja el az új TCP-kapcsolatokat a workerek között. Ez rövid HTTP requesteknél megfelelő, de a hosszú életű WebSocketek annál a workernél maradnak, amelyik először elfogadta őket. Így néhány worker kezelheti a streaming forgalom nagy részét, miközben mások tétlenek. Az nginx least_conn routing ismeri a workerenkénti aktív kapcsolatok számát, ezért egyenletesebben osztja el a WebSocketeket.

Az API containerben futó ari_manager és campaign_orchestrator folyamatok a FASTAPI_WORKERS értékétől függetlenül singletonok maradnak. Globális state-et koordinálnak (Asterisk channelök, kampányütemezés), ezért nem duplikálhatók. Az ARQ background workerek számát külön az ARQ_WORKERS vezérli.

Worker-szám kiválasztása

Biztonságos kiindulási érték egy worker minden elérhető vCPU-ra, legfeljebb 8, amíg nem profilozta a workloadot. A Remote Server Deployment előfeltételei legalább 4 vCPU-t írnak elő:

vCPU-k	Javasolt FASTAPI_WORKERS
4	4
8	6–8
16+	előbb profilozza a workloadot

Minden worker saját Python-folyamatot és memóriát használ. A Postgres/Redis/MinIO overhead mellett számoljon körülbelül 300–500 MB RAM-mal workerenként. Ha közel van a 8 GB-os minimumhoz és OOM hibákat lát, csökkentse a workerek számát.

Worker-szám beállítása telepítéskor

A setup_remote.sh a többi config mellett bekéri a workerek számát:

Number of FastAPI workers (uvicorn processes nginx will load-balance):
[4]:

Az alapértelmezett érték (4) elfogadásához nyomja meg az Entert, vagy adjon meg más pozitív egész számot. Nem interaktív futtatásnál (cloud-init, CI, Terraform) environment variable-ben is átadható az érték:

sudo SERVER_IP=... TURN_SECRET=... FASTAPI_WORKERS=8 ./setup_remote.sh

A script az értéket a .env fájlban tárolja (FASTAPI_WORKERS=N). A támogatott startup path (./remote_up.sh) minden remote indítás előtt ellenőrzi az IntraCord-init renderelését, így az nginx és az API worker-szám szinkronban marad.

Worker-szám módosítása futó stackben

Ha az IntraCord fut, a workerek száma egy fájl szerkesztésével és újraindítással módosítható. Módosítsa a .env fájlt, majd futtassa a ./remote_up.sh parancsot. Az IntraCord-init újragenerálja az nginx runtime configját, mielőtt a Docker elindítja a stacket.

Lépések

Minden parancs a IntraCord/ könyvtárából fut (a docker-compose.yaml-vel rendelkező könyvtárból).

1. A .env szerkesztése és a FASTAPI_WORKERS sor módosítása:

# Before
FASTAPI_WORKERS=4

# After
FASTAPI_WORKERS=8

2. Hozza létre újra a stacket az ellenőrzött wrapper scripttel. A legegyszerűbb út – rövid állásidő, meglepetések nélkül:

./remote_up.sh

Ha el szeretné kerülni az állásidőt, és a stack egészséges, csak a api és nginx konténereket hozhatja újra:

./remote_up.sh -- api nginx

A remote_up.sh ellenőrzi a .env fájlt, lefuttatja a Compose startup során is használt IntraCord-init renderelést és a docker compose config -q parancsot, majd elindítja a kért service-eket.

3. Ellenőrzés. Győződjön meg arról, hogy megfelelő számú uvicorn process fut. Az API image minimalista, és nem tartalmazza a ps parancsot, ezért használja a Docker host oldali nézetét:

sudo docker compose --profile remote top api | grep uvicorn

Workerenként egy sort kell látnia. A bindolt portok ellenőrzéséhez nézze meg a startup logokat: minden worker egy Uvicorn running on http://0.0.0.0:800X sort ír boot során:

sudo docker compose --profile remote logs api | grep "Uvicorn running"

Ezután hívja meg az API-t nginxen keresztül, és ellenőrizze, hogy a requestek továbbra is célba érnek-e:

curl -k https://YOUR_SERVER_IP/api/v1/health

Miért nem futja újra a setup_remote.sh-t?

A setup_remote.sh szándékosan nem ír felül meglévő telepítést. Újrafuttatása újragenerálná az OSS_JWT_SECRET értékét (mindenkit kijelentkeztetne), visszaállítaná a TURN shared secretet (megszakítaná a WebRTC authot a kapcsolódó klienseken), és újragenerálná az SSL certificate-eket. Telepítés után a fenti kétfájlos módosítás a támogatott worker-szám-váltási eljárás.

Tiszta újratelepítéshez használja a scriptben dokumentált IntraCord_FORCE_OVERWRITE=1 escape hatch mechanizmust.

Amit ez nem skáláz

A multi-worker mód a HTTP/WebSocket API surface-t skálázza. Nem skálázza a következőket:

• ARQ background workerek — az ARQ_WORKERS vezérli őket (alapértelmezés: 1). Növelje ezt az API container environmentjében, ha feltorlódik a background job queue.
• ari_manager / campaign_orchestrator — tervezetten singletonok; az extra folyamatok nem gyorsítják őket.
• Postgres, Redis, MinIO – mindegyik egyetlen containerként fut a stackben. Production méretű PostgreSQL-hez használjon managed service-t, és állítsa rá a DATABASE_URL értékét; ugyanez érvényes Redisre és S3-kompatibilis storage-ra.

Többgépes horizontal scalinghez – amikor külön API containerek futnak több hoston – tekintse meg az Egyéni domain útmutató load balancer mintáját. Az elv azonos a containeren belüli least_conn upstreammel, csak egy réteggel magasabban.