База данных

Панель работает с PostgreSQL, MySQL или MariaDB и SQLite. Выбор задаётся двумя переменными в config.env:

DATABASE_DRIVER=postgres
DATABASE_URL=postgres://gameap:пароль@localhost:5432/gameap?sslmode=disable

Какую выбрать

Для типовой установки на одном сервере достаточно SQLite: он не требует ни отдельной службы, ни настройки, ни резервного копирования сложнее копирования файла.

Строка подключения

PostgreSQL

DATABASE_DRIVER=postgres
DATABASE_URL=postgres://пользователь:пароль@хост:5432/база?sslmode=disable

Имена драйвера взаимозаменяемы: postgres, postgresql, pgsql, pg, pgx.

Параметр sslmode задаёт режим шифрования соединения: disable для локальной базы, require или verify-full — для удалённой.

MySQL и MariaDB

DATABASE_DRIVER=mysql
DATABASE_URL=пользователь:пароль@tcp(хост:3306)/база?parseTime=true

Формат отличается от привычного адреса со схемой — это формат драйвера Go. Параметр parseTime=true обязателен.

Подключение через сокет:

DATABASE_URL=пользователь:пароль@unix(/var/run/mysqld/mysqld.sock)/база?parseTime=true

SQLite

DATABASE_DRIVER=sqlite
DATABASE_URL=file:/var/lib/gameap/db.sqlite?_busy_timeout=5000&_journal_mode=WAL&cache=shared

Файл создаётся автоматически. Параметры в примере включают журналирование WAL и ожидание при блокировке — оставьте их, они заметно улучшают поведение при одновременных запросах.

Каталог с файлом базы должен быть доступен на запись пользователю, от которого работает панель.

inmemory

DATABASE_DRIVER=inmemory
DATABASE_URL=inmemory

Данные хранятся только в оперативной памяти и теряются при перезапуске. Предназначен для тестов, для рабочей установки не годится.

DATABASE_URL требуется задать даже здесь: панель проверяет её на непустоту до того, как узнаёт драйвер, и без неё не запустится. Значение при этом не используется.

Миграции

Панель применяет миграции сама при запуске — отдельной команды нет. Версия схемы хранится в служебной таблице внутри той же базы.

Из этого следуют два практических правила:

• Обновление панели меняет схему при первом же запуске. Резервную копию нужно делать до него.
• Откат на предыдущую версию панели без восстановления базы не сработает — схема уже изменена.

Миграции применяются в том числе с пропусками номеров, поэтому пропуск промежуточной версии панели при обновлении допустим.

Резервное копирование

Панель резервных копий не делает — ни сама, ни через gameapctl. Настройте копирование средствами СУБД.

PostgreSQL

pg_dump -U gameap gameap > gameap-$(date +%F).sql

Восстановление:

psql -U gameap gameap < gameap-2026-08-02.sql

MySQL и MariaDB

mysqldump -u gameap -p gameap > gameap-$(date +%F).sql

Восстановление:

mysql -u gameap -p gameap < gameap-2026-08-02.sql

SQLite

Останавливать панель не обязательно, если использовать штатную команду:

sqlite3 /var/lib/gameap/db.sqlite ".backup '/backup/gameap-$(date +%F).sqlite'"

Простое копирование файла на работающей панели может дать повреждённую копию из-за журнала WAL.

Что ещё нужно сохранять

Базы недостаточно. Вместе с ней сохраняйте:

• config.env — в нём AUTH_SECRET и ENCRYPTION_KEY. Восстанавливать нужно те же значения, что были на момент копирования: при другом AUTH_SECRET перестанут приниматься выданные токены. Если ENCRYPTION_KEY на установке был задан, без него не восстановить зашифрованные данные и перестанет работать двухфакторная аутентификация. Если он не задавался, ключ шифрования секретов TOTP выводится из AUTH_SECRET — тогда достаточно сохранить его, а добавлять ENCRYPTION_KEY при восстановлении нельзя, это сломает 2FA всем пользователям;
• каталог файлов панели — в нём сертификаты gRPC, по которым подключаются демоны, и данные ACME. Путь задаётся FILES_LOCAL_BASE_PATH.

Файлы игровых серверов лежат на выделенных серверах и в резервную копию панели не входят.

Переключение на другую СУБД

Штатного переноса данных между СУБД нет: схемы для PostgreSQL, MySQL и SQLite создаются независимо, а инструмента переливки в панели не предусмотрено.

Порядок:

1. Сделайте резервную копию текущей базы.
2. Подготовьте новую базу и укажите её в DATABASE_DRIVER и DATABASE_URL.
3. Запустите панель — она создаст схему с нуля.
4. Перенесите данные: заведите пользователей, выделенные серверы, игры и игровые серверы заново либо через API.

Игровые серверы при этом не трогаются: их файлы остаются на выделенных серверах, достаточно описать серверы в панели с теми же каталогами и портами.

Перелить дамп из одной СУБД в другую напрямую не получится — типы столбцов и синтаксис отличаются.

Несколько экземпляров панели

Для установки из нескольких экземпляров подойдут PostgreSQL или MySQL. SQLite не годится: он не рассчитан на нескольких клиентов, работающих с файлом базы одновременно.

Кроме базы понадобятся общий кэш, общий обмен событиями и общее хранилище файлов. Подробнее — Несколько экземпляров панели.

Проверка

Если панель не запускается из-за базы, в журнале будет сообщение о подключении или о миграции:

journalctl -u gameap -n 50 --no-pager

Частые причины: неверный формат DATABASE_URL (особенно у MySQL — там нужен формат драйвера Go, а не адрес со схемой), нет прав на каталог с файлом SQLite, база не создана или пользователю не выданы права на неё.