文档 9.6.24

分步安装

从空服务器到防护生效并连接面板，大约需要 20 分钟。每一步结尾都有检查项；如果检查不通过，先修复再继续。

开始之前#

开始前请确认以下条件已准备好。

较新的 FiveM 服务器版本（artifact），并已开启 OneSync（set onesync on）。没有 OneSync，大部分服务端检测无法工作，反作弊启动时也会给出警告。
已安装并运行 oxmysql。反作弊只通过 oxmysql 访问数据库，从不需要单独的 MySQL 密码。
一个面板账户，且所用套餐包含下载权限。
数据库和 resources 文件夹的备份。更新时，还要单独保存 configs、admins、editable、locales 和 bridge 文件夹。
能向服务器上传文件的方式（FTP、txAdmin 文件管理器或远程桌面），以及执行 SQL 的工具（HeidiSQL 或 phpMyAdmin）。

1. 在面板中添加服务器#

许可证密钥只属于一台服务器，所以安装从在面板中添加这台服务器开始。

在客户面板中打开“服务器”页面，点击“添加服务器”。
填写服务器名称，选择框架（QBCore、Qbox 或 ESX）和背包脚本。
在“数据库连接”中，保持选择“通过脚本连接”。这种模式不需要 MySQL 密码，也不需要对外开放数据库端口。
保存后打开该服务器，复制“许可证密钥”卡片上的值。如果你有多台服务器，每台使用各自的密钥。
检查：服务器已出现在列表中，并且你已复制它的许可证密钥。

2. 下载服务器安装包#

安装包在下载时为所选服务器单独生成，可能需要几秒钟。

安装包包含 tosun-ac（主资源，必需）、tosun-ac-guardian（防止反作弊被停止的小型资源，建议安装），以及在包含时提供的 tosun_render（证据视频组件）。tosun-ac 文件夹中还有 INSTALL.sql（创建全部数据表的单个 SQL 文件）、KURULUM.txt（简短的安装说明）和 INTEGRATION.md（面向其他脚本的集成指南）。

下载新安装包不会更新正在运行的服务器。在放入文件并重启资源之前，什么都不会改变。

进入面板的“下载”页面。
选择你的服务器，点击“下载”。
把 ZIP 文件解压到电脑上的一个文件夹。

3. 放置文件#

在服务器的 resources 文件夹中新建一个名为 [tosun] 的文件夹。在 FiveM 中，方括号文件夹只用于给资源分组。把 tosun-ac、tosun-ac-guardian 以及（如果包含）tosun_render 文件夹复制进去。

不要重命名这些文件夹。其他脚本通过 exports['tosun-ac'] 调用反作弊，Guardian 也按 tosun-ac 这个名称进行监视；改名会导致集成和防护失效。

不要删除文件夹中的文件。安装包完整性检查会发现缺失或被修改的文件。

resources/
  [tosun]/
    tosun-ac/
    tosun-ac-guardian/
    tosun_render/

4. 创建数据表#

反作弊把封禁、检测记录、日志和设置保存在你的游戏数据库中。请在 oxmysql 连接的数据库里创建这些表，也就是存放框架数据表的同一个数据库。

INSTALL.sql 不会删除你的数据。数据表使用 CREATE TABLE IF NOT EXISTS 创建，已有的表会保持原样。

oxmysql 使用的数据库用户需要对该数据库拥有 CREATE 和 ALTER 权限。如果你的共享主机不允许，请自己在主机控制面板中执行该 SQL。

备份数据库。
在 HeidiSQL 中选中游戏数据库，通过 File → Load SQL file 打开 tosun-ac/INSTALL.sql 并执行（F9）。在 phpMyAdmin 中使用“导入”选项卡。
如果你更习惯命令行，使用下面的命令。
确认 ts_anticheat、ac_detections 和 admin_logs 表已经存在。

mysql -u USER -p DATABASE_NAME < INSTALL.sql

5. 为旧版安装补充缺失的列#

如果你从旧版本升级，数据表已经存在，但可能缺少新版的列。如果控制台出现 Unknown column 'log_message' in 'field list' 之类的错误，请先备份数据库，再执行下面的命令。它们只添加缺失的列，不会改动已有数据。

这段语法适用于 MariaDB。MySQL 8 在这里不支持 IF NOT EXISTS：先用 SHOW COLUMNS FROM admin_logs; 列出现有的列，再用 ADD COLUMN 只添加缺失的列。

