GNU/Linux

Это руководство поможет установить Gml.Backend на GNU/Linux и открыть панель по своему домену с HTTPS.

Лучший способ для новичков

Для первой установки на отдельном VPS рекомендуем режим global. Gml Manager запустит сервисы, а встроенный Angie настроит HTTPS, получит сертификат Let's Encrypt и будет автоматически его продлевать. Вам нужно подготовить домен, DNS и доступ к портам 80/443.

Самый простой вариант — новый VPS с публичным IPv4, на котором ещё нет сайтов и другого веб-прокси. Если сервер уже обслуживает сайты через nginx, Caddy, Traefik или другой прокси, выбирайте external и подключайте GML к существующей конфигурации.

Выберите режим

Раскройте подходящую инструкцию. global автоматически настраивает HTTPS на отдельном сервере; external подключает GML к вашему существующему прокси.

Режим по умолчанию

При новой установке предложенный режим — external. Для рекомендуемой установки с автоматическим HTTPS явно выберите 2 / global в меню либо передайте --proxy-mode global.

global — автоматический HTTPS (рекомендуется новичкам)

Пользователь → https://gml.example.com:443 → Angie → панель / API / скины

Angie занимает публичные TCP-порты 80 и 443. Он автоматически получает сертификат Let's Encrypt для выбранного домена и перенаправляет обычные HTTP-запросы на HTTPS. Порт 80 остаётся доступным для проверки домена и продления сертификата.

Этот режим подходит, когда GML — основной веб-сервис на отдельном сервере. Другие программы могут работать на других портах, но отдельный nginx, Apache, Caddy или иной контейнер не должен занимать 80/443. Само слово global не означает поддержку нескольких сайтов: штатная настройка обслуживает один указанный домен GML.

Требования для global

Сервер и доступ

• GNU/Linux с правами root или возможностью выполнить команды через sudo. Gml Manager поддерживает Debian, Ubuntu, Fedora, Alpine Linux, Arch Linux и их производные.
• Публичный IPv4, на который можно направить домен и принимать входящие TCP-соединения. Установщик требует DNS-запись A: сервер только с IPv6 для этого сценария не подходит.
• Подключение к интернету для загрузки установщика, пакетов и Docker-образов. Нужен исходящий HTTPS-доступ к GitHub, GHCR, Let's Encrypt, сервисам определения публичного IP и публичным DNS-over-HTTPS Google/Cloudflare, а также работающий DNS.
• Свободная или отсутствующая директория установки, по умолчанию /srv/gml. Для существующей установки используйте обновление, а не повторную установку в занятую директорию.
• Docker Engine и Compose plugin. Gml Manager устанавливает Docker, если он отсутствует; возможность устанавливать системные пакеты нужна в любом случае.

Для новичка удобнее VPS с публичным IPv4 непосредственно на сервере. За роутером потребуется корректный проброс TCP 80/443; за CGNAT без входящего доступа этот сценарий не заработает.

Домен и DNS

Подготовьте домен или поддомен, например gml.example.com, и доступ к его DNS-записям. Далее в инструкции заменяйте этот пример своим именем.

Установщик принимает одно полное доменное имя. Вводите gml.example.com, без https://, номера порта, пути и завершающей точки. Не подходят IP-адрес, localhost, *.example.com и имена с подчёркиваниями. Для кириллического домена используйте ASCII-представление Punycode (xn--…).

Настройте DNS:

1. Создайте A-запись выбранного имени с публичным IPv4 вашего сервера. Например, в зоне example.com имя записи обычно будет gml. Некоторые панели требуют полное имя — следуйте формату своей панели.
2. Если для этого имени несколько A-записей, каждая должна указывать на этот сервер. Удалите старые адреса и записи других серверов: текущая проверка установщика отклоняет несовпадение любой A-записи.
3. AAAA-запись необязательна. Оставляйте её только при рабочем публичном IPv6 на этом сервере и доступности 80/443 по IPv6. Если IPv6 не настроен, удалите AAAA для этого имени. Каждая существующая AAAA должна совпадать с публичным IPv6 сервера.
4. При использовании Cloudflare поставьте для записи DNS only — серое облако. Cloudflare может оставаться вашим DNS-провайдером, но его проксирование и аналогичный CDN-прокси текущий режим global не поддерживает: DNS должен возвращать адрес самого сервера.
5. Дождитесь обновления публичного DNS. Запись в /etc/hosts на ноутбуке или сервере не заменяет публичный DNS: установщик проверяет A/AAAA через публичные резолверы.

