中文

游戏服务器

如何在 FiveM 上安装和配置 oxmysql

在 Linux FiveM 服务器上安装或更新 oxmysql,编写正确的 MariaDB 连接字符串,检查连接,并修复最常见的错误。

阅读约 6 分钟, 更新于 2026年11月18日

本页内容

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 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 子文件夹。然后在 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.sql

took 350.0000ms to execute a query

此消息表示有查询较慢,并显示发起该查询的资源名称。它在启动时属正常现象,也可能源于服务器整体变慢。如果同一资源在游戏中频繁出现此消息,请参阅诊断 FiveM 服务器的崩溃和卡顿。

与 mysql-async 或 ghmattimysql 冲突

oxmysql 会取代这两个资源,并代替它们响应。请在备份后,删除它们的 ensure 行并删除其文件夹。