Godot 客户端自检信号：别把安全全押在前端，也别放弃基础 sanity check

客户端安全有一个基本原则：不能把关键安全完全押在客户端。发奖、扣费、排行榜、匹配资格都应该由服务端权威判断。但这不代表客户端什么都不用做。客户端可以做基础 sanity check，发现资源版本不一致、配置被破坏、调试入口误开、运行环境异常，并把信号上报给服务端和日志系统。

Godot 项目尤其需要这层基础自检，因为资源、PCK、远端配置、导出模板和平台插件都可能影响运行状态。自检不是反作弊万能药，它更像体检和告警：发现异常、限制高风险功能、帮助排查发布事故。

项目里的真实问题

一次灰度包中，部分玩家拿到了新配置和旧资源组合，客户端没有检查资源协议版本，进入活动后才崩溃。另一次测试包里调试菜单入口误带到外部测试渠道，虽然服务端挡住了发奖接口，但客户端仍然暴露了危险按钮。还有玩家本地文件损坏，游戏启动后不断黑屏。

这些问题都不能靠“安全防护”一句话解决，但可以靠自检提前发现。启动时检查资源版本、配置签名、渠道配置、调试开关、关键文件哈希；运行时检查异常状态组合；高风险操作前检查客户端是否处于可信状态。

设计目标

• 基础完整性：检查资源版本、配置版本、关键文件和渠道参数是否一致。
• 风险分级：异常不都阻断，按风险决定提示、降级、限制或上报。
• 不越权：客户端自检只提供信号，不替代服务端权威安全判断。
• 可诊断：自检结果进入日志和问题反馈包，方便排查发布事故。

这些目标不是为了把系统做重，而是为了让 Godot 客户端在真实设备、真实网络和真实内容量下仍然可控。很多功能原型只需要一个脚本，但进入发布流程后，必须回答状态从哪里来、失败怎么恢复、UI 如何同步、日志能否说明问题。下面的设计会围绕这些问题展开。

推荐架构

flowchart TD
    A["输入事件/业务意图"] --> B["ClientSanityService"]
    B --> C["资源版本检查"]
    B --> D["配置完整性"]
    B --> E["运行环境信号"]
    B --> F["风险上报"]
    C --> H["状态快照"]
    D --> H
    E --> H
    F --> H
    H --> I["UI反馈和日志"]

图里的每个模块都可以按项目规模合并或拆分。小团队可以用一个 Autoload 承担管理器职责，大项目可以拆成服务、Resource 配置和 UI ViewModel。关键是调用方向要稳定：业务层提交意图，管理器判断状态，执行层接触 Godot 节点、资源或网络，最后统一反馈给 UI 和日志。

关键实现细节

自检项要分级。阻断级包括资源协议不兼容、关键配置缺失、渠道签名错误；降级级包括远端配置过期、可选资源缺失；观察级包括调试设备、模拟器、性能异常。分级能避免一有小问题就把玩家挡在门外。
资源和配置都要带版本。活动配置引用资源组时，声明最低资源协议版本。客户端启动后比对本地资源版本和配置版本，不匹配时不要进入活动。这个检查能挡住很多灰度发布的组合错误。
调试开关要纳入自检。正式渠道如果发现危险调试命令可用，应立即隐藏入口并上报。不要只依赖 UI 入口不显示，命令执行层也要检查渠道和权限。
自检结果要结构化。每个 check 有 id、level、status、detail、action。日志里记录所有失败项，UI 只展示玩家需要知道的内容。服务端可以根据风险信号限制排行榜、交易或多人匹配。

失败处理和恢复路径

自检服务本身失败时，要有保守策略。读取本地版本失败可能阻断，读取可选配置失败可以降级。不同 check 的失败策略写在配置里。
网络不可用时，不能完成远端校验。客户端可以使用最近可信配置，但要标记为 offline_trusted，并限制依赖最新配置的活动入口。
发现异常不要展示吓人的安全文案。玩家需要知道“资源需要修复”或“请更新客户端”，内部日志再记录具体风险。

GDScript 接口草图

class_name ClientSanityService
extends Node

signal state_changed(snapshot: Dictionary)
signal operation_failed(code: String, detail: Dictionary)

var _version := 0
var _snapshot := {}

func submit(intent: Dictionary) -> void:
    _version += 1
    var token := _version
    _snapshot = {"phase": "pending", "intent": intent}
    emit_signal("state_changed", _snapshot)
    _execute(intent, func(result: Dictionary):
        if token != _version:
            return
        if result.get("ok", false):
            _snapshot = result
            emit_signal("state_changed", _snapshot)
        else:
            emit_signal("operation_failed", result.get("code", "unknown"), result)
    )

func current_snapshot() -> Dictionary:
    return _snapshot.duplicate(true)

这段代码只表达接口边界。真实项目里，intent 可以替换成 typed Resource 或明确的 Dictionary schema，_execute 里也要接入超时、取消和错误码。保留 _version 的原因，是客户端经常出现旧异步结果晚于新操作返回的情况。没有版本保护，UI 快速切换、网络重试和资源加载都会把状态改回旧值。

数据契约和协作接口

SanityCheckResult 包含 check_id、level、status、action、user_message_id、debug_detail。UI 只读 user_message_id，日志和上报读 debug_detail。
服务端接收 sanity signals，但不把客户端信号当唯一依据。高风险功能仍由服务端独立校验。
发布流程输出资源 manifest、配置签名和渠道参数，客户端自检读取同一份 manifest。

