---
title: "Nginx-роутинг"
id: "1536"
type: "page"
slug: "routes"
published_at: "2026-08-28T05:15:08+00:00"
modified_at: "2026-09-05T01:25:59+00:00"
url: "https://pastukhov.com/agents/multiagent/docs/routes"
markdown_url: "https://pastukhov.com/agents/multiagent/docs/routes.md"
excerpt: "MultiAgent никогда не распределяет запросы сам: на каждом сервере работает свой Nginx-контейнер agents-nginx, который MultiAgent…"
---

# Nginx-роутинг

[https://pastukhov.com/agents/multiagent/docs/routes.md](https://pastukhov.com/agents/multiagent/docs/routes.md)

MultiAgent никогда не распределяет запросы сам: на каждом сервере работает свой Nginx-контейнер `agents-nginx`, который MultiAgent разворачивает, настраивает и обновляет. Все приложения сервера — агенты, продукты, инструменты с веб-интерфейсом и произвольные сервисы — раздаются по подпапкам одного адреса: `{база}/{слаг}/`. Никаких отдельных доменов, поддоменов и ручных конфигов под каждое приложение: у сервера один адрес, и каждое приложение живёт в своей подпапке.

## Как это работает

На каждом управляемом сервере MultiAgent поднимает один контейнер `agents-nginx` (образ `nginx:alpine`, сервис `nginx`). Контейнер ставится из вкладки **Nginx** страницы сервера: MultiAgent создаёт файлы конфигурации на сервере (загружаются по защищённому каналу), присоединяет контейнер к общей docker-сети и запускает его.

Конфигурация маршрутов собирается из базы MultiAgent автоматически: при каждом изменении (создали агента, продукт или инструмент, добавили или отредактировали кастомный маршрут, изменили порты) конфиг пересобирается и применяется сам. Установки показывают свои шаги в ленте прогресса, изменения записей применяются в фоне. Кнопка **«Apply configuration»** во вкладке прогоняет то же обновление вручную — удобно, когда правку сделали прямо на сервере.

## Источники маршрутов

Общая таблица маршрутов собирается из трёх источников:

- **Агенты и продукты** — каждая развёрнутая запись агента (включая продукты из каталога) автоматически даёт маршрут: появляется вместе с записью и исчезает с её удалением;
- **Инструменты с веб-интерфейсом** — инструмент, у шаблона которого объявлен веб-порт, получает маршрут автоматически (порт берётся из шаблона и обновляется при каждом развёртывании); без веб-порта инструмент остаётся на прямом адресе `http://{хост}:{порт}`;
- **Кастомные маршруты** — единственный вид с ручным управлением: произвольный http(s)-адрес (не обязательно управляемый MultiAgent — служба на своём порту, локальный сервис, внешняя система), с редактированием, отключением и удалением.

Вкладка показывает все маршруты, отсортированные по слагу, с публичным адресом и целью для каждого; автоматические виды помечены «Managed by MultiAgent» и кликом ведут к исходной записи.

## Схема трафика

Трафик идёт так: `http(s)://{хост сервера}/{слаг}/` → Nginx сервера → контейнер приложения во внутренней docker-сети (`{имя контейнера}:{порт}`). Приложения адресуются по именам контейнеров, поэтому публиковать порты наружу не нужно.

- **Резолвинг на лету** — конфиг использует внутренний резолвер и переменные адресов: Nginx стартует и работает независимо от того, какие приложения существуют. Неработающее, остановленное или ещё не развёрнутое приложение даёт ошибку только на своей подпапке, остальные маршруты продолжают работать;
- **WebSocket и большие ответы** — поддерживаются постоянные соединения (живые чаты агентов), длинные таймауты и безлимитный размер передаваемых данных;
- **Заголовки** — приложению передаются служебные данные о префиксе, хосте и схеме, поэтому чувствительные к префиксу приложения строят правильные абсолютные адреса; за внешним прокси приложения получают https-схему и исходный хост;
- **Корень `/`** — отдаётся домашней страницей сервера Heimdall, когда она установлена (см. ниже); без неё корень ведёт себя как обычная резервная страница.

## Пространство имён и зарезервированные префиксы

Слаг первого уровня — единое пространство имён на каждый сервер, общее для агентов, продуктов, инструментов и кастомных маршрутов: один и тот же слаг может существовать на разных серверах, но на одном сервере его можно занять только один раз. Слаги — только строчные буквы, цифры и дефисы (`[a-z0-9-]+`).

Служебные пути MultiAgent зарезервированы и не могут стать слагами: `api`, `v1`, `swagger`, `servers`, `agents`, `tools`, `workspaces`, `analytics`, `accounts`, `data` и другие пути интерфейса. Агента с именем `api` или `servers` создать нельзя — форма подсветит это сразу, а сервер отклонит запись.

## Кастомные маршруты

Кастомный маршрут направляет подпапку на любой абсолютный http(s)-адрес, доступный с сервера: служба на своём порту, локальное приложение, внешняя система. Для создания нужны имя, слаг по правилам пространства имён и цель — абсолютный адрес вида http(s)://… (значение без схемы отклоняется).

- Каждое изменение (создание, редактирование, включение, отключение, удаление) сразу пересобирает и применяет конфиг;
- Отключённый маршрут убирает свою подпапку — она начинает отвечать ошибкой 404, запись остаётся в таблице;
- Удаление освобождает слаг для любого вида — другой агент, инструмент или маршрут сможет его занять;
- Если у цели есть собственный базовый путь (например, `http://host/wiki`), он подставляется вместо слага: `/{слаг}/docs/page` достигает `/wiki/docs/page`.

## Сертификаты

Сертификаты управляются из того же вкладки Nginx — три вида:

- **Самоподписанный** — генерируется MultiAgent и служит резервным сертификатом; его можно скачать как файл `.crt` и импортировать в доверенные сертификаты системы;
- **Собственная пара PEM** — вставляется или загружается; цепочка и ключ проверяются до записи (ключ должен совпадать с сертификатом, просроченный отклоняется с предупреждением);
- **Let’s Encrypt** — бесплатные сертификаты через сам Nginx (проверка владения доменом по протоколу ACME): тестовая (staging) и рабочая площадка, один запрос за раз, домен должен указывать на сервер.

Ключевые материалы хранятся только на сервере (папка `ssl/{домен}/`: полная цепочка + приватный ключ) и монтируются в контейнер только для чтения — в базе MultiAgent лишь метаданные. Каждое обновление конфигурации продлевает сертификаты, истекающие в течение 30 дней (самоподписанные перегенерируются, Let’s Encrypt запрашивается заново), плюс есть ручное продление по строке. HTTPS-порт опционален: пока он пуст, публикуется только HTTP, и сертификаты хранятся, но не раздаются.

## Домашняя страница сервера (Heimdall)

Корень `/` Nginx отдаёт домашнюю страницу сервера **Heimdall**, когда контейнер установлен (вкладка Heimdall страницы сервера; требуется установленный Nginx). Карточки приложений синхронизируются из базы MultiAgent с реальными логотипами проектов, а страница защищена собственным входом — отдельной учётной записью, не связанной с аккаунтами MultiAgent. Подробнее — на странице [Домашняя страница сервера](/agents/multiagent/docs/heimdall)
.

Подпапки приложений всегда имеют приоритет над путями Heimdall: агент со слагом `settings` будет отдан по `/settings/`, а сама домашняя страница продолжит работать в корне. Если Heimdall остановлен, страдает только корень — подпапки приложений продолжают работать.

## Публичный адрес

Канонический публичный адрес каждого приложения — `{база}/{слаг}/`. База выводится в одном месте: это база из шаблона адреса агентов, когда он имеет вид `{база}/{slug}` (так за проксированным сервером получаются https-ссылки без собственного сертификата); иначе — `http(s)://{хост сервера}[:{порт nginx}]`. Схема следует одному правилу: любой сертификат + включённый HTTPS-порт → https, иначе http. Прямой доступ `http://{хост}:{порт}` остаётся запасным путём и помечен «direct access» в интерфейсе.

[← Оглавление документации](/agents/multiagent/docs)