# Масштабирование и управление участниками

`ORDERS` работает с `R=3` на `n1-east`, `n2-east`, `n3-east` согласно [размещению](/learn/clustering/placement.md). Состав не фиксирован навсегда: можно увеличить число копий или перенести реплику с выводимого сервера без остановки потока и потери согласованности.

Здесь меняется состав работающей группы RAFT. **Участник** — роль сервера в группе `ORDERS`, как определено в [RAFT и лидерах](/learn/clustering/raft-and-leaders.md). Управление состоит из **расширения группы** с синхронизацией нового участника и **переноса реплики** с сервера.

**Движение сообщений — Добавление и удаление участника (анимация):** Увеличение и уменьшение группы ORDERS. Новый n4-east получает недостающие записи до нулевого отставания и отметки актуальности в stream info. Пока истории нет, он не может выиграть выборы; полагаться на него как на реплику с данными следует только после синхронизации. Позже участник удаляется: лидер метаданных размещает его реплику на другом сервере, удалённый узел отменяет подписки RAFT, остальные продолжают работу.

* n1-east (лидер) → n2-east
* n2-east → n3-east
* n1-east (лидер) → n3-east
* n1-east (лидер) → RAFT (тема: AddPeer)
* n1-east (лидер) → RAFT (тема: синхронизация)
* n1-east (лидер) → RAFT (тема: отставание → 0)
* n2-east → RAFT
* n3-east → RAFT
* n1-east (лидер) → RAFT (тема: RemovePeer)
* n1-east (лидер) → RAFT (тема: потеряно)

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

## Расширение группы: синхронизация нового участника

Увеличьте число реплик потока. Четвёртый сервер уже должен входить в `east`: запустите `n4-east` с конфигурацией [первой страницы](/learn/clustering/forming-a-cluster.md), дождитесь присоединения, затем увеличьте `ORDERS` с трёх до четырёх реплик:

```
nats --server nats://127.0.0.1:4222 stream edit ORDERS --replicas=4
```

Имя нового сервера не задаётся. Лидер метаданных выбирает узел, подходящий под [размещение](/learn/clustering/placement.md), записывает состав в журнал назначений, и группа `ORDERS` принимает `n4-east`.

Новый участник пока не содержит историю потока. Сначала выполняется **догоняющая синхронизация**: лидер передаёт недостающую часть журнала, участник применяет записи, а отставание стремится к нулю. Здесь оно измеряет число недостающих записей журнала лидера.

Добавление сразу меняет кворум: `R=4` требует трёх держателей записи вместо двух. Пока журнал пуст, новый участник не может победить на выборах: он остаётся наблюдателем до первых записей лидера. Практическое правило — не считать `n4-east` полноценной копией данных до отметки `current` в `stream info`.

Наблюдайте синхронизацию в блоке `Cluster` команды `nats stream info`:

```
nats --server nats://127.0.0.1:4222 stream info ORDERS
```

В `Replicas` появилась четвёртая запись с уменьшающимся отставанием:

```
Cluster Information:



                Name: east

              Leader: n1-east

             Replica: n2-east, current, seen 0.12s ago

             Replica: n3-east, current, seen 0.20s ago

             Replica: n4-east, outdated, seen 0.18s ago, 14,231 operations behind
```

`outdated` и число недостающих операций означают продолжающуюся синхронизацию. После `current` без отставания `n4-east` содержит полный поток и работает как обычная реплика.

## Перенос реплики с сервера

Для освобождения сервера выполните **эвакуацию** участника. Она не уменьшает поток: реплика переносится на другой подходящий сервер при сохранении количества. Укажите поток и освобождаемый узел:

```
nats --server nats://127.0.0.1:4222 stream cluster evacuate ORDERS n4-east
```

Лидер метаданных выбирает замену и записывает новый состав, но `n4-east` пока остаётся в группе. Замена присоединяется и синхронизируется; только после её готовности фиксируется изменение, исключающее `n4-east`. Если уходящий узел был лидером, до ухода выбирается новый.

Если размещение не допускает замену, запрос возвращает `peer remap failed` и ничего не меняет. Это защищает заданное число реплик. Исправьте условия или добавьте подходящий сервер, затем повторите.

Потребители перемещаются вместе с потоком. Отдельного потребителя тоже можно перенести:

```
nats --server nats://127.0.0.1:4222 consumer cluster evacuate ORDERS NEW n4-east
```

Чтобы изменить *количество*, например `R=3` на `R=1`, используйте `nats stream edit ORDERS --replicas=1`. Эвакуация меняет расположение, `--replicas` — число копий.

Сразу после команды группа может ещё перемещаться. Оба участника видны одновременно, замена отстаёт, а присоединяющийся или уходящий узел отмечен `(pending)`.

#### CLI

