安装

1. 准备服务器#

使用受支持的 FiveM artifact 并检查 OneSync 要求。保留正常运行的 oxmysql 连接。将 tosun-ac 解压至 resources，勿重命名。先启动框架和依赖。 反作弊首次启动需要在本地数据库创建所需表的权限。桥接无需单独导入 SQL；若缺少表，仅在备份后使用安装包附带的 SQL 文件排查。

2. 添加仅服务器可用的配置#

从服务器页面复制许可证，替换 YOUR_SERVER_LICENSE。使用 set，切勿使用 setr 或 sets。不要公开密钥或放入共享/客户端 Lua。面板数据连接（桥接）默认开启，无需在 server.cfg 中添加任何行；旧的 tosun_db_bridge_enabled 和 tosun_db_bridge_money_write 行会被忽略，可以删除。

set tosun_ac_license "YOUR_SERVER_LICENSE"
ensure oxmysql
ensure tosun_render
ensure tosun-ac
ensure tosun-ac-guardian

3. 启动并验证#

在维护窗口中先启动 oxmysql，再启动 tosun-ac。检查版本及控制台错误。桥接默认开启，无需在 server.cfg 中额外添加行。在服务器控制台运行下方命令检查其状态。请勿向支持人员发送真实密钥。

tosunac_db_status

准备可恢复的安装#

改动正在运行的服务器前，记录 artifact 版本以及框架、背包资源名称。在 Servers 中选择正确服务器后下载对应安装包，其他服务器的包或许可证可能连接到错误实例。确认付费订阅有效、账户有服务器管理权限。ZIP 应保密，不要上传公开网盘。

1. 备份现有 tosun-ac 目录、可编辑配置和游戏数据库。替换文件之前，确认备份可以读取。
2. 先解压到独立目录。fxmanifest.lua 必须直接位于 tosun-ac 中，不能再嵌套第二层同名目录。
3. 将旧配置的改动与新默认配置对照，只迁移有意保留的设置和集成，不要用旧配置完整覆盖新文件。

• 许可证与升级

设置依赖与私密参数#

保留已经正常工作的 oxmysql 数据库连接。面板数据库桥接和在线余额编辑默认开启，因此示例中没有桥接配置行。旧的 tosun_db_bridge_enabled 和 tosun_db_bridge_money_write 行会被忽略，可以删除。按实际依赖顺序加入现有框架和背包启动行，不要为照搬示例同时启动互相冲突的框架。许可证使用 set；setr 会向客户端复制值，sets 会公开服务器信息。

资源需要权限来建立自己的表。首次建表与桥接是两件事。如需为某台服务器关闭桥接，请在面板的 Servers → 该服务器 → Tosun Connect 中点击 Disable connection。如需手动控制，请添加 set tosun_db_bridge_manual "1"，此时 tosun_db_bridge_enabled 和 tosun_db_bridge_money_write 从 server.cfg 读取，未设为 "1" 的项保持关闭。不要未经核对就向已有数据的数据库导入 SQL，也不要把数据库密码或 Tosun 许可证写进 shared/client Lua。请安排维护时间：ensure 可能重启已经运行的资源。

set tosun_ac_license "YOUR_SERVER_LICENSE"

ensure oxmysql
# 在这里启动已有框架和背包资源。
ensure tosun-ac

• 官方服务器命令
• 数据库桥接

重新开放前验证正常玩法#

资源能够启动并不能证明全部集成正确。先检查 manifest 版本、启动输出和连接状态，再用测试账户进入游戏。在服务器控制台执行这些诊断命令。桥接默认开启；只有在未设置 tosun_db_bridge_enabled "1" 的手动模式下，或启用了旧版面板镜像时，出现 disabled 才属于预期。配置 doctor 会在应用设置后报告风险值，但不会修改配置。

记录版本、时间、负责管理员及验收玩法。只有某个自定义脚本失败时，用测试玩家复现并记下资源名称；先检查该集成，不要给所有玩家全面豁免或直接提高全服处罚。

