Навигация

Worker Threads и cluster

Любой JavaScript в приложении исполняется в одном потоке, и один тяжёлый расчёт останавливает все запросы сразу. Асинхронность здесь не помогает: await не делит вычисление на части. Разберём, как вынести CPU-bound работу в worker_threads, зачем нужен cluster, чем они отличаются по памяти и цене запуска и когда вместо всего этого достаточно spawn.

Содержание

  1. Зачем распараллеливать: CPU-bound и I/O-bound
  2. Как устроен worker thread
  3. Запуск воркера и обмен сообщениями
  4. Структурированное клонирование и transfer list
  5. SharedArrayBuffer и Atomics
  6. Пул воркеров
  7. cluster: процессы вместо потоков
  8. Общий порт и sticky sessions
  9. child_process: внешние процессы
  10. PM2 и несколько инстансов
  11. Что выбрать
  12. Частые ошибки
  13. Эксперименты
  14. Ключевые тезисы для интервью
  15. Заключение
  16. Полезные ссылки

Зачем распараллеливать: CPU-bound и I/O-bound

Узкое место сервиса бывает двух видов. I/O-bound нагрузка ждёт сеть, диск или базу: поток в это время свободен, и event loop обслуживает другие запросы. CPU-bound нагрузка считает: хеширует пароли, сжимает архивы, парсит JSON на десятки мегабайт, рендерит PDF, применяет регэксп к большому тексту.

Разница принципиальна. В первом случае Node уже использует всё, что нужно, — асинхронные вызовы и пул libuv. Во втором не помогает ничего: пока функция считает, цикл стоит, и сервис не отвечает даже на healthcheck. Подробнее про границу между V8 и libuv — в статье «Node.js: как устроен рантайм».

Соблазн «увеличить UV_THREADPOOL_SIZE» — ловушка. Пул обслуживает нативные операции: fs, dns.lookup, crypto.pbkdf2, zlib. Но JSON.parse, сортировка массива и цикл на миллион итераций выполняются в V8, то есть всегда в главном потоке. Пул тут ни при чём.

Отсюда три уровня решения, каждый дороже предыдущего:

ЗадачаРешение
Много ожиданияничего не делать: async/await и event loop
Расчёт внутри процесса, нужен результатworker_threads (обычно через пул)
Полная изоляция, другой рантайм, внешний бинарникchild_process или отдельный сервис
Занять все ядра HTTP-трафикомcluster или несколько инстансов

Есть и нулевой уровень, который часто забывают: убрать вычисление из горячего пути. Посчитать заранее, закешировать, отдать пагинацию вместо всего датасета, вынести в фоновую очередь. Worker ускоряет расчёт, но не отменяет его стоимость.


Как устроен worker thread

worker_threads создаёт новый поток внутри того же процесса. У него собственный изолят V8, собственная куча, собственный event loop и собственная очередь микрозадач. Глобальные переменные, модульный кеш и замыкания не разделяются: воркер загружает модули заново и получает чистое окружение.

Что при этом общее:

  • идентификатор процесса и файловые дескрипторы;
  • адресное пространство — а значит, SharedArrayBuffer;
  • process.env по умолчанию (копия; изменения не видны другим потокам, если не передать SHARE_ENV);
  • код, загруженный из node_modules, — но не его состояние.
ХарактеристикаЗначение
Память на воркердесятки мегабайт кучи плюс код
Время запускапорядка 10–30 мс
Сборка мусорасвоя, независимая от главного потока
Обмен даннымиpostMessage (копия) или SharedArrayBuffer (общая память)
Падениеошибка в воркере не роняет процесс, если её обработать

Стоимость запуска — главный аргумент против схемы «воркер на запрос». Поток нужно создать, инициализировать V8, разобрать и выполнить модули, а по завершении дождаться остановки. На короткой задаче эти накладные расходы могут превысить саму работу.

Размер кучи воркера ограничивается опцией resourceLimits:

import { Worker } from 'node:worker_threads';

const worker = new Worker(new URL('./resize.js', import.meta.url), {
  workerData: { width: 1200, quality: 80 },
  resourceLimits: { maxOldGenerationSizeMb: 256 },
});

