Конфигурация
Все флаги 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 |
Отметки идущего самообновления и состояние сборки модуля ядра; появляются, только пока они нужны. |