Node.js v21.7.2 文档

工作原理#

工作进程使用 child_process.fork() 方法生成，以便它们可以通过 IPC 与父进程通信并将服务器句柄来回传递。

cluster 模块支持两种分配传入连接的方法。

第一种（也是除 Windows 外所有平台上的默认方法）是轮询方法，其中主进程监听端口，接受新连接并以轮询方式将它们分配到工作进程，并具有一些内置的智能功能以避免过载工作进程。

第二种方法是主进程创建监听套接字并将其发送给感兴趣的工作进程。然后，工作进程直接接受传入连接。

理论上，第二种方法应该提供最佳性能。然而，在实践中，由于操作系统调度程序的差异，分配往往非常不平衡。已经观察到负载，其中超过 70% 的连接最终只出现在两个进程中，而总共八个进程。

由于 server.listen() 将大部分工作交给了主进程，因此在三种情况下，普通 Node.js 进程和集群工作进程之间的行为有所不同

1. server.listen({fd: 7}) 由于消息传递给主进程，因此将监听父进程中的文件描述符 7，并将句柄传递给工作进程，而不是监听工作进程对文件描述符 7 的理解。
2. server.listen(handle) 显式地监听句柄将导致工作进程使用提供的句柄，而不是与主进程通信。
3. server.listen(0) 通常，这会导致服务器监听随机端口。但是，在集群中，每个工作进程在每次执行 listen(0) 时都会收到相同的“随机”端口。本质上，端口在第一次是随机的，但之后是可预测的。要监听唯一端口，请根据集群工作进程 ID 生成端口号。

Node.js 不提供路由逻辑。因此，重要的是设计一个应用程序，使其不依赖于内存数据对象来处理诸如会话和登录之类的事情。

由于工作进程都是独立的进程，因此可以根据程序的需要杀死或重新生成它们，而不会影响其他工作进程。只要有一些工作进程仍然存活，服务器将继续接受连接。如果没有任何工作进程存活，现有的连接将被断开，新的连接将被拒绝。但是，Node.js 不会自动管理工作进程的数量。管理工作进程池是应用程序根据自身需求的责任。

虽然 node:cluster 模块的主要用例是网络，但它也可以用于其他需要工作进程的用例。

类：Worker#

• 扩展：<EventEmitter>

Worker 对象包含有关工作进程的所有公共信息和方法。在主进程中，可以使用 cluster.workers 获取它。在工作进程中，可以使用 cluster.worker 获取它。

事件：'disconnect'#

类似于 cluster.on('disconnect') 事件，但特定于此工作进程。

cluster.fork().on('disconnect', () => {
  // Worker has disconnected
}); copy

事件：'error'#

此事件与 child_process.fork() 提供的事件相同。

在工作进程中，也可以使用 process.on('error')。

事件：'exit'#

• code <number> 退出代码，如果正常退出。
• signal <string> 导致进程被杀死的信号名称（例如 'SIGHUP'）。

类似于 cluster.on('exit') 事件，但特定于此工作进程。

import cluster from 'node:cluster';

if (cluster.isPrimary) {
  const worker = cluster.fork();
  worker.on('exit', (code, signal) => {
    if (signal) {
      console.log(`worker was killed by signal: ${signal}`);
    } else if (code !== 0) {
      console.log(`worker exited with error code: ${code}`);
    } else {
      console.log('worker success!');
    }
  });
}const cluster = require('node:cluster');

if (cluster.isPrimary) {
  const worker = cluster.fork();
  worker.on('exit', (code, signal) => {
    if (signal) {
      console.log(`worker was killed by signal: ${signal}`);
    } else if (code !== 0) {
      console.log(`worker exited with error code: ${code}`);
    } else {
      console.log('worker success!');
    }
  });
}copy

事件：'listening'#

• address <Object>

类似于 cluster.on('listening') 事件，但特定于此工作进程。

cluster.fork().on('listening', (address) => {
  // Worker is listening
});cluster.fork().on('listening', (address) => {
  // Worker is listening
});copy

它不会在工作进程中发出。

事件：'message'#

• message <Object>
• handle <undefined> | <Object>

类似于 cluster 的 'message' 事件，但特定于此工作进程。

在工作进程中，也可以使用 process.on('message')。

参见 process 事件：'message'。