Если воркер упрётся в лимит, он завершится с ERR_WORKER_OUT_OF_MEMORY, а главный процесс останется жив. Это и есть изоляция: утечка или раздувание памяти в воркере не убивает сервис целиком.

Внутри воркера доступны isMainThread, threadId, workerData и parentPort. process.exit() в воркере останавливает только этот поток, а не приложение.


Запуск воркера и обмен сообщениями

Код воркера — отдельный модуль, который исполняется в новом потоке. Связь идёт через сообщения: worker.postMessage() в одну сторону, parentPort.postMessage() в другую.

// main.js
import { Worker } from 'node:worker_threads';

const worker = new Worker(new URL('./hash.js', import.meta.url), {
  workerData: { rounds: 12 },
});

worker.on('message', (digest) => {
  console.log('готово:', digest);
});

worker.on('error', (err) => {
  console.error('воркер упал:', err);
});

worker.on('exit', (code) => {
  console.log('воркер завершился с кодом', code);
});

worker.postMessage('секрет');
// hash.js
import { parentPort, workerData } from 'node:worker_threads';
import { createHash } from 'node:crypto';

parentPort.on('message', (value) => {
  let digest = value;

  for (let i = 0; i < workerData.rounds; i++) {
    digest = createHash('sha256').update(digest).digest('hex');
  }

  parentPort.postMessage(digest);
});

Три события обязательны в любой обвязке:

  • message — результат или промежуточный отчёт;
  • error — необработанное исключение в воркере; без слушателя оно всплывает как uncaughtException и роняет главный процесс;
  • exit — поток завершился, с кодом или сигналом.

Сообщения асинхронны и доставляются через event loop принимающей стороны, поэтому порядок внутри одного порта сохраняется, а между разными — нет.

workerData передаётся один раз при создании и клонируется тем же алгоритмом, что и сообщения. parentPort в главном потоке равен null, поэтому код, который может исполняться и там, и там, проверяет isMainThread.

Воркеры держат процесс живым, даже если главный поток простаивает. Если фоновый воркер не должен мешать завершению приложения, вызывают worker.unref(). Обратная операция — worker.ref().

Завершение бывает двух видов. worker.terminate() останавливает исполнение немедленно: блоки finally не выполнятся, ресурсы нужно освобождать в главном потоке. Кооперативный вариант — попросить воркер закончить (parentPort.postMessage({ type: 'shutdown' }) или parentPort.close()) и дождаться exit. Для долгоживущих воркеров второй способ обязателен, иначе можно оборвать запись файла на середине.


Структурированное клонирование и transfer list

postMessage не передаёт ссылку на объект — он копирует значение по алгоритму структурного клонирования (structured clone). Это тот же механизм, что используется в structuredClone() и в postMessage браузера.

Что клонируется: примитивы, plain-объекты и массивы, Map, Set, Date, RegExp, Error, BigInt, ArrayBuffer, типизированные массивы, Blob, File.

Что не клонируется:

  • функции и замыкания;
  • промисы;
  • символы;
  • WeakMap и WeakSet;
  • экземпляры классов — теряется прототип, остаются только собственные свойства;
  • геттеры и сеттеры — превращаются в обычные значения.

Попытка передать неподдерживаемое значение бросает DataCloneError. Это частая причина «странных» ошибок при передаче объекта из ORM: у него прототип, а после клонирования методы исчезли.

Копирование большого ArrayBuffer — это полноценное memcpy: 100 МБ туда и 100 МБ обратно на каждый вызов. Для таких данных есть transfer list — второй аргумент postMessage:

const buffer = Buffer.alloc(64 * 1024 * 1024);

worker.postMessage({ buffer }, [buffer]);

console.log(buffer.byteLength); // 0 — владение передано воркеру

Передача не копирует байты: буфер отвязывается от отправителя и достаётся получателю. Правило простое: буфер нужен дальше — копируйте, не нужен — передавайте.

Две оговорки. Маленькие Buffer, выделенные из общего пула, передать нельзя: пул помечен как untransferable, и Node бросит ошибку — нужен буфер, выделенный отдельно через Buffer.allocUnsafeSlow(). А markAsUntransferable() работает в обратную сторону: помечает объект так, чтобы его нельзя было случайно передать и потерять у себя.

Второй механизм — MessageChannel: два связанных порта, один из которых можно отдать воркеру. Тогда воркеры общаются напрямую, без участия главного потока.

