中文

游戏服务器

如何在 FiveM 服务器上安装 ESX 或 QBCore

在 ESX Legacy 与 QBCore 之间做出选择,准备 MariaDB 数据库,使用 txAdmin 在 Linux 服务器上部署框架,检查结果,并在需要时回退。

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

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

ESX Legacy 和 QBCore 是角色扮演框架:它们为 FiveM 添加角色、职业、金钱和物品栏。本指南帮助您在两者之间做出选择,然后使用 txAdmin 部署其中一个,同时不丢失您当前的配置。

前提条件

  • 已按照指南创建 FiveM 服务器安装服务器:fivem 用户、fivem.service 服务、/usr/local/sbin/backup-fivem.sh 脚本
  • 已安装 MariaDB,并已在该指南的 MariaDB 一节中创建 fivem 数据库和 fivem 用户
  • 该 MariaDB 用户的密码
  • 您的 cfxk_ 许可证密钥和一个 txAdmin 主管理员账户

在 ESX 和 QBCore 之间选择

两个框架满足相同的需求。决定性的标准是您打算使用的资源列表:为其中一个编写的资源无法直接在另一个上运行。

标准 ESX Legacy QBCore
在 txAdmin 中部署 Popular Recipes,ESX Legacy 配方 Remote URL Template,填入配方地址
主要资源 es_extended qb-core
主要依赖项 oxmysql、esx_lib oxmysql
玩家表 users players
玩家权限 组保存在数据库中,使用 setgroup 修改 god、admin 和 mod 级别,由 ACE 权限管理
OneSync 由配方启用 由配方启用
文档 docs.esx-framework.org qbcore.org/docs

做决定时:

  • 选择 ESX Legacy:如果您想走 txAdmin 直接提供的路径,或者您的目标资源是为 ESX 编写的。
  • 选择 QBCore:如果您的目标资源是为 QBCore 编写的,或者您的团队已经熟悉它。
  • 也可以考虑 Qbox:如果您在 QBCore 一侧犹豫不决,txAdmin 在 Popular Recipes 中提供其配方,并称其与 QBCore 资源兼容。本指南不详细介绍它的安装。

之后更换框架等于从头开始:数据表、函数和资源都不相同。切勿在同一台服务器上同时安装两者。

步骤 1:备份服务器

运行备份脚本,并确认归档文件已成功创建:

终端
sudo /usr/local/sbin/backup-fivem.sh
sudo ls -lh /home/fivem/backups

请记下最新两个文件 fivem_DATE.tar.gz 和 fivem_db_DATE.sql.gz 的日期,回退时会用到。

步骤 2:准备数据库

检查 MariaDB 是否正常运行,并统计 fivem 数据库中的表数量:

终端
sudo systemctl is-active mariadb
sudo mariadb -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='fivem';"
  • 结果为 0:数据库为空,请使用 fivem 并进入步骤 3。
  • 结果大于 0:数据库中已有数据。请像下面这样为框架另建一个数据库。
终端
sudo mariadb
SQL
CREATE DATABASE fivem_rp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON fivem_rp.* TO 'fivem'@'localhost';
FLUSH PRIVILEGES;
EXIT;

然后将该数据库告知备份脚本,否则它不会被备份:

终端
sudo sed -i 's/^DB_NAME="fivem"$/DB_NAME="fivem_rp"/' /usr/local/sbin/backup-fivem.sh
sudo grep '^DB_NAME' /usr/local/sbin/backup-fivem.sh

在后续步骤中,凡涉及数据库名称之处,请将 fivem 替换为 fivem_rp。

如果您丢失了密码,请使用 openssl rand -hex 16 生成一个,然后在 sudo mariadb 中应用:

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

如果已有服务器在使用该账户,请同时更新其 mysql_connection_string 行。

步骤 3:返回 txAdmin 向导

如果尚未部署任何服务器,请跳过此步骤:txAdmin 已经显示向导。

否则,请通过 SSH 隧道打开 txAdmin,然后:

  1. 进入 Settings,打开 FXServer 选项卡。
  2. 复制 Server Data Folder 的值并保存好:这是您当前服务器的路径。
  3. 点击 Reset,然后确认。

此操作会停止服务器,并让 txAdmin 回到向导。它不会删除资源文件,也不会删除数据库。

步骤 4:启动部署

在向导中,为服务器命名,然后选择配方:

  • ESX Legacy:选择 Popular Recipes,然后选择 ESX Legacy。
  • QBCore:选择 Remote URL Template,然后粘贴以下地址:
文本
https://raw.githubusercontent.com/qbcore-fivem/txAdminRecipe/main/qbcore.yaml

保留建议的目标文件夹,然后进入 Recipe Deployer。粘贴您的 cfxk_ 密钥,然后点击 Show/Hide Database options (advanced) 并填写:

字段 值
Database Host 127.0.0.1
Database Port 3306
Database Username fivem
Database Password fivem 用户的密码
Database Name fivem(或 fivem_rp)
Delete Database 关闭

点击 Run Recipe。部署会下载大量资源,可能持续数分钟。完成后,点击 Save & Run Server。

步骤 5:检查安装

等待约一分钟,然后在控制台中查找数据库连接和框架启动的信息:

终端
sudo grep -a -E 'Database server connection established|Started resource (es_extended|qb-core)' /home/fivem/fxserver.log

您应该看到数据库连接的那一行,以及 es_extended 或 qb-core 的那一行。接着检查服务器是否声明了这些资源:

终端
curl -fsS http://127.0.0.1:30120/info.json | grep -oE '"(oxmysql|es_extended|qb-core)"'

最后确认配方已创建玩家表:

终端
# ESX Legacy
sudo mariadb fivem -e "SHOW TABLES LIKE 'users';"

# QBCore
sudo mariadb fivem -e "SHOW TABLES LIKE 'players';"

然后使用 connect 服务器IP:30120 连接游戏并创建一个角色。此时该表中应出现一行数据。

步骤 6:授予自己管理权限

  • ESX Legacy:连接服务器,在 txAdmin 的在线玩家列表中找到您的玩家编号,然后在 Live Console 中输入 setgroup 1 admin,并将 1 替换为该编号。该组会保存在 users 表中。
  • QBCore:将您的标识符加入 qbcore.god 组,方法见在 FiveM 上管理 ACE 权限。

请同时再做一次备份:它现在是您的参考回退点。

终端
sudo /usr/local/sbin/backup-fivem.sh

回退

此流程会将服务器和数据库恢复到步骤 1 时的状态。请将 DATE 替换为您记下的日期。

终端
sudo systemctl stop fivem.service
sudo mv /home/fivem/txData /home/fivem/txData.framework
sudo -u fivem tar -xzf /home/fivem/backups/fivem_DATE.tar.gz -C /home/fivem
sudo mariadb -e "DROP DATABASE fivem; CREATE DATABASE fivem CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
zcat /home/fivem/backups/fivem_db_DATE.sql.gz | sudo mariadb fivem
sudo systemctl start fivem.service

如果您创建了 fivem_rp,则步骤 1 的归档中包含原来的 fivem 数据库,它未被修改:请不要运行 DROP DATABASE 和 zcat 这两行。请改用 sudo mariadb -e "DROP DATABASE fivem_rp;" 删除 fivem_rp,然后在备份脚本中改回 DB_NAME="fivem"。

文件夹 /home/fivem/txData.framework 保留着这次尝试的内容。不再需要时请将其删除。

故障排除

Database connection failed

此消息出现在 Recipe Deployer 中,后面跟着原因:

  • connect ECONNREFUSED 127.0.0.1:3306:MariaDB 没有运行。请使用 sudo systemctl status mariadb 检查。
  • Access denied for user 'fivem'@'localhost':密码不正确。
  • Access denied for user 'fivem'@'127.0.0.1':请按照在 FiveM 上安装和配置 oxmysql添加该账户。

Access denied for user 'fivem'@'localhost' to database

Database Name 字段中的名称不是 fivem。默认情况下,txAdmin 会在其中填入部署的标识符,而 fivem 用户对该数据库没有任何权限。请更正该字段。

Table 'addon_account' already exists

ESX 配方已在该数据库上运行过,例如部署被中断的情况。如果数据库中没有有用的内容,请将其清空,然后重新运行配方:

终端
sudo mariadb -e "DROP DATABASE fivem; CREATE DATABASE fivem CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

部署在下载过程中中断

配方会从 GitHub 下载大量文件,而 GitHub 可能会暂时限制请求。请等待几分钟,然后重新启动部署。同时请使用 df -h /home 检查磁盘空间。

配方未出现,或 txAdmin 认为它不兼容

QBCore 不在 Popular Recipes 中:请使用 Remote URL Template。如果 txAdmin 提示 Some recipes are not compatible with your txAdmin version,请更新 FXServer,txAdmin 内置于其中。

Could not find dependency oxmysql for resource es_extended

oxmysql 资源缺失或放置位置不对。qb-core 和 esx_lib 也会出现相同的消息。请参照指南在 FiveM 上安装和配置 oxmysql检查它是否存在。

Resource 'oxmysql' can't run

如果下一行显示 server needs to be 12913 or higher,则说明您的 FXServer 版本对于该版本的 oxmysql 来说太旧。请更新 FXServer。

Table 'fivem.users' doesn't exist

连接字符串指向的数据库与部署所用的数据库不同,或者 SQL 导入未成功。请将 CFG Editor 中的 mysql_connection_string 与 sudo mariadb -e "SHOW DATABASES;" 的结果进行比较。

服务器能启动,但仍不稳定

请参阅诊断 FiveM 服务器的崩溃和卡顿,找出问题所在的资源。