mistgate Документация
RU
300

Конфигурация

Все флаги mistgate serve и mistgate setup с переменными окружения и значениями по умолчанию, другие настраиваемые команды, флаги агента ноды и устройство каталогов данных.

На этой странице

Файла конфигурации у панели нет. mistgate setup один раз сохраняет адреса установки в базе; всё остальное — флаги mistgate serve, и у каждого флага есть переменная окружения MISTGATE_*. Здесь перечислены все они, а также флаги агента ноды и то, что лежит в каталогах данных. Сами команды описаны в CLI.

Как сочетаются флаги и переменные окружения#

  • Флаг в командной строке важнее своей переменной окружения.
  • Переменная, заданная пустой строкой, считается незаданной, и действует значение по умолчанию. Исключения — MISTGATE_SOURCE_URL (пустое значение прячет ссылку на исходный код) и MISTGATE_ACME_HTTP (пустое значение выключает слушатель на порту 80).
  • Логические переменные (MISTGATE_DEV) принимают 1, true, yes или on в любом регистре.
  • Повторяемые флаги --acme-domain и --trusted-proxy принимают и значения через запятую. Их переменные окружения — списки через запятую, и читаются они, только если флаг не указан вовсе.

mistgate serve#

Флаг Переменная По умолчанию Что значит
--listen MISTGATE_LISTEN 127.0.0.1:8080 Адрес публичного слушателя: сайт-ширма, подписки и страницы пользователей, админка в режимах с секретным путём и секретным хостом, а также (при TLS) точка подключения агентов нод. На настоящем сервере — :443.
--tls-cert MISTGATE_TLS_CERT нет PEM-сертификат (с цепочкой) для публичного слушателя. Перечитывается, когда меняется файл (проверка не чаще раза в 30 секунд); если новая пара не загрузилась, это попадает в лог, а работает старая. Нужен вместе с --tls-key.
--tls-key MISTGATE_TLS_KEY нет Закрытый ключ к --tls-cert. Эти два флага указываются вместе.
--acme-domain MISTGATE_ACME_DOMAIN нет Получить сертификат Let's Encrypt на это имя хоста. Можно повторять. Только обычные имена, без wildcard. Использует TLS-ALPN-01 на публичном слушателе, который поэтому должен быть доступен на порту 443. Пользуясь им, вы принимаете условия удостоверяющего центра. Если задан и --tls-cert, эти имена получают Let's Encrypt, а все остальные — статический сертификат.
--acme-email MISTGATE_ACME_EMAIL нет Контактный адрес для Let's Encrypt. Не обязателен.
--acme-http MISTGATE_ACME_HTTP :80 Слушатель для ACME HTTP-01 и перенаправления с HTTP на HTTPS, работает только вместе с --acme-domain. Другие имена хостов и неизвестные адреса получают 404 сайта-ширмы. Чтобы выключить, передайте --acme-http= (пустое значение) или задайте переменную пустой: MISTGATE_ACME_HTTP=.
--admin-listen MISTGATE_ADMIN_LISTEN адрес, сохранённый командой setup Отдельный слушатель админки по обычному HTTP. Только для установки, подготовленной с setup --admin-listen; при секретном пути или хосте это ошибка. Заменяет сохранённый адрес, но passkey остаются привязаны к порту, который сохранила команда setup.
--agent-listen MISTGATE_AGENT_LISTEN нет (127.0.0.1:8082 при --dev) Отдельный TLS-слушатель для точки подключения агентов. Без него агенты подключаются к публичному слушателю с секретным именем SNI, а для этого на публичном слушателе нужен TLS.
--agent-addr MISTGATE_AGENT_ADDR выводится host:port, к которому подключаются агенты; попадает в новые команды установки. Без флага: --agent-listen, если в нём указан конкретный хост (не пустой, не 0.0.0.0 и не [::]), иначе хост и порт публичного URL (443, если порта в URL нет). Уже подключённые ноды продолжают ходить на тот адрес, с которым подключались.
--trusted-proxy MISTGATE_TRUSTED_PROXY нет CIDR или IP обратного прокси, чьему заголовку X-Forwarded-For можно верить. Прокси должен сам выставлять или перезаписывать этот заголовок; прокси, который пишет только Forwarded, не поддерживается. Можно повторять. Без него клиентом считается TCP-собеседник, что бы ни было в заголовках.
--decoy-dir MISTGATE_DECOY_DIR встроенная страница Каталог с вашим статическим сайтом-ширмой (index.html, по желанию 404.html, 429.html, robots.txt).
--data-dir MISTGATE_DATA_DIR /var/lib/mistgate (./.data при --dev) Каталог данных. Он должен существовать (сначала запустите mistgate setup); при каждом запуске serve выставляет ему права 0700.
--update-service MISTGATE_UPDATE_SERVICE mistgate.service (при --dev — нет) Собственный юнит systemd панели, который механизм обновления останавливает и снова запускает вокруг замены бинарника. Важен, когда панель работает от root: тогда помощник обновления запускается временным юнитом с этим именем. Панель от другого пользователя вместо этого запускает фиксированный root-юнит mistgate-panel-update.service, в командной строке которого юнит и каталог данных указаны сами (если у вас они другие, поправьте этот юнит); см. «Обновления». При --dev панель себя не обновляет.
--source-url MISTGATE_SOURCE_URL https://github.com/Mistgate/mistgate Где опубликован исходный код этой сборки; ссылка «Исходный код» рядом с версией в админке (AGPL-3.0, раздел 13). Форк указывает свой репозиторий; пустое значение прячет ссылку.
--dev MISTGATE_DEV выключен Режим разработки: данные в ./.data (создаются вместе с мастер-ключом), обычный HTTP, сайт-ширма на --listen (127.0.0.1:8080) и админка на 127.0.0.1:8081, точка подключения агентов на 127.0.0.1:8082, WebAuthn на localhost, а пока нет админа, при запуске печатается ссылка настройки. Адреса нигде не сохраняются. Никогда не на публичном сервере.