import { MessageChannel } from 'node:worker_threads';

const { port1, port2 } = new MessageChannel();

worker.postMessage({ port: port2 }, [port2]);

port1.on('message', (msg) => console.log('ответ:', msg));
// внутри воркера
parentPort.on('message', ({ port }) => {
  port.postMessage('привет из воркера');
});

Так строят пары «producer → consumer» между воркерами: главный поток только создаёт канал и больше не участвует в трафике.


SharedArrayBuffer и Atomics

Копирование — не единственный способ обмена. SharedArrayBuffer выделяет память, видимую всем потокам процесса: те же байты, без копий и сериализации.

import { Worker } from 'node:worker_threads';

const shared = new SharedArrayBuffer(4);
const counter = new Int32Array(shared);

const workers = Array.from({ length: 4 }, () =>
  new Worker(new URL('./count.js', import.meta.url), { workerData: shared }),
);

await Promise.all(workers.map((w) => new Promise((resolve) => w.once('exit', resolve))));

console.log(Atomics.load(counter, 0)); // 4_000_000
// count.js
import { workerData } from 'node:worker_threads';

const counter = new Int32Array(workerData);

for (let i = 0; i < 1_000_000; i++) {
  Atomics.add(counter, 0, 1);
}

Без Atomics тот же код терял бы часть инкрементов: операция «прочитать, прибавить, записать» не атомарна, и два потока перезаписывают результат друг друга. Atomics даёт атомарные load, store, add, sub, exchange, compareExchange, а также wait и notify для организации ожидания.

Atomics.wait блокирует поток до изменения значения или таймаута. В воркере это нормально, в главном потоке — запрещено: вызов бросает TypeError, потому что остановил бы весь сервис. Для главного потока есть Atomics.waitAsync, возвращающий промис.

Практические ограничения:

  • SharedArrayBuffer работает только с числами фиксированного размера — строки и объекты в общей памяти не хранятся;
  • структура данных в общей памяти проектируется вручную: кольцевой буфер, счётчики, флаги;
  • гонки здесь настоящие, в отличие от обычного JS-кода, где общих данных нет.

Поэтому общее правило: сначала сообщения, общая память — только после профилирования. Передача больших бинарных данных через transfer list решает большинство задач без ручной синхронизации.


Пул воркеров

Запуск воркера на каждый запрос — самая частая ошибка. При 50 одновременных запросах это 50 потоков, 50 изолятов V8 и 50 копий загруженных модулей: процессор тратит время на переключение контекста и сборку мусора вместо полезной работы.

Правильная схема — пул: фиксированное число воркеров, очередь задач и переиспользование потоков.

import Piscina from 'piscina';

const pool = new Piscina({
  filename: new URL('./hash.js', import.meta.url).href,
  maxThreads: 4,
});

const digest = await pool.run(payload, { transferList: [payload.buffer] });

Piscina — де-факто стандарт для пулов: она держит потоки, распределяет задачи, поддерживает transfer list и AbortSignal. Альтернативы — workerpool и threads.js; встроенного пула в Node нет.

Размер пула считают по доступным ядрам:

import { availableParallelism } from 'node:os';

const size = availableParallelism();

availableParallelism() учитывает ограничения контейнера (cgroup quota), а os.cpus().length — нет: в поде с лимитом 2 CPU он покажет все ядра хоста, и пул окажется в несколько раз больше нужного.

Два правила подбора:

  • CPU-bound: потоков не больше числа доступных ядер; больше — только хуже из-за переключений.
  • Смешанная нагрузка: воркер, который половину времени ждёт, можно запускать с небольшим превышением, но это уже повод измерить, а не угадывать.

Очередь тоже нужно ограничивать. Если пул забит, а задачи продолжают приходить, они копятся в памяти и увеличивают задержку — лучше вернуть 503 или применить backpressure, чем принять всё и упасть по памяти. У Piscina для этого есть maxQueue.


cluster: процессы вместо потоков

cluster решает другую задачу: не распараллелить вычисление, а занять все ядра HTTP-трафиком и пережить падение отдельного обработчика.

import cluster from 'node:cluster';
import { availableParallelism } from 'node:os';
import { createServer } from 'node:http';