分阶段落地

第一阶段检查资源协议版本、关键配置存在和渠道调试开关。
第二阶段加入 manifest 哈希、远端配置签名和自检报告。
第三阶段把风险信号接入服务端策略和问题反馈包。

自动化验证和人工验收

配置要求资源协议 v3，本地只有 v2，确认活动入口被降级或阻断。
正式渠道启用危险调试命令，确认自检失败并隐藏入口。
关键资源文件损坏，确认启动进入修复或安全模式。
离线启动时使用最近可信配置，并标记状态。

观测指标

• 自检失败项分布。
• 资源配置版本不匹配次数。
• 因自检降级或阻断的功能入口数量。
• 自检报告随问题反馈上传的比例。

指标不必一开始就全部上报。开发包可以展示完整调试面板，内测包采样关键字段，正式包只保留错误码和聚合计数。重要的是每个异常都能留下足够证据，团队能判断它是内容问题、网络问题、平台问题还是客户端状态机问题。

上线前检查清单

• 关键资源和配置都有版本或签名。
• 自检项有 level、action 和用户文案。
• 正式渠道检查危险调试开关。
• 客户端信号不替代服务端权威判断。
• 自检结果写入日志和反馈包。

清单最好能逐步脚本化。不能自动检查的内容，也要明确由谁在什么阶段确认。Godot 项目里的客户端系统经常横跨程序、策划、美术、运营和 QA，如果验收口径只停留在口头，下一次类似问题还会以不同名字回来。

现场演练

现场演练可以制作三个包：资源版本落后、配置签名错误、正式渠道误开调试命令。启动后，客户端应分别进入活动降级、配置拒绝和调试入口隐藏上报。玩家看到的是可理解提示，开发日志看到完整 check_id 和 detail。

案例复盘

自检系统的一次典型收益，是灰度配置误配。活动配置要求资源协议 v5，但部分玩家仍是 v4 资源包。旧客户端会进入活动后崩溃；新自检在活动入口前发现协议不匹配，隐藏入口并提示需要更新，同时上报 check_id。这个案例说明自检不是为了吓阻玩家，而是为了把发布组合错误变成可控降级。

上线后的维护策略

自检上线后，维护重点是 check 分级。阻断项过多会误伤玩家，观察项过多又会淹没真正风险。每次发版后看自检失败分布，决定哪些 check 应升级、降级或删除。

灰度阶段要有回退开关。回退不是把功能粗暴关闭，而是退回更简单但完整的玩家路径：离线队列可以暂停新入队但继续处理已有队列，改键系统可以回到默认档案，地图标记可以关闭聚合但保留任务目标，邮件可以禁用批量领取但保留单封领取。每个系统上线前都应该写清楚“降级后玩家还能做什么”。

责任边界也要明确。谁维护配置，谁看指标，谁处理内容接入，谁判断是否回滚，都要写在系统说明里。Godot 客户端功能经常横跨多个岗位，如果只有实现者知道细节，后续每次活动、版本或平台接入都会重新踩坑。文档不需要很长，但必须包含接入示例、常见错误和验收步骤。

灰度验收脚本

灰度验收要准备错误包：资源版本落后、配置签名错误、渠道参数错误、调试开关误开。每个错误包都应该触发对应 check_id 和 action。阻断项要有玩家可理解文案，观察项要进入日志和上报。自检不是为了制造神秘错误，而是为了让错误组合能被明确识别。

验收脚本要同时面向人和机器。机器负责断言状态、错误码、数量和耗时；人负责判断文案是否能理解、视觉反馈是否打扰、操作路径是否顺手。很多客户端系统的失败不是“没有执行”，而是“执行了但玩家不知道发生了什么”。因此每个验收步骤都应该包含预期 UI、预期日志和预期状态快照三部分。

灰度结束后要做一次小复盘。指标是否符合预期，玩家是否使用了降级路径，QA 是否发现难以描述的问题，配置是否需要收紧。复盘结论要回写到检查清单里。这样下一批内容或下一次平台接入时，团队不需要重新摸索同一类边界。

边界补充

自检信号还要避免收集过多个人信息。设备、渠道、资源版本和错误码通常足够排查发布问题，不需要上传玩家本地文件路径或敏感账号信息。风险上报越克制，越容易在正式包长期保留。安全和隐私要一起考虑。

交付补充

交付时要明确哪些自检失败允许玩家继续。比如可选活动资源缺失可以隐藏入口，核心配置缺失必须阻断，调试开关异常则隐藏危险入口并上报。每个 action 都要有玩家文案和内部错误码，不能只在日志里写失败。

小团队接入版本

小团队可以先做版本一致性检查。资源 manifest、配置版本、客户端版本三者对齐，就能挡住很多发布事故。不要一开始追求复杂反作弊；基础 sanity check 先稳定，比空喊安全更实际。

交付边界

交付标准是客户端能在进入高风险功能前发现明显异常，并把结果留给日志和服务端。它不是安全终点，而是发布质量和异常诊断的第一道筛网。

结语

Godot 客户端自检不该被神化，也不该被忽略。关键安全仍然属于服务端，但客户端有责任确认自己处在合理版本、合理配置和合理渠道里。基础 sanity check 做好后，许多发布事故会提前变成可控降级。