如何在 FiveM 上安装和配置 oxmysql
在 Linux FiveM 服务器上安装或更新 oxmysql,编写正确的 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'如果出现多个文件夹,正确的是 Settings 的 FXServer 选项卡中 Server Data Folder 所指的那个。然后打开 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 权限:请参阅在 FiveM 上管理 ACE 权限。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 子文件夹。然后在 Live Console 中输入 refresh,再输入 ensure oxmysql。
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 行并删除其文件夹。