跳转到指南

文档 9.6.24

数据库与桥接

桥接使用现有 oxmysql 连接，无需在面板输入游戏数据库密码，也无需向公网开放 MySQL。

支持的读取内容#

每台服务器的连接默认开启，无需 server.cfg 行。要对某台服务器关闭，请在服务器页面打开该服务器，在 Tosun Connect 卡片上点击“Disable connection”；在同一卡片上可重新开启。若 server.cfg 中有 set tosun_db_bridge_manual "1"，tosun_db_bridge_enabled 和 tosun_db_bridge_money_write 将照旧从 server.cfg 读取，未设为 "1" 的保持关闭。如果有意开启了旧版完整镜像（configs/anticheat_config.lua 中 ts.panelMirror.enabled = true），桥接会自动保持关闭，以便旧镜像继续工作。受支持的 QBCore/ESX 结构可提供指定玩家、背包、车辆和日志数据。这不是完整数据库浏览器。

有限查询与余额编辑#

空闲时约每 10 秒通过 HTTPS 检查面板，不查询游戏数据库。每页最多 25 条结果，同时只处理一个任务。在线余额编辑（在面板中设置在线角色的现金或银行总额）默认开启。仅限 admin 或 owner 角色（经济权限）的面板用户使用。角色必须在线，且预期的当前余额必须一致；否则返回 stale_balance，不做任何更改。面板在发送前显示确认摘要，每个请求都会写入审计日志。该操作设置总额，而不是累加。结果不明的操作不会自动重试；请先检查游戏内余额。要在某台服务器上停止读取和余额编辑，请在 Tosun Connect 卡片上点击“Disable connection”。如需保留读取但关闭余额编辑，请使用手动模式：set tosun_db_bridge_manual "1" 和 set tosun_db_bridge_enabled "1"，不设置 tosun_db_bridge_money_write "1"。

通过现有游戏服务器连接#

桥接使用已有 oxmysql 连接。面板通过 HTTPS 队列发送受支持任务，游戏服务器在本地执行并返回选定结果。不需要把 MySQL 密码复制到网站，也不必向互联网开放数据库端口。

  1. 每个服务器的连接默认开启，使用 tosun-ac 9.6.14 及以上版本时无需手动启用。要为某个服务器关闭连接：服务器 → 该服务器 → Tosun Connect 卡片 → “Disable connection”。如果在 configs/anticheat_config.lua 中有意设置 ts.panelMirror.enabled = true 启用了旧版完整镜像，桥接会自动保持关闭，以便旧版镜像继续工作。
  2. 使用 tosun-ac 9.6.14 及以上版本时，连接不需要在 server.cfg 中添加任何行，只需保留带正确许可证的 set tosun_ac_license。旧的 tosun_db_bridge_enabled 和 tosun_db_bridge_money_write 行会被忽略，可以删除；仍在运行旧版资源包的服务器在安装新包之前仍需要这些行。在线余额修改同样默认开启，仅限 admin 或 owner 角色的面板用户使用。
  3. 允许向 admin.tosundev.com 发出 HTTPS 请求，检查控制台状态，再从面板请求小规模玩家列表。
# 在服务器控制台执行：
tosunac_db_status

只用许可证的社区网站#

社区网站通过同一个 Tosun Connect 连接读取游戏数据。如果面板中没有为该服务器填写游戏数据库设置，网站不需要 MySQL 用户、GRANT 或开放 3306 端口：玩家、封禁、反作弊检测和日志页面在打开时从游戏服务器加载数据。

此模式下，网站不能搜索、筛选、解封、添加封禁，也不能修改金钱和背包。要解除封禁，请在游戏中使用 /ts unban <banID>，或在服务器控制台使用 ts unban <banID>。每个页面都是一次新请求，约 10 秒内返回；如果游戏服务器离线，或在 Tosun Connect 卡片上关闭了连接，页面会说明原因，而不是显示空列表。

名字、职业、余额、背包和车辆型号需要游戏服务器上运行 tosun-ac 9.6.17 或更高版本。使用旧包时，部分 MySQL/MariaDB 服务器只返回角色 ID。

直接连接游戏数据库是可选的。只有需要在网站上搜索和编辑时才添加：创建一个只能从 Tosun 面板服务器 IP 地址连接的数据库用户（可向支持确认该地址），授予其对游戏数据库的 SELECT、INSERT、UPDATE 和 DELETE 权限，只对该地址开放 3306 端口，然后在“服务器”中该服务器的数据库设置里填写（Direct MySQL · Advanced）。面板只有在连接测试成功后才会保存。未填写这些信息时，继续使用只需许可证的设置。

  • 玩家：每页 25 个角色，显示角色 ID、名字和职业。管理团队还能看到现金和银行余额。
  • 管理团队（版主及以上）可以点击角色查看在线状态、余额和背包，并加载该角色的车辆。
  • 封禁和反作弊检测：每页 25 条记录，只读。检测记录从最早到最新排列；封禁按封禁 ID 排序。
  • 仪表盘上的玩家、封禁和检测总数显示“—”：该连接没有计数操作，因此不会估算数字。