• 角色选择、出生、医院复活、进房和出车库没有意外处罚。
• 正常背包武器、警察装备和竞技场武器由正确检查或限定授权处理。
• 表情道具、手机菜单和管理操作正常；日志可定位需要适配的具体资源。
• 启动失败时记录第一条相关错误及安装版本，必要时恢复备份资源。分享日志前删除所有密钥。

tosunac_integration
tosunac_doctor
tosunac_db_status

• 自定义脚本集成
• 设置与性能

只更新一个资源，避免混用两个安装包#

把更新视为具有明确前后状态的一次变更。保留 tosun-ac 文件夹名称，让现有导出调用和辅助文件路径继续指向同一资源。将 configs/anticheat_config.lua、configs/anticheat_webhooks.lua 及可编辑集成与新包逐项对比，只迁移确实需要的设置。保留服务器私有 convar 与经过审核的信任列表。从 9.6.14 起，server.cfg 中的 tosun_db_bridge_enabled 和 tosun_db_bridge_money_write 行会被忽略，因此更新后桥接以及面板管理员和所有者的在线余额编辑都会开启。如需保持桥接关闭，请在该服务器的 Tosun Connect 卡片上点击 Disable connection，或添加 set tosun_db_bridge_manual "1"；此时这些行重新生效，未设为 "1" 的项保持关闭。旧配置可能缺少新增默认值；整目录覆盖则可能让旧模块与新文件混存。启动顺序仍应是 oxmysql 和对应核心先于 tosun-ac，依赖其导出的集成随后启动。

1. 维护期间暂停新玩家加入，记录首次启动输出、实际版本以及配置差异。
2. 只保留一个活动的 tosun-ac 目录；将备份移出活动资源树，避免误启动。
3. 重启后让普通测试玩家重新连接；继续使用更新前的客户端会话不能算干净的验收。

按照具体症状选择排查分支#

从首个具体错误开始，不要一次改变多项防护。资源无法启动时，检查目录结构、manifest 和缺失依赖；已经启动但无法连接面板时，先核对服务器选择、许可证和连接状态，再调查游戏规则。Launcher 拒绝准入属于另一道检查，应查看它自己的状态。只有某个房屋、竞技场或服装脚本失败时，记录资源名称和操作，查看集成拒绝日志。员工账号可能具有豁免，所以管理员测试成功不能证明普通玩家也会获得正确处理。

1. 用普通测试角色复现一次最小失败操作，记录控制台或面板给出的准确结果。
2. 与上次正常配置下的同一流程对比，只修复相关依赖或集成，再重复该测试。
3. 分享报告前移除密钥；不要为了消除一个症状而关闭信任检查或所有检测。

恢复已知状态后重新验收#

维护前就准备回退方案。保存相互匹配的资源和配置备份、原启动顺序以及有意修改的 convar。若新版本阻碍正常加入或必要流程，在维护窗口恢复已知版本，再次验证。恢复 Lua 文件不会撤销余额修改、删除面板任务或还原数据库。不要把删除 AC 表、封禁记录或检测历史当作安装修复。涉及数据库变更时，应由维护人员制定独立恢复方案，并考虑备份之后新增的数据。

1. 先只恢复受影响的资源及配置，再检查启动、普通玩家加入和此前失败的操作。
2. 余额编辑默认开启。恢复的配置及结果不明的余额操作完成审查之前，请在该服务器的 Tosun Connect 卡片上关闭连接；再次发送修改前，先检查游戏内余额。审查完成后，在同一张卡片上点击 Enable connection 重新开启。恢复到 9.6.14 之前的包会沿用旧行为：server.cfg 中没有相应配置行时，桥接保持关闭。
3. 记录恢复内容和原因，使下次更新解决可以复现的根因，避免再次进行同样的大范围调整。

检查解压后的目录结构#