if (cluster.isPrimary) {
  for (let i = 0; i < availableParallelism(); i++) cluster.fork();

  cluster.on('exit', (worker, code, signal) => {
    console.error(`воркер ${worker.process.pid} умер (${signal ?? code})`);
    cluster.fork(); // поддержать число процессов
  });
} else {
  createServer((req, res) => {
    res.end(`pid ${process.pid}\n`);
  }).listen(3000);
}

cluster.fork() запускает новый процесс — не поток — с тем же входным модулем. У него свой PID, своя память, свой event loop и своя сборка мусора. Общение идёт через IPC: process.send() в дочернем, worker.send() в главном, сообщения сериализуются в JSON.

Что cluster даёт:

  • загрузку всех ядер одним приложением;
  • устойчивость: упавший воркер перезапускается, остальные продолжают работать;
  • перезапуск по одному процессу без простоя;
  • общий порт — не нужно вручную распределять соединения.

Чего он не даёт:

  • общей памяти — кеш и сессии в одном процессе не видны другому; состояние выносят в Redis или другое внешнее хранилище;
  • распараллеливания одного запроса — запрос целиком живёт в одном процессе.

Именно поэтому in-memory кеш и сессии в cluster-режиме превращаются в баг: пользователь попадает в разные процессы и видит то авторизованное состояние, то нет.


Общий порт и sticky sessions

Как несколько процессов слушают один порт? Есть две стратегии, и cluster выбирает одну из них.

СтратегияКто распределяетПлатформа
round-robin (SCHED_RR)главный процесс принимает соединение и передаёт воркерупо умолчанию везде, кроме Windows
shared handle (SCHED_NONE)ядро ОС само решает, кто приметWindows по умолчанию

В round-robin главный процесс становится точкой распределения: он принимает TCP-соединение и отдаёт дескриптор одному из воркеров. Распределяются соединения, а не запросы. При HTTP/1.1 с keep-alive один клиент держит соединение с одним воркером и отправляет туда все запросы — для stateless API это нормально, но нагрузка между процессами может лечь неровно.

Для WebSocket и socket.io это критично. Апгрейд происходит один раз, и дальше всё общение идёт по тому же соединению. Если балансировщик раскидывает HTTP-запросы по разным инстансам, long-polling socket.io ломается: handshake на одном процессе, следующий запрос — на другом.

Решения:

  • sticky sessions на балансировщике — привязка по cookie или IP (ip_hash в nginx);
  • sticky-модуль вроде @socket.io/sticky, который работает вместе с cluster;
  • отказ от long-polling в пользу чистого WebSocket, если клиенты это поддерживают.

Отдельно стоит упомянуть reusePort: в свежих версиях Node (22.12+ и 23+) server.listen({ port, reusePort: true }) позволяет каждому процессу открыть свой сокет на том же порту, а распределением занимается ядро через SO_REUSEPORT. Это убирает главный процесс из горячего пути, но не даёт встроенного graceful reload — за него отвечает внешний супервизор.


child_process: внешние процессы

Когда задача не про JavaScript, а про внешний инструмент (ffmpeg, imagemagick, git, python-скрипт) или нужна полная изоляция от падений, берут child_process. Модуль даёт четыре функции.