Если в зоне есть ограничивающие CAA-записи, они должны разрешать выпуск сертификата Let's Encrypt. Менять CAA при отсутствии таких ограничений не нужно.

Порты и сетевые экраны

TCP 80 и 443 должны быть одновременно свободны на сервере и доступны из интернета. Проверьте firewall внутри ОС, правила VPS-провайдера / security group и, при наличии, роутер. Правила только внутри Linux не отменяют блокировку в панели провайдера. Проверка свободных портов установщиком также не доказывает их доступность из интернета.

Порт 80 используется для проверки HTTP-01 Let's Encrypt, которая работает именно на порту 80.После установки оставьте 80 открытым для продления и HTTP → HTTPS перенаправлений.

Проверьте слушающие процессы:

sudo ss -ltnp '( sport = :80 or sport = :443 )'

До новой установки global вывод не должен содержать слушателей на этих портах. Посмотрите также контейнеры, если Docker уже установлен:

sudo docker ps --format 'table {{.Names}}\t{{.Ports}}'

Если порты заняты действующим сайтом, используйте external. На новом сервере с ненужным веб-сервисом сначала выясните, кто занимает порт, и отключите именно этот сервис. Не останавливайте все контейнеры или веб-серверы без разбора.

Рекомендуемая настройка UFW для новичков

На отдельном VPS новичкам рекомендуем самостоятельно настроить UFW — простой инструмент управления сетевым экраном. Gml Manager проверяет DNS и занятость портов, но правила firewall за вас не настраивает.

Разрешите три входящих TCP-порта:

• 22 — SSH: удалённый доступ к серверу для установки, обновления и администрирования. Этот порт нужно разрешить до включения UFW, чтобы сохранить доступ.
• 80 — HTTP: Angie перенаправляет пользователей на HTTPS; Let's Encrypt использует этот порт для проверки домена при выпуске и продлении сертификата. Оставьте его открытым после установки.
• 443 — HTTPS: защищённый доступ пользователей к панели, API и скинам через домен GML.

Пример для нового VPS и стандартным SSH-портом 22:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Сначала команды задают политику: запрещают неразрешённые входящие подключения и разрешают исходящие. Затем добавляют разрешения для SSH, HTTP и HTTPS, включают UFW и показывают результат. На вопрос при ufw enable подтвердите включение после проверки разрешения SSH. В статусе должны быть Status: active и правила ALLOW для выбранного SSH-порта, 80 и 443.

Если SSH работает на другом порту, замените 22/tcp своим портом до выполнения ufw enable. Сохраните текущую SSH-сессию и проверьте вход во второй сессии после включения. На сервере с другими сервисами предварительно разрешите и их необходимые порты.

UFW не заменяет firewall в панели VPS-провайдера: там тоже разрешите SSH и TCP 80/443.

Пошаговая установка global

Gml Manager сам подготавливает необходимые инструменты, проверяет публичный DNS и занятость портов. Домен и DNS-записи создайте у своего провайдера по требованиям выше; правила firewall настройте самостоятельно. Отдельно устанавливать диагностические утилиты и вручную проверять DNS перед запуском не требуется.

1. Запустите Gml Manager

Рекомендуемый интерактивный запуск:

curl -sSL https://raw.githubusercontent.com/Gml-Launcher/Gml.Backend/refs/heads/master/installer/gml-manager.sh | sudo sh

Если вы уже вошли как root, используйте sh без sudo:

curl -sSL https://raw.githubusercontent.com/Gml-Launcher/Gml.Backend/refs/heads/master/installer/gml-manager.sh | sh

Менеджер спросит язык, действие, директорию, параметры прокси и версию. Выберите:

1. Действие 1 — установить.
2. Директорию /srv/gml, если вы не хотите другую. Она должна быть пустой или ещё не существовать.
3. Режим 2 — global.
4. Ваш домен, например gml.example.com, без протокола и пути.
5. Ознакомьтесь с условиями Let's Encrypt и подтвердите согласие ответом y, если принимаете их. Без согласия режим не включится.
6. Последнюю предложенную стабильную версию. Для новой установки поддерживаются версии от v2026.2, а также ветки master и dev; новичкам рекомендуем стабильный релиз.