Без --tls-cert и --acme-domain публичный слушатель работает по обычному HTTP. Это имеет смысл только за обратным прокси, который завершает TLS, вместе с --trusted-proxy и --agent-listen; см. раздел «За обратным прокси» в Установке панели.

Встроенные ограничения, которые не настраиваются флагами: каждый клиент (адрес IPv4 или сеть IPv6 /64) может делать 10 запросов в секунду с всплеском до 60 на публичной стороне, 30 в секунду с всплеском до 200 в админке и 5 в секунду с всплеском до 30 к точке подключения агентов. Запрос сверх лимита получает страницу 429 в стиле сайта-ширмы.

mistgate setup#

Команда setup запускается один раз на установку. Первый запуск сохраняет адреса из таблицы ниже; следующие запуски их не трогают, печатают адрес админки и, пока нет ни одного админа, новую одноразовую ссылку настройки.

Флаг Переменная По умолчанию Что значит
--data-dir MISTGATE_DATA_DIR /var/lib/mistgate Где создать каталог данных, мастер-ключ и базу.
--public-url MISTGATE_PUBLIC_URL нет URL публичного сайта (сайта-ширмы), http(s)://host[:port], например https://panel.example.com. От него строятся ссылки подписки и адрес для агентов. Обязателен, если не задан --admin-host или --admin-listen, а желателен всегда.
--admin-host MISTGATE_ADMIN_HOST нет Отдавать админку на этом секретном имени хоста вместо секретного пути.
--admin-listen MISTGATE_ADMIN_LISTEN нет Отдавать админку на отдельном слушателе, например 127.0.0.1:8081. Вместе с --admin-host не работает.
--rp-id MISTGATE_RP_ID выводится Идентификатор проверяющей стороны WebAuthn (RP ID).
--rp-origins MISTGATE_RP_ORIGINS выводится Через запятую — origin браузера, которым разрешены WebAuthn и меняющие данные запросы к админке.

Что команда setup выводит в каждом режиме:

