Skip to content

add-node.md

Latest commit

 

History

History
177 lines (125 loc) · 23.2 KB

add-node.md

File metadata and controls

177 lines (125 loc) · 23.2 KB
Raw
title Добавление ноды
description Как выбрать между установкой по SSH и ручной установкой, подключить сервер одноразовой командой, дождаться, пока он выйдет на связь, и потом аккуратно его убрать.

Нода входит во флот, когда её агент получает сертификат панели, ставит себя службой systemd и подключается. В окне Ноды → Добавить ноду есть два способа:

Способ Что вы делаете Когда подходит
Запустить автоустановку по SSH Вводите адрес сервера, подтверждаете его SSH host key, входите с ключом панели или паролем; остальное делает панель. Обычный путь. Описан на странице Установка ноды по SSH.
Получить команду для ручной установки Копируете агента на сервер и выполняете одноразовую команду от root. Панель не может подключиться к серверу по SSH (в Cloudflare-версии: адрес принадлежит Cloudflare или проксируется им, сеть частная или SSH открыт только для вашего IP) или вы хотите сами выполнять команды. Описан на этой странице.

Установку по SSH может запустить и AI-агент через MCP; вы одобряете её и выбираете ключ панели или вводите пароль на экране одобрения: см. инструкцию для AI-агента. Ещё на этой странице описано, как убрать ноду. Если окно сразу показывает поля имени, страны и адреса, панель старше установки по SSH: сначала обновите её (см. «Обновления панели»).

Перед ручной установкой

  • Сервер, который подходит под требования, с доступом root по SSH.
  • Бинарник агента из того же релиза, что и панель: mistgate-node-linux-amd64 или mistgate-node-linux-arm64. Панель с доверенным пакетом релиза печатает для него готовую команду scp; иначе возьмите его из того же релиза на GitHub, что и панель, или из bin/ своей сборки.
  • Панель должна быть доступна с сервера по публичному адресу на TCP 443 (или по адресу, который вы дали serve --agent-addr). Сама панель к ноде не подключается.

1. Выберите ручную установку

В окне Ноды → Добавить ноду выберите «Получить команду для ручной установки». То же окно открывается плиткой Добавить ноду на «Обзоре», из командной палитры и в конце мастера первой настройки. Если вы уже создали ноду вручную со статусом ожидания, выведите её из флота перед SSH-установкой под тем же именем или укажите другое свободное имя.

Поле Что вписать
Имя a–z, 0–9 и дефис, от 2 до 24 символов, например de1. Имена уникальны среди активных нод и SSH-установок; вывод ноды освобождает имя, но сохраняет историю.
Страна Не обязательно. Нужна для DNS: на нодах в России доктор проверяет госуслуги и предлагает Яндекс DNS, а на нодах в Китае проверяет www.baidu.com и предлагает AliDNS и DNSPod.
Адрес Домен или IP, без https:// и без порта. К нему подключаются клиенты, и он попадает во все подписки. Сертификату Let's Encrypt для Hysteria2 нужен домен, у которого A-запись указывает на сервер.

Если адрес — IP, окно скажет об этом заранее: тогда Hysteria2 на этой ноде нужен домен с A-записью или самоподписанный сертификат (с пином), который выбирается при добавлении профиля. AmneziaWG работает и по IP.

Нажмите Получить команду установки. Нода появится в списке со статусом «Ждёт установки», а окно покажет три шага.

2. Положите агента на сервер

Если в каталоге данных панели лежит доверенный пакет релиза (панель из официального релиза скачивает его сама), первый шаг в окне покажет готовую команду scp, которую нужно выполнить на сервере панели. Она копирует агента для amd64; для сервера на ARM замените amd64 на arm64.

Иначе скопируйте агента из того же релиза сами, в /root/mistgate-node, например с машины, где собирали:

scp bin/mistgate-node-linux-amd64 root@de1.example.com:/root/mistgate-node

3. Выполните команду от root

Зайдите на сервер по SSH от root и вставьте команду из второго шага окна (Скопировать команду). Она выглядит так:

chmod +x /root/mistgate-node && /root/mistgate-node enroll --panel panel.example.com:443 --sni <секретное имя> \
  --ca-sha256 <отпечаток> --token <одноразовый токен> && /root/mistgate-node install
Часть Что значит
--panel Хост и порт, к которым подключается агент.
--sni Секретное имя SNI, ведущее к точке подключения агентов. Без него панель показывает сайт-ширму.
--ca-sha256 Отпечаток CA панели. Нода доверяет панели только по нему. Окно показывает его и в разделе Подробнее.
--token Одноразовый токен подключения. Работает один раз и истекает через час; до какого времени — написано в окне.

Если всё прошло, команда напечатает:

enrolled as nod_... with panel.example.com:443; state in /var/lib/mistgate-node
next: mistgate-node install   (or, in the foreground: mistgate-node run)
installed /etc/systemd/system/mistgate-node.service (state /var/lib/mistgate-node)
started; follow it with: journalctl -u mistgate-node -f