以下是一个使用消息系统的示例。它在主进程中跟踪工作进程接收到的 HTTP 请求数量。

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

if (cluster.isPrimary) {

  // Keep track of http requests
  let numReqs = 0;
  setInterval(() => {
    console.log(`numReqs = ${numReqs}`);
  }, 1000);

  // Count requests
  function messageHandler(msg) {
    if (msg.cmd && msg.cmd === 'notifyRequest') {
      numReqs += 1;
    }
  }

  // Start workers and listen for messages containing notifyRequest
  const numCPUs = availableParallelism();
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  for (const id in cluster.workers) {
    cluster.workers[id].on('message', messageHandler);
  }

} else {

  // Worker processes have a http server.
  http.Server((req, res) => {
    res.writeHead(200);
    res.end('hello world\n');

    // Notify primary about the request
    process.send({ cmd: 'notifyRequest' });
  }).listen(8000);
}const cluster = require('node:cluster');
const http = require('node:http');
const process = require('node:process');

if (cluster.isPrimary) {

  // Keep track of http requests
  let numReqs = 0;
  setInterval(() => {
    console.log(`numReqs = ${numReqs}`);
  }, 1000);

  // Count requests
  function messageHandler(msg) {
    if (msg.cmd && msg.cmd === 'notifyRequest') {
      numReqs += 1;
    }
  }

  // Start workers and listen for messages containing notifyRequest
  const numCPUs = require('node:os').availableParallelism();
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  for (const id in cluster.workers) {
    cluster.workers[id].on('message', messageHandler);
  }

} else {

  // Worker processes have a http server.
  http.Server((req, res) => {
    res.writeHead(200);
    res.end('hello world\n');

    // Notify primary about the request
    process.send({ cmd: 'notifyRequest' });
  }).listen(8000);
}copy

事件：'online'#

类似于 cluster.on('online') 事件，但特定于此工作进程。

cluster.fork().on('online', () => {
  // Worker is online
}); copy

它不会在工作进程中发出。

worker.disconnect()#

• 返回值: <cluster.Worker> 对 worker 的引用。

在工作进程中，此函数将关闭所有服务器，等待这些服务器上的 'close' 事件，然后断开 IPC 通道。

在主进程中，会向工作进程发送内部消息，导致它对自己调用 .disconnect()。

导致 .exitedAfterDisconnect 被设置。

服务器关闭后，将不再接受新连接，但任何其他正在监听的工作进程都可能接受连接。现有的连接将按常例关闭。当不再存在连接时，请参阅 server.close()，与工作进程的 IPC 通道将关闭，使其能够优雅地退出。

以上仅适用于服务器连接，客户端连接不会被工作进程自动关闭，并且断开连接不会在退出之前等待它们关闭。

在工作进程中，process.disconnect 存在，但它不是此函数；它是 disconnect()。

由于长时间存在的服务器连接可能会阻止工作进程断开连接，因此发送消息可能很有用，以便可以采取特定于应用程序的操作来关闭它们。实现超时也可能很有用，如果在一段时间后未发出 'disconnect' 事件，则会杀死工作进程。

if (cluster.isPrimary) {
  const worker = cluster.fork();
  let timeout;

  worker.on('listening', (address) => {
    worker.send('shutdown');
    worker.disconnect();
    timeout = setTimeout(() => {
      worker.kill();
    }, 2000);
  });

  worker.on('disconnect', () => {
    clearTimeout(timeout);
  });

} else if (cluster.isWorker) {
  const net = require('node:net');
  const server = net.createServer((socket) => {
    // Connections never end
  });

  server.listen(8000);

  process.on('message', (msg) => {
    if (msg === 'shutdown') {
      // Initiate graceful close of any connections to server
    }
  });
} copy

worker.exitedAfterDisconnect#

• <boolean>

如果工作进程因 .disconnect() 而退出，则此属性为 true。如果工作进程以任何其他方式退出，则为 false。如果工作进程尚未退出，则为 undefined。

布尔值 worker.exitedAfterDisconnect 允许区分自愿退出和意外退出，主进程可以选择不根据此值重新生成工作进程。

cluster.on('exit', (worker, code, signal) => {
  if (worker.exitedAfterDisconnect === true) {
    console.log('Oh, it was just voluntary – no need to worry');
  }
});

