Как установить и настроить oxmysql на FiveM
Установите или обновите oxmysql на вашем Linux-сервере FiveM, составьте корректную строку подключения к MariaDB, проверьте подключение и устраните наиболее частые ошибки.
На этой странице
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 fivemBASE=/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"
exitsudo 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.logUnable 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:
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:
GRANT ALL PRIVILEGES ON fivem.* TO 'fivem'@'localhost';
FLUSH PRIVILEGES;Пароль содержит специальные символы
: или / в пароле обрывает строку в неправильном месте, и тогда в ошибке указывается неожиданный хост или пользователь. Сгенерируйте новый пароль командой openssl rand -hex 16, примените его в sudo mariadb, затем обновите server.cfg:
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.sqltook 350.0000ms to execute a query
Это сообщение указывает на медленный запрос и содержит имя ресурса, который его выполнил. Оно нормально при запуске и может также возникать из-за общего замедления сервера. Если оно часто повторяется в игре для одного и того же ресурса, следуйте руководству Диагностика сбоев и тормозов сервера FiveM.
Конфликт с mysql-async или ghmattimysql
oxmysql заменяет эти два ресурса и отвечает вместо них. Удалите их строки ensure и их папки, предварительно сделав резервную копию.