> For the complete documentation index, see [llms.txt](https://docs.iexexchanger.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iexexchanger.com/help-center/upravlenie-serverom/pm2/nastroika-fork-i-cluster-v-pm2.md).

# Настройка Fork и Cluster в PM2

PM2 используется для запуска Frontend iEXExchanger, контроля его состояния и автоматического перезапуска при сбое.

Frontend работает через Node.js и принимает локальные подключения на порту `4000`. Nginx передаёт запросы клиентского сайта на запущенный Frontend-процесс.

PM2 позволяет использовать один процесс Frontend или несколько процессов одновременно. Количество процессов необходимо выбирать с учётом мощности сервера и фактической нагрузки.

Для большинства проектов рекомендуется начинать с одного процесса, а затем увеличивать `instances`, если это действительно требуется.

## Создание конфигурации PM2

В корневой директории Frontend создайте файл:

```
ecosystem.config.cjs
```

Добавьте:

```javascript
module.exports = {
    apps: [
        {
            name: 'iexexchanger',
            script: 'dist/exchanger/server/server.mjs',
            cwd: __dirname,

            instances: 1,
            exec_mode: 'fork',

            autorestart: true,
            watch: false,
            max_memory_restart: '1G',

            env: {
                NODE_ENV: 'production',
                PORT: 4000,
                HOST: '127.0.0.1',
                PM2: 'true',
            },

            log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
            error_file: 'logs/err.log',
            out_file: 'logs/out.log',
            merge_logs: true,
            time: true,

            listen_timeout: 10000,
            kill_timeout: 5000,
            exp_backoff_restart_delay: 100,
        },
    ],
};
```

Эта конфигурация запускает один Frontend-процесс в режиме `fork`.

После создания сохраните файл.

## Что означают `instances` и `exec_mode`

На производительность Frontend в PM2 в первую очередь влияют два параметра:

```javascript
instances: 1,
exec_mode: 'fork',
```

`instances` определяет количество одновременно работающих экземпляров Frontend.

`exec_mode` определяет способ их запуска.

PM2 поддерживает режимы `fork` и `cluster`. В режиме `cluster` PM2 может запускать несколько экземпляров Node.js-приложения и распределять между ними входящие соединения.

## Режим Fork

Базовая конфигурация:

```javascript
instances: 1,
exec_mode: 'fork',
```

В этом режиме работает один экземпляр Frontend.

Этот вариант рекомендуется использовать как начальный для большинства проектов.

Он подходит, когда:

* обменный пункт только запускается;
* нагрузка на Frontend небольшая или средняя;
* на одном сервере также работают Backend, PostgreSQL, Redis и фоновые процессы;
* нет необходимости использовать несколько процессов Frontend.

Преимущество такой конфигурации — предсказуемое потребление ресурсов и простая диагностика.

Если одного процесса достаточно для текущей нагрузки, увеличивать `instances` не требуется.

## Режим Cluster

Для запуска нескольких Frontend-процессов используется `cluster`.

Например:

```javascript
instances: 2,
exec_mode: 'cluster',
```

PM2 запустит два экземпляра Frontend и будет распределять входящие соединения между ними. Cluster Mode предназначен именно для использования нескольких процессов Node.js и распределения нагрузки между ними.

Например, можно использовать:

```javascript
instances: 4,
exec_mode: 'cluster',
```

если сервер имеет достаточный запас ресурсов и такая конфигурация действительно требуется по нагрузке.

{% hint style="warning" %}
Каждый дополнительный `instance` — это отдельный процесс Node.js, который использует процессор и оперативную память.

Не увеличивайте количество процессов только потому, что сервер имеет несколько vCPU.
{% endhint %}

## Можно ли использовать один процесс в Cluster Mode

Да. Допустима конфигурация:

```javascript
instances: 1,
exec_mode: 'cluster',
```

Frontend будет работать с одним экземпляром, но через Cluster Mode.

При одном процессе преимуществ распределения нагрузки между несколькими экземплярами нет. Такой вариант можно использовать, если вы планируете в дальнейшем увеличивать `instances` и хотите сразу оставить Frontend в режиме `cluster`.

Например, сначала:

```javascript
instances: 1,
exec_mode: 'cluster',
```

а при росте нагрузки изменить только количество:

```javascript
instances: 2,
exec_mode: 'cluster',
```

После этого конфигурацию не потребуется переводить с `fork` на `cluster`.

## Какой режим выбрать

Для большинства проектов используйте один из двух вариантов.

| Вариант            | Конфигурация              | Когда использовать                           |
| ------------------ | ------------------------- | -------------------------------------------- |
| **Стандартный**    | `1` instance, `fork`      | Рекомендуемый начальный вариант              |
| **Масштабируемый** | `1+` instances, `cluster` | Когда требуется несколько Frontend-процессов |

Если вы не знаете, какой вариант нужен, начинайте с:

```javascript
instances: 1,
exec_mode: 'fork',
```

Если вы понимаете работу PM2, контролируете ресурсы сервера и планируете масштабировать Frontend, можно сразу использовать:

```javascript
instances: 1,
exec_mode: 'cluster',
```

а затем постепенно увеличивать `instances`.

## Сколько `instances` использовать

Не существует одного правильного количества процессов для всех серверов.

Количество зависит от:

* количества vCPU;
* объёма RAM;
* нагрузки на Frontend;
* количества одновременных посетителей;
* нагрузки на остальные службы сервера.

Если Frontend, Backend, PostgreSQL, Redis и фоновые процессы работают на одном сервере, нельзя отдавать все ресурсы только PM2.

Для стандартных конфигураций iEXExchanger можно использовать следующую отправную точку:

| Сервер                  | PM2           | Рекомендация                                                 |
| ----------------------- | ------------- | ------------------------------------------------------------ |
| **2–4 vCPU, 8 GB RAM**  | 1 instance    | Оставить `fork`                                              |
| **4 vCPU, 16 GB RAM**   | 1 instance    | Начать с `fork`, при необходимости проверить `2` в `cluster` |
| **8+ vCPU, 32+ GB RAM** | 1–2 instances | Увеличивать постепенно после проверки нагрузки               |

Эти значения не являются жёсткими ограничениями.

Например, сервер с `4 vCPU` не означает, что нужно обязательно устанавливать:

```javascript
instances: 4,
```

Часть ресурсов требуется Backend, PostgreSQL, Redis, очередям и другим процессам.

{% hint style="info" %}
Лучший подход — начать с одного процесса, посмотреть фактическую нагрузку и увеличивать количество экземпляров только при необходимости.
{% endhint %}

## Почему не рекомендуется сразу использовать `max`

PM2 позволяет автоматически использовать максимальное количество доступных процессорных ядер.

Например:

```javascript
instances: 'max',
exec_mode: 'cluster',
```

Также PM2 поддерживает значение `0`, при котором количество процессов определяется по доступным CPU.

Для стандартной установки iEXExchanger использовать `max` без контроля ресурсов не рекомендуется.

Если сервер имеет 8 vCPU, PM2 может запустить несколько экземпляров Frontend, хотя на этом же сервере должны работать PostgreSQL, Redis, PHP и другие компоненты.

В результате увеличение количества Frontend-процессов может не ускорить проект, а создать дополнительную нагрузку.

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

```javascript
instances: 2,
exec_mode: 'cluster',
```

и затем проверить результат.

## Как увеличить количество процессов

Если Frontend уже работает в Cluster Mode, количество процессов можно изменить в конфигурации.

Например, было:

```javascript
instances: 1,
exec_mode: 'cluster',
```

измените на:

```javascript
instances: 2,
exec_mode: 'cluster',
```

После изменения перезагрузите приложение:

```bash
pm2 reload ecosystem.config.cjs
```

Для сетевых приложений Cluster Mode поддерживает перезагрузку процессов без обычного полного остановочного цикла `restart`: PM2 запускает новые workers и заменяет старые.

Количество процессов также можно изменять через PM2:

```bash
pm2 scale iexexchanger 2
```

Например:

```bash
pm2 scale iexexchanger 4
```

устанавливает четыре экземпляра процесса. Команда `pm2 scale` поддерживается PM2 для изменения количества workers.

Если вы изменили рабочую конфигурацию, не забудьте сохранить текущее состояние:

```bash
pm2 save
```

## Как проверить нагрузку

Перед увеличением `instances` проверьте текущее состояние Frontend.

### Список процессов

Выполните:

```bash
pm2 list
```

Команда показывает запущенные процессы, их состояние, использование памяти и другую основную информацию.

Если используется Cluster Mode с несколькими экземплярами, в списке будут отображаться отдельные процессы `iexexchanger`.

### Мониторинг в реальном времени

Для наблюдения за CPU и памятью выполните:

```bash
pm2 monit
```

PM2 откроет мониторинг процессов непосредственно в терминале.

Не оценивайте необходимость масштабирования сразу после запуска.

Проверяйте сервер во время обычной и повышенной нагрузки.

## Как понять, нужно ли увеличивать `instances`

Увеличивать количество процессов имеет смысл, если Frontend действительно становится ограничением.

Перед изменением проверьте:

* нагрузку CPU Frontend;
* использование памяти процессами;
* общую загрузку сервера;
* остаётся ли запас ресурсов для PostgreSQL, Redis и Backend;
* изменяется ли скорость работы Frontend при высокой нагрузке.

Если один Frontend-процесс работает стабильно и не создаёт ограничений, оставьте:

```javascript
instances: 1,
```

Большее количество процессов само по себе не означает более быстрый сайт.

## Ограничение памяти

В конфигурации используется:

```javascript
max_memory_restart: '1G',
```

PM2 контролирует потребление памяти процесса и может перезапустить его после превышения установленного значения. Форматы `K`, `M` и `G` поддерживаются PM2.

Важно учитывать, что значение применяется к отдельному процессу.

Например:

```javascript
instances: 4,
exec_mode: 'cluster',
max_memory_restart: '1G',
```

означает запуск четырёх отдельных процессов Frontend.

Поэтому при увеличении `instances` всегда контролируйте общее использование RAM.

## Автоматический перезапуск

Параметр:

```javascript
autorestart: true,
```

разрешает PM2 автоматически перезапускать Frontend после аварийного завершения процесса.

Параметр:

```javascript
exp_backoff_restart_delay: 100,
```

используется для увеличивающейся задержки между повторными попытками запуска при последовательных сбоях.

Это помогает избежать слишком частых перезапусков, если приложение не может нормально запуститься.

## Почему отключён `watch`

Используется:

```javascript
watch: false,
```

Для production-сервера автоматический перезапуск Frontend при изменении файлов не требуется.

Обновление приложения должно выполняться контролируемо, после чего Frontend перезапускается или перезагружается через PM2.

PM2 поддерживает автоматический режим `watch`, но он предназначен для перезапуска приложения при изменении файлов.

## Логи Frontend

В конфигурации используются:

```javascript
error_file: 'logs/err.log',
out_file: 'logs/out.log',
```

Ошибки Frontend записываются в:

```
logs/err.log
```

Обычный вывод:

```
logs/out.log
```

Посмотреть текущие логи через PM2 можно командой:

```bash
pm2 logs iexexchanger
```

Для вывода последних строк:

```bash
pm2 logs iexexchanger --lines 200
```

PM2 предоставляет просмотр логов непосредственно через `pm2 logs`.

Если Frontend не запускается или постоянно перезапускается, проверка логов должна быть одним из первых действий.

## Запуск Frontend

После создания `ecosystem.config.cjs` перейдите в директорию Frontend и выполните:

```bash
pm2 start ecosystem.config.cjs
```

Проверьте результат:

```bash
pm2 list
```

Процесс должен отображаться с названием:

```
iexexchanger
```

и находиться в рабочем состоянии.

## Перезапуск и перезагрузка

Для обычного перезапуска:

```bash
pm2 restart iexexchanger
```

В режиме `cluster` предпочтительно использовать:

```bash
pm2 reload iexexchanger
```

`restart` останавливает и заново запускает процесс, а `reload` в Cluster Mode предназначен для последовательной замены workers с минимизацией простоя.

После изменения `ecosystem.config.cjs` можно выполнить:

```bash
pm2 reload ecosystem.config.cjs
```

## Автоматический запуск после перезагрузки сервера

Просто запустить Frontend через PM2 недостаточно. Необходимо также настроить восстановление процессов после перезагрузки Linux.

Сначала выполните:

```bash
pm2 startup
```

PM2 определит используемую систему запуска и выведет дополнительную команду.

Скопируйте и выполните команду, которую покажет PM2.

После этого сохраните текущий список процессов:

```bash
pm2 save
```

PM2 использует сохранённый список для восстановления приложений после перезагрузки сервера.

{% hint style="warning" %}
`pm2 save` необходимо выполнять под тем пользователем, от которого запускается Frontend.

Не запускайте один и тот же Frontend одновременно через PM2 разных пользователей.
{% endhint %}

## Проверка после перезагрузки

После настройки автозапуска рекомендуется проверить его реальной перезагрузкой сервера.

После запуска сервера выполните:

```bash
pm2 list
```

Убедитесь, что `iexexchanger` появился в списке автоматически.

Затем откройте клиентский сайт:

```
https://ваш_домен
```

Frontend должен работать без ручного запуска PM2.

## Если после перезагрузки Frontend не запустился

Сначала выполните:

```bash
pm2 list
```

Если список пустой, проверьте, выполнялись ли:

```bash
pm2 startup
```

и:

```bash
pm2 save
```

При необходимости ранее сохранённый список процессов можно восстановить вручную:

```bash
pm2 resurrect
```

PM2 использует `resurrect` для восстановления списка, ранее сохранённого через `pm2 save`.

Если процесс существует, но находится в состоянии ошибки, откройте его логи:

```bash
pm2 logs iexexchanger --lines 200
```

## Рекомендуемая базовая конфигурация

Если у вас обычный production-сервер и нет отдельной причины использовать несколько экземпляров Frontend, используйте:

```javascript
instances: 1,
exec_mode: 'fork',
```

Если вы заранее хотите использовать Cluster Mode:

```javascript
instances: 1,
exec_mode: 'cluster',
```

также является допустимым вариантом.

При росте нагрузки можно перейти на:

```javascript
instances: 2,
exec_mode: 'cluster',
```

и проверить изменение нагрузки и производительности.

Дальнейшее увеличение:

```javascript
instances: 3,
```

```javascript
instances: 4,
```

или больше должно выполняться только после контроля CPU, RAM и общей нагрузки сервера.

Не используйте `instances: 'max'` только для того, чтобы задействовать все доступные vCPU. На сервере iEXExchanger ресурсы требуются не только Frontend, но и остальным компонентам проекта.

## Проверка настройки

Настройка PM2 выполнена правильно, если:

* `pm2 list` показывает процесс `iexexchanger`;
* процесс находится в рабочем состоянии;
* Frontend отвечает на локальном порту `4000`;
* клиентский сайт открывается через Nginx;
* в `logs/err.log` нет постоянных ошибок запуска;
* после перезагрузки сервера процесс восстанавливается автоматически;
* выбранное количество `instances` не создаёт нехватку CPU или оперативной памяти.

Начинайте с минимально необходимого количества процессов и увеличивайте его только после проверки реальной нагрузки. Это позволяет использовать ресурсы сервера предсказуемо и не отбирать их у Backend, PostgreSQL, Redis и других компонентов iEXExchanger.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.iexexchanger.com/help-center/upravlenie-serverom/pm2/nastroika-fork-i-cluster-v-pm2.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.