了解可读取的数据#

支持玩家列表、单个角色详情、该角色车辆、封禁和检测日志。QBCore/Qbox 通常使用 players 与 player_vehicles，ESX 使用 users 与 owned_vehicles。所需列和索引必须符合支持的结构。ready 心跳不代表任意自定义表都能读取。

背包仅返回选定物品字段，限制保存数据的读取量，最多遍历 100 个条目。任意 metadata、stash 仓库和所有自定义表不会整体镜像。截断的背包是部分结果，未显示物品不能证明玩家没有该物品。完整调查应使用游戏背包系统提供的工具。

判断状态与负载#

空闲时约每十秒通过 HTTPS 轮询面板，不读取游戏数据库。同一时间只运行一个任务。列表每页最多 25 条并使用游标，应翻到下一页而非反复刷新第一页。请求过的表结构元数据缓存五分钟。

  • oxmysql_unavailable：检查启动顺序和已有数据库连接。
  • unsupported_framework / schema_unavailable：检查真实框架、表与列是否受支持。
  • unsupported_index：让数据库维护者核对所需键与索引，不要在繁忙服务器盲目加索引。
  • request_expired / 状态过期：再次读取前检查网络与请求时间。

谨慎修改余额#

在线余额修改默认开启。拥有 admin 或 owner 角色（经济权限）的面板用户，可在查看确认摘要后设置受支持在线角色的现金或银行余额。操作把余额设为指定最终值，不是每次重试增加相同金额。执行前会核对预期旧余额；不一致时返回 stale_balance，不做任何修改。每个请求都会写入审计日志。

不会退回使用离线 SQL 更新。结果不明的操作保留记录，以阻止自动重复。只需查看数据的人员不要授予 admin 或 owner 角色。要在某个服务器停止余额修改，可在其 Tosun Connect 卡片点击“Disable connection”（读取也会停止），或使用手动模式 set tosun_db_bridge_manual "1"：此时 tosun_db_bridge_enabled 与 tosun_db_bridge_money_write 从 server.cfg 读取，未设为 "1" 的项保持关闭。

  1. 读取角色与当前余额，确认最终金额，只操作一次。
  2. 出现 stale_balance 时重新读取并判断，玩家可能刚刚获得或消费资金。
  3. 出现 unknown_outcome 时停止，核对实时余额和审计记录；没有确认首次结果前不要再次写入。

区分已保存的列表与在线角色详情#

玩家列表来自已保存的角色记录，并不是持续实时流。打开角色详情时，受支持框架的在线余额可替换已保存的余额；条件允许时还会读取该玩家当前的 ox_inventory 物品。应按持久 character_id 选择角色，而不是记住某次连接的服务器编号。在面板上先关注余额不可用提示与库存不完整警告，再解释零值或认定列表完整。开发人员可查看对应的 balance_available 与 inventory_truncated 标志。字段不可用或列表不完整不能证明金钱或财产丢失。车辆结果仅包含选定的存储字段，不能证明车辆当前已生成或属于某个正在进行的车库会话。

  1. 在记录好的时间，将一个已知角色的详情与游戏对照，包含在线状态和所选账户。
  2. 数据不同先核对角色身份、查询的是列表还是详情以及可用性标志，再决定行动。
  3. 重新连接或切换角色之后重新请求详情，避免复用上个角色的结果。

逐页调查，不请求整个数据库转储#

面板队列每个服务器最多允许三个待处理或已领取请求，每分钟最多十二个新请求。任务有效期为 120 秒；结果是临时数据，任务过期五分钟后才达到清理条件，而非保证在固定时刻删除。限制用于定向管理，而非自动收集整个数据库。面板用户应使用下一页控件；开发人员只在相同操作和角色上下文中使用 has_more 与 next_cursor。下一页为空和查询失败是两种情况。系统会检查唯一键与车辆所属者索引，让不兼容结构可以安全拒绝。不要只为消除错误就重命名生产列或新增索引，先评估应用和查询计划。

  1. 面板中每次读取一页。自定义集成将游标与操作一同保存，只有 has_more 为真才继续。
  2. 遇到 queue_full 或 rate_limited 时等待现有工作完成，不要重复打开同一视图。
  3. 请数据库维护人员先在副本上分析 unsupported_index；结构元数据可能仍缓存五分钟。

暂停访问时保留结果不明的操作记录#

