RU

Игровые серверы

Как установить и настроить oxmysql на FiveM

Установите или обновите oxmysql на вашем Linux-сервере FiveM, составьте корректную строку подключения к MariaDB, проверьте подключение и устраните наиболее частые ошибки.

6 мин чтения, обновлено 18 ноября 2026 г.

На этой странице

oxmysql — это ресурс, который связывает ваш сервер FiveM с его базой данных. От него зависят ESX Legacy, QBCore и множество скриптов. Это руководство объясняет, как установить или обновить его, составить строку подключения, убедиться, что она работает, и устранить частые ошибки.

Предварительные требования

  • Сервер, установленный по руководству Создание сервера FiveM
  • Установленная MariaDB с базой данных fivem и пользователем fivem, созданными в этом руководстве
  • Доступ к txAdmin для работы с CFG Editor и Live Console

Проверка того, что уже установлено

Рецепты ESX Legacy и QBCore уже устанавливают oxmysql. Сначала найдите папку вашего сервера, имя которой заканчивается на .base:

Терминал
sudo find /home/fivem/txData -maxdepth 1 -type d -name '*.base'

Если появилось несколько папок, нужная — та, что указана в Server Data Folder, в Settings, вкладка FXServer. Затем откройте сессию fivem и найдите ресурс, заменив FOLDER_NAME:

Терминал
sudo -iu fivem
BASE=/home/fivem/txData/FOLDER_NAME.base
find "$BASE/resources" -type d -name oxmysql
grep -E "^version" "$(find "$BASE/resources" -type f -path '*/oxmysql/fxmanifest.lua' | head -n 1)"
exit

Запишите выведенный путь. В рецептах ESX Legacy и QBCore это resources/[standalone]/oxmysql. Если find не возвращает ни одного пути, oxmysql не установлен, а grep сообщает об ошибке, которая ни на что не влияет.

Установка или обновление oxmysql

Сделайте резервную копию сервера, установите unzip, затем остановите сервис:

Терминал
sudo /usr/local/sbin/backup-fivem.sh
sudo apt install -y unzip
sudo systemctl stop fivem.service
sudo -iu fivem

В сессии fivem загрузите последнюю версию и замените ею старую. Измените TARGET, если найденный ранее путь отличается:

Терминал
BASE=/home/fivem/txData/FOLDER_NAME.base
TARGET="$BASE/resources/[standalone]/oxmysql"

TMP=$(mktemp -d "$HOME/oxmysql.XXXXXX")
curl -fL -o "$TMP/oxmysql.zip" https://github.com/overextended/oxmysql/releases/latest/download/oxmysql.zip
unzip -q "$TMP/oxmysql.zip" -d "$TMP"
grep -E "^version" "$TMP/oxmysql/fxmanifest.lua"

rm -rf "$HOME/oxmysql.previous"
[ -d "$TARGET" ] && mv "$TARGET" "$HOME/oxmysql.previous"
mkdir -p "$(dirname "$TARGET")"
mv "$TMP/oxmysql" "$TARGET"
rm -rf "$TMP"
ls "$TARGET"
exit

Папка должна содержать fxmanifest.lua, dist и lib. Старая версия остаётся в /home/fivem/oxmysql.previous, вне resources, чтобы FXServer её не загружал.

Настройка server.cfg

В txAdmin откройте CFG Editor. Строка подключения должна быть задана до запуска ресурсов:

Текст
set mysql_connection_string "mysql://fivem:GENERATED_PASSWORD@127.0.0.1/fivem?charset=utf8mb4"

ensure oxmysql

Поместите ensure oxmysql перед фреймворком и ресурсами, использующими базу данных. В рецепте QBCore этой строки нет: он запускает всю папку [standalone], а qb-core запускает oxmysql как зависимость. В этом случае добавлять её не нужно.

Два формата строки

oxmysql принимает два равнозначных написания:

Текст
set mysql_connection_string "mysql://fivem:GENERATED_PASSWORD@127.0.0.1:3306/fivem?charset=utf8mb4"
set mysql_connection_string "user=fivem;password=GENERATED_PASSWORD;host=127.0.0.1;port=3306;database=fivem;charset=utf8mb4"

Оставьте только одну из этих строк.

Элемент Значение Примечание
Пользователь fivem Не используйте root
Пароль Сгенерированное значение Только буквы и цифры, командой openssl rand -hex 16
Хост 127.0.0.1 Исключает ситуацию, когда localhost разрешается в IPv6, а MariaDB слушает IPv4
Порт 3306 Необязателен, если используется порт по умолчанию
База данных fivem Или fivem_rp, если вы создали другую
charset utf8mb4 Сохраняет диакритику и эмодзи

Документация oxmysql не рекомендует использовать в значениях следующие символы: ; , / ? : @ & = + $ #. Проще всего не включать их в пароль.

Проверка подключения

Сначала проверьте учётные данные напрямую через MariaDB. Команда запросит пароль:

Терминал
mariadb -h 127.0.0.1 -P 3306 -u fivem -p fivem -e "SELECT VERSION();"

Если версия отображается, запустите сервер и найдите сообщение об успешном подключении oxmysql:

Терминал
sudo systemctl start fivem.service
sudo grep -a 'Database server connection established' /home/fivem/fxserver.log