```
#!/bin/bash



# Move a replica off one server, safely, then verify the new peer set

# before trusting the change.

#

# This assumes the east cluster (n1-east on 4222, n2-east on 4223,

# n3-east on 4224, plus a fourth server n4-east) is running and ORDERS

# holds a replica on n4-east. Evacuating does NOT shrink the stream: it

# moves the replica off n4-east onto another qualifying server, so the

# replica count stays the same. Make ONE change at a time and wait for a

# leader and a caught-up replacement before the next -- stacking changes

# can drop the peers holding the data below a majority and the stream

# stops committing.



# First, read the current peer set. The Cluster block lists the leader

# and every replica with its lag. Confirm there is a leader and that

# every replica's lag is 0 before you change anything — a peer mid

# catchup is not safe to lean on.

nats --server nats://127.0.0.1:4222 stream info ORDERS



# Move the replica off one server by name. The meta leader picks a

# replacement server and records the new peer set, but n4-east does not

# drop out yet: it keeps serving the stream while the replacement joins

# and catches up, and only then does the change removing it commit.

#

# If no other server qualifies -- placement is too narrow, or the cluster

# is too small -- the request fails with "peer remap failed" and NOTHING

# moves. That refusal protects the replica count; fix the placement or

# add a qualifying server, then run this again. Do not reach for --force.

#

# (To change the replica COUNT, use: nats stream edit ORDERS --replicas=N)

nats --server nats://127.0.0.1:4222 stream cluster evacuate ORDERS n4-east



# A single consumer can be moved on its own the same way:

#

#   nats --server nats://127.0.0.1:4222 consumer cluster evacuate ORDERS NEW n4-east



# Verify. Run this while the move is in flight and you see it in

# progress: both peers listed, the replacement behind on lag, and a

# "(pending)" marker on the peer joining or on its way out.

#

# The move is done when n4-east is gone from the Replicas list and the

# migration section is no longer printed. Do not wait on lag reaching 0

# instead: a stream taking constant writes always has followers slightly

# behind, since a write commits once a quorum holds it.

#

# If the move looks stuck, the migration section carries a status line

# saying what it is waiting on.

nats --server nats://127.0.0.1:4222 stream info ORDERS
```

Перенос завершён, когда `n4-east` исчез из `Replicas`, а `stream info` больше не показывает раздел миграции. Не используйте нулевое отставание как единственный критерий: при постоянных записях ведомые могут немного отставать, поскольку фиксация требует кворума, а не всех копий. Если перенос завис, строка состояния миграции объяснит ожидание; её разбирает [следующая страница](/learn/clustering/desired-state.md).

Удаление сервера из **группы метаданных** — другая команда: `nats server cluster peer-remove`. Она разрешает лишь одно изменение одновременно; повторное возвращает `cluster member change is in progress`. Дождитесь завершения. Эта операция предназначена для навсегда потерянного сервера, а для работающего применяется эвакуация.

Перед peer-remove обязательно остановите сервер. Работающий узел в ответ отключает у себя JetStream — это прервёт обслуживание вместо удаления уже остановленного участника.

Все операции управления участниками и назначениями описаны в [справочнике](/reference/jetstream/api/meta/.md). Здесь нужны расширение, перенос и проверка.

## Типичные ошибки

Две распространённые ошибки связаны с синхронизацией нового участника и переносом реплики.

**Расширение временно уменьшает запас устойчивости.** Переход с трёх реплик на четыре повышает кворум с двух до трёх. Новый участник ещё не имеет истории и до синхронизации не может дать необходимое подтверждение, поэтому требуются все три исходных узла. Потеря одного приостанавливает запись до готовности нового. Временно четыре реплики терпят меньше отказов, чем прежние три. Окно закрывается при `current` нового участника.

**`peer remap failed` означает безопасный отказ без изменений.** При отсутствии подходящего сервера эвакуация потока или потребителя отклоняется вместо потери реплики. Исправляйте размещение или добавляйте ресурсы, не обходите отказ через `--force`. Иначе ведёт себя лишь общесерверный `nats server cluster evacuate`: он освобождает узел по возможности и может оставить ресурс с недостаточным числом реплик. Различие разобрано на [следующей странице](/learn/clustering/desired-state.md).

Эвакуация не меняет число копий. Для `R=3` → `R=1` прочитайте текущее значение и примените `nats stream edit --replicas`.

## Что уже готово

Теперь вы умеете менять работающую группу RAFT без остановки потока:

* Увеличивать `--replicas` и ждать синхронизации до `current`.
* Переносить реплику через `nats stream cluster evacuate`, сохраняя количество и проверяя лидера.
* Понимать `peer remap failed` как защиту числа реплик без выполненного перемещения.

`ORDERS` снова находится на `n1-east`, `n2-east`, `n3-east`, но теперь вы умеете осознанно менять состав.

## Что дальше

До сих пор вы меняли группу по одному участнику и ждали вручную. Начиная с 2.15 сервер сохраняет целевое состояние и сам доводит изменение до конца. Это позволяет освободить сервер одной командой или отменить ошибочно начатый перенос.

Перейдите к [желаемому состоянию и эвакуации](/learn/clustering/desired-state.md).

## См. также

* [RAFT и лидеры](/learn/clustering/raft-and-leaders.md) — выборы и `leader-stepdown` при выводе лидера.
* [Желаемое состояние и эвакуация](/learn/clustering/desired-state.md) — модель 2.15 и массовый перенос.
* [Справочник → API метаданных](/reference/jetstream/api/meta/.md) — все операции участников и назначений.
* [Резервное копирование и восстановление](/learn/backup-recovery/.md) — копия перед рискованным изменением состава.