Установщик проверит DNS и свободные порты, подготовит Docker Compose и .env, создаст ключ безопасности, загрузит образы и запустит сервисы. Angie запросит сертификат автоматически. Отдельно устанавливать Certbot, вручную копировать сертификаты или писать конфигурацию nginx для этого сценария не нужно.

Установщик ждёт сертификат и проверяет его локальным HTTPS-запросом с проверкой доверия и имени домена. Это может занять несколько минут. Дождитесь сообщения об успешном запуске и адреса панели; сам факт старта контейнера ещё не означает, что сертификат уже получен.

2. Вариант запуска с готовыми параметрами

После выполнения требований можно сразу передать параметры установки:

curl -sSL https://raw.githubusercontent.com/Gml-Launcher/Gml.Backend/refs/heads/master/installer/gml-manager.sh | sudo sh -s -- install --dir /srv/gml --proxy-mode global --domain gml.example.com --accept-acme-terms

Замените домен своим. --accept-acme-terms означает ваше согласие с условиями Let's Encrypt. Без --version менеджер выбирает последний стабильный тег; для закрепления версии добавьте, например, --version v2026.2.

Важное отличие команды

Команда install --dir /srv/gml без --proxy-mode global создаёт установку в режиме external. Для автоматического HTTPS нужны все параметры global из примера выше.

3. Откройте панель и проверьте HTTPS

Откройте https://gml.example.com. Если начальная настройка ещё не завершена, переход на /mnt ожидаем: выполните мастер настройки в панели. Используйте домен, указанный при установке; сертификат выпущен для этого имени.

Проверьте с ноутбука или другой машины вне сервера:

curl -I http://gml.example.com/
curl -I https://gml.example.com/
curl https://gml.example.com/health

Ожидается:

• HTTP возвращает 308 с Location: https://gml.example.com/.
• HTTPS устанавливает доверенное TLS-соединение; ответ страницы может быть 2xx или перенаправлением на настройку/авторизацию.
• /health отвечает 200, если API работает.

Диагностика проблем с global

DNS не совпадает или включён CDN

Если менеджер сообщает has no DNS A record или DNS A ... points to ..., сравните A-записи с публичным IPv4 сервера. Проверьте все адреса имени, отключите проксирование Cloudflare/CDN и дождитесь обновления публичного DNS. Если ошибка относится к AAAA, исправьте IPv6 или удалите ненужную запись.

Ошибка Unable to query public DNS означает, что установщику не удалось запросить публичный DNS через HTTPS. Проверьте исходящий доступ сервера и его DNS; локальная запись /etc/hosts такую проверку не исправит.

Порт 80 или 443 занят

Сообщение TCP port ... is already in use означает конфликт слушателей. Посмотрите ss и docker ps из раздела требований. Если порт нужен существующему сайту, выбирайте external.

Сертификат не получен

При Timed out waiting for a valid Let’s Encrypt certificate проверьте DNS A/AAAA, доступность TCP 80 извне, firewall провайдера и исходящий доступ контейнера к Let's Encrypt. Посмотрите журналы, в том числе причины отказа центра сертификации:

cd /srv/gml
sudo docker compose ps -a
sudo docker compose logs --tail 200 gml-web-proxy

Если журнал указывает на CAA или лимиты выпуска, исправьте соответствующее ограничение перед новой попыткой; многократная переустановка не исправляет DNS или закрытый порт. При проблемах с выпуском полезны правила проверки домена Let's Encrypt.

Если ошибка возникла на новой установке и менеджер уже создал /srv/gml/docker-compose.yml и /srv/gml/.env, после исправления DNS/сети можно снова запустить созданный стек:

cd /srv/gml
sudo docker compose up -d
sudo docker compose logs --tail 200 gml-web-proxy

Затем повторите внешние проверки HTTP, HTTPS и /health из инструкции выше. Команда up -d только запускает контейнеры и не ждёт сертификат как Gml Manager. Не запускайте повторную команду install в непустую директорию и не удаляйте данные для исправления DNS.

Контейнеры работают, но панель недоступна

Проверьте не только статус контейнера, но и HTTPS по домену с внешней машины. Если /health не отвечает, посмотрите API:

cd /srv/gml
sudo docker compose logs --tail 100 gml-web-api

При обращении по IP браузер может показать ошибку имени сертификата: используйте домен, выбранный для global. Если домен открывает другой сайт, перепроверьте DNS и сервер, который фактически принимает 80/443.