仅检查数据时只授予需要的读取权限；只有 admin 和 owner 角色可以修改余额。要停用某个服务器的连接，打开 服务器 → 该服务器 → Tosun Connect 卡片并点击“Disable connection”；该服务器的所有读取和余额修改都会停止，之后可在同一卡片重新开启。如需保留读取但关闭余额修改，可使用手动模式：在 server.cfg 中添加 set tosun_db_bridge_manual "1" 和 set tosun_db_bridge_enabled "1"，tosun_db_bridge_money_write 不设置或设为 "0"。手动模式下这两个值从 server.cfg 读取，未设为 "1" 的项保持关闭；因此只开启手动模式而不设置 set tosun_db_bridge_enabled "1"，读取也会停止。面板会把待处理或已领取任务标记失败；已领取的余额写入会标记 unknown_outcome，因为其效果可能已经发生。因此游戏端操作账本不是可以随手删除的缓存。为强制重试而删除 KVP，可能丢掉防止重复操作的证据。也应审查取得的玩家数据权限：桥接不会让公开分享的截图或支持日志自动变成私有。

  1. 计划断开之前让读取完成，并以当前余额和审计记录调查所有未明确的金钱结果。
  2. 关闭后确认面板状态及 tosunac_db_status；不要把新排队的检查显示为已成功。
  3. 在卡片上重新开启后先执行一次读取；权限、能力与此前不明操作完成审查前不要修改余额。
# Server console / Sunucu konsolu:
tosunac_db_status

检查表结构，不修改玩家数据#

遇到 schema_unavailable 或 unsupported_index 时，先确认当前选择的数据库确实是游戏正在使用的数据库。以下示例只读取字段名称和类型，不会修改余额、背包或车辆记录。这不是安装必须执行的步骤。调查结构错误时，获得授权的数据库管理员可以在现有的私有数据库工具中运行。不要把 SQL 文本提交给面板桥接接口；桥接只接受预定义操作。

QBCore/Qbox 玩家读取需要 players 表中的 citizenid、money、job 和 charinfo；ESX 需要 users 表中的 identifier、accounts 和 job。存在表并不代表完全兼容。角色键的类型必须受支持，并且具有完整长度、单列的唯一索引。

车辆读取还会检查与车主和车辆键匹配的索引布局，避免强行执行高成本查询。不要为了消除错误而重命名自定义车库表；先让框架和车库开发者评估兼容性。

  • 记录错误代码、框架版本和受影响的读取操作。
  • 比较字段和索引，不要在支持请求中附带玩家数据行。
  • 先在测试副本评估必要的变更。桥接的结构缓存可能不会立即识别新结构。
SELECT TABLE_NAME, COLUMN_NAME, COLUMN_TYPE
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
  AND TABLE_NAME IN ('players', 'users', 'player_vehicles', 'owned_vehicles')
ORDER BY TABLE_NAME, ORDINAL_POSITION
LIMIT 128;

角色可以打开，但车辆列表为空#

例如，从玩家列表选择的角色能正常打开详情，但车辆列表为空。首先区分成功完成的结果和失败任务。成功的空列表表示这次读取没有返回匹配记录，并不能证明该玩家在所有系统中都没有车辆。query_failed、schema_unavailable 或 unsupported_index 都不能当作空列表处理。

确认选择使用的是同一个永久 character_id。重新连接后可能变化的会话编号不能代替角色键。QBCore/Qbox 通过 player_vehicles.citizenid 匹配车主，ESX 通过 owned_vehicles.owner 匹配。如果自定义车库使用另一张表或不同的车主格式，标准桥接不会自动发现这些记录。

多角色账户选择错角色也会出现类似现象。请获得授权的车库管理员核对一辆已知车辆在游戏端的记录上下文。诊断时不需要通过桥接修改余额、重新生成车辆或清空原始表。

  • 记录服务器 ID、已脱敏的角色引用、操作时间和任务状态。
  • 如果还有下一页，继续使用同一角色上下文；不要把 cursor 转给其他角色。
  • 向支持说明收到的是成功的空结果还是具体错误代码，并去除玩家个人信息。

区分数字、文本与无法取得的字段#

桥接并非原样显示数据库中的整行记录，而是将受支持的字段规范为指定类型与长度。角色余额从 JSON 数值读取。例如，1200 与带引号的 "1200" 属于不同的存储类型；如果自定义脚本把金额字段改成文本，余额数据可能无法读取。余额不可读取时，面板显示 —；这不表示余额为零。背包结果选取名称、标签、数量、槽位与质量等字段，不涵盖任意 metadata、stash 内容或企业账户。