如果错误仍然存在，admin_logs 表可能属于其他脚本。请把 SHOW CREATE TABLE admin_logs; 的输出发给客服。

ALTER TABLE admin_logs
  ADD COLUMN IF NOT EXISTS log_message LONGTEXT NULL,
  ADD COLUMN IF NOT EXISTS log_playerid LONGTEXT NULL,
  ADD COLUMN IF NOT EXISTS log_playername LONGTEXT NULL,
  ADD COLUMN IF NOT EXISTS log_type VARCHAR(20) NOT NULL DEFAULT 'LOG',
  ADD COLUMN IF NOT EXISTS log_date TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  ADD COLUMN IF NOT EXISTS created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP;

ALTER TABLE ac_detections
  ADD COLUMN IF NOT EXISTS player_id INT NULL,
  ADD COLUMN IF NOT EXISTS player_name VARCHAR(100) NOT NULL DEFAULT '',
  ADD COLUMN IF NOT EXISTS license VARCHAR(100) NULL,
  ADD COLUMN IF NOT EXISTS steam VARCHAR(50) NULL,
  ADD COLUMN IF NOT EXISTS discord VARCHAR(50) NULL,
  ADD COLUMN IF NOT EXISTS ip VARCHAR(40) NULL,
  ADD COLUMN IF NOT EXISTS detection_type VARCHAR(60) NOT NULL DEFAULT '',
  ADD COLUMN IF NOT EXISTS detail TEXT NULL,
  ADD COLUMN IF NOT EXISTS reason VARCHAR(512) NOT NULL DEFAULT '',
  ADD COLUMN IF NOT EXISTS punishment VARCHAR(10) NOT NULL DEFAULT 'LOG',
  ADD COLUMN IF NOT EXISTS ban_id VARCHAR(20) NULL,
  ADD COLUMN IF NOT EXISTS screenshot VARCHAR(512) NULL,
  ADD COLUMN IF NOT EXISTS config VARCHAR(100) NULL,
  ADD COLUMN IF NOT EXISTS config_key VARCHAR(100) NULL,
  ADD COLUMN IF NOT EXISTS server_id INT NULL,
  ADD COLUMN IF NOT EXISTS created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP;

6. 配置 server.cfg 和基本设置#

把下面几行添加到 server.cfg。set 行必须放在 ensure 行之前，因为资源会在启动时读取这些值。oxmysql 和你的框架必须在反作弊之前启动。

把 qb-core 换成你的框架资源（qbx_core 或 es_extended）。只有安装包中包含 tosun_render 时才添加这一行。

tosun_ac_license 是唯一必填的设置。面板数据连接和在线角色余额修改默认开启，无需为它们添加任何配置行。旧的 set tosun_db_bridge_enabled 和 set tosun_db_bridge_money_write 行从 9.6.14 版安装包起会被忽略，可以删除。更早的安装包仍需要这些行才能开启连接，所以请从面板下载当前安装包。

可选设置：tosun_ac_panel_key（站点设置 → AntiCheat API 密钥；留空时，反作弊会自行从数据库中找到该密钥）和 tosun_ac_central_token（在“AC API 令牌”页面创建的、组件为 fivem 的令牌；留空时使用面板密钥）。

许可证和各类密钥只能用 set 设置。setr 会把值发送给玩家，sets 会把值公开到服务器列表中。不要把密钥写进 configs/anticheat_config.lua，因为这个文件也会发送给玩家。除了 server.cfg，你也可以使用 configs/anticheat_server.lua 中的 credentials 表，它只在服务端加载；两边都填写时，以 server.cfg 为准。

ts.Framework.framework：保持 "auto"；QBCore、Qbox 和 ESX 会被自动识别。如果识别失败，设为 "qb"、"qbox"、"esx" 或 "standalone"。
ts.punishType：第一天使用 'LOG'，只记录检测结果；在面板中检查无误后，再改为 'BAN'。
ts.Debug：保持 false。开启后所有人都会被检测，包括管理人员。
webPanelKey、Central.token 和 licenseLock.licenseKey 字段保持为空。

set onesync on

set tosun_ac_license "YOUR_LICENSE_KEY"

ensure oxmysql
ensure qb-core
# ... 你的其他框架和背包资源 ...
ensure tosun_render
ensure tosun-ac
ensure tosun-ac-guardian

