FiveM 登录器与游戏盾：一键进服的完整链路

这个登录器的最终目标很明确：服主在编译前完成品牌和游戏盾连接配置，玩家拿到程序后只能点击“进入服务器”。玩家不接触 SDK 密钥、127.x 转发入口、端口、设置窗口或外部连接 JSON。

工程使用 .NET Framework 4.8、WPF 和 x64 原生 SDK。界面是原生桌面窗口，不依赖 WebView。视觉采用冷峻深色底和单一琥珀色强调，连接状态比装饰更重要。

最终玩家版由哪些部分组成

组件	职责
`OwnerConfig.cs`	保存服主的编译期品牌、连接和行为配置
`PlayerWindow`	只提供进入服务器、状态反馈和关闭入口
`ShieldClient`	加载 x64 `clinkAPI.dll`，封装游戏盾启动和端口检查
`FiveMProcessLauncher`	通过 FiveM 协议或指定程序路径启动游戏
`FiveMShieldLauncher_Ship.csproj`	排除设置窗口和外部配置存储，构建玩家锁定版
发布脚本	白名单复制 EXE、运行时配置、SDK DLL、说明和哈希

设置版草稿仍保留在工程中用于服主调试，但 Ship 项目明确把 MainWindow、SettingsWindow 和 LauncherStore 排除在玩家构建之外。

点击进入服务器之后

玩家点击按钮后，实际链路如下：

检查服主是否已经编译进非空 SDK key、127.x 地址和有效端口。
确认当前进程是 x64，并从程序目录加载 clinkAPI.dll。
配置端口冲突提示和自动换端口策略。
调用 clinkStart 建立游戏盾通道。
SDK 返回就绪状态后，读取当前 TCP 和 UDP 转发端口。
校验两个端口都有效，并且 TCP 与 UDP 使用同一个端口。
使用 fivem://connect/127.x.x.x:port 启动 FiveM。
登录器继续常驻，定时观察 FiveM 进程并更新界面状态。

如果网络暂时不可用，ShieldClient 会进行一段有限等待，给 SDK 自动恢复的机会。启动失败时，底层保留返回码和运行状态，玩家界面只显示可行动的简短提示，避免把内部连接信息直接暴露出来。

为什么登录器仍然需要 127.x 规则

这版 SDK 中，dunGetClientIP() 表示玩家本机公网 IP，并不是游戏盾下发给登录器的转发入口。dunGetCurrentTCPPort() 和 dunGetCurrentUDPPort() 也需要传入控制台已经配置的 127.x 地址与原始端口，才能返回端口冲突处理后的实际值。

因此正确关系是：

服主先在游戏盾控制台建立 TCP 和 UDP 转发规则。
登录器调用 SDK，让本机游戏盾通道生效。
SDK 返回最终可用端口。
登录器连接控制台规则对应的 127.x 本地入口。

登录器不会凭空从 SDK 获得一个服务器入口，也不会把玩家公网 IP 当作 FiveM 连接地址。

TCP 与 UDP 必须一致

FiveM 的连接地址只有一个端口。若 SDK 因冲突分别把 TCP 和 UDP 改到不同端口，登录器无法用单一地址正确连接。

当前实现会在启动 FiveM 前同时读取两个端口。任一端口无效，或二者不一致，都会中止进入服务器并提示服主检查控制台规则。默认关闭自动换端口，就是为了避免玩家端出现无法解释的协议分叉。

品牌内容如何配置

玩家看见的内容全部来自编译期 OwnerConfig.cs：

品牌名和文字 Logo
主标题、副标题
服务器名称和说明
公告、按钮文字、页脚文字
单一强调色
启动 FiveM 后是否最小化

可选 brand-logo.png 和背景图会作为 WPF Resource 编译进 EXE。程序图标使用 Assets/app.ico，覆盖同名 ICO 后重新构建即可。图片缺失时会回退到文字 Logo 和纯色背景，不会因为品牌素材不完整而崩溃。

玩家只能操作什么

玩家版界面只保留进入服务器和关闭窗口。连接过程通过“本机、游戏盾、FiveM”三个节点展示当前阶段，并区分准备、连接中、安全通道已建立、FiveM 启动中和运行中。

FiveM 运行期间关闭登录器会出现确认提示，因为退出可能中断游戏盾通道。若服主开启 MinimizeOnLaunch，FiveM 启动后登录器会自动最小化，但继续在后台保持生命周期。

构建与发布边界

玩家 ZIP 采用白名单输出，只包含：

FiveMShieldLauncher.exe
FiveMShieldLauncher.exe.config
clinkAPI.dll
玩家说明
SDK DLL 的 SHA-256

包内不放 OwnerConfig.cs、launcher.json、密钥文件、设置窗口源码、PDB、Logo 原图或背景原图。

工程已经补充服主编译说明、ICO 替换位置和玩家包预检设计。需要注意，当前工作目录中的一键构建入口仍以 .legacy 草稿名保留，正式发布前应恢复最终脚本名并重新跑完整构建链，不能只根据文档宣称一键构建已经交付。

已验证与未验证

当前本地自检结果为：

SELF_TEST=PASS
MODE=PLAYER_LOCKED
ARCH=x64
OWNER_CONFIG=NOT_SET

这能证明玩家锁定入口、x64 进程和原生 DLL 加载成功。当前玩家 ZIP 也只包含五个白名单文件。

它不能证明真实游戏盾联机已经通过。会话中没有提供正式 SDK key，也没有提供控制台的 127.x 转发规则，因此没有执行生产 clinkStart 和真实 FiveM 进服回归。

最后还有一个安全事实：客户端 SDK 必须取得 key。把 key 编译进 EXE 可以阻止普通玩家从界面修改，但不能把它变成不可提取的服务端秘密。正式部署仍要依赖厂商控制台的绑定、限额、轮换、吊销、有效期，以及 EXE 代码签名。