Режим Адрес админки RP ID WebAuthn Разрешённый origin
Секретный путь (нет ни --admin-host, ни --admin-listen) <public-url>/<24 случайных символа>/ хост публичного URL схема, хост и порт публичного URL
--admin-host https://<хост админки>/ (схема и порт берутся из публичного URL, если он задан) хост админки origin адреса админки
--admin-listen http://localhost:<порт>/ localhost http://localhost:<порт>

В любом режиме команда setup создаёт ещё два секрета: секретное имя SNI точки подключения агентов (16 случайных символов меткой в домене публичного URL, иначе в домене хоста админки, иначе в com, если доменного имени у панели нет; DNS-запись ему не нужна) и секретный путь ссылок подписки (24 случайных символа). Всё это хранится в базе. Команды, чтобы потом поменять эти значения, нет.

Внимание

MISTGATE_ADMIN_LISTEN читают и setup, и serve. Задавайте её только для установки с отдельным слушателем админки.

Другие команды панели#

mistgate auth turnstile off и mistgate auth reset-login работают на сервере панели — и при запущенной, и при остановленной панели:

Флаг Переменная По умолчанию Что значит
--data-dir MISTGATE_DATA_DIR /var/lib/mistgate (./.data при --dev) Каталог данных панели. Каталог без базы команда не примет.
--dev MISTGATE_DEV выключен Взять каталог данных разработки ./.data.
--admin нет нет Только reset-login: какой админ получает новый вход по паролю, если у него только passkey, а админов в панели несколько.
--qr-invert нет выключен Только reset-login: нарисовать QR-код для светлого фона терминала.

mistgate mcp — stdio-прокси для MCP-клиентов:

Флаг Переменная По умолчанию Что значит
--url MISTGATE_URL нет Адрес админки, который напечатала команда setup, например https://panel.example.com/<секрет>/. Обычный http не принимается, если хост не localhost.
--token-file MISTGATE_TOKEN_FILE нет Файл, в первой строке которого лежит API-токен. Из командной строки и из окружения токен не берётся никогда.

mistgate backup keygen и mistgate backup restore — офлайн-часть зашифрованных бэкапов — принимают только флаги, все обязательные, без переменных окружения:

Флаг Что значит
keygen --identity-file Где создать закрытый age-ключ восстановления (права 0600, существующий файл не перезаписывается).
restore --identity-file Этот ключ.
restore --file Скачанный зашифрованный бэкап (.tar.gz.age).
restore --data-dir Новый, ещё не существующий каталог. MISTGATE_DATA_DIR не читается.

mistgate release keygen, mistgate release build и mistgate release sign принимают только флаги, без переменных окружения (release trust-key читает ещё MISTGATE_DATA_DIR и MISTGATE_DEV и принимает --data-dir и --dev): см. CLI и «Релизы и подпись».

Скрытая mistgate panel-update-helper принимает --fetch-latest (обязателен), --data-dir и --service. Её запускает только механизм обновления панели, от root; фиксированный юнит mistgate-panel-update.service запускает её с --data-dir /var/lib/mistgate --service mistgate.service.

Другие переменные окружения#