7. 授予管理人员权限#

管理人员不会被检测，并且可以打开游戏内管理菜单。推荐在 server.cfg 中使用 ACE 权限。

tosun.admin 包含管理菜单和检测豁免；tosunac.admin 允许在游戏内执行 tosunac_setup。把 license 的值换成你自己的。

也可以把 license:、steam: 或 discord: 标识符添加到 tosun-ac/admins/anticheat_admins.lua 的 Admins 列表中，或者在面板中授予权限。

只是 txAdmin 管理员的人不会被检测，但无法打开游戏内菜单；菜单需要上述任一方式授权。

在游戏中用 /ts 或 /tsmenu 打开菜单，或按 F7。可以通过 ts.AdminMenu.openKeyControl 修改按键。

add_ace group.admin tosun.admin allow
add_ace group.admin tosunac.admin allow
add_principal identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx group.admin

8. 首次启动与验证#

首次安装时，请重启整个服务器，而不只是重启资源，这样启动顺序的问题会立即暴露出来。

重启服务器，检查控制台中是否有红色的 tosun-ac 错误。
在服务器控制台执行 tosunac_doctor，它会列出有风险或相互冲突的设置。
执行 tosunac_db_status 检查面板数据连接，执行 tosunac_integration 检查与其他脚本的连接。
确认控制台中出现 [AC-Guardian] Aktif 这一行。
如果确定服务器是干净的，执行 tosunac_setup。它会先扫描后门，然后把干净的资源和服务器的事件加入允许列表。如果怀疑有资源被感染，不要执行：它会把当前状态视为可信。

面板中服务器显示为在线，玩家人数会更新。
用管理人员账户进入游戏后，/ts 可以打开菜单。
面板的日志区域出现新的记录。
用普通账户游玩 10-15 分钟后，面板中没有意外的检测记录。

tosunac_doctor
tosunac_db_status
tosunac_integration
tosunac_setup

9. 检查面板数据连接#

此连接默认开启，无需在 server.cfg 中添加任何行，也无需在面板中开启。有权限的面板用户可以在需要时查看玩家、角色、背包、车辆、封禁和检测数据。数据库不会被复制，MySQL 密码留在你的服务器上。该连接只读取数据，唯一的例外是下文介绍的在线角色余额修改。

每页返回 25 条记录，同一时间只处理一个请求，每次响应最大 64 KB。空闲时，该连接不会对游戏数据库执行任何查询。支持标准的 QBCore、Qbox 和 ESX 数据表；自定义表不会自动映射。

余额修改同样默认开启，只有身份为管理员或所有者（经济权限）的面板用户可以使用。它不是在原有余额上增加，而是把现金或银行总额设为你输入的值。角色必须在线。如果预期的当前余额不一致，请求会以 stale_balance 被拒绝，不会有任何改动。发送前面板会显示确认摘要，每个请求都会写入审计日志。结果不确定的请求绝不会自动重试；再次尝试前请先在游戏内核对余额。

如需高级手动模式，在 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），连接会自动保持关闭，以便旧镜像继续工作。

社区网站使用同一个连接。没有游戏数据库设置时，玩家、封禁和检测页面从游戏服务器读取数据，不需要 MySQL 用户或开放数据库端口。数据库与桥接 → “只用许可证的社区网站”一节说明了此模式显示的内容，以及何时值得添加可选的直接 SQL 连接。

在面板中打开服务器 → 你的服务器 → Tosun Connect 卡片。资源运行时，卡片应显示 Connection ready（连接就绪）。
也可以在服务器控制台用 tosunac_db_status 检查连接状态。
如需为某台服务器关闭连接，在同一张卡片上点击 Disable connection（停用连接）。这会停止该服务器的所有读取和余额修改。之后可以在同一张卡片上重新开启。

10. 让其他脚本兼容#

传送玩家、发放武器或冻结玩家的脚本，如果不通知反作弊，可能会被当成作弊。最常见的情况及解决方法：

任何脚本都可以调用 MarkTeleport。AllowWeapon 和 SetExempt 会授予大范围豁免，所以只接受来自可信资源的调用。把使用它们的脚本名称用逗号分隔添加进去，并保留列表中已有的名称。

