Перейти к основному содержимому

Масштабирование

OrderInventory отвечает на запросы, сообщает конечные точки через обнаружение и ведёт их статистику. Пока всё это делает один экземпляр. Здесь запустим несколько.

Предполагается, что вы прочитали подробную главу Core NATS и знаете запросы и ответы и группы очередей. Для масштабирования ничего сверх этого не нужно. При создании сервиса фреймворк уже поместил каждую конечную точку в группу очереди, как показано на первой странице. Эта группа и обеспечивает масштабирование: запускаете больше копий, а сервер распределяет между ними запросы.

Здесь рассмотрены две задачи: как N экземпляров балансируют нагрузку без дополнительной настройки и как остановить экземпляр, не потеряв принятую им работу.

Запуск дополнительных экземпляров​

Горизонтальное масштабирование — запуск нескольких копий одного сервиса. Каждая копия — экземпляр: работающий сервис со своим идентификатором. Все экземпляры OrderInventory имеют одно имя и версию; различается лишь автоматически созданный идентификатор сервиса.

Регистрировать экземпляры или настраивать балансировщик не нужно. Запустите второй так же, как первый, с теми же Name, Version и конечной точкой. Фреймворк создаст новый идентификатор сервиса, и экземпляр присоединится к работе.

Запросы распределяет группа очереди по умолчанию "q". Каждая конечная точка входит в неё, если вы не переопределили настройку. Когда несколько экземпляров подписаны на orders.inventory.check в одной группе, сервер доставляет каждый запрос ровно одному участнику. При двух экземплярах один входящий запрос обрабатывает один из них. Это поведение групп очередей Core NATS, автоматически применённое к экземплярам; механизм описан на странице Группы очередей.

Запустите второй экземпляр, отправьте серию заказов и посмотрите распределение:

#!/bin/bash
# Scale OrderInventory by running more instances. There is no scaling
# command and no coordinator to register with: you start another copy of
# the same service, with the same Name, Version, and endpoint, and the
# framework does the rest. Each copy gets its own service ID but shares the
# name OrderInventory and the default queue group "q".
#
# The CLI has no flag to host this shape (`nats service serve` only runs a
# demo echo service), so start the second instance by running your service
# program again, in another terminal, while the first is still up.

# With two instances up, send a burst of requests. --count sends the
# request six times; because both instances joined the queue group "q",
# the server delivers each one to a single instance, so the six spread
# across the two without any extra config.
nats service request OrderInventory check \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}' \
--count 6

# Confirm both instances are answering. `nats service stats` aggregates
# the per-instance counters by name, so num_requests across the two
# instances should add up to the six requests you just sent.
nats service stats OrderInventory

Шесть запросов распределятся между двумя экземплярами примерно по три. Это не управляемый вами round-robin: сервер доставляет каждое сообщение готовому участнику группы. Добавьте третий экземпляр — те же шесть запросов распределятся между тремя. Координатора нет; группа очереди на сервере решает это для каждого запроса.

Анимация показывает пять экземпляров OrderInventory в группе "q". Каждый запрос подсвечивает ровно один экземпляр, а следующий может попасть другому. Вся модель масштабирования: больше участников одной группы и одна доставка на запрос.

Отключение группы нарушает эту модель. С WithEndpointQueueGroupDisabled вы познакомились на странице Конечные точки и группы: конечная точка становится обычной подпиской, и каждый экземпляр получает каждый запрос. Это широковещательная доставка, полезная для рассылки всем участникам, но не для балансировки. Для масштабирования оставляйте группу очереди включённой.

Корректная остановка экземпляра​

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

Фреймворк поддерживает корректную остановку. Вызов Stop() сервиса выполняет drain подписки каждой конечной точки: сразу удаляет её интерес в группе очереди, поэтому сервер больше не направляет сюда новые запросы, затем отменяет подписки обнаружения $SRV. Уже принятые запросы продолжают обрабатываться в фоне. Stop() возвращается до завершения этой обработки, поэтому не завершайте процесс сразу: поддерживайте экземпляр работающим (выполните drain соединения или дождитесь DoneHandler фреймворка) до завершения текущей работы, иначе она всё же потеряется.

Поскольку при остановке конечная точка выходит из группы очереди, оставшиеся экземпляры автоматически получают все новые запросы. Нет промежутка, когда запрос попадает в группу, чей единственный участник только что исчез. Остановите экземпляр — остальные примут нагрузку:

