Первая сеть с нуля

Эта инструкция рассчитана на администратора, который хочет развернуть самостоятельную KnotRoute network для нескольких клиентов и сервисов.

Что понадобится

Рекомендуется:

2 VPS с публичными IP/DNS для Beacon/relay;
домены beacon-a.example.net, beacon-b.example.net;
TLS reverse proxy для Beacon HTTP и Control;
1 host для Control (может совпадать с одним VPS, но это не обязательно);
Docker/Compose на managed servers.

Шаг 1. Network ID

knotroute network create

Сохраните значение kn_... в password manager/config repository. Оно не является паролем, но это canonical identifier вашей overlay.

Шаг 2. Первый Beacon/relay

Поднимите Beacon A с persistent /data, HTTPS front-end для 8080 и raw TCP 7447.

Проверьте:

curl -fsS https://beacon-a.example.net/healthz

Шаг 3. Второй Beacon/relay

Разверните его на другом host/provider. Используйте тот же Network ID, но отдельную node identity/volume.

Клиентам отдавайте оба URL:

https://beacon-a.example.net
https://beacon-b.example.net

Шаг 4. Дополнительные relays

Добавьте несколько always-on KnotRoute nodes. Чем меньше стабильных узлов, тем меньше реальная route diversity, независимо от configured circuit hop count.

Шаг 5. Control

Разверните knotroute-control за HTTPS и создайте сильные раздельные secrets:

KNOTROUTE_CONTROL_ADMIN_PASSWORD
KNOTROUTE_CONTROL_ENROLL_TOKEN

Добавьте network profile с вашим Network ID и Beacon URLs.

Шаг 6. Agents

На каждом Docker host запустите Agent. Для первого enrollment ему нужен token. После enrollment Agent использует persistent Ed25519 identity.

Docker socket монтируйте только тем Agents, которым действительно разрешён deployment workloads.

Шаг 7. Первый service

Опубликуйте test app через sidecar и получите canonical .knot address.

Сразу сделайте backup persistent sidecar data volume.

Шаг 8. Client onboarding

Сгенерируйте в Control:

Windows instructions/invite;
Android QR/deep-link;
Linux proxy instructions;
raw profile для advanced users.

Шаг 9. End-to-end monitoring

Поставьте отдельный client в другом failure domain и периодически открывайте test .knot service. Это полезнее, чем только /healthz самого Beacon.

Шаг 10. Зафиксируйте эксплуатационную политику

Минимально документируйте:

кто имеет доступ к Control;
где хранятся service identity backups;
как добавляются relays;
как отзывается скомпрометированный host;
какой release channel используется;
кто получает alerts synthetic monitor.

Вариант для первого сервера: всё основное на одном host

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

SVG ↗

Здесь 8080 Beacon — HTTP discovery API, а 7447 — сырой KnotRoute relay transport. Это разные протоколы. В клиентский список Beacon всегда записывается HTTP(S) URL, например https://beacon.example.net, не http://beacon.example.net:7447.

Один сервер подходит для bootstrap и проверки, но остаётся единой точкой отказа. После успешного end-to-end теста вынесите второй Beacon/relay на другой host.

Если Beacon уже поднят вручную

Control не обязан разворачивать Beacon сам. Откройте Сети → Добавить сеть и укажите:

Название: Production
Network ID: kn_...
Beacon: https://beacon.example.net

После сохранения нажмите Проверить Beacon. Control делает запрос к /healthz; успешная проверка означает только доступность HTTP API. Отдельно проверьте доступность relay-порта 7447/tcp извне.

Не создавайте второй Beacon только потому, что Control показывает кнопку «Развернуть новый Beacon». Эта операция нужна, когда вы действительно хотите, чтобы Agent создал новый managed-container.

Что проверить до подключения первого клиента

Проверка по слоям помогает быстро понять, где именно проблема:

# 1. HTTP discovery API
curl -fsS https://beacon.example.net/healthz

# 2. DNS
getent hosts beacon.example.net

# 3. Relay TCP с другой машины
nc -vz beacon.example.net 7447

На сервере также проверьте container logs и persistent volume Beacon. Если HTTP работает, а 7447 закрыт firewall’ом, клиент сможет обратиться к discovery API, но не сможет использовать этот endpoint как relay.

Настройка первого Windows-клиента

На клиенте должны совпадать только параметры сети и bootstrap:

Network ID: тот же kn_...
Beacon URL: https://beacon.example.net

После сохранения конфигурации дождитесь появления хотя бы одного peer. Затем включите .knot integration, если нужен браузерный доступ. Не начинайте диагностику CA/HTTPS, пока в Dashboard нет peer connectivity: это более поздний слой.

Первый end-to-end сервис

Для проверки сети удобно опубликовать маленький HTTP service через sidecar. У sidecar должны быть:

тот же network_id;
хотя бы один рабочий Beacon URL или иной реально настроенный discovery path;
Docker network, в которой разрешается имя target-контейнера;
persistent /data для service identity.

После появления canonical <service>.knot проверьте его с другого KnotRoute node. Собственный node теперь поддерживает local fast-path и тоже может открыть свой опубликованный service, но удалённая проверка дополнительно подтверждает descriptor/introduction/rendezvous path.

Когда считать bootstrap завершённым

Сеть ещё не становится production-ready от одного зелёного /healthz. Минимальный практический критерий:

два клиента обнаруживают relay через Beacon;
между nodes есть routes;
опубликованный service разрешается по canonical .knot;
HTTP request проходит через overlay;
после перезапуска Beacon/sidecar identities сохраняются;
после перезапуска клиента он снова подключается без ручного редактирования конфигурации;
backup service identity проверен хотя бы чтением/восстановлением в тестовой среде.

Для системной диагностики используйте пошаговый runbook.

Исходник