传送玩家（房屋、车库、监狱、医院）：在移动玩家之前调用 exports['tosun-ac']:MarkTeleport(src)。
打开会冻结玩家的短暂菜单（服装店、理发店）：exports['tosun-ac']:MarkTeleport(src, 15000)。
发放不进入背包的武器（竞技场、彩弹）：exports['tosun-ac']:AllowWeapon(src, "WEAPON_PISTOL", ms)。需要可信资源。
需要让玩家在一段时间内完全豁免（过场动画、自定义复活）：exports['tosun-ac']:SetExempt(src, ms, "reason")。需要可信资源。

set tosun_ac_trusted_resources "my-clothing,my-housing,my-arena"

11. 更新#

请在维护期间更新，并保留你自己的设置。

如果你的面板密钥以前写在 anticheat_config.lua 中，它可能已经被发送给玩家。请在面板中创建新密钥，并同步更新 server.cfg；更新本身不会吊销旧密钥。

从面板下载新的安装包。
备份服务器上的 tosun-ac 文件夹，并单独保存你在 configs、admins、editable、locales 和 bridge 文件夹中的修改。
删除旧的 tosun-ac、tosun-ac-guardian 和 tosun_render 文件夹，换成新的。直接覆盖旧文件夹会留下已被移除的文件。
把你自己的设置迁移回去。为了保留新版本新增的配置行，只迁移你改过的值，不要替换整个文件。
如果更新说明提到数据库变更，重新执行第 4 步和第 5 步。
重启服务器，并重新完成第 8 步的检查。

12. 故障排查#

最常见的症状及解决方法：

联系客服时，请提供版本号（fxmanifest.lua 中的 version）、完整的控制台错误和 tosunac_doctor 的输出。不要分享你的许可证或 API 密钥；客服不会向你索要。

Unknown column '…' in 'field list'：数据表来自旧版本。执行第 5 步中的 SQL。
Table '…' doesn't exist：没有导入 INSTALL.sql，或导入到了错误的数据库。请导入到 oxmysql 连接的数据库。
出现 oxmysql 错误，反作弊在第一秒就停止：把 ensure oxmysql 移到 ensure tosun-ac 之前。
许可证无效警告：填写了其他服务器的许可证、set 行放在了 ensure 之后，或使用了 setr。请从正确服务器的卡片上重新复制许可证。
管理菜单打不开：该用户只是 txAdmin 管理员。添加第 7 步中的 ACE 配置行，然后重新进入服务器。
无辜玩家被检测：在面板中打开该检测记录，查看是哪项检测触发，然后在相关脚本中加入第 10 步中的调用。在此期间，在面板中把该检测的处罚改为 LOG。
面板中服务器显示为离线：查看 tosunac_doctor 的输出；如果设置了 tosun_ac_panel_key，确认它与面板中的密钥一致。
无法下载安装包：查看“下载”页面上的提示；你的套餐可能不包含下载，或者还没有添加服务器。

首次以网站所有者身份登录#

在 TosunDev 选择自己的租用网站并打开网站管理。未登录时先进入登录页，成功后返回管理。通过邮箱注册的用户使用网站创建时有效的邮箱和密码；后续修改密码不一定同步到独立网站账户。

核对网站地址与选中的租用记录。
在浏览器隐私窗口验证登录和返回正确的网站管理页。
关联自己的 FiveM 服务器；网站密码、Tosun 许可证、MySQL 密码是不同凭据。
出现问题时使用账户恢复和所有权验证，不要使用共享管理员密码。

复制所选服务器的 Tosun 许可证#

在 TosunDev 的服务器页面选择自己的 FiveM 服务器，复制该记录的 Tosun AC 许可证。tac_live_ 不是 Cfx.re 许可证、sv_licenseKey、Discord Token 或面板 API 密钥，各项凭据不能混用。

将 server.cfg 中引号内的 YOUR_SERVER_LICENSE 替换为真实 Tosun 许可证。
tosun_ac_license 必须位于 ensure tosun-ac 前；只用 set，不能使用 setr 或 sets。
也可以填写 configs/anticheat_server.lua 的 credentials.licenseKey。非空 convar 优先于文件。
不要在截图、聊天、shared config 或客户端文件中公开许可证。

set tosun_ac_license "YOUR_SERVER_LICENSE"
# Alternative: configs/anticheat_server.lua
# credentials.licenseKey = "YOUR_SERVER_LICENSE"

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

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

