Установка панели

Эта страница ведёт от чистого Linux-сервера до работающей панели с аккаунтом владельца. В примерах — panel.example.com; сначала загляните в Требования. Команды на сервере панели выполняются от root.

1. Соберите бинарники#

На машине для сборки, где есть Go, Node.js, pnpm, make и git:

git clone https://github.com/Mistgate/mistgate.git
cd mistgate
make build

В bin/ появятся панель (mistgate-linux-amd64, mistgate-linux-arm64) и агент ноды (mistgate-node-linux-amd64, mistgate-node-linux-arm64). Веб-админка уже встроена в бинарник панели. Бинарники агента сохраните: они понадобятся, когда будете добавлять ноду.

Скопируйте бинарник панели на сервер и установите его:

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'

2. Решите, как открывать админку#

Всем посетителям публичный адрес показывает сайт-ширму. До админки можно добраться одним из трёх способов; выбирается он один раз, при запуске mistgate setup:

• Всё, что не совпало с админкой (неверный путь, неизвестный хост, неизвестный адрес), получает сайт-ширму, так что сканер не отличит почти верную догадку от случайной.

• Всегда указывайте --public-url. От него строятся все ссылки подписки и адрес в командах установки нод. Без него панель не выдаёт ссылки подписки, а добавить ноду не получится, пока serve не получит --agent-addr.

• --admin-host и --admin-listen вместе не работают.

• Отдельный порт админки работает по обычному HTTP. Вешайте его на loopback и открывайте через SSH:

  sh

  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 выводит из адреса админки. Обычно они не нужны.

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:

1. Создаёт каталог данных /var/lib/mistgate с правами 0700 (путь меняет --data-dir).
2. Создаёт master.key — 32 случайных байта с правами 0600. Им шифруются все секреты, которые хранит панель.
3. Создаёт базу mistgate.db и применяет схему.
4. Сохраняет адреса выбранного режима и создаёт ещё два секрета: имя SNI, по которому агенты нод находят панель, и секретный путь для ссылок подписки.
5. Печатает одноразовую ссылку настройки, она действует 30 минут.

Адрес админки никому не показывайте. Запускать setup повторно безопасно: настройки останутся прежними, а пока нет ни одного админа, команда выдаст новую ссылку настройки.

4. Выберите сертификат#

--acme-domain принимает только обычные имена хостов, без 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).

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.target

systemctl daemon-reload
systemctl enable --now mistgate
journalctl -u mistgate -f

Почему он такой:

• Команда mistgate setup запускалась от root, поэтому каталог данных принадлежит root, и служба тоже работает от root. При этом у неё отобраны все права, кроме занятия низких портов, а писать она может только в /var/lib/mistgate. Если у вас другой --data-dir, поправьте ReadWritePaths.
• По SIGTERM панель останавливается аккуратно. С Restart=on-failure systemd перезапустит её, если упадёт слушатель, но не тогда, когда вы её остановили.
• У каждого флага есть переменная окружения 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 — целиком, вместе с частью после #.

1. Язык. Выберите русский или английский, потом его можно сменить.
2. Создай админа. Поле ЛОГИН (в нём сразу стоит admin) — это ваш логин и имя, под которым панель вас показывает. Дальше:
   • Создать passkey: браузер попросит отпечаток пальца, лицо, PIN-код или ключ безопасности. Ключ остаётся на вашем устройстве. Это рекомендуемый способ.
   • пароль + код из приложения: пароль не короче 12 символов, затем отсканируйте QR-код приложением-аутентификатором (Google Authenticator, 1Password, Aegis и подобными), введите 6-значный код и нажмите Создать админа.
3. Готово. Выберите Добавить первую ноду или Позже, сначала осмотрюсь.

Первый админ — владелец. Ещё мастер настройки создаёт пустую группу «Все» для первых пользователей.

• Логин — от 3 до 64 символов: a–z, 0–9 и . _ @ -.
• Ссылка тратится только в момент, когда админ создан. Если она истекла или что-то пошло не так, запустите mistgate setup ещё раз и получите новую.
• Passkey работает только на том адресе админки, который сохранила команда setup. Сообщение «Браузер отклонил passkey для этого адреса» значит, что страница открыта по другому адресу.

Потом вы входите по адресу админки кнопкой Войти по passkey или другим способом: логин, пароль и код. Пять неверных паролей в течение часа блокируют этот логин на 15 минут. Если потерялся телефон или passkey, команду mistgate auth reset-login описывает страница Безопасность.

9. Сразу сделайте резервную копию#

Всё, что знает панель, лежит в каталоге данных:

Сделайте копию сейчас и после каждого важного изменения. Ту же команду показывает раздел Настройки → Бэкапы в админке:

systemctl stop mistgate
tar czf mistgate-backup-$(date +%F).tgz -C /var/lib mistgate
systemctl start mistgate

Автоматические шифрованные бэкапы — Планируется. Если на шаге 1 вы сделали ключ релиза, его файл тоже храните офлайн и с копией.

Что дальше#

Добавление ноды.