Важно: пока работает enroll, токен виден в списке процессов на сервере. Он одноразовый и живёт недолго; если сервером пользуются другие люди, задайте переменную MISTGATE_ENROLL_TOKEN или передайте токен через стандартный ввод с --token-stdin вместо --token.

Что происходит на сервере

enroll:

  1. Создаёт на ноде ключ P-256 и запрос сертификата. Ключ никогда не покидает сервер.
  2. Подключается к --panel по TLS 1.3 с секретным именем и принимает сервер, только если его цепочка заканчивается на CA с закреплённым отпечатком.
  3. Отправляет токен и запрос. Панель проверяет токен (у себя она хранит только его хеш), выпускает клиентский сертификат на 30 дней и возвращает его вместе со своим CA.
  4. Записывает ключ и сертификат (identity.pem), CA панели (ca.pem) и адрес панели (agent.json) в /var/lib/mistgate-node (каталог 0700, файлы 0600).

install:

  1. Проверяет, что запущен от root и что в каталоге состояния есть данные подключения.
  2. Копирует себя в /usr/local/bin/mistgate-node. Файл в /root больше не нужен.
  3. Пишет защищённый юнит /etc/systemd/system/mistgate-node.service с лимитами под память сервера и выполняет systemctl daemon-reload, enable и restart.

Запущенный агент:

  1. Применяет свою базовую настройку хоста: значения sysctl для fq и BBR, UDP-буферы сокетов net.core.rmem_max и net.core.wmem_max не ниже 16 МиБ, ограничение размера журнала и защиту SSH в собственной таблице nftables. Новые UDP-сокеты ретрансляции получают не менее 1 МиБ из net.core.rmem_default и net.core.wmem_default; суммарную память UDP по-прежнему ограничивает net.ipv4.udp_mem. Таблица conntrack получает не менее 65 536 записей и 16 384 корзин хеширования; заданные вами более высокие значения сохраняются.
  2. Восстанавливает последнее применённое состояние из каталога состояния (при первом запуске его нет).
  3. Открывает одно долгоживущее соединение с панелью со взаимным TLS, сообщает сведения о хосте и получает настройки и желаемое состояние: какие серверы запускать и с учётными данными каких пользователей.
  4. Каждые 10 секунд отправляет трафик, сессии и метрики хоста, запускает доктора через 30 секунд после подключения и потом каждые 10 минут, а когда до конца сертификата остаётся меньше 10 дней, продлевает его с новым ключом.

Полный список того, что агент меняет на хосте, — в разделе «Что агент меняет на ноде» на странице Требования.

4. Нода выходит на связь

Окно обновляется само. Через несколько секунд после install третий шаг сменится на Подключена, а в событиях ноды появится «впервые вышла на связь» с версией агента. Нажмите Добавить профиль на de1 и переходите к Первым пользователям: пока на ноде нет ни одного профиля, она пишет «нет профилей — пользователи её не получат».

Статус Что значит
Ждёт установки Нода создана, но ни один агент ещё не подключился. На странице ноды видно, до какого времени действует команда.
Работает Агент на связи, серверы на ноде работают.
Хостер моргнул Связь пропала меньше 10 минут назад; часто виноват хостер.
Недоступна Связи нет 10 минут. Страница ноды покажет команду, которая перезапускает агента и выводит его лог.
Выведена Нода выведена из флота.

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

systemctl restart mistgate-node && journalctl -u mistgate-node -n 50 --no-pager

В строках panel connection lost написана причина. Проверьте заодно, что часы на сервере идут правильно.

Новая команда установки

У ноды, которая ждёт установки, есть кнопка Новая команда установки — на странице ноды, на «Обзоре» и в чек-листе первого запуска. Она нужна, если команда истекла или потерялась. Новая команда отменяет все прежние неиспользованные.

У ноды, которая уже подключалась раньше (потерян сертификат, сервер переустановлен, каталог состояния потерян), та же кнопка есть на вкладке Сервер — у любой ноды, кроме выведенных из флота. Её видит только владелец. Нода сохраняет имя, профили и пользователей; старый сертификат перестаёт работать, как только подключится новый агент. Если на сервере остался старый каталог состояния, enroll откажется с already enrolled; use --force to replace the identity: добавьте --force после enroll.

Удаление ноды

Откройте ноду, Сервер → Опасная зона → Вывести из флота, и для подтверждения введите имя ноды. После этого панель:

  • убирает ноду из доступа всех пользователей: в их подписках её больше нет, сами ссылки не меняются;
  • отзывает сертификат ноды и отменяет её неиспользованные команды установки;
  • сохраняет запись о ноде и её историю в панели и в аудите; имя можно использовать при следующей установке;
  • оставляет сохранённый SSH-доступ, если ноду ставили по SSH: пароль по-прежнему можно показать в Сервер → SSH-доступ выведенной ноды, а удаляется он только кнопкой Забыть сохранённый доступ. Если пароль сгенерировала панель (смена через MCP), окно вывода предупредит: покажите его и сохраните копию.