先备份游戏数据库，并确认 oxmysql 使用的库名。
在 HeidiSQL/phpMyAdmin 仅导入 INSTALL.sql；使用 mysql 时明确指定目标数据库。
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 连接。
面板连接（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

从 ZIP 到 txAdmin 启动#

将 tosun-ac、tosun-ac-guardian、tosun_render 放在 resources 下同一层级，每个目录根部必须有 fxmanifest.lua。discord-bot 是 Node.js 应用，不是 FiveM resource。新版 Render 只声明 gta5，请勿保留 common 与 gta5 混合的旧配置。

保留正常工作的 mysql_connection_string；先启动 oxmysql 和现有框架、背包，再启动 Render、AC、Guardian。
在 txAdmin 执行 refresh，再按下面顺序启动。支持 tosun-render 别名，标准目录名仍是 tosun_render。
tosun_render_status 应显示 started 和文件可用；还需用测试玩家验证实际画面捕获。
阅读第一条错误，分别检查依赖、目录或所选服务器的许可证。

set tosun_ac_license "YOUR_SERVER_LICENSE"

ensure oxmysql
# Start your existing framework/inventory here.
ensure tosun_render
ensure tosun-ac
ensure tosun-ac-guardian

# txAdmin console:
tosun_render_status
tosunac_doctor
tosunac_db_check
tosunac_db_status

验证管理员权限及撤销#

ACE、管理员标识与面板授权在服务器端验证。all 不是标识或授权。allowedIds 必须填写来自服务器玩家标识列表的完整 license:...、discord:... 或 fivem:...。

给测试管理员最小必要权限，并验证菜单和一个允许的操作。
撤销面板授权后再次测试同一玩家；新版默认约每五秒轮询，网络延迟需单独观察。
同时检查独立的 ACE/admins.lua 授权；在线玩家遥测不是授权来源。
普通测试玩家应保持无权访问；敏感操作只使用测试数据。

ts.AdminMenu.allowedIds = {
    "license:YOUR_EXACT_PLAYER_IDENTIFIER",
    "discord:YOUR_DISCORD_USER_ID"
}
# Examples are placeholders, not grants.

单独安装包内的 Discord 机器人#

discord-bot 运行在 Node.js 上，不能用 ensure 启动。在 Discord Developer Portal 创建自己的应用，使用自己的 Application ID、Guild ID、频道和角色 ID。Token 仅保存在私有环境文件中。

租用网站的数据库账户默认仅能从服务商 localhost 连接。将机器人放在另一台 FiveM 机器不会自动开放连接。应在网站主机上运行托管服务，或使用服务商批准且仅属于自己网站账户的私有连接。不要使用服务商 root 账户，也不要公开 MySQL。需要直接查询游戏表的旧命令必须单独验证。

以站点所有者身份，在站点管理 → Discord 机器人中保存 token、Client ID 和 Guild ID。通过 Download private bot setup 下载私有文件，将其保存为自己机器人目录中的 .env。它仅包含所选站点的密钥，与 ZIP 中的空白示例不同。不要分享或提交到版本库。

安装受支持的 Node.js LTS 22 或更高版本，通过安装脚本准备示例配置。
使用 bot 和 applications.commands 范围邀请机器人，仅授予所需权限。
配置网站数据库和 HTTPS API。命令签名密钥仅属于该机器人与网站，不是 Tosun 许可证，也不能分发主 SaaS 密钥。
启动前运行 npm run doctor，全部必需检查通过后再运行。doctor 不登录 Discord；实际在线状态和角色权限需另行测试。

cd discord-bot
sh setup.sh
# Configure the private .env and site bot settings first.
npm run doctor
npm start

避免重启时重复进行昂贵分析#

每次启动都会核对资源内容的 SHA256 指纹。文件和扫描策略未变的资源会复用服务器 KVP 中经过认证的结果，不再重复昂贵的签名和事件分析。文件、例外或规则变化会使相关分析失效并重新执行。指纹检查仍需读取文件；不保证固定的 resmon 数值。

正常更新时保留 KVP 缓存；损坏或无法验证的记录会重新分析。
启动目录收集 Lua/JS 中明确声明的事件名。动态名称、不可读或 escrow 文件及 DLL 不会被认定为已完整扫描。
手动自动配置会等待安全分析完成。不完整、可疑、已变化或超时的资源不会自动获准。
在测试服务器检查玩家加入、正常游戏和管理员操作；结合玩家数量与框架负载评估 resmon。