#!/bin/bash
# Stop one instance gracefully. A graceful stop drains the endpoint
# subscriptions: it removes the instance's queue-group interest so the
# server stops routing new requests to it, lets requests already accepted
# finish processing, and unsubscribes the $SRV discovery verbs, so the
# instance disappears cleanly instead of dropping work on the floor.
#
# This is a client-library behavior: your service calls Stop() (svc.Stop()).
# There is no CLI equivalent. Ctrl-C on `nats service serve` closes the
# connection abruptly, with no drain, which is the failure mode to avoid.
# Stop the instance from your own service, then use the CLI to confirm the
# result.

# After stopping one instance, discovery reflects the new count. PING
# returns one reply per running instance, so a name that had two
# instances now answers with one.
nats service ping OrderInventory

# The remaining instance keeps answering. Send another order to confirm
# the queue group now routes every request to the one that is left.
nats service request OrderInventory check \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'

После остановки PING возвращает на один ответ меньше, а nats service stats агрегирует оставшиеся экземпляры. Для постепенного обновления версии сначала запускайте новые экземпляры, затем по одному останавливайте старые; в каждый момент хотя бы один участник группы отвечает на заказы.

Если сервису нужно долговременное состояние, переживающее остановку (несбрасываемый счётчик или очередь работ, живущая дольше процесса), оно не должно храниться в экземпляре. Сервис ничего не сохраняет: это запросы и ответы с доставкой не более одного раза. Храните долговременное состояние в JetStream. Выполнение drain самого соединения при завершении, помимо Stop() фреймворка, рассматривается в главе об устойчивых клиентах.

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

Подводные камни​

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

У экземпляров нет общей памяти — защищайте внешнее состояние. Если обработчик увеличивает счётчик, кэширует значение или резервирует запас в локальной переменной, у каждого экземпляра своя копия. При трёх экземплярах получаются три независимых счётчика, кэша и представления об остатке товара, которые расходятся. Не предполагайте, что один экземпляр хранит правильное значение. Делайте обработчики без состояния, а необходимое общее состояние переносите во внешнее хранилище: базу данных, поток JetStream или бакет ключей и значений, через который читают и пишут все экземпляры. Экземпляры остаются взаимозаменяемыми, а состояние хранится в общем месте.

Блокирующий обработчик мешает экземпляру обслуживать другие запросы. Обработчики выполняются синхронно на соединении сервиса. Пока один блокируется на медленном запросе к базе, ожидании или блокировке, экземпляр не отвечает на другие запросы. Группа очереди некоторое время скрывает это, отправляя запросы другим участникам, но если заблокируются все, остановится весь сервис. Не выполняйте медленную работу непосредственно в обработчике. Поддерживайте быстрые обработчики, выносите длительные задачи из пути запроса и добавляйте экземпляры, чтобы остальные компенсировали краткую задержку одного.

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

#!/bin/bash
# Stop one instance gracefully. A graceful stop drains the endpoint
# subscriptions: it removes the instance's queue-group interest so the
# server stops routing new requests to it, lets requests already accepted
# finish processing, and unsubscribes the $SRV discovery verbs, so the
# instance disappears cleanly instead of dropping work on the floor.
#
# This is a client-library behavior: your service calls Stop() (svc.Stop()).
# There is no CLI equivalent. Ctrl-C on `nats service serve` closes the
# connection abruptly, with no drain, which is the failure mode to avoid.
# Stop the instance from your own service, then use the CLI to confirm the
# result.

# After stopping one instance, discovery reflects the new count. PING
# returns one reply per running instance, so a name that had two
# instances now answers with one.
nats service ping OrderInventory

# The remaining instance keeps answering. Send another order to confirm
# the queue group now routes every request to the one that is left.
nats service request OrderInventory check \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'

Если запрос после остановки получает ответ, группа очереди перераспределила нагрузку корректно и заказ не потерян.

Текущее состояние​

Теперь у вас есть:

  • Несколько экземпляров OrderInventory с одинаковыми именем, версией и стандартной группой очереди "q".
  • Распределение запросов без координатора: сервер выбирает одну доставку на запрос.
  • Корректный Stop(), завершающий текущую работу и выводящий экземпляр из группы очереди, чтобы оставшиеся приняли нагрузку без потерь.

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

Что дальше​

Теперь рассмотрен весь фреймворк: именованный сервис с версией, конечными точками и группами; обнаружение и наблюдение через $SRV; масштабирование запуском экземпляров. Последняя страница подводит итоги и указывает, где искать остальные подробности.

Переходите к странице Куда двигаться дальше.

См. также​

  • Группы очередей — механизм балансировки, лежащий в основе стандартной группы "q".
  • JetStream — долговременное состояние для работ, которые должны пережить остановку экземпляра.
  • Справочник — все поля жизненного цикла сервиса и конфигурации групп очередей.