external — за существующим прокси

Пользователь → ваш nginx / Caddy / Traefik с HTTPS → Angie по HTTP:5003 → сервисы GML

GML публикует HTTP-вход на PORT_GML_FRONTEND, по умолчанию 5003. Ваш внешний прокси принимает запросы домена на 80/443, получает и продлевает сертификат и передаёт запросы в GML. Встроенный Angie продолжает распределять их между сервисами.

Выбирайте этот режим, если на сервере уже размещены сайты, настроен HTTPS или нужна собственная схема маршрутизации. Без внешнего прокси панель доступна по HTTP, например http://SERVER_IP:5003; автоматический публичный HTTPS в этом режиме не настраивается.

Настройка external

При интерактивной установке выберите 1 — external. Для установки с заданными параметрами:

curl -sSL https://raw.githubusercontent.com/Gml-Launcher/Gml.Backend/refs/heads/master/installer/gml-manager.sh | sudo sh -s -- install --dir /srv/gml --proxy-mode external

Откройте http://SERVER_IP:5003 или настройте внешний прокси на этот HTTP-вход. Если прокси работает на том же сервере, его upstream обычно — http://127.0.0.1:5003. Из отдельного контейнера 127.0.0.1 указывает на сам контейнер: используйте доступный ему адрес хоста/сеть.

На внешнем прокси настройте:

• HTTPS и продление сертификата для домена;
• передачу всего сайта на HTTP-вход GML, включая API и скины;
• поддержку WebSocket с заголовками Upgrade / Connection для /ws*;
• передачу исходного Host, X-Forwarded-Proto, X-Real-IP и корректного X-Forwarded-For.

Режим external доверяет метаданным внешнего прокси. Внешний прокси должен формировать доверенные заголовки, а сетевой доступ к HTTP-входу GML следует ограничить этим прокси. Сертификат в external обслуживает именно ваш внешний прокси.

Обновление и смена режима

Для установленного GML используйте ту же директорию. Обычное обновление сохраняет текущий режим, если --proxy-mode не указан:

curl -sSL https://raw.githubusercontent.com/Gml-Launcher/Gml.Backend/refs/heads/master/installer/gml-manager.sh | sudo sh -s -- update --dir /srv/gml

Для перехода из external в global сначала выполните все требования global, включая освобождение 80/443 и прямой DNS, затем запустите:

curl -sSL https://raw.githubusercontent.com/Gml-Launcher/Gml.Backend/refs/heads/master/installer/gml-manager.sh | sudo sh -s -- update --dir /srv/gml --proxy-mode global --domain gml.example.com --accept-acme-terms

Для возврата из global в external:

curl -sSL https://raw.githubusercontent.com/Gml-Launcher/Gml.Backend/refs/heads/master/installer/gml-manager.sh | sudo sh -s -- update --dir /srv/gml --proxy-mode external

При таком переходе HTTP-вход возвращается на порт 5003; HTTPS после перехода должен обслуживать ваш внешний прокси. Для смены домена в global подготовьте DNS нового имени и выполните update --proxy-mode global --domain НОВЫЙ_ДОМЕН с остальными параметрами команды выше.

Обновление выбирает последний стабильный релиз, если не задан --version; смена режима этой командой также может обновить сервисы. Для сохранения версии задайте текущий тег явно. Менеджер отдельно спрашивает подтверждение перезаписи управляемого docker-compose.yml, даже если параметры переданы в командной строке: проверьте свои изменения и подтвердите, если согласны.

Перед обновлением сохраните резервную копию данных. Менеджер загружает новые образы до остановки старого стека, но переключение контейнеров сопровождается перерывом. Если запуск новой конфигурации или получение сертификата при обновлении не удалось, он пытается восстановить предыдущие Compose, .env и стек. Это не заменяет резервное копирование. При неудаче получения сертификата на новой установке менеджер останавливает созданный стек и сообщает ошибку.

Если ранее использовался старый установщик, укажите его существующую директорию в Gml Manager при обновлении. Для global нужен образ прокси на Angie с HTTPS/ACME; старый YARP-прокси этого режима не поддерживает.

Другие варианты запуска

Если Gml Manager не подходит для вашей системы, используйте ручную установку. Для разработки на ноутбуке без Docker предусмотрен запуск через Rider/Visual Studio или скрипт.

Дополнительная информация: репозиторий Gml.Backend.