ФункцияShellВыводКогда использовать
spawnнетпотокидолгие процессы, большой вывод, стриминг
execдабуфер целикомкороткие команды, нужен shell-синтаксис
execFileнетбуфер целикомзапуск бинарника с аргументами
forkнетIPC-каналдочерний процесс на Node с обменом сообщениями
import { execFile, spawn } from 'node:child_process';
import { createWriteStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';

// плохо: пользовательский ввод попадает в shell
exec(`convert ${userInput} out.png`);

// хорошо: аргументы массивом, shell не участвует
execFile('convert', [userInput, 'out.png'], (err, stdout) => {
  if (err) throw err;
  console.log(stdout);
});

// долгий процесс с потоковым выводом
const ffmpeg = spawn('ffmpeg', ['-i', input, '-f', 'mp3', 'pipe:1'], {
  stdio: ['ignore', 'pipe', 'inherit'],
});

await pipeline(ffmpeg.stdout, createWriteStream('out.mp3'));

exec опасен по двум причинам. Во-первых, он передаёт строку в shell, поэтому ;, &&, $() и обратные кавычки в пользовательском вводе превращаются в произвольные команды — это command injection. Во-вторых, он собирает весь вывод в память и падает с maxBuffer exceeded (по умолчанию 1 МБ). Для больших данных нужен spawn и pipeline, как в примере выше: те же правила, что и для файлов в статье «Стримы и backpressure».

fork отличается тем, что запускает модуль Node и сразу открывает IPC-канал:

import { fork } from 'node:child_process';

const child = fork('./reindex.js');

child.send({ task: 'reindex' });
child.on('message', (msg) => console.log('от дочернего:', msg));

Этот способ подходит, когда нужна не скорость, а изоляция: упавший процесс не задевает основной, память не делится, а общение идёт сообщениями. Цена — запуск процесса и сериализация, поэтому для расчётов на миллисекунды он проигрывает worker thread.


PM2 и несколько инстансов

PM2 — менеджер процессов: держит приложение живым, перезапускает при падении, собирает логи и умеет cluster-режим.

pm2 start app.js -i max      # столько процессов, сколько ядер
pm2 reload app               # перезапуск по одному, без простоя
pm2 logs
pm2 monit

В cluster-режиме PM2 использует встроенный cluster, добавляя логи, рестарты и max_memory_restart. pm2 reload перезапускает воркеров по очереди, поэтому часть процессов продолжает принимать трафик.

systemd решает похожую задачу для одного процесса:

[Service]
ExecStart=/usr/bin/node /srv/app/server.js
Restart=always
RestartSec=2
KillSignal=SIGTERM

Но в контейнере PM2 чаще мешает. Оркестратор уже перезапускает контейнер, масштабирует реплики и проверяет healthcheck; а PM2 как PID 1 не всегда корректно пробрасывает SIGTERM дочернему Node, из-за чего graceful shutdown не срабатывает и соединения обрываются. Если менеджер всё же нужен, берут pm2-runtime (он создан для контейнеров и forwarding сигналов) либо init-процесс вроде tini в Docker — подробнее в статье «Docker и деплой Node.js».

Число инстансов подбирают по availableParallelism(), а не по os.cpus().length: в контейнере с лимитом 2 CPU восемь процессов будут драться за два ядра.


Что выбрать

СитуацияИнструмент
Много ожидания сети или дисканичего: async/await, event loop
Тяжёлый расчёт, нужен результат в ответеworker thread из пула
Расчёт редкий и долгий, важна изоляцияfork или отдельный сервис
Нужно занять все ядра HTTP-трафикомcluster, PM2 cluster mode или несколько реплик
Нужен внешний бинарникspawn / execFile
Другой язык или рантаймотдельный сервис, не child_process

Порядок выбора простой. Сначала спросите, можно ли вообще не считать это в запросе. Если нельзя — можно ли посчитать в фоне и вернуть результат позже. Если нужен синхронный ответ — worker. Если нужно масштабировать весь сервис — cluster или реплики. child_process — крайний случай, когда задача вообще не про Node.


Частые ошибки

  • Воркер на каждый запрос. Сто запросов — сто потоков и повторная загрузка модулей; нужен пул.
  • Нет обработчика error. Исключение в воркере всплывает в главном процессе и роняет сервис.
  • Копирование больших буферов. postMessage без transfer list удваивает память на каждом вызове.
  • Передача буфера из пула. Маленький Buffer из общего пула не transferable; нужен allocUnsafeSlow или копия.
  • SharedArrayBuffer без Atomics. Потерянные инкременты и гонки, которых в обычном JS не бывает.
  • Atomics.wait в главном потоке. Бросает TypeError; для главного есть waitAsync.
  • cluster и состояние в памяти. Сессии и кеш в процессе не видны соседям: нужен Redis.
  • cluster как ускоритель одного запроса. Запрос не делится между процессами.
  • exec с пользовательским вводом. Command injection и лимит maxBuffer.
  • PM2 в контейнере без init-процесса. SIGTERM не доходит, graceful shutdown не работает.
  • os.cpus().length для размера пула. В контейнере даёт число ядер хоста, а не лимит.
  • Воркеры на I/O-bound нагрузке. Оверхед без выигрыша: ожидание и так не занимает поток.

Эксперименты

Три запуска, которые показывают разницу между «блокирует» и «не блокирует».

1. Тот же расчёт в главном потоке и в воркере

// server.js
import { createServer } from 'node:http';
import { Worker } from 'node:worker_threads';

function heavy(n) {
  let acc = 0;
  for (let i = 0; i < n; i++) acc += Math.sqrt(i);
  return acc;
}

function runWorker(n) {
  return new Promise((resolve, reject) => {
    const worker = new Worker(new URL('./heavy.js', import.meta.url), {
      workerData: n,
    });
    worker.once('message', resolve);
    worker.once('error', reject);
  });
}

createServer(async (req, res) => {
  const result = req.url === '/sync'
    ? heavy(5e7)
    : await runWorker(5e7);

  res.end(String(result));
}).listen(3000);
// heavy.js
import { parentPort, workerData } from 'node:worker_threads';

let acc = 0;
for (let i = 0; i < workerData; i++) acc += Math.sqrt(i);

parentPort.postMessage(acc);

Запустите два запроса подряд: сначала /sync, затем /. Второй не получит ответа, пока первый не освободит главный поток: пока считается heavy, цикл не принимает новые соединения. Если оба запроса идут через runWorker, расчёты выполняются в разных потоках, а главный поток продолжает обслуживать соединения.

2. Потерянные инкременты без Atomics

Замените в примере из раздела про общую память Atomics.add на counter[0]++ и запустите несколько раз. Результат будет меньше 4_000_000 и разным от запуска к запуску — это и есть гонка, которую Atomics устраняет.

3. Два процесса cluster

import cluster from 'node:cluster';
import { createServer } from 'node:http';

if (cluster.isPrimary) {
  cluster.fork();
  cluster.fork();
} else {
  createServer((req, res) => {
    res.end(`pid ${process.pid}\n`);
  }).listen(3000);
}

Несколько запросов curl localhost:3000 покажут два разных PID: соединения распределяет главный процесс. Если добавить keep-alive, один клиент будет попадать в один и тот же процесс.


Ключевые тезисы для интервью

  • JavaScript исполняется в одном потоке, поэтому CPU-bound код блокирует event loop; пул libuv обслуживает нативные операции и не распараллеливает JS ни при каком UV_THREADPOOL_SIZE.
  • worker_threads — потоки внутри одного процесса, каждый со своим изолятом V8, event loop и кучей; общими могут быть только SharedArrayBuffer и файловые дескрипторы.
  • postMessage копирует данные структурным клонированием: функции и прототипы теряются, большие буферы дороги; transferList передаёт владение ArrayBuffer без копии.
  • SharedArrayBuffer требует Atomics для атомарности и видимости; Atomics.wait блокирует поток и запрещён в главном, где доступен только waitAsync.
  • Воркер на запрос — дорого: нужен пул на availableParallelism() с ограниченной очередью, потому что запуск потока стоит мегабайт и десятков миллисекунд.
  • cluster форкает процессы и распределяет соединения: он занимает ядра и переживает падения, но не делит память и не ускоряет один запрос.
  • spawn/execFile вместо exec для внешних команд, а PM2 в контейнере обычно лишний: рестарты и масштабирование берёт оркестратор, а сигналы требуют init-процесса.

Заключение

Однопоточность Node — не дефект, а следствие модели, которая делает дешёвым ожидание и дорогим счёт. Пока нагрузка I/O-bound, ничего добавлять не нужно. Как только в обработчике появляется вычисление, выбор сводится к трём вариантам: убрать его из горячего пути, вынести в пул воркеров внутри процесса или изолировать в отдельном процессе. cluster при этом решает другую задачу — занять все ядра HTTP-трафиком и пережить падение отдельного обработчика, а не ускорить конкретный запрос. Главные практические правила: не создавать воркер на запрос, передавать большие буферы без копии, синхронизировать общую память через Atomics и не держать состояние в памяти процесса, если процессов несколько.

Полезные ссылки

  • worker_threads — API воркеров, MessageChannel, SharedArrayBuffer
  • cluster — форк процессов, стратегии планирования, общий порт
  • child_process — spawn, exec, execFile, fork
  • Piscina — пул воркеров для Node
  • PM2: Cluster Mode — cluster-режим и zero-downtime reload