燃油、发动机与状态等选定车辆值可能以文本返回，不要仅根据显示格式做数值比较。角色键支持的 char/varchar 定义长度 <=96；传输的文本键还受 96 字节限制，多字节字符的字符数与字节数不同。也支持 int、bigint 和 mediumint；不要假定自定义二进制键属于标准格式。长文本与背包结果可能被截断，未显示的信息并不等于已删除。排查缺失字段前，先请开发者确认真实来源的格式。如果确实需要转换类型，应在测试环境中对照游戏的数据约定评估，而不是为了填满页面就修改生产数据。

用具体结果验收余额写入#

假设在获得授权并批准的更正中，需要把一位在线角色的现金从 1200 调整到 1250。目标最终余额是 1250；输入 50 会把余额设为五十，而不是增加五十。检查选中的是现金还是银行账户，并用最近的实时详情核对永久角色身份。确认摘要应显示角色、账户，以及当前总额到新总额的变化。金额要求为非负整数，表示最终余额；自定义货币与企业余额不能套用这个操作。

任务进入队列时，验收尚未完成。确认已完成结果对应同一角色和账户，并显示 before=1200 与 after=1250，再通过一次普通角色读取检查当前状态。玩家后续支出可能让这次读取得到不同余额；已经完成的结果不能成为自动重发的理由。遇到 stale_balance，应调查已过时的余额假设；遇到 unknown_outcome，应调查尚未确认的实际影响。保留请求标识、时间和已脱敏的结果摘要。结果不确定时，不要发起新的写入；应先重新核实实际余额与计划进行的更正。

响应时限不会取消 SQL#

SQL 响应默认等待 5,000 毫秒。query_timeout 只结束面板的等待，实际查询可能仍在运行。在第一次真正的回调到达之前，SQL 容量一直被占用，此时再次读取会返回 query_busy。迟到的响应不会改变之前的显示结果。如果始终没有回调，时限也不会自动释放容量。服务器管理员应检查连接和数据库；重新启动资源并不能证明 SQL 已被取消。

只有服务器所有者可以按需在 server.cfg 中添加下面的 set 行。该值限制在 1,000–10,000 毫秒之间；无效或无穷大的数字按 5,000 毫秒处理。此设置不会加快 SQL，也不会自动重试查询。

对于具有 admin 或 owner 角色（经济权限）的面板用户，在线余额编辑默认开启；在手动模式（set tosun_db_bridge_manual "1"）下，除非 tosun_db_bridge_money_write 为 "1"，否则保持关闭。它需要受支持的在线角色，并需在面板中确认。该操作在核对预期的当前余额后，只替换现金或银行总额；绝不会退回到离线 SQL 写入。unknown_outcome 或连接不确定的情况绝不会自动重试。再次写入前，请检查实时余额和审计记录；不要为了强制重试而删除不确定操作的 KVP 记录。

set tosun_db_bridge_query_timeout_ms "5000"

只导入一个 SQL，并选对数据库#

新版 ZIP 仅通过 tosun-ac/INSTALL.sql 导入 SQL，不要再导入相同结构的旧第二份文件。目标是 FiveM/oxmysql 的游戏数据库，而非租用网站的账户、主题数据库。安装程序先补齐旧表缺失字段，再添加默认值，保留已有封禁和自定义设置。

  1. 先备份游戏数据库，并确认 oxmysql 使用的库名。
  2. 在 HeidiSQL/phpMyAdmin 仅导入 INSTALL.sql；使用 mysql 时明确指定目标数据库。
  3. tosunac_db_check 检查查询，tosunac_db_status 显示桥接状态。桥接默认开启，无需在 server.cfg 中添加任何行。在手动模式（set tosun_db_bridge_manual "1"）下未设置 tosun_db_bridge_enabled "1"，或有意启用了旧版完整镜像（configs/anticheat_config.lua 中的 ts.panelMirror.enabled = true）时，enabled=false 属于正常；输入许可证不会自动建立 MySQL 连接。
  4. 面板连接（Tosun Connect）和在线余额编辑默认开启。不要在 server.cfg 中添加 tosun_db_bridge_enabled 或 tosun_db_bridge_money_write；从 9.6.14 版安装包起，旧的这两行会被忽略，可以删除（更早的安装包在更新到当前安装包之前仍需要这两行）。只有身份为 admin 或 owner 的面板用户可以设置余额：游戏角色必须在线，预期余额必须一致（否则返回 stale_balance，不做任何更改），面板发送前会显示确认摘要，每个请求都会写入审计日志，结果不确定时不会自动重试，请先在游戏内核对余额。此操作设置总额，不是累加。要对某台服务器关闭整个连接（这会停止该服务器的所有面板读取和余额修改）：面板 → 服务器 → 选择服务器 → Tosun Connect 卡片 → Disable connection；之后可以在同一张卡片上重新开启。数据库密码留在游戏服务器。
mysql -u YOUR_DB_USER -p YOUR_GAME_DATABASE < tosun-ac/INSTALL.sql

# txAdmin console:
tosunac_db_check
tosunac_db_status