Переменная Кто читает Что значит
CREDENTIALS_DIRECTORY панель Её задаёт LoadCredential= в systemd. Если там лежит master.key, он используется вместо <каталог данных>/master.key. Учтите, что mistgate auth reset-login, запущенная из оболочки, этой переменной не видит.
MISTGATE_HEALTH_BLIP_WINDOW mistgate serve Длительность в формате Go, которая сокращает окно «хостер моргнул» в модуле здоровья. Нужна для сквозных тестов; не задавайте её.
MISTGATE_UNIT_GEN mistgate-node run Поколение юнита systemd; его пишет в юнит mistgate-node install. Сами не задавайте.
GOMEMLIMIT mistgate-node run Лимит памяти Go; его пишет в юнит install (около 60% RAM).
QUIC_GO_DISABLE_ECN панель и mistgate-node Если не задана, оба при старте ставят 1: quic-go тогда не помечает пакеты Hysteria2 для ECN. На пути, который выбрасывает помеченный ECN UDP, помеченное соединение ждёт секунду и больше, пока не пройдут первые обмены. 0 оставляет ECN включённым.
MISTGATE_PANEL dev-сервер Vite Только для разработки: куда pnpm dev проксирует API админки (по умолчанию http://127.0.0.1:8081). Не путать с одноимённой переменной агента ниже.

Агент ноды: mistgate-node#

Команда и флаг Переменная По умолчанию Что значит
enroll --panel MISTGATE_PANEL нет Адрес панели, host:port.
enroll --sni MISTGATE_AGENT_SNI нет Секретное имя SNI панели для агентов.
enroll --ca-sha256 MISTGATE_CA_SHA256 нет Отпечаток SHA-256 сертификата CA панели, 64 шестнадцатеричные цифры (двоеточия и регистр не важны).
enroll --token MISTGATE_ENROLL_TOKEN нет Одноразовый токен подключения. Переменная не даёт ему попасть в список процессов.
enroll --token-stdin нет выключен Прочитать токен из stdin (одна строка, не больше 256 байт). Не вместе с --token или MISTGATE_ENROLL_TOKEN.
enroll --resume-key нет выключен Хранить новый ключ в enroll-pending.pem, пока подключение не удастся, и брать его снова при повторе. Им пользуется установка по SSH.
enroll --force нет выключен Заменить уже существующие данные подключения.
enroll, install, run --state-dir MISTGATE_NODE_STATE_DIR /var/lib/mistgate-node Каталог состояния агента. Для всех трёх команд — один и тот же.
run --link-url MISTGATE_LINK_URL пусто Необязательная базовая ссылка wss://host/<секретный_путь> для подписанного WebSocket. Агент использует её, если панель объявляет поддержку; иначе он подключается по mTLS. Каждая панель отдаёт и объявляет эту ссылку; пользуются ею только агенты с этим значением. Если ссылку не удалось установить, агент возвращается на mTLS и пробует ссылку снова через 10 минут. Без этой настройки существующие ноды остаются на mTLS. Команда установки её не задаёт. Сессия по ссылке шифруется, а агент подписывает и сам запрос на шифрование, так что отключить его по дороге нельзя. Когда узел хоть раз открыл шифрованную сессию, панель больше не принимает от него нешифрованную (в журнале событий появляется link_downgrade_refused); повторная регистрация узла снимает запрет, если агент откатили на сборку, которая не умеет шифровать.
install --bin нет /usr/local/bin/mistgate-node Где лежит бинарник; если запущенный файл лежит в другом месте, он копируется туда. Каталог бинарника становится доступен агенту на запись (для самообновления).
install --no-start нет выключен Записать и включить юнит, но не запускать.
run --log-level MISTGATE_LOG_LEVEL info debug, info, warn или error.
run --log-format MISTGATE_LOG_FORMAT text text или json.
awg prepare-kernel --yes нет выключен Выполнить план; без флага план только печатается.
awg prepare-kernel --verify-only нет выключен Только проверить уже установленный модуль.
awg prepare-kernel --status-file нет нет Куда писать ход работы; им пользуется агент.
awg prepare-kernel --timeout нет 45m Жёсткий предел времени работы.

У cleanup-net и version флагов нет. Всё остальное о ноде (адрес, страна, DNS, таймауты, бэкенд AmneziaWG, WARP) задаётся в админке и приходит к агенту по его соединению.

Каталог данных панели#

По умолчанию /var/lib/mistgate. У каталога права 0700, и все файлы в нём панель создаёт доступными только владельцу.

Путь Что это Секрет
mistgate.db База SQLite: настройки и адреса, админы и сессии, ноды и их сертификаты, сохранённый SSH-доступ к нодам, профили, группы, пользователи, устройства, учётные данные, трафик, события, алерты, выкатки и расписания обновлений, настройки бэкапов, API-токены и журнал аудита. Секреты внутри (ключ CA панели, секреты приложений-аутентификаторов, токены подписок, ключи устройств, ключи WARP, SSH-пароли, секретный ключ бакета бэкапов и подобное) зашифрованы мастер-ключом; пароли хранятся как хеши argon2id, API-токены и токены подключения — как хеши SHA-256. да
mistgate.db-wal, mistgate.db-shm Журнал упреждающей записи SQLite и его индекс. Это часть базы: копируйте их вместе с ней или сначала остановите панель. да
master.key 32 случайных байта, права 0600. Шифрует все хранимые секреты (XChaCha20-Poly1305) и служит основой для паролей страниц пользователей, которые нигде не хранятся. Если файл доступен группе или остальным, панель не запустится. самый важный файл
release.pub Открытый ключ релиза установки (ed25519); им проверяются пакеты нод в dist/. Первая сборка панели с ключом записывает его; следующая сборка с тем же ключом им пользуется, сборка без ключа продолжает пользоваться сохранённым, а сборка с другим вшитым ключом не доверяет ни одному пакету, пока mistgate release trust-key не заменит файл. Релизы панели проверяются только ключом, вшитым в бинарник, и никогда этим файлом. нет
dist/ Подписанный пакет для обновления нод: manifest.json, manifest.sig и mistgate-node-linux-amd64 / -arm64. Его копируете сюда вы, или панель кладёт его сама: каждые 10 минут она смотрит последний стабильный релиз на GitHub и ставит более новый пакет, который проверяется release.pub (но не во время выкатки). Панель пересматривает каталог раз в минуту. нет
panel-update.request Релиз панели, подтверждённый владельцем (версия и SHA-256), оставленный для помощника обновления; помощник его удаляет. нет
panel-update.new Новый бинарник панели, скачанный помощником обновления и сверенный с подписанным манифестом панели; удаляется после удачного обновления. нет
.mistgate-backup-*/ Рабочий каталог идущего бэкапа: снимок базы и зашифрованный архив. Удаляется, когда бэкап заканчивается (оставшийся после сбоя — при следующем бэкапе), и в бэкап никогда не попадает. да
acme/ Ключ аккаунта и сертификаты Let's Encrypt, только с --acme-domain. Если пропадёт, восстановится сам. да

Ещё механизм обновления панели пишет рядом с каталогом данных и бинарником: <каталог данных>.panel-update-backup.tar.gz (например, /var/lib/mistgate.panel-update-backup.tar.gz, права 0600) — весь каталог данных, заархивированный при остановленной панели прямо перед заменой бинарника; неудачное обновление возвращает его на место, хранится только последний. В нём есть master.key и база, так что защищайте его так же, как каталог. Прежний бинарник остаётся как <бинарник>.prev (например, /usr/local/bin/mistgate.prev), а откаченный — как <бинарник>.failed.

База автоматически обновляется до новой схемы всякий раз, когда её открывает serve, setup, команда auth или backup restore.

Опасно

Без master.key ни один зашифрованный секрет не прочитать, включая ключ CA панели и сохранённые SSH-пароли нод; без всего каталога придётся заново подключать все ноды. Делайте резервную копию, как описано в шаге 9 Установки панели, и настройте зашифрованные бэкапы.

Каталог состояния ноды#

По умолчанию /var/lib/mistgate-node, права 0700, файлы 0600.

Путь Что это
identity.pem Закрытый ключ ноды и её сертификат от CA панели, в одном файле. Если он есть, нода считается подключённой.
enroll-pending.pem Закрытый ключ подключения, начатого с --resume-key (установка по SSH); хранится, только пока подключение не удастся.
ca.pem CA панели — единственный удостоверяющий центр, которому доверяет агент.
agent.json Адрес панели, секретное имя SNI и идентификатор ноды.
state.json Последнее применённое состояние, чтобы после перезапуска серверы поднялись и без панели. В нём есть секреты профилей (пароли обфускации, ключи серверов, ключ WARP) и то, чем нода проверяет пользователей (хеши токенов Hysteria2, публичные ключи и общие ключи AmneziaWG), но никогда — закрытый ключ клиента или его исходный токен.
certs/ Сертификаты серверов на ноде: данные Let's Encrypt и самоподписанные сертификаты.
last_version Версия, которая запускалась последней.
update.*, awg-prepare.json Отметки идущего самообновления и состояние сборки модуля ядра; появляются, только пока они нужны.

Править страницу на GitHub