// kill worker
worker.kill(); copy

worker.id#

• <整数>

每个新工作进程都会被分配一个唯一的 ID，这个 ID 存储在 id 中。

当工作进程处于活动状态时，这个 ID 作为其在 cluster.workers 中的索引键。

worker.isConnected()#

如果工作进程通过其 IPC 通道连接到其主进程，则此函数返回 true，否则返回 false。工作进程在创建后连接到其主进程。在发出 'disconnect' 事件后，它将断开连接。

worker.isDead()#

如果工作进程已终止（无论是退出还是被信号终止），则此函数返回 true。否则，它返回 false。

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

const numCPUs = availableParallelism();

if (cluster.isPrimary) {
  console.log(`Primary ${process.pid} is running`);

  // Fork workers.
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on('fork', (worker) => {
    console.log('worker is dead:', worker.isDead());
  });

  cluster.on('exit', (worker, code, signal) => {
    console.log('worker is dead:', worker.isDead());
  });
} else {
  // Workers can share any TCP connection. In this case, it is an HTTP server.
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end(`Current process\n ${process.pid}`);
    process.kill(process.pid);
  }).listen(8000);
}const cluster = require('node:cluster');
const http = require('node:http');
const numCPUs = require('node:os').availableParallelism();
const process = require('node:process');

if (cluster.isPrimary) {
  console.log(`Primary ${process.pid} is running`);

  // Fork workers.
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on('fork', (worker) => {
    console.log('worker is dead:', worker.isDead());
  });

  cluster.on('exit', (worker, code, signal) => {
    console.log('worker is dead:', worker.isDead());
  });
} else {
  // Workers can share any TCP connection. In this case, it is an HTTP server.
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end(`Current process\n ${process.pid}`);
    process.kill(process.pid);
  }).listen(8000);
}copy

worker.kill([signal])#

• signal <字符串> 要发送到工作进程的终止信号的名称。默认值： 'SIGTERM'

此函数将终止工作进程。在主工作进程中，它通过断开 worker.process 的连接来实现，并且一旦断开连接，就会使用 signal 进行终止。在工作进程中，它通过使用 signal 终止进程来实现。

kill() 函数会终止工作进程，而不会等待优雅地断开连接，它与 worker.process.kill() 的行为相同。

为了向后兼容，此方法被别名为 worker.destroy()。

在工作进程中，process.kill() 存在，但它不是此函数；它是 kill()。

worker.process#

• <子进程>

所有工作进程都是使用 child_process.fork() 创建的，此函数返回的对象存储为 .process。在工作进程中，全局 process 被存储。

参见：子进程模块。

如果 process 上发生 'disconnect' 事件并且 .exitedAfterDisconnect 不是 true，则工作进程将调用 process.exit(0)。这可以防止意外断开连接。

worker.send(message[, sendHandle[, options]][, callback])#

• message <Object>
• sendHandle <Handle>
• options <Object> 如果存在，options 参数是一个用于参数化某些类型句柄发送的对象。options 支持以下属性
  • keepOpen <boolean> 当传递 net.Socket 实例时可以使用的一个值。当为 true 时，套接字在发送过程中保持打开状态。默认值： false。
• callback <Function>
• 返回值： <boolean>

向工作进程或主进程发送消息，可以选择性地包含句柄。

在主进程中，这会向特定工作进程发送消息。它与 ChildProcess.send() 相同。

在工作进程中，这会向主进程发送消息。它与 process.send() 相同。

此示例将回显来自主进程的所有消息

if (cluster.isPrimary) {
  const worker = cluster.fork();
  worker.send('hi there');

} else if (cluster.isWorker) {
  process.on('message', (msg) => {
    process.send(msg);
  });
} copy

事件： 'disconnect'#

• worker <cluster.Worker>

在工作进程 IPC 通道断开连接后发出。这可能发生在工作进程正常退出、被杀死或手动断开连接（例如使用 worker.disconnect()）时。

'disconnect' 和 'exit' 事件之间可能存在延迟。这些事件可用于检测进程是否卡在清理过程中或是否存在长期连接。

cluster.on('disconnect', (worker) => {
  console.log(`The worker #${worker.id} has disconnected`);
}); copy

事件： 'exit'#

• worker <cluster.Worker>
• code <number> 退出代码，如果正常退出。
• signal <string> 导致进程被杀死的信号名称（例如 'SIGHUP'）。