先解压到独立工作目录，检查意外的 tosun-ac/tosun-ac 嵌套、根目录 fxmanifest.lua，以及包内独立的 tosun-ac-guardian（如果提供）。不要按扩展名把文件摊平：清单按 client、shared、configs、editable、server 和 html 路径加载。配置复制到机器上但不在预期路径，仍可能不被使用。

@oxmysql/lib/MySQL.lua 错误应查依赖，而非轮换许可证；缺 html/index.html 应查 NUI 与目录。从正确包恢复缺失路径，不要混入另一版本的单个模块。存在可选 INSTALL.sql 时先对照现有表结构并备份。ZIP、准备目录和活动资源应形成清晰安装链，优先处理首个启动错误。

检查秘密在哪一侧加载#

文件名不能说明玩家会收到什么。configs/anticheat_config.lua 位于 shared_scripts，同时加载到服务器和客户端。不要在其中添加许可证、私有 API 凭据或数据库密码。client 文件与 html/NUI 也不是秘密存储。配置可读、可编辑，并不表示所有字段都适合放凭据。

检查你改过的文件。许可证只应在受保护的 server.cfg 中通过服务器 set 保存，不用 setr 或 sets。Webhook 配置使用服务器侧 configs/anticheat_webhooks.lua，截图隐藏地址。删除已分发到公开/客户端的秘密不会撤回旧副本，应评估轮换。验收记录写已检查的路径与加载侧，不写秘密值。

分阶段验收启动流程#

将维护分成四个阶段：现有数据库连接与 core、AC 启动、正常玩家流程，以及默认开启的面板桥接。确认当前阶段的结果后，再进入下一阶段。先检查正在使用的框架与背包的正常功能；另加一个 core 可能掩盖原因。随后核对正在运行的 tosun-ac 输出与已安装的包。测试普通玩家流程时，使用不享有管理员豁免的角色。面向面板管理员和所有者的在线余额编辑同样默认开启；验收桥接只需完成一次读取，不需要修改余额。

为每个阶段用一行记录时间、预期结果与实际结果。例如，角色选择成功而驶出车库失败，就回到首先出错的流程，不必重新下载整个安装包。游戏正常运行与桥接读取成功完成，是两项独立的验收结果。暂时隐藏一条消息，不能让前一个阶段通过验收。先解决缺失的依赖，再继续推进；必要阶段全部确认后，恢复正常使用。这份记录应清楚区分已经完成和仍在等待的步骤。

结合实际结果解读控制台消息#

启动时带颜色的消息并不都表示同一件事。武器或背包检查因等待受支持的背包而暂停，不是对某位玩家的作弊判定；应检查背包 provider 与 core 的状态。缺少 GetSelectedPedWeapon 的消息表示该模块无法调用所需 native，不代表所有模块都已禁用。Integration 输出中的 enforce 与 trusted 描述调用方策略，也不能证明某个游戏流程运作正常。排查应从完整消息开始，而不是只看颜色。

桥接的 Connected 消息确认健康通信已经建立；角色查询是否完成，需要另行确认。Waiting: oxmysql_unavailable 指向依赖问题，Panel unavailable or not authorized 则需要检查连接或授权。仅凭后者，不能断定许可证损坏。桥接默认开启；只有在未设置 tosun_db_bridge_enabled "1" 的手动模式下，或启用了旧版面板镜像时，状态命令显示 enabled=false 才属于预期。如果连接是在 Tosun Connect 卡片上关闭的，状态命令仍显示 enabled=true，面板也会拒绝该服务器的请求；此时最近的面板状态可能只显示 Panel unavailable or not authorized。看到这条消息时，先确认该服务器的 Tosun Connect 卡片显示连接已开启，再检查许可证和网络。向支持提供记录时，应同时保留此前出现的第一个错误、资源名称、时间及当时执行的操作。区分启动警告与针对玩家的处罚，可以让诊断更清楚。

为正确的服务器下载软件包#

