Установка панели
Как скачать или собрать Mistgate, подготовить панель командой mistgate setup, запустить её под systemd и войти в первый раз.
На этой странице
Эта страница ведёт от чистого Linux-сервера до работающей панели с аккаунтом владельца. В примерах — panel.example.com; сначала загляните в Требования. Команды на сервере панели выполняются от root. Те же шаги может сделать за вас AI-агент с SSH-доступом к серверу: готовый промпт — в инструкции для AI-агента.
Эта страница — про панель на вашем собственном сервере. Чтобы запустить панель на Cloudflare Workers без сервера (предварительная версия), см. Установку Cloudflare-версии.
Установка одной командой#
Для чистого Linux-сервера amd64 или arm64 с systemd выполните команду от root. Домен должен указывать прямо на сервер, TCP-порты 80 и 443 должны быть свободны. Для проверки подписи нужен openssh-client с поддержкой ssh-keygen -Y verify либо OpenSSL версии 3.2 или новее. Установщик скачивает последний релиз, сверяет бинарник с SHA256SUMS и подписанным манифестом панели, запускает настройку и устанавливает службу systemd. Правила firewall он не меняет: если активен UFW или firewalld, он напечатает команды, которые нужно выполнить.
curl -fsSL https://mistgate.app/install.sh | sudo bash -s -- --public-url https://panel.example.comПо умолчанию установщик запрашивает сертификат Let's Encrypt для домена из URL. Перед изменениями он спрашивает подтверждение; для запуска без вопросов добавьте --yes. С --dry-run установщик скачает и проверит релиз, но не изменит сервер. Флаг --version vX.Y.Z задаёт конкретный релиз, а --channel testing или --channel dev ставит новейший релиз более раннего канала обновлений, которому панель потом и следует. --restore FILE вместе с --identity-file KEY или --passphrase-file FILE восстанавливает бэкап вместо настройки новой панели: см. Бэкапы. Параметры --admin-host, --admin-listen, --acme-domain и --data-dir задают режимы настройки и службы, описанные ниже.
После установки откройте одноразовую ссылку в браузере и создайте аккаунт владельца. Ссылка истекает через 30 минут. Затем добавьте ноду в Nodes → Add node.
Установка вручную#
1. Получите бинарник#
Панель — один статический бинарник для Linux amd64 или arm64, веб-админка уже встроена в него. Берите официальный релиз, если у вас нет причин собирать свой.
Из GitHub Releases (рекомендуется)#
В каждом релизе на GitHub Releases лежат панель (mistgate-linux-amd64, mistgate-linux-arm64), агент ноды (mistgate-node-linux-amd64, mistgate-node-linux-arm64), SHA256SUMS, BUILDINFO и два подписанных манифеста: manifest.json с manifest.sig для агентов нод и panel-manifest.json с panel-manifest.sig и panel-manifest.sshsig для панели. В официальные бинарники вшит ключ релиза проекта, поэтому панель из них сама скачивает подписанных агентов нод и умеет обновляться до следующих релизов (см. Обновления).
На сервере панели, от root (uname -m печатает x86_64 для amd64 и aarch64 для arm64):
ARCH=amd64 # arm64 на сервере с ARM
cd /root
for f in "mistgate-linux-$ARCH" SHA256SUMS panel-manifest.json; do
curl -fsSLO "https://github.com/Mistgate/mistgate/releases/latest/download/$f"
done
sha256sum --check --ignore-missing SHA256SUMS
grep -q "$(sha256sum "mistgate-linux-$ARCH" | cut -d' ' -f1)" panel-manifest.json && echo "listed in panel-manifest.json"
install -m 0755 "mistgate-linux-$ARCH" /usr/local/bin/mistgate
mistgate versionЧто эти проверки доказывают, а что нет:
sha256sum --checkдоказывает, что файл скачался целым и совпадает с контрольными суммами, опубликованными в релизе.SHA256SUMSпишет workflow релиза, и он не подписан, поэтому не доказывает, кто собрал бинарник.- Та же сумма SHA-256 указана в panel-manifest.json, который мейнтейнер подписывает офлайн-ключом релиза после пересборки бинарников из тега. Установщик одной командой предпочитает panel-manifest.sshsig и ssh-keygen -Y verify, а если эта команда недоступна — проверяет panel-manifest.sig через OpenSSL 3.2 или новее. В ручной инструкции grep остаётся только проверкой совпадения.
- Дальше подписи проверяет сама панель: она устанавливает релиз панели и отдаёт агентам пакет нод, только если подпись сходится с ключом релиза, вшитым в неё.
mistgate versionпечатает версию и отпечаток этого ключа.
Из исходников#
На машине для сборки с инструментами из Требований:
git clone https://github.com/Mistgate/mistgate.git
cd mistgate
make build
scp bin/mistgate-linux-amd64 root@panel.example.com:/root/
ssh root@panel.example.com 'install -m 0755 /root/mistgate-linux-amd64 /usr/local/bin/mistgate'В bin/ лежат и агенты нод (mistgate-node-linux-amd64, mistgate-node-linux-arm64); сохраните их для ручной установки ноды.
У сборки без RELEASE_KEY нет ключа релиза: её агенты нод никогда не обновляются сами, панель не может устанавливать релизы панели, а установке по SSH нечего ставить — у неё нет доверенного пакета агента. Сборка со своим ключом доверяет только релизам, которые подписали вы. Сделайте ключ до первой сборки: см. Релизы и подпись.
2. Решите, как открывать админку#
Всем посетителям публичный адрес показывает сайт-ширму. До админки можно добраться одним из трёх способов; выбирается он один раз, при запуске mistgate setup:
| Режим | Флаги setup |
Адрес админки | Когда подходит |
|---|---|---|---|
| Секретный путь (по умолчанию) | --public-url https://panel.example.com |
https://panel.example.com/<секрет>/, где секрет — 24 случайных символа |
Самый простой: одно имя хоста, один сертификат. |
| Секретный хост | --public-url https://panel.example.com --admin-host <секретный хост> |
https://<секретный хост>/ |
Нужно, чтобы админка жила на имени, которое никто не угадает. Нужны DNS-запись и сертификат на это имя. |
| Отдельный порт | --public-url https://panel.example.com --admin-listen 127.0.0.1:8081 |
http://localhost:8081/ через SSH-туннель |
Админки вообще нет на публичном порту. |
-
Всё, что не совпало с админкой (неверный путь, неизвестный хост, неизвестный адрес), получает сайт-ширму, так что сканер не отличит почти верную догадку от случайной.
-
Всегда указывайте
--public-url. От него строятся все ссылки подписки и адрес в командах установки нод. Без него панель не выдаёт ссылки подписки, а добавить ноду не получится, покаserveне получит--agent-addr. -
--admin-hostи--admin-listenвместе не работают. -
Отдельный порт админки работает по обычному HTTP. Вешайте его на loopback и открывайте через SSH:
ssh -N -L 8081:127.0.0.1:8081 root@panel.example.comЗатем откройте в браузере
http://localhost:8081/. Порт на своей стороне берите тот же: passkey привязаны к адресуhttp://localhost:<порт>, который сохранила команда setup. -
--rp-idи--rp-originsпереопределяют настройки WebAuthn, которые команда setup выводит из адреса админки. Обычно они не нужны.
Команда setup сохраняет эти адреса один раз. Повторный запуск их не меняет, и команды, чтобы поменять их потом, в Mistgate нет. Выберите до того, как идти дальше: начать заново — это новый каталог данных и повторное подключение всех нод.
3. Запустите setup#
mistgate setup --public-url https://panel.example.comОна напечатает:
Data dir: /var/lib/mistgate
Admin URL: https://panel.example.com/<секрет>/
Setup link: https://panel.example.com/<секрет>/setup#<токен>
The link works once and expires in 30 minutes. Open it in a browser and create your admin (a passkey, or a password with an authenticator code).Что делает команда setup:
- Создаёт каталог данных
/var/lib/mistgateс правами 0700 (путь меняет--data-dir). - Создаёт
master.key— 32 случайных байта с правами 0600. Им шифруются все секреты, которые хранит панель. - Создаёт базу
mistgate.dbи применяет схему. - Сохраняет адреса выбранного режима и создаёт ещё два секрета: имя SNI, по которому агенты нод находят панель, и секретный путь для ссылок подписки.
- Печатает одноразовую ссылку настройки, она действует 30 минут.
Адрес админки никому не показывайте. Запускать setup повторно безопасно: настройки останутся прежними, а пока нет ни одного админа, команда выдаст новую ссылку настройки.
4. Выберите сертификат#
| Вариант | Флаги serve |
Что происходит |
|---|---|---|
| Let's Encrypt | --acme-domain panel.example.com |
Панель сама получает и продлевает сертификат (TLS-ALPN-01 на публичном порту, поэтому он должен быть доступен на 443). Второй слушатель на :80 отвечает на HTTP-01 и перенаправляет HTTP на HTTPS (--acme-http; пустое значение его выключает). Сертификаты хранятся в <каталог данных>/acme. --acme-email добавляет контактный адрес. Пользуясь им, вы принимаете условия Let's Encrypt. |
| Свой сертификат | --tls-cert /path/fullchain.pem --tls-key /path/privkey.pem |
Панель отдаёт ваши PEM-файлы и перечитывает их, когда меняется файл сертификата (проверка не чаще раза в 30 секунд), так что продление другой программой не требует перезапуска. |
| Оба | оба набора флагов | Имена из --acme-domain получают сертификаты Let's Encrypt, все остальные — ваш сертификат. Удобно, когда секретный хост админки покрыт вашим wildcard-сертификатом. |
--acme-domain принимает только обычные имена хостов, без wildcard. Флаг можно повторять для нескольких имён.
Сертификат Let's Encrypt на секретный хост админки попадёт в открытые журналы Certificate Transparency. Чтобы имя осталось секретным, покройте его своим wildcard-сертификатом.
5. Сайт-ширма#
Если ничего не настраивать, панель показывает встроенную страницу «Coming soon». Она одинакова во всех установках, а значит узнаваема; свой сайт лучше. Положите статические файлы в каталог и укажите --decoy-dir:
/и каждый каталог отдают свойindex.html.404.htmlи429.html, если они есть, заменяют встроенные страницы «не найдено» и «слишком много запросов». Любой неизвестный адрес, неверный путь админки и неизвестная ссылка подписки получают один и тот же ответ 404.- Если
robots.txtнет, отдаётся встроенный, который закрывает сайт от известных ИИ-краулеров. - Отвечают только GET и HEAD. Файлы и каталоги, чьё имя начинается с точки, не отдаются никогда, а в ответах нет заголовков Last-Modified и ETag.
Панель этот каталог только читает. С юнитом systemd ниже держите его вне /home и /root (например, в /srv/mistgate-decoy). Каким должен быть такой сайт и как поручить AI-агенту придумать уникальный — в разделе «Свой сайт-ширма».
6. Проверьте запуск вручную#
mistgate serve --listen :443 --acme-domain panel.example.comПо умолчанию --listen равен 127.0.0.1:8080, поэтому на настоящем сервере указывайте --listen :443. Лог идёт в stderr; ищите строки listening для публичного слушателя (и acme-http для порта 80). Когда всё работает, остановите его через Ctrl+C.
7. Запустите под systemd#
Сохраните это как /etc/systemd/system/mistgate.service и поправьте ExecStart под выбранные флаги:
[Unit]
Description=Mistgate panel
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
ExecStart=/usr/local/bin/mistgate serve --listen :443 --acme-domain panel.example.com
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
# Панель пишет только в свой каталог данных, и ей нужно только занять порты 443 и 80.
NoNewPrivileges=yes
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
ProtectSystem=strict
ReadWritePaths=/var/lib/mistgate
ProtectHome=yes
PrivateTmp=yes
PrivateDevices=yes
ProtectClock=yes
ProtectControlGroups=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectKernelLogs=yes
ProtectHostname=yes
LockPersonality=yes
RestrictRealtime=yes
RestrictSUIDSGID=yes
RestrictNamespaces=yes
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK
SystemCallArchitectures=native
SystemCallFilter=@system-service
UMask=0077
[Install]
WantedBy=multi-user.targetsystemctl daemon-reload
systemctl enable --now mistgate
journalctl -u mistgate -fПочему он такой:
- Команда
mistgate setupзапускалась от root, поэтому каталог данных принадлежит root, и служба тоже работает от root. При этом у неё отобраны все права, кроме занятия низких портов, а писать она может только в/var/lib/mistgate. Если у вас другой--data-dir, поправьтеReadWritePaths. - По SIGTERM панель останавливается аккуратно. С
Restart=on-failuresystemd перезапустит её, если упадёт слушатель, но не тогда, когда вы её остановили. - У каждого флага есть переменная окружения
MISTGATE_*, так что флаги можно перенести в строкиEnvironment=или вEnvironmentFile=. См. Конфигурация. - Файлам из
--decoy-dir,--tls-certи--tls-keyдостаточно быть доступными на чтение.
За обратным прокси#
Если порт 443 на этом хосте должен принадлежать другому веб-серверу, Mistgate может работать за ним:
- Публичный слушатель запускайте без TLS на loopback (
--listen 127.0.0.1:8080, без--acme-domainи--tls-cert), а TLS дляpanel.example.comпусть завершает прокси, передавая заголовок Host и путь без изменений. - Добавьте
--trusted-proxy 127.0.0.1, чтобы ограничения запросов, сессии и аудит видели настоящий адрес клиента изX-Forwarded-For. Прокси должен сам выставлять или перезаписывать этот заголовок, чтобы клиент не мог подставить свой; прокси, который пишет толькоForwarded, не поддерживается. - Агентам нод нужен TLS от самой панели. Дайте им отдельный порт и впишите его адрес в команды установки:
--agent-listen :8443 --agent-addr panel.example.com:8443. Прокси этот порт трогать не должен.
Порт агентов тогда отдельный и отвечает только на секретное имя SNI, а на общем порту 443 он прятался бы за сайтом-ширмой. Если можно, выбирайте обычную схему выше.
8. Первый вход#
Откройте в браузере ссылку настройки из шага 3 — целиком, вместе с частью после #.
- Язык. Выберите русский, английский, упрощённый китайский, персидский или турецкий, потом его можно сменить.
- Создай админа. Поле ЛОГИН (в нём сразу стоит
admin) — это ваш логин и имя, под которым панель вас показывает. Дальше:- Создать passkey: браузер попросит отпечаток пальца, лицо, PIN-код или ключ безопасности. Ключ остаётся на вашем устройстве. Это рекомендуемый способ.
- пароль + код из приложения: пароль не короче 12 символов, затем отсканируйте QR-код приложением-аутентификатором (Google Authenticator, 1Password, Aegis и подобными), введите 6-значный код и нажмите Создать админа.
- Готово. Выберите Добавить первую ноду или Позже, сначала осмотрюсь.
Первый админ — владелец. Ещё мастер настройки создаёт пустую группу «Все» для первых пользователей.
- Логин — от 3 до 64 символов: a–z, 0–9 и
. _ @ -. - Ссылка тратится только в момент, когда админ создан. Если она истекла или что-то пошло не так, запустите
mistgate setupещё раз и получите новую. - Passkey работает только на том адресе админки, который сохранила команда setup. Сообщение «Браузер отклонил passkey для этого адреса» значит, что страница открыта по другому адресу.
Потом вы входите по адресу админки кнопкой Войти по passkey или другим способом: логин, пароль и код. Пять неверных паролей в течение часа блокируют этот логин на 15 минут. Если потерялся телефон или passkey, команду mistgate auth reset-login описывает страница Безопасность.
9. Сразу сделайте резервную копию#
Всё, что знает панель, лежит в каталоге данных:
| Файл | Что это |
|---|---|
mistgate.db, mistgate.db-wal, mistgate.db-shm |
База: админы, ноды, профили, пользователи, устройства, трафик, события, журнал аудита. Секреты в ней зашифрованы мастер-ключом. |
master.key |
Ключ, которым зашифрованы хранимые секреты, в том числе ключ CA панели, которому доверяют все ноды. |
acme/ |
Аккаунт и сертификаты Let's Encrypt (только с --acme-domain). |
Сделайте копию сейчас, остановив панель, чтобы база была согласованной:
systemctl stop mistgate
tar czf mistgate-backup-$(date +%F).tgz -C /var/lib mistgate
systemctl start mistgateВ копии лежит мастер-ключ: у кого она, тот прочтёт все секреты панели. Храните её зашифрованной и не на этом сервере. Без каталога данных придётся заново подключать все ноды, а все пользователи, ссылки и ключи пропадут.
Для регулярных копий включите зашифрованные бэкапы в Настройки → Бэкапы: панель по расписанию шифрует согласованный снимок вашим офлайн-ключом восстановления и загружает его в ваш бакет Cloudflare R2. Если вы собирали панель со своим ключом релиза, его файл тоже храните офлайн и с копией.
Что дальше#
Добавление ноды: автоматически по SSH или командой, которую вы выполните сами.