当任何工作进程死亡时，集群模块将发出 'exit' 事件。

这可用于通过再次调用 .fork() 来重新启动工作进程。

cluster.on('exit', (worker, code, signal) => {
  console.log('worker %d died (%s). restarting...',
              worker.process.pid, signal || code);
  cluster.fork();
}); copy

参见 child_process 事件：'exit'。

事件：'fork'#

• worker <cluster.Worker>

当一个新的 worker 被 fork 时，cluster 模块会发出一个 'fork' 事件。这可以用来记录 worker 活动，并创建一个自定义超时。

const timeouts = [];
function errorMsg() {
  console.error('Something must be wrong with the connection ...');
}

cluster.on('fork', (worker) => {
  timeouts[worker.id] = setTimeout(errorMsg, 2000);
});
cluster.on('listening', (worker, address) => {
  clearTimeout(timeouts[worker.id]);
});
cluster.on('exit', (worker, code, signal) => {
  clearTimeout(timeouts[worker.id]);
  errorMsg();
}); copy

事件：'listening'#

• worker <cluster.Worker>
• address <Object>

在 worker 中调用 listen() 后，当 'listening' 事件在服务器上被发出时，'listening' 事件也会在主进程中的 cluster 上被发出。

事件处理程序使用两个参数执行，worker 包含 worker 对象，address 对象包含以下连接属性：address、port 和 addressType。如果 worker 监听多个地址，这将非常有用。

cluster.on('listening', (worker, address) => {
  console.log(
    `A worker is now connected to ${address.address}:${address.port}`);
}); copy

addressType 是以下之一

• 4 (TCPv4)
• 6 (TCPv6)
• -1 (Unix 域套接字)
• 'udp4' 或 'udp6' (UDPv4 或 UDPv6)

事件：'message'#

• worker <cluster.Worker>
• message <Object>
• handle <undefined> | <Object>

当集群主进程从任何 worker 接收消息时发出。

参见 child_process 事件：'message'。

事件：'online'#

• worker <cluster.Worker>

fork 一个新的 worker 后，worker 应该用一个在线消息进行响应。当主进程收到在线消息时，它将发出此事件。'fork' 和 'online' 之间的区别在于，fork 在主进程 fork 一个 worker 时发出，而 'online' 在 worker 运行时发出。

cluster.on('online', (worker) => {
  console.log('Yay, the worker responded after it was forked');
}); copy

事件：'setup'#

• settings <Object>

每次调用 .setupPrimary() 时发出。

settings 对象是调用 .setupPrimary() 时 cluster.settings 对象，仅供参考，因为可以在单个 tick 中多次调用 .setupPrimary()。

如果精度很重要，请使用cluster.settings。

cluster.disconnect([callback])#

• callback <Function> 当所有工作进程断开连接且句柄关闭时调用。

对cluster.workers中的每个工作进程调用.disconnect()。

当它们断开连接时，所有内部句柄将被关闭，如果没有任何其他事件等待，则允许主进程优雅地退出。

该方法接受一个可选的回调参数，该参数将在完成时被调用。

这只能从主进程调用。

cluster.fork([env])#

• env <Object> 要添加到工作进程环境中的键值对。
• 返回值：<cluster.Worker>

生成一个新的工作进程。

这只能从主进程调用。

cluster.isMaster#

已弃用的 cluster.isPrimary 别名。

cluster.isPrimary#

• <boolean>

如果进程为主进程，则为真。这由process.env.NODE_UNIQUE_ID决定。如果process.env.NODE_UNIQUE_ID未定义，则isPrimary为true。

cluster.isWorker#

• <boolean>

如果进程不是主进程（它是cluster.isPrimary的否定），则为真。

cluster.schedulingPolicy#

调度策略，可以是cluster.SCHED_RR（循环调度）或cluster.SCHED_NONE（留给操作系统处理）。这是一个全局设置，一旦第一个工作进程生成或调用.setupPrimary()（以先发生者为准），它就会被有效地冻结。

SCHED_RR 是除 Windows 外所有操作系统的默认值。Windows 将在 libuv 能够有效地分配 IOCP 句柄而不会造成重大性能损失后切换到SCHED_RR。

