如何在 FiveM 上管理 ACE 权限
了解 FiveM 的 ACE 和 principal,在专用文件中创建管理组,从控制台测试每项权限,并修复 Access denied 错误。
本页内容
FXServer 通过 ACE(access control entries,访问控制条目)和 principal 系统来控制命令的访问。本指南介绍它如何做出判定、如何在单独的文件中创建您的组、如何测试每项权限,以及如何撤销访问权限。
前提条件
- 已按照指南创建 FiveM 服务器安装服务器
- 可访问 txAdmin,以使用 Live Console、CFG Editor 和玩家列表
- 您要授予权限的玩家的标识符
需要了解的概念
一条规则可以这样理解:某个 principal 有权或无权访问某个对象。
| 概念 | 作用 | 示例 |
|---|---|---|
| Principal | 谁获得权限 | group.admin、identifier.license:abc123、resource.es_extended |
| 对象 | 被保护的内容 | command、command.quit、myserver.garage |
| ACE | 一条 allow 或 deny 规则 |
add_ace group.admin command allow |
| 继承 | 一个 principal 获得另一个 principal 的权限 | add_principal identifier.license:abc123 group.admin |
最常见的 principal:
| Principal | 指代 |
|---|---|
identifier.license:... |
通过 Rockstar 许可证标识的玩家。这是最可靠的标识符 |
identifier.fivem:... |
通过 Cfx.re 账户标识的玩家 |
identifier.discord:... |
通过 Discord 账户标识的玩家,仅当其连接时检测到 Discord 才有效 |
player.1 |
当前会话中的 1 号玩家。该编号在每次连接时都会变化 |
group.name |
您可自由定义的组 |
resource.name |
资源,当它自己执行命令时 |
builtin.everyone |
所有人 |
FXServer 如何做出判定
四条规则就足以预测结果:
- 没有规则就是拒绝。 principal 默认无权访问任何内容。
- 权限覆盖其子对象。
command覆盖command.quit,myserver.garage覆盖myserver.garage.open。 deny优先于allow,与各行的顺序无关。- 玩家按标识符逐个评估。 只要其中一个标识符被授权,该玩家就有访问权限。
第四条规则有一个重要的后果:如果同一玩家的 identifier.fivem:42 被授权,那么对 identifier.license:abc123 设置的 deny 并不能阻止其访问。要撤销某位玩家的权限,请将其从组中移除,而不是添加 deny。
步骤 1:查找玩家的标识符
该玩家必须已经连接过服务器。在 txAdmin 中,从玩家列表打开其资料页,然后打开 IDs 选项卡。您会在其中看到类似 license:abc123 或 fivem:42 的值。
对于 FXServer,请加上前缀 identifier.:license:abc123 变为 identifier.license:abc123。
步骤 2:创建权限文件
单独的文件可使 server.cfg 保持清晰。请找到服务器文件夹,其名称以 .base 结尾。如果出现多个文件夹,正确的是 Settings 的 FXServer 选项卡中 Server Data Folder 所指的那个:
sudo find /home/fivem/txData -maxdepth 1 -type d -name '*.base'打开 fivem 会话,备份配置,然后创建文件:
sudo -iu fivem
BASE=/home/fivem/txData/FOLDER_NAME.base
cp "$BASE/server.cfg" "$BASE/server.cfg.before-permissions"
nano "$BASE/permissions.cfg"下面是一个包含版主组和管理组的示例,请根据需要调整:
# 版主的权限
add_ace group.moderator command.clientkick allow
add_ace group.moderator command.say allow
# 管理员继承版主的权限
add_principal group.admin group.moderator
# 管理员的权限
add_ace group.admin command allow
add_ace group.admin command.quit deny
# 团队成员
add_principal identifier.license:MODERATOR_LICENSE group.moderator
add_principal identifier.license:ADMIN_LICENSE group.admin使用 exit 退出会话。
步骤 3:加载文件
在 CFG Editor 中,将下面这一行添加到已有权限的旁边:
exec permissions.cfg路径相对于服务器文件夹。保存后,在 Live Console 中输入同一条命令,即可无需重启而应用该文件。无论如何,它都会在下次启动时被重新读取。
已连接的玩家会立即获得新权限,无需重新连接。
步骤 4:测试权限
所有这些命令都在 Live Console 中输入。test_ace 会返回 true 或 false:
test_ace identifier.license:MODERATOR_LICENSE command.clientkick
test_ace identifier.license:MODERATOR_LICENSE command.quit
test_ace group.admin command.quit按照上面的示例,您应依次得到 true、false、false。返回的格式如下:
identifier.license:MODERATOR_LICENSE -> command.clientkick = true要显示所有已加载的内容:
list_principals
list_aceslist_principals 显示 子项 <- 父项,list_aces 显示 principal -> 对象 = ALLOW 或 DENY。
如果某个结果出乎您的意料,请启用详细跟踪,重新执行该操作,然后将其关闭:
se_debug true
se_debug false此时控制台会显示每条被查询的规则,包含 TEST ACL [...] -> ALLOW 或 DENY 这样的行。
授权某条命令或某个资源
向所有玩家开放某条受限命令:
add_ace builtin.everyone command.mycommand allow允许资源运行某条命令。 当资源使用 ExecuteCommand 时,必须由该资源本身拥有权限。请只授予所需的那条命令:
add_ace resource.my_resource command.add_principal allow保护您自己脚本中的某个功能。 创建一个自定义对象,然后在服务器端使用 IsPlayerAceAllowed 进行测试:
add_ace group.moderator myserver.garage allowif IsPlayerAceAllowed(source, 'myserver.garage') then
-- 受限操作
endACE 与框架
框架基于这套系统,但各自有自己的方法。请勿删除其配方添加的 add_ace resource... 行:它们需要这些行才能正常工作。
ESX Legacy
玩家所属的组存储在 users 表的 group 列中。每次连接时,ESX 都会自动将玩家加入 group.<玩家的组>。因此请在玩家已连接的情况下,在 Live Console 或游戏中使用专用命令更改组:
setgroup 1 admin这里的 1 是玩家在会话中的编号。
QBCore
QBCore 使用 god、admin 和 mod 级别。要获得持久的权限,请将许可证放入 permissions.cfg:
add_principal identifier.license:PLAYER_LICENSE qbcore.god游戏内命令 /addpermission 1 god 作用于 player.1:玩家一断开连接,该权限就会丢失。
txAdmin
txAdmin 界面的账户与 ACE 相互独立。其权限在 Admins 中管理,并存储在 admins.json 中。因此,将 group.admin 授予某位玩家并不会让其获得 txAdmin 的访问权限,反之亦然。
撤销权限
请删除 permissions.cfg 中的相应行,否则该权限会在下次启动时恢复。仅删除一行并不足以影响当前运行的服务器,因为规则仍保留在内存中。请同时在 Live Console 中输入:
remove_principal identifier.license:MODERATOR_LICENSE group.moderator
remove_ace group.moderator command.say allow然后使用 test_ace 进行检查。您也可以重启服务器,这样将只从文件重新开始。
要完全撤销您的更改,请从 CFG Editor 中删除 exec permissions.cfg 这一行,必要时还原副本 server.cfg.before-permissions,然后重启服务器。
故障排除
Access denied for command
消息 Access denied for command xxx. 会根据上下文指出谁没有权限:
- 某位玩家运行了该命令:使用
test_ace identifier.license:... command.xxx测试其标识符。 - 它出现在资源启动时,或没有玩家操作时:是资源没有权限。请添加
add_ace resource.name command.xxx allow。
对于 ESX,关于 add_principal 或 remove_principal 的消息通常表示配方中的 add_ace resource.es_extended ... 行已被删除。
No such config file: permissions.cfg
文件不在服务器文件夹中,或名称不同。它必须位于 server.cfg 旁边,并且 fivem 用户可读。如有疑问,请修正所有者:
sudo chown fivem:fivem /home/fivem/txData/FOLDER_NAME.base/permissions.cfgAccess type needs to be 'allow' or 'deny'
add_ace 或 remove_ace 这一行写错了。其格式是 add_ace principal 对象 allow,后面不能再有其他词。
test_ace 返回 true,但玩家没有访问权限
- 请在其资料页的 IDs 选项卡中,确认使用的是同一个标识符。
- 如果其连接时 Discord 未打开,请勿使用
identifier.discord:请优先使用许可证。 - 请确认该命令的运行方式与您设想的一致。菜单或脚本可能在 ACE 之外应用自己的检查。
deny 没有拦住玩家
该玩家很可能被其另一个标识符授权了。请使用 list_principals 查找这些标识符,然后将其从相关的组中移除。
重新连接或重启后权限消失了
该权限是通过 player.N 授予的,或者仅在控制台中输入过。请使用 identifier.license:... 将其添加到 permissions.cfg。
已从文件中删除的权限仍然有效
已加载的规则在重启之前一直有效。请使用 remove_ace 或 remove_principal,或者重启服务器。