Если агент на связи, он получает приказ выйти из флота и на сервере:

  1. останавливает свои серверы;
  2. убирает WARP, если он был;
  3. убирает свои изменения на хосте: свои таблицы nftables, свои помеченные правила UFW (правила UDP-портов и правила 80/443 после SSH-установки; правило SSH остаётся), интерфейсы AmneziaWG, файлы sysctl и journald (journald перезапускается, так что его предел размера снимается сразу), а также исправление резолвера из доктора, если его применяли;
  4. удаляет свой каталог состояния (ключ — первым) и завершается.

На сервере остаются бинарник, юнит (по-прежнему включённый), значения, уже выставленные в работающем ядре (fq, BBR, UDP-буферы, пересылка IP), — до следующей перезагрузки, и модуль ядра AmneziaWG с пакетами, если вы его ставили. Остальное уберите сами:

systemctl disable --now mistgate-node
rm -f /etc/systemd/system/mistgate-node.service
systemctl daemon-reload
rm -f /usr/local/bin/mistgate-node /usr/local/bin/mistgate-node.prev /usr/local/bin/mistgate-node.new /root/mistgate-node
rm -rf /var/lib/mistgate-node

Внимание: нода, которая была не на связи, когда вы её выводили, приказа не получила. Панель отвергает её сертификат, но агент продолжает работать с последним применённым состоянием (его серверы так и обслуживают прежних пользователей) и пытается подключиться снова. Панель сразу говорит об этом («{name} не получила приказ») и показывает все нужные команды, чтобы их скопировать. Такой сервер чистите вручную: сначала шаги ниже, потом команды выше.

systemctl disable --now mistgate-node      # при остановке выполняется cleanup-net: интерфейсы туннелей, маршруты WARP, их таблицы
nft delete table inet mistgate_node        # защита SSH и правила прыжков по портам
rm -f /etc/sysctl.d/90-mistgate.conf /etc/systemd/journald.conf.d/90-mistgate.conf
systemctl restart systemd-journald

Если на этой ноде применяли исправление резолвера из доктора, удалите /etc/systemd/resolved.conf.d/90-mistgate.conf и перезапустите systemd-resolved или верните /etc/resolv.conf из /etc/resolv.conf.mistgate.bak (если есть /etc/resolv.conf.mistgate.bak.link, исходный файл был символической ссылкой на путь, записанный в нём).

mistgate-node cleanup-net можно запускать когда угодно. Команда убирает интерфейсы AmneziaWG и WARP, маршруты и правила WARP и их таблицы nftables; при запуске агент создаёт их заново. IPv6-адреса, которые агент добавил на сервер (собственные адреса ноды из ipv6-owned.json в каталоге состояния), она не трогает, чтобы перезапуск или обновление их не снимали; mistgate-node cleanup-net --ipv6-addresses снимает и их, но никогда не адрес, который был на хосте. Вывод ноды из парка тоже снимает их.

Если подключение не удалось

Что видно Причина Что делать
enroll: --panel, --sni, --ca-sha256 and --token are required Команда обрезалась при вставке. Скопируйте её заново кнопкой Скопировать команду.
--ca-sha256 must be 64 hex digits То же. То же.
enrollment token unknown, expired or used Команде больше часа, её уже использовали или для этой ноды сделали новую. Новая команда установки на странице ноды.
too many failed attempts, try later Десять неудачных попыток за минуту с этого адреса. Подождите минуту и возьмите свежую команду.
node retired Нода выведена из флота. Добавьте новую ноду.
no certificate in the chain matches the pinned CA fingerprint, panel did not present its CA certificate или the CA returned by the panel does not match --ca-sha256 По адресу --panel TLS отвечает не панель: перед ней стоит CDN или обратный прокси, адрес неверен или каталог данных панели создан заново уже после того, как была сделана команда. Направьте DNS панели прямо на её сервер, проверьте --public-url и --agent-addr, сделайте новую команду.
Таймаут или connection refused Панель не запущена, файрвол закрывает TCP 443 к панели или в команде неверный адрес. Проверьте панель и её файрвол; с ноды проверьте curl -I https://panel.example.com/.
already enrolled; use --force to replace the identity В каталоге состояния уже есть данные подключения. Добавьте --force после enroll или сначала удалите /var/lib/mistgate-node.
install: must run as root Запуск не от root. Выполните команду от root.
holds no identity: run mistgate-node enroll first enroll не прошёл, или install получил другой --state-dir. Повторите enroll с тем же каталогом состояния.
Админка отвечает на Получить команду установки сообщением «panel address is not configured» Панель не знает адреса для агентов: setup запускали без --public-url, а у serve нет --agent-addr. Перезапустите панель с --agent-addr panel.example.com:443.

Другие симптомы и их решения — в Решении проблем. Повседневные настройки нод — на странице Ноды.