跳转到指南

文档 9.6.24

框架设置

启用集成前检查实际使用的框架与背包资源。

QBCore 与 ESX#

仅支持特定表结构和索引字段。缺失列或自定义标识可能导致请求被拒绝。空响应或不支持并不代表数据库为空。

自定义流程#

在测试服验证角色选择、工作、传送和车库。权限必须由服务器验证，仅可信服务器代码可授予有限豁免。

分别识别框架与背包#

确认管理玩家状态的资源：qb-core、qbx_core 或 es_extended，再核对背包资源与 API 改动。框架名称相同不代表所有第三方银行或背包脚本兼容。保留正常依赖顺序，不要为排错同时运行互相冲突的 core。

修改现有字段：QBCore 使用 qb，Qbox 使用 qbox；这是配置值而非文件夹名称，auto 可自动检测。在启动输出及服务端 GetStatus 中核对实际模式。桥接单独识别已启动 core，状态可能指出缺失依赖。

-- 修改现有字段，不要替换整个表。
ts.Framework.framework = "qb"
-- 其他支持的值： "esx", "qbox", "auto", "standalone"

核对角色数据#

QBCore/Qbox 读取使用 citizenid，ESX 使用 identifier。临时服务器 ID 不能替代持久角色 ID。需要支持的列与索引，自定义结构可能被拒绝。

  1. 使用现金、银行、职业和车辆已知的测试角色，对比面板与游戏。
  2. 运行 ox_inventory 时对比小规模在线背包；注意截断，不要期待 stash 或任意 metadata。
  3. API 失败时检查启动与版本。武器检查把不可用 API 视为未知，不会当成未拥有武器的证明。

测试真实玩法#

自动识别无法知道每个自定义事件的权限、位置、价格或奖励规则，脚本必须在服务器验证。选择配置档不会自动修复不安全的资金或物品事件。调用集成前检查服务器 source 与有效会话。

Standalone/vRP 可使用合适的通用检查，但桥接不保证其自定义角色及经济结构。说明不支持的功能，不要换用无关表。更新 core、背包或职业脚本后重新验证。

记录每次测试的 core 和背包版本。core 重启后先重新连接测试角色再判断在线 API。不要同时改变数据库结构和 AC 处罚，分开修改才能定位原因并恢复正常配置。

  • 角色切换及复活不会留下永久豁免。
  • 房屋、车库与监狱传送在移动前立即调用 MarkTeleport。
  • 没有背包物品的竞技场武器由可信服务端资源短期调用 AllowWeapon。
  • 提高处罚前，核对警察操作、管理工具、商店和合法大额奖励日志。

正确理解配置名称和检测到的核心名称#

AC 配置和数据库连接器可能用不同标签描述同一安装：QBCore 的配置值为 qb，桥接健康状态却显示 qbcore。Qbox 使用 qbox，对应已启动的 qbx_core。应在各自上下文中理解这些名称，不要为匹配文件夹而改名。自动设置也能识别 vrp 或 ox_core 并选择相应标签，但不会因此为数据库桥接创建受支持的角色或经济适配器。对于不受支持的核心，明确采用 standalone 进行通用防护，有助于避免将检测名称误解为完整集成承诺。

  1. 检查 configs/anticheat_config.lua 与实际运行的核心，保留明确的一种选择和现有依赖顺序。
  2. 面板能力不同先查看运行中的核心资源及桥接健康状态，不要盲目修改 AC 配置标签。
  3. 不要只为获得另一个状态名称而同时启动 qb-core、qbx_core 或 es_extended。

按真实角色建立验收测试矩阵#

分别测试普通玩家、警察或其他职业以及员工。员工可能具有合法 AC 豁免，因此基础流程也必须使用普通角色验证。涵盖加入、角色选择、死亡与复活、房屋移动、车库、库存武器及服务器实际职业奖励。每个操作记录预期位置、物品或账户结果和观察日志。菜单与脚本活动不仅要测试成功完成，也要测试取消。资源正常启动不能证明修改过的库存、银行脚本或角色选择器符合该集成预期的 API。

  1. 核心或库存更新前后执行同一组小规模测试，一次只改变一个组件。
  2. 失败时记录核心与库存版本、调用资源及玩家角色，并保护身份数据。
  3. 重启或切换角色后重新连接，确认临时豁免结束，不要仅测试有豁免的员工流程。

明确自定义脚本的责任#

将检测配置与游戏脚本拥有的业务规则分开。AC 无法自动知道自定义转账允许的收款人、职业奖励上限或房屋主人。对应资源必须在修改金钱、物品或位置之前验证玩家、权限和服务器状态。库存武器检查使用受支持的 API；API 不可用代表结果未知，不能证明非法生成武器。角色查询因列或索引不同而失败时，应独立调查结构兼容性。不要因集成错误惩罚玩家，也不要用广泛白名单代替缺失适配器。

  1. 为框架或库存适配器指定维护人员，并为每个自定义操作明确负责人。
  2. 通过游戏脚本自己的验证，复现一次正常授权操作和一次权限拒绝路径。
  3. 将通用 AC 防护和面板数据库桥接（Tosun Connect）分开；自定义表需要经过审查的集成工作。

分别读取武器库存与角色详情#

框架和库存提供者可能不同：QBCore 管理角色与金钱，ox_inventory 提供物品。武器拥有检查优先使用运行中的 ox_inventory，否则采用支持的 QBCore/Qbox 或 ESX API。面板角色详情是另一桥接操作。一个页面看到物品，不能证明全部武器检查在同源、同时间、同格式读取。改变框架标签不会同步自定义武器库。

ESX loadout 武器记录与物品库存数量是不同概念。nil、错误或异常 API 数据不证明不存在。验证支持的方法，记录发放时间、正常玩家动作、库存提供者与结果。审核过的 AllowWeapon 可在必要范围覆盖服务器合法发放的非库存武器。这是兼容性检查，不表示全部检测缺陷已经修复。

核心迁移不只是重命名表#

QBCore 与 ESX 迁移并非仅改标签。桥接在 QBCore 使用 players/citizenid，在 ESX 使用 users/identifier。旧会话号或显示名不标识迁移角色。金钱、车辆所有者、库存和规则可能不同。不要仅为查询通过而改生产表名；数据迁移属于游戏服务器自己的计划，AC 不是丢失数据转换工具。

在独立测试环境选择已知角色及车辆。小范围读取前记核心、持久身份、cash/bank 与在线状态。表结构或索引错误不证明数据丢失，由维护者评估兼容。面板余额修改默认开启，迁移验收前不要使用；如需从技术上禁止，使用手动模式：在 server.cfg 中写入 set tosun_db_bridge_manual "1" 和 set tosun_db_bridge_enabled "1"，不要设置 tosun_db_bridge_money_write。重新测试角色选择和正常库存。看到正确数据属于正确角色才验收，不以资源启动代替。