Если вы только изменили server.cfg, лучше перезапустите сервер из txAdmin. Наконец, убедитесь, что ресурс активен:

Терминал
curl -fsS http://127.0.0.1:30120/info.json | grep -o '"oxmysql"'

Полезные настройки

Эти переменные размещаются в server.cfg, перед ensure oxmysql, всегда с помощью set:

Переменная Действие Значение по умолчанию
mysql_slow_query_warning Порог в миллисекундах, после которого запрос помечается как медленный 200
mysql_debug Выводит запросы в консоль false
mysql_ui Включает интерфейс мониторинга в игре, открываемый командой /mysql false

Интерфейс /mysql дополнительно требует права command.mysql: см. Управление правами ACE на FiveM. Документация oxmysql относит его к разработке или серверам с небольшим числом игроков.

Чтобы отслеживать один ресурс без перезапуска, введите в Live Console, а по окончании анализа уберите его:

Текст
oxmysql_debug add es_extended
oxmysql_debug remove es_extended

Не включайте mysql_debug на постоянной основе: отображаемые запросы могут содержать данные игроков и засоряют журналы.

Возврат к предыдущей версии

Терминал
sudo systemctl stop fivem.service
sudo -iu fivem
Терминал
BASE=/home/fivem/txData/FOLDER_NAME.base
TARGET="$BASE/resources/[standalone]/oxmysql"
rm -rf "$HOME/oxmysql.failed"
mv "$TARGET" "$HOME/oxmysql.failed"
mv "$HOME/oxmysql.previous" "$TARGET"
exit
Терминал
sudo systemctl start fivem.service

При возникновении проблем

Если подключение не удаётся, oxmysql выводит Unable to establish a connection to the database, а за ним код в скобках. Найдите его командой:

Терминал
sudo grep -a -A2 'Unable to establish a connection' /home/fivem/fxserver.log

Unable to establish a connection to the database (ECONNREFUSED)

MariaDB не отвечает по указанному адресу.

  • Проверьте сервис командой sudo systemctl status mariadb.
  • Проверьте порт прослушивания командой sudo ss -ltnp | grep ':3306'.
  • Если в ошибке упоминается ::1, замените localhost на 127.0.0.1 в строке.

ER_ACCESS_DENIED_ERROR

Внимательно прочитайте учётную запись, указанную в сообщении:

  • 'fivem'@'localhost' (using password: YES): пароль неверен. Сравните его с тем, который вы проверили командой mariadb.
  • 'root'@'localhost' (using password: NO): oxmysql не прочитал вашу строку и использует значение по умолчанию. Убедитесь, что строка записана как set mysql_connection_string, что она не закомментирована и что она находится перед ensure oxmysql.
  • 'fivem'@'127.0.0.1': MariaDB не связывает этот адрес с учётной записью localhost, что случается, в частности, при опции skip_name_resolve. Создайте учётную запись для этого адреса в sudo mariadb:
SQL
CREATE USER 'fivem'@'127.0.0.1' IDENTIFIED BY 'GENERATED_PASSWORD';
GRANT ALL PRIVILEGES ON fivem.* TO 'fivem'@'127.0.0.1';
FLUSH PRIVILEGES;

ER_BAD_DB_ERROR

Сообщение Unknown database означает, что базы данных не существует. Сравните имя в строке со списком, возвращаемым командой sudo mariadb -e "SHOW DATABASES;".

ER_DBACCESS_DENIED_ERROR

Пользователь существует, но не имеет прав на эту базу данных. Предоставьте их в sudo mariadb:

SQL
GRANT ALL PRIVILEGES ON fivem.* TO 'fivem'@'localhost';
FLUSH PRIVILEGES;

Пароль содержит специальные символы

: или / в пароле обрывает строку в неправильном месте, и тогда в ошибке указывается неожиданный хост или пользователь. Сгенерируйте новый пароль командой openssl rand -hex 16, примените его в sudo mariadb, затем обновите server.cfg:

SQL
ALTER USER 'fivem'@'localhost' IDENTIFIED BY 'GENERATED_PASSWORD';

Could not find dependency oxmysql for resource

Указанному ресурсу нужен oxmysql, который не найден. Убедитесь, что fxmanifest.lua находится непосредственно в этой папке, а не во вложенной папке oxmysql/oxmysql. Затем введите refresh и ensure oxmysql в Live Console.

Resource 'oxmysql' can't run

Если следующая строка содержит server needs to be 12913 or higher, обновите FXServer или пока вернитесь к предыдущей версии oxmysql.

Table 'fivem.xxx' doesn't exist

Ресурс ожидает таблицу, которая не была создана. Импортируйте файл .sql, поставляемый с этим ресурсом, предварительно сделав резервную копию:

Терминал
sudo mariadb fivem < /path/to/file.sql

took 350.0000ms to execute a query

Это сообщение указывает на медленный запрос и содержит имя ресурса, который его выполнил. Оно нормально при запуске и может также возникать из-за общего замедления сервера. Если оно часто повторяется в игре для одного и того же ресурса, следуйте руководству Диагностика сбоев и тормозов сервера FiveM.

Конфликт с mysql-async или ghmattimysql

oxmysql заменяет эти два ресурса и отвечает вместо них. Удалите их строки ensure и их папки, предварительно сделав резервную копию.