cluster.schedulingPolicy 也可以通过 NODE_CLUSTER_SCHED_POLICY 环境变量设置。有效值为 'rr' 和 'none'。

cluster.settings#

• <Object>
  • execArgv <string[]> 传递给 Node.js 可执行文件的字符串参数列表。默认值： process.execArgv。
  • exec <string> 工作文件的文件路径。默认值： process.argv[1]。
  • args <string[]> 传递给工作进程的字符串参数。默认值： process.argv.slice(2)。
  • cwd <string> 工作进程的当前工作目录。默认值： undefined（从父进程继承）。
  • serialization <string> 指定用于在进程之间发送消息的序列化类型。可能的值为 'json' 和 'advanced'。有关更多详细信息，请参见 child_process 的高级序列化。默认值： false。
  • silent <boolean> 是否将输出发送到父进程的 stdio。默认值： false。
  • stdio <Array> 配置派生进程的 stdio。由于 cluster 模块依赖于 IPC 才能运行，因此此配置必须包含 'ipc' 条目。提供此选项时，它会覆盖 silent。参见 child_process.spawn() 的 stdio。
  • uid <number> 设置进程的用户标识。（参见 setuid(2)。）
  • gid <number> 设置进程的组标识。（参见 setgid(2)。）
  • inspectPort <number> | <Function> 设置工作进程的检查器端口。这可以是数字，也可以是无参数并返回数字的函数。默认情况下，每个工作进程都会获得自己的端口，从主进程的 process.debugPort 开始递增。
  • windowsHide <boolean> 隐藏在 Windows 系统上通常创建的分叉进程控制台窗口。默认值： false。

调用 .setupPrimary()（或 .fork()）后，此设置对象将包含设置，包括默认值。

此对象不打算手动更改或设置。

cluster.setupMaster([settings])#

.setupPrimary() 的弃用别名。

cluster.setupPrimary([settings])#

• settings <Object> 请参阅 cluster.settings。

setupPrimary 用于更改默认的“fork”行为。调用后，设置将出现在 cluster.settings 中。

任何设置更改仅影响对 .fork() 的未来调用，并且对已运行的 worker 没有影响。

worker 的唯一无法通过 .setupPrimary() 设置的属性是传递给 .fork() 的 env。

上面的默认值仅适用于第一次调用；后续调用的默认值是在调用 cluster.setupPrimary() 时当前的值。

import cluster from 'node:cluster';

cluster.setupPrimary({
  exec: 'worker.js',
  args: ['--use', 'https'],
  silent: true,
});
cluster.fork(); // https worker
cluster.setupPrimary({
  exec: 'worker.js',
  args: ['--use', 'http'],
});
cluster.fork(); // http workerconst cluster = require('node:cluster');

cluster.setupPrimary({
  exec: 'worker.js',
  args: ['--use', 'https'],
  silent: true,
});
cluster.fork(); // https worker
cluster.setupPrimary({
  exec: 'worker.js',
  args: ['--use', 'http'],
});
cluster.fork(); // http workercopy

这只能从主进程调用。

cluster.worker#

• <Object>

对当前 worker 对象的引用。在主进程中不可用。

import cluster from 'node:cluster';

if (cluster.isPrimary) {
  console.log('I am primary');
  cluster.fork();
  cluster.fork();
} else if (cluster.isWorker) {
  console.log(`I am worker #${cluster.worker.id}`);
}const cluster = require('node:cluster');

if (cluster.isPrimary) {
  console.log('I am primary');
  cluster.fork();
  cluster.fork();
} else if (cluster.isWorker) {
  console.log(`I am worker #${cluster.worker.id}`);
}copy

cluster.workers#

• <Object>

一个哈希表，存储活动 worker 对象，以 id 字段为键。这使得循环遍历所有 worker 变得容易。它仅在主进程中可用。

worker 在断开连接并退出后从 cluster.workers 中删除。这两个事件之间的顺序无法预先确定。但是，可以保证从 cluster.workers 列表中删除发生在最后一个 'disconnect' 或 'exit' 事件发出之前。

import cluster from 'node:cluster';

for (const worker of Object.values(cluster.workers)) {
  worker.send('big announcement to all workers');
}const cluster = require('node:cluster');

for (const worker of Object.values(cluster.workers)) {
  worker.send('big announcement to all workers');
}copy