登录面板，在服务器与下载页面选择同一个服务器。需要付费方案的下载权限和该服务器的管理权限。下载票据绑定会话、用户和服务器，有效期为90秒，只能使用一次。

票据过期或已使用时，请返回面板领取新票据。先保存ZIP再传到游戏服务器；下载不会自动更新正在运行的资源。URL、Bearer或X-License-Key中的许可证不提供下载权限。不要把票据或会话Cookie保存在安装脚本中。

仅在服务器保存凭据#

在server.cfg中使用set，或编辑configs/anticheat_server.lua的credentials表。非空服务器convar优先于文件；旧共享值仅用于服务器端临时迁移兼容。机密值不要使用setr或sets。

共享配置中的ts.webPanelKey、ts.Central.token及ts.licenseLock.licenseKey应保持为空。新服务器文件中的panelKey、centralToken、licenseKey可以编辑，未使用的连接保持为空。已泄露的密钥应在对应面板轮换；删除本地值不会撤销远端凭据。

set tosun_ac_license "YOUR_SERVER_LICENSE"
set tosun_ac_panel_key "YOUR_PANEL_API_KEY"
# Optional: only configure a central connection you use.
set tosun_ac_central_token "YOUR_FIVEM_CENTRAL_TOKEN"
ensure oxmysql
ensure tosun_render
ensure tosun-ac
ensure tosun-ac-guardian

诊断 Guardian 启动与主动停止#

在 txAdmin 服务器控制台先运行 tosunac_doctor，再运行 tosunac_guardian_status。ready 表示目标资源已启动；waiting_dependency 表示依赖问题；transition 表示正在启动或停止；held 表示主动临时等待。这些状态不代表游戏保护或 SQL 模式测试已通过。

先启动 oxmysql 和 tosun_render，再启动 tosun-ac，最后启动 tosun-ac-guardian。修复许可证或版本错误后才使用 resume。pause 只能由控制台执行，最长30分钟。失败的启动会受到次数限制和退避延迟。

# txAdmin server console:
tosunac_doctor
tosunac_guardian_status

# Pause only during planned maintenance; repair the reported cause first:
tosunac_guardian_pause 300
tosunac_guardian_resume

依赖就绪后检查事件发现#

EventScanner 默认30秒后启动，每小时执行；服务器控制台用 tosunac_eventscan 手动运行。tosunac_setup 是独立维护：backdoor 与签名检查完成，并确认最新指纹相同，才批准符合条件的干净已启动资源 baseline。这不证明没有 backdoor。使用已审查安装与备份。事件发现不会注册权限验证器、改写原始 handler 或授权玩家。

# txAdmin server console: event discovery only
tosunac_eventscan

未变化扫描缓存真正省去什么#

内容和分析策略未变时复用分析结果，但仍检查内容指纹，不是零磁盘工作。内容或策略变化会重新分析。Backdoor：25秒后，每30分钟；资源：20秒后，每90秒；事件：30秒后，每小时。signatureScanFirstRun 启用时，即使有旧首次运行标记也在启动检查。部分扫描、无法读取、不支持的 glob、只有 escrow 都不等于完整干净结果，不能据此自动批准 baseline。

-- Edit the existing configs/anticheat_config.lua tables.
ts.EnforceExportCallerWhitelist = true
ts.EventScanner.autoProtect = false
-- 0 disables only the periodic event scan, not initial/manual discovery.
-- ts.EventScanner.scanIntervalMs = 0

使用普通玩家验收#

不用人员权限或玩家白名单，测试角色选择、外观、revive、验证后的房屋传送、车库出口、一次奖励。再测试取消、断线、AC 重启、拒绝未授权请求。分别查看 export 返回和业务回执。合法相机/移动宽限不能关闭武器或事件检测。敏感服务器操作使用可信 export；本地宽限不保证暂停所有直接签名检测。记录版本、资源、预期与观察结果，不记录密钥或密码。

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

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

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

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

从 ZIP 到 txAdmin 启动#

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

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

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

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

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

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