逐文件精读源码生成。行号基于当前工作区版本,仅用于快速定位。 本文件覆盖:
src-tauri/src/utils/下全部 15 个文件(mod / api_health / error / crash / diagnostics / game_icon / game_playtime / hg_crypto / http_client / logger / official_launcher / paths / proxy / capture / process / steam)。
职责:工具层模块清单。声明 14 个子模块并统一再导出统一错误类型。
导出:pub mod api_health、pub mod capture、pub mod crash、pub mod diagnostics、pub mod error、pub mod game_icon、pub mod game_playtime、pub mod hg_crypto、pub mod http_client、pub mod logger、pub mod official_launcher、pub mod paths、pub mod process、pub mod proxy、pub mod steam;pub use error::AppError。
主要依赖:crate::utils::error。
| 符号 | 位置 | 说明 |
|---|---|---|
pub mod api_health/capture/crash/diagnostics/error/game_icon/game_playtime/hg_crypto/http_client/logger/official_launcher/paths/process/proxy/steam |
mod.rs:1-14 | 14 个子模块声明,全部 pub |
pub use error::AppError |
mod.rs:16 | 别名导出,使调用方写作 crate::utils::AppError |
备注:全 crate 通过 crate::utils::{capture, paths, http_client, AppError} 这类分组导入使用(如 services/account_service.rs:20、services/avatar_cache_service.rs:6、services/config_service.rs:8)。
职责:定义全后端统一错误枚举 AppError(约 60 行),用 thiserror 派生 Display 与三个自动 From 转换,供 service/command 层的 Result<T, AppError> 使用;并提供会话失效判定 AppError::is_session_invalid。
导出:pub enum AppError、impl AppError(is_session_invalid)、SESSION_INVALID_MARKER。
主要依赖:thiserror、reqwest、serde_json、std::io。
| 符号 | 位置 | 说明 |
|---|---|---|
AppError(enum,#[derive(Debug, Error)]) |
AppError |
应用错误根类型;字段式变体用具名字段 { message } / { code, message } |
AppError::HttpError(reqwest::Error) |
HttpError |
Display:HTTP request failed: {0};#[from] reqwest::Error ⇒ From<reqwest::Error> 自动实现,? 可直接转换 |
AppError::JsonError(serde_json::Error) |
JsonError |
Display:JSON serialization failed: {0};#[from] serde_json::Error ⇒ From<serde_json::Error> |
AppError::IoError(std::io::Error) |
IoError |
Display:IO error: {0};#[from] std::io::Error ⇒ From<std::io::Error> |
AppError::AuthError { message: String } |
AuthError |
Display:Authentication failed: {message};无 From,手动构造,是登录/签名校验/数美接口失败的主力变体 |
AppError::ConfigError { message: String } |
ConfigError |
Display:Configuration error: {message};无 From,多用于 Mutex 中毒、路径获取失败包装 |
AppError::NetworkError { message: String } |
NetworkError |
Display:Network error: {message};无 From,用于代理连通性测试等网络类失败(utils/proxy.rs) |
AppError::ValidationError { message: String } |
ValidationError |
Display:Invalid input: {message};无 From,入参校验失败(如代理未启用/主机为空) |
AppError::ApiError { code: i32, message: String } |
ApiError |
Display:API error (code={code}): {message};无 From,用于远端业务错误码 |
AppError::is_session_invalid(&self) |
impl AppError |
判断是否为「该 cred 已对数据域失效」:AuthError 看是否带 SESSION_INVALID_MARKER,ApiError 转交 api_health::is_session_invalid,HttpError 看 401/403 |
SESSION_INVALID_MARKER |
文件末尾常量 | "SESSION_INVALID";由 call_skland_api 拼进错误文案,供上层稳定识别(不解析服务端原文) |
备注:
- 三个
#[from]是thiserror生成的From实现的全部来源;其余变体只能显式构造。 - 调用面覆盖 account / avatar_cache / char_detail / char_wiki_detail / config / attendance / proxy 等 service 与 command;
AppError不实现serde::Serialize,因此#[tauri::command]层通常把它转成String再返回。 is_session_invalid是替代宽泛to_string().contains("API error")的显式判据:后者会把「请勿重复签到」这类正常业务码也算成故障。- 存在对
AppError的模式匹配工具函数,如account_service::is_new_device_verification_error(&AppError)。
职责:鹰角(Hypergryph)游戏侧加解密与校验工具(131 行):解密 CDN/本地加密资源(game_files 清单、config.ini),以及 MD5/SHA-256 哈希与可取消的分块 MD5 校验,供启动器/下载安装链路使用。
导出:decrypt_bytes_to_string、decrypt_bytes、decrypt_file_to_string、sha256_hex、verify_md5、verify_md5_with_cancel、md5_hex;私有常量 AES_KEY、AES_IV(均为 const,非 pub)。
主要依赖:aes(Aes256)、cbc(Decryptor + Pkcs7)、sha2(Sha256)、md-5(crate 名 md5)、digest、hex、std::fs。
| 符号 | 位置 | 说明 |
|---|---|---|
AES_KEY: [u8; 32] |
hg_crypto.rs:9-12 | AES-256 密钥常量,注释标注「from reverse engineering Hypergryph launcher」(逆向鹰角启动器所得),非 pub |
AES_IV: [u8; 16] |
hg_crypto.rs:15-17 | AES-256-CBC 固定 IV 常量,同样来自逆向,非 pub |
decrypt_bytes_to_string(encrypted_bytes: &[u8]) -> Result<String, String> |
hg_crypto.rs:21 | 空输入直接返回 Ok("");否则调用 decrypt_bytes 后 String::from_utf8,失败报 UTF-8 decode failed: ...。调用方:game_launcher_service.rs:481(解密清单字节) |
decrypt_bytes(encrypted_bytes: &[u8]) -> Result<Vec<u8>, String> |
hg_crypto.rs:32 | AES-256-CBC + PKCS7 解密,key/IV 取文件内常量(hg_crypto.rs:37-38),decrypt_padded_mut::<Pkcs7> 原地解密后拷贝返回;空输入返回空 Vec。调用方:decrypt_bytes_to_string(hg_crypto.rs:26) |
decrypt_file_to_string(file_path: &str) -> Result<String, String> |
hg_crypto.rs:50 | std::fs::read 整文件读入(失败报 Failed to read file '<path>': ...)再交给 decrypt_bytes_to_string。调用方:commands/launcher.rs:242(读加密 config.ini)、game_launcher_service.rs:417 |
sha256_hex(data: &[u8]) -> String |
hg_crypto.rs:57 | SHA-256 → hex 小写。调用方:game_launcher_service.rs:477(对加密清单原文求哈希) |
verify_md5(file_path: &str, expected_md5: &str) -> Result<bool, String> |
hg_crypto.rs:65 | 薄封装,等价 verify_md5_with_cancel(path, expected, None)(hg_crypto.rs:66)。调用方:game_launcher_service.rs:379、591、724、763、903、1087、1856、2582(下载/校验/备份比对) |
verify_md5_with_cancel(file_path, expected_md5, cancelled: Option<&AtomicBool>) -> Result<bool, String> |
hg_crypto.rs:70 | 分块读取(HASH_BUFFER_SIZE = 4 MiB,hg_crypto.rs:79),每轮循环前/开始/结束三处检查 cancelled 标志,命中即返回 Err("Hash verification cancelled")(hg_crypto.rs:80、93、104);Windows 下用 OpenOptionsExt::custom_flags(0x08000000)(FILE_FLAG_NO_BUFFERING,hg_crypto.rs:85-86);比较用 eq_ignore_ascii_case 忽略大小写(hg_crypto.rs:110)。调用方:game_launcher_service.rs:1352(可取消的安装校验) |
md5_hex(data: &[u8]) -> String |
hg_crypto.rs:114 | 内存字节 MD5 → hex。调用方:game_launcher_service.rs:726(下载文件哈希)、2913 |
mod tests |
hg_crypto.rs:122-131 | 仅一个测试 test_decrypt_roundtrip_key_iv,只断言 key=32/IV=16 长度,不做真实解密回环 |
备注:解密目标为 CDN 上的加密资源(game_files 清单)与本地加密 config.ini;哈希校验贯穿下载、落盘、备份全流程。密钥/IV 硬编码在源码中,属逆向常量。
职责:创建统一配置的 reqwest::Client(全局 30 秒超时),并维护一个全局代理配置缓存,使设置页保存的 proxy_config 对所有 HTTP 请求即时生效。同时负责 Android 的 TLS 根证书策略(见下)。
导出:pub fn client_builder、pub fn default_client、pub fn create_client、pub fn create_proxied_client、pub fn set_global_proxy_config、pub fn global_proxy_config。
主要依赖:reqwest、serde_json::Value、std::sync::RwLock、std::time::Duration、crate::utils::proxy;Android 目标额外依赖 rustls + webpki-roots(仅 cfg(target_os = "android"))。
| 符号 | 位置 | 说明 |
|---|---|---|
static PROXY_CONFIG: RwLock<Option<Value>> |
http_client.rs:9 | 全局代理配置缓存(进程级);None 表示直连 |
set_global_proxy_config(config) |
http_client.rs:12 | 写入缓存;由 set_config("proxy_config")、set_proxy_config、remove_proxy_config、save_proxy_settings、clear_proxy_settings 以及启动时的 create_config_service() 调用 |
global_proxy_config() |
http_client.rs:19 | 读取缓存快照(None 表示未启用代理) |
client_builder() -> reqwest::ClientBuilder |
http_client.rs:51 | 所有 HTTP 客户端的统一入口。桌面返回裸 Client::builder();Android 上调用 use_preconfigured_tls(android_tls_config()),改走内置 Mozilla 根证书,绕开 rustls-platform-verifier |
android_tls_config()(私有,仅 Android) |
http_client.rs:61 | 用 webpki_roots::TLS_SERVER_ROOTS 构造 rustls::RootCertStore,并安装 aws_lc_rs 默认 provider,返回 rustls::ClientConfig |
default_client() -> Client |
http_client.rs:76 | client_builder().build() 的便捷封装(不读全局代理);构建失败 log_warn! 后回退 Client::new() |
create_client() -> Client |
http_client.rs:92 | 等价于 create_proxied_client(global_proxy_config().as_ref()),即默认跟随全局代理设置,30 秒超时 |
create_proxied_client(proxy_config) -> Client |
http_client.rs:101 | 基于 client_builder() 按传入代理配置构建 client(proxy::from_config 生成 reqwest::Proxy);未启用时显式调用 ClientBuilder::no_proxy(),禁止 reqwest 回退到读取 HTTP_PROXY/HTTPS_PROXY/ALL_PROXY 等环境变量(否则后台运行的 v2ray 等第三方代理仍会被使用,即使 EndProtocol 内部代理开关已关闭);构建失败时 log_warn! 并回退 Client::new(),不再 panic |
备注:调用方约 15 处(services/skland_service.rs、services/account_service.rs、services/gacha_service.rs),自动继承全局代理。Android TLS 约束:reqwest 0.13 的 rustls 后端固定依赖 rustls-platform-verifier,该 crate 在 Android 上需要注入 Kotlin 组件并显式初始化,否则首次 HTTPS 握手会在 tokio worker 里 panic(实测 Expect rustls-platform-verifier to be initialized)。因此禁止直接 reqwest::Client::new() / Client::builder()——commands/updater.rs、services/char_detail_service.rs、services/skland_service.rs、services/game_launcher_service.rs、utils/proxy.rs 已全部改为走 client_builder() / default_client() / create_client()。
职责:代理配置的解析与生效层:把 proxy_config JSON 收敛为 reqwest::Proxy、创建带代理的 client、解析系统代理(Windows 注册表 / 环境变量)、通过代理做连通性探测、自动嗅探本地常用代理端口。
导出:from_config、test_connection、read_system_proxy、auto_detect_proxy、struct TestConnectionResult、struct SystemProxyInfo、struct ProxyConfigValue。
主要依赖:reqwest(需启用 socks feature)、serde/serde_json、windows-sys(仅 Windows,注册表 API)、crate::utils::AppError、log_debug! / log_warn!。
| 符号 | 位置 | 说明 |
|---|---|---|
is_enabled(config)(私有) |
proxy.rs:13-25 | 宽松判定:enabled == true 且 host 非空 |
exclude_list(config)(私有) |
proxy.rs:27-35 | 解析 exclude 逗号分隔的主机名列表,返回小写字符串向量 |
proxy_server(config)(私有) |
proxy.rs:43-71 | 规范成 scheme://host:port:scheme 由 scheme_for 决定,端口非法时回退 8080,host 中的 scheme:// 前缀与尾部 / 会被剥掉 |
scheme_for(config)(私有) |
proxy.rs:77-95 | 非 SOCKS5 一律 http;SOCKS5 且 remoteDns=true → socks5h(域名交由代理解析),否则 socks5 |
credentials(config)(私有) |
proxy.rs:98-115 | 用户名非空才返回认证对(密码缺省补空串),否则 (None, None) |
from_config(config) -> Option<Proxy> |
proxy.rs:122-154 | Proxy::all(server);有用户名时 basic_auth。记录排除列表(no_proxy 由 http_client::set_global_proxy_config 写入环境变量)。URL 非法时 log_warn! 并返回 None(请求降级为直连而不是报错) |
test_connection(config, url, timeout_secs) |
proxy.rs:155-182 | 异步探测:用代理建 client → GET url → 返回 TestConnectionResult;未启用/主机为空 → AppError::ValidationError,请求失败 → AppError::NetworkError;超时夹取 1-60 秒 |
struct ProbeCandidate(私有) |
proxy.rs:184-193 | 自动嗅探的候选端口参数:proxy_type/host/port/urls(探测 URL 列表) |
PROBE_URLS(私有常量) |
proxy.rs:195-198 | 嗅探探测目标:https://www.gstatic.com/generate_204 与 http://www.baidu.com/(后者保证代理无出墙能力时仍可被识别) |
auto_detect_proxy() |
proxy.rs:206-305 | 异步嗅探:按顺序探测本地常用代理端口(HTTP 7890/8080/10809/8888/8118/1080,SOCKS5 10808/7891/1080/1081/7890/8080),每个候选对每个探测 URL 用 3 秒超时发起连通性测试,首个成功的即返回 ProxyConfigValue;全部失败则返回错误 |
struct ProxyConfigValue |
proxy.rs:307-318 | enabled/proxy_type/host/port/username/password/remote_dns/exclude;Serialize 供前端 |
struct TestConnectionResult |
proxy.rs:320-326 | status: u16、duration_ms: u64;Serialize 供前端 |
struct SystemProxyInfo |
proxy.rs:329-343 | enabled/proxy_type/host/port/username/password/pac_url/from_env;Serialize + Deserialize |
read_system_proxy() |
proxy.rs:361-366 | Windows 先读注册表,取不到再读环境变量,最后返回全空的 none() |
env_proxy()(私有) |
proxy.rs:373-387 | 依次尝试 HTTPS_PROXY/https_proxy/HTTP_PROXY/http_proxy/ALL_PROXY/all_proxy,命中后 from_env=true |
parse_proxy_url(raw)(私有) |
proxy.rs:394-435 | 解析 scheme://[user:pass@]host[:port];socks* scheme → proxy_type="socks5";缺省端口 http 8080 / socks5 1080 |
split_host_port(authority)(私有) |
proxy.rs:440-460 | 拆分 host 与可选端口,支持 IPv6 字面量 [::1]:1080;非数字后缀整体视作 host |
windows_registry_proxy()(私有,cfg(windows)) |
proxy.rs:465-511 | 读 HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings:ProxyEnable(DWORD)、ProxyServer、AutoConfigURL、ProxyOverride;未启用或无 ProxyServer 时返回 enabled:false 并带上 pac_url |
pick_proxy_entry(server)(私有,cfg(windows)) |
proxy.rs:516-537 | 处理 http=host:port;https=host:port 与单一 host:port 两种写法,优先 https 条目 |
wide / read_raw_value / read_dword / read_string(私有,cfg(windows)) |
proxy.rs:542-617 | 注册表读取工具(UTF-16 路径、64KB 上限、REG_SZ/REG_EXPAND_SZ/REG_DWORD) |
mod tests |
proxy.rs:624-680 | 4 个单测:HTTP 配置、SOCKS5+认证、禁用/空主机、系统代理 URL 解析 |
备注:
- reqwest 需要
socksfeature 才能构造socks5:///socks5h://代理——Cargo.toml中的reqwest依赖已加上"socks"。 - 代理 URI 一律经
Proxy::all(HTTP 与 HTTPS 流量都走代理);SOCKS5 默认本地解析 DNS,打开remoteDns后改用socks5h://由代理解析域名(可绕过本地 DNS 污染)。 - 排除列表(
exclude字段):前端以逗号分隔的主机名填写,保存后写入no_proxy环境变量,reqwest 对这些主机直连不走代理。 AppError新增两个变体以承载这里的错误:NetworkError { message }、ValidationError { message }(见utils/error.rs)。- 注册表
ProxyOverride(“不使用代理”列表)当前读出来但未参与解析——reqwest 不支持 per-host bypass 列表;PAC 脚本同理,只回传pac_url供 UI 提示。
职责:自研日志系统(491 行):控制台彩色输出 + 按日期文件落盘 + 内存环形缓冲(供前端读取),支持运行时切换日志级别;未开启开发者模式时默认 INFO,DEBUG 不进入内存/文件/控制台。包含 tracing 桥接层(输出裁剪到模块短名与紧凑字段)与 9 个导出宏。
导出:LogLevel、LogEntry、LoggerConfig、Logger、console_available、eprint_console、init_logger、get_logger、try_get_logger、set_log_level、init_tracing_subscriber、宏 log_debug! / log_info! / log_warn! / log_error! / log_debug_module! / log_info_module! / log_warn_module! / log_error_module! / safe_eprintln!。私有项:TracingBridgeLayer、TracingVisitor、GLOBAL_LOGGER、MAX_DEBUG_MESSAGE_CHARS、NOISY_TARGETS、is_noisy_target。
主要依赖:chrono(Local 时间)、serde::Serialize、tracing / tracing-subscriber、super::paths、std::sync::{atomic::{AtomicU8, Ordering}, Mutex}。
| 符号 | 位置 | 说明 |
|---|---|---|
enum LogLevel { Debug=0, Info=1, Warn=2, Error=3 } |
logger.rs:45 | 派生 Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize;#[repr(u8)] 便于存入 AtomicU8,派生序使 level >= current_level 可直接比较 |
LogLevel::as_str |
logger.rs:53 | → "DEBUG"/"INFO"/"WARN"/"ERROR" |
LogLevel::parse |
logger.rs:63 | 解析 "debug"/"info"/"warn"/"error"(大小写不敏感,warning 兼容),供 set_log_level 命令与启动配置使用 |
LogLevel::from_u8 |
logger.rs:77 | AtomicU8 → 枚举(私有,越界按 ERROR) |
LogLevel::color_code |
logger.rs:86 | ANSI 颜色:Debug \x1b[36m 青、Info \x1b[32m 绿、Warn \x1b[33m 黄、Error \x1b[31m 红(私有) |
struct LogEntry |
logger.rs:98 | 字段 timestamp(String) / level(LogLevel) / module(String) / message(String) / source(String,后端固定写 "backend");Serialize 供前端 |
struct LoggerConfig |
logger.rs:107 | log_to_console / log_to_file / log_level / log_dir: PathBuf / max_memory_entries |
impl Default for LoggerConfig |
logger.rs:111-127 | 默认:控制台开、文件开、级别 Info、log_dir = paths::log_dir()(失败依次回退 current_dir()/logs、temp_dir()/endprotocol-logs),内存上限 5000 条。移动端相关:Android 上 paths::log_dir() 在数据目录覆盖值注入前必然失败,因此原 current_dir().unwrap() 已改为无 panic 的逐级回退 |
| 符号 | 位置 | 说明 |
|---|---|---|
console_available() -> bool |
logger.rs:16、23 | Windows 实现 GetConsoleWindow() != null;非 Windows 恒真。main.rs 无条件使用 GUI 子系统后,进程可能根本没有控制台,此时 std 的 stderr 句柄不可用,直接 eprintln! 会 panic |
eprint_console(fmt: Arguments) |
logger.rs:28 | console_available() 为真才 eprintln!;safe_eprintln! 宏的落点 |
safe_eprintln! 宏(#[macro_export]) |
logger.rs:34 | 展开为 $crate::utils::logger::eprint_console(format_args!(...));全 crate 的裸 eprintln! 均应替换为它 |
| 符号 | 位置 | 说明 |
|---|---|---|
struct Logger |
logger.rs:126 | 持有 config、level: AtomicU8(运行时可调,避免每条日志加锁)、log_file: Mutex<Option<File>>、memory_buffer: Mutex<VecDeque<LogEntry>> |
Logger::new(config) -> Result<Self, Box<dyn Error>> |
logger.rs:135 | 用 config.log_level 初始化原子级别;log_to_file 为真时调用 init_log_file |
init_log_file |
logger.rs:151 | create_dir_all(log_dir) → 文件名 app-%Y-%m-%d.log → create(true).append(true) 打开并存入 Mutex |
format_timestamp |
logger.rs:163 | %Y-%m-%d %H:%M:%S%.3f(本地时间,毫秒精度) |
level() / set_level() / is_enabled() |
logger.rs:167、171、175 | 读取/写入原子级别;is_enabled 即 level >= current |
truncate_debug(message) |
logger.rs:179 | DEBUG 消息按字符截断到 800,追加 … (N chars),避免超长 payload |
write_log(level, module, message) |
logger.rs:188 | 核心写入:入口先按当前级别过滤(低于级别直接 return,不进入内存/文件)→ 构造 LogEntry 入内存 VecDeque,超 max_memory_entries 则 pop_front;控制台仅当 log_to_console && console_available();文件 writeln! 后立即 flush() |
get_recent_logs() -> Vec<LogEntry> |
logger.rs:247 | 克隆整个内存缓冲;调用方 commands/logs.rs(get_backend_logs 命令) |
info(&self, message: &str) |
logger.rs:252 | module 固定 "backend" |
debug_fmt/info_fmt/warn_fmt/error_fmt(fmt: Arguments) |
logger.rs:256、260、264、268 | 接收 format_args!,供同名宏使用 |
debug_with_module/info_with_module/warn_with_module/error_with_module(module, message) |
logger.rs:273、277、281、285 | 指定 module(tracing 桥接与带模块宏使用) |
| 符号 | 位置 | 说明 |
|---|---|---|
static GLOBAL_LOGGER: OnceLock<Logger> |
logger.rs:291 | 全局单例,std::sync::OnceLock(线程安全,无 unsafe) |
init_logger() -> Result<(), Box<dyn Error>> |
logger.rs:293 | 用 LoggerConfig::default()(默认 INFO)建实例并 GLOBAL_LOGGER.set(logger),随后 info("Logger initialized successfully");调用方 lib.rs、utils/official_launcher.rs(提权 helper 进程) |
get_logger() -> &'static Logger |
logger.rs:303 | GLOBAL_LOGGER.get().expect(...);未初始化即调用会 panic |
try_get_logger() -> Option<&'static Logger> |
logger.rs:310 | 未初始化时返回 None;供 panic hook、诊断导出与 set_log_level 安全使用 |
set_log_level(level) |
logger.rs:315 | 运行时更新全局日志级别;未初始化时静默忽略。调用方 commands/logs.rs::set_log_level、lib.rs setup(按 developer_mode / log_level 配置应用) |
struct TracingBridgeLayer + impl Layer<S> |
logger.rs:321-411 | enabled 先按当前级别短路(级别关闭时 tracing 宏不再构造字段),再按 metadata.target() 对第三方网络栈(h2/hyper/reqwest/rustls/mio/tower/zbus 等,见私有常量 NOISY_TARGETS)的 DEBUG/TRACE 事件降噪——reqwest 0.13 起其依赖启用 tracing,不降噪会以约 50 KB/s 灌满日志与终端;on_event 取 module 路径最后一段(无 module_path 的 log crate 桥接事件回退到字段里的 log.target,再回退 metadata.target()),消息不再拼 [target] 前缀,仅保留字段汇总后调用 *_with_module |
struct TracingVisitor(String) + impl field::Visit |
logger.rs:451-490 | 实现 record_debug/record_str/record_i64/record_u64/record_bool;message 字段去掉 message= 前缀,其它字段以 name=value 空格连接 |
init_tracing_subscriber() |
logger.rs:492 | registry().with(TracingBridgeLayer).try_init().ok(),已初始化则忽略;调用方 lib.rs |
| 宏 | 位置 | 展开到 |
|---|---|---|
log_debug! / log_info! / log_warn! / log_error! |
logger.rs:437、... | get_logger().*_fmt(format_args!(...)),module=backend |
log_debug_module! / log_info_module! / log_warn_module! / log_error_module! |
logger.rs:466、... | get_logger().*_with_module($module, &format_args!(...).to_string()) |
safe_eprintln! |
logger.rs:34 | console_available() 为真才写 stderr(见上表);供非 logger 系统的裸 eprintln! 使用 |
备注(格式 / 目标 / 轮转):
- 单行格式:
[YYYY-MM-DD HH:MM:SS.mmm] [LEVEL] [module] message。 - 输出目标:stderr(控制台,带 ANSI 色)与日志文件(无色);内存缓冲同时保留 5000 条供前端
get_backend_logs拉取。 - 级别过滤:内存缓冲、文件与控制台共用当前级别,DEBUG 在开发者模式关闭时不会写入任何目标;DEBUG 消息超过 800 字符自动截断。
- tracing 桥接:模块名只保留最后一段(如
game_launcher_service),消息不再重复完整 crate 路径。 - 轮转/清理:仅有「按启动日期命名
app-YYYY-MM-DD.log」这一按日分文件的命名策略——文件句柄在init_logger时打开一次,跨天不会切换文件,也没有任何旧日志删除/轮转逻辑,历史日志会无限累积(异常项)。
职责:官方启动器父进程伪造 —— 在不打开鹰角启动器界面、不注入代码、不修改任何游戏文件的前提下启动《明日方舟:终末地》(约 2180 行,其中非 Windows 部分为返回错误的桩)。游戏会校验自己的直接父进程必须是签名有效的官方 Games.exe,本模块以 CREATE_SUSPENDED 创建官方启动器并永不恢复它(只有映像与签名存在),再用 PROC_THREAD_ATTRIBUTE_PARENT_PROCESS 把它指定为游戏进程的父进程,等待游戏退出后终止该挂起父进程并转发退出码。已提权时由当前进程直接创建(保留 Steam overlay 的 CreateProcess 注入链),未提权时才以 runas helper 完成创建;两条路径的清理职责最终都交给会话驻守进程(helper 本身 / --endfield-session-keeper),使游戏进程与应用进程生命周期彻底解耦。逻辑逐函数移植自 EndfieldNoLauncher 的 src/launch.cpp(AGPL-3.0,上游为 Better Endfield Next 的 native/loaders/shared/official_launcher.cpp,commit 514f6d6),函数名与结构一一对应。
导出:跨平台 —— HELPER_FLAG、KILL_HELPER_FLAG、SESSION_KEEPER_FLAG、exit_code 模块、kill_exit_code 模块、LaunchToken、LaunchError、ElevatedLaunch、HelperOptions、KeeperOptions、KillOptions、quote_argument、quote_command_line、is_official_publisher、version_key、parse_helper_options、parse_keeper_options、parse_kill_options、usage;Windows 专属 —— launch_via_official_parent、kill_game_process、process_is_elevated、shell_execute_game、try_run_helper、try_run_kill_helper、try_run_session_keeper(其余全部私有)。
主要依赖:windows-sys(Win32_Security* / Win32_System_Threading / Win32_System_JobObjects / Win32_System_Registry / Win32_System_Environment / Win32_System_Console / Win32_System_Diagnostics_Debug / Win32_UI_Shell / Win32_UI_WindowsAndMessaging)、tracing、crate::utils::logger(helper 与会话驻守写同一份日志文件)、crate::utils::paths(调用方算状态文件路径)、crate::utils::process(进程快照与终止原语:kill_game_process、run_kill_helper、kill_existing_game 共用)。
| 符号 | 位置 | 说明 |
|---|---|---|
HELPER_FLAG |
:60 | "--endfield-launch-helper",提权 helper 的私有首参数 |
KILL_HELPER_FLAG |
:66 | "--endfield-kill-helper",提权结束游戏 helper 的私有首参数(与启动 helper 共用同一个 exe) |
SESSION_KEEPER_FLAG |
:73 | "--endfield-session-keeper",会话驻守进程的私有首参数(同 exe 第四种模式);已提权启动后接管游戏会话,应用退出不影响游戏 |
PUBLISHER(私有) |
:76 | "Shanghai Hypergryph Network Technology Co., Ltd.",签名者证书 O 字段期望值(对应 C++ kPublisher) |
pub mod exit_code |
:79-88 | INVALID_ARGUMENTS=2 / CREATE_FAILED=4 / NO_VALID_LAUNCHER=7 / WAIT_FAILED=8 |
pub mod kill_exit_code |
:91-96 | INVALID_ARGUMENTS=2 / STILL_RUNNING=3(提权终止之后同名进程仍存活) |
LaunchToken |
:100-119 | 失败/提示的机器可读标记(not_found/no_launcher/cancelled/create/wait_failed/kill_failed/fallback/overlay_unavailable/unknown),前端据此选 i18n 文案 |
LaunchError |
:139-170 | { token, detail };message() 产出 "<token>: <detail>" 契约串;私有 exit_code() 把 token 映射回退出码(kill_failed 归入 CREATE_FAILED,仅用于 helper 内部错误路径) |
ElevatedLaunch |
:183-185 | { helper_pid: Option<u32> };Some = 提权 helper 已建立,None = 当前进程已提权并直接创建了游戏(清理已移交会话驻守) |
wide / quote_argument / quote_command_line |
:192-237 | UTF-16 编码与 CreateProcessW 引号转义(对应 QuoteArgument:反斜杠仅在引号前与结尾翻倍) |
is_official_publisher |
:239 | eq_ignore_ascii_case 版 _wcsicmp(对应 IsOfficialPublisher) |
version_key |
:246 | 解析 …\1.6.0\Games.exe 的父目录名 → Vec<u64>;非法名返回空(排序最低,对应 Version) |
HelperOptions |
:264-282 | helper 命令行结构(--game/--parent/--status/--),对应 Options |
KeeperOptions / parse_keeper_options |
:283-336 | 会话驻守命令行(--game-handle/--parent-handle/--job-handle,纯字符串校验以便单测;数值句柄由父进程经 HANDLE_LIST 继承传入) |
usage |
:338-348 | 三个内部模式的说明文本(--help) |
KillOptions / parse_kill_options |
:350-385 | kill helper 命令行(--name <x.exe>,--help);只接受 <name>.exe 且拒绝路径/引号,避免提权入口被当作通用进程终止器 |
parse_helper_options |
:387-436 | helper 参数解析(取值选项只允许一次、未知选项报错、-- 之后原样转发),对应 ParseOptions |
RegistryKey / read_registry / subkeys / add_root / installed_roots |
:629-841 | 发现安装位置(对应 RegistryKey/ReadRegistry/Subkeys/AddRoot/InstalledRoots) |
OwnedHandle |
:520-548 | RAII 内核句柄(CloseHandle),null 与 INVALID_HANDLE_VALUE 视为无句柄;take() 用于移交所有权;unsafe impl Send(内核句柄是进程级对象,可跨线程等待/终止/关闭) |
process_is_elevated |
:556-575 | 读当前进程令牌的 TokenElevation;用于决定游戏由当前进程直接创建还是交给 runas helper |
windows_error |
:577-606 | <操作> (Win32 <码>) + FormatMessageW 本地化文本,740 额外附提权提示(对应 WindowsError) |
ensure_console_hidden |
:617-626 | 仅 GetConsoleWindow+ShowWindow(SW_HIDE),不调用 FreeConsole(原因见备注);main.rs 全构建改用 GUI 子系统后,正常路径下本函数已是 no-op(无控制台可隐藏),纯防御性保留 |
TrustState / verify_official_launcher / signer_organization |
:847-1000 | 签名校验:独占只读句柄(FILE_SHARE_READ)+ WINTRUST_FILE_INFO.hFile + WTD_UI_NONE/WTD_CHOICE_FILE/WTD_CACHE_ONLY_URL_RETRIEVAL|WTD_REVOCATION_CHECK_NONE,再取第 0 个签名者证书链 pasCertChain[0].pCert 的 O 字段比对(对应 TrustState/VerifyOfficialLauncher) |
find_official_launcher |
:1002-1042 | 给定 --parent 时只校验它,否则枚举候选并按版本降序取第一个通过者(对应 FindOfficialLauncher) |
OfficialParent + start / create_game / release / Drop |
:1044-1223 | 挂起父进程(CREATE_SUSPENDED|CREATE_NO_WINDOW + SW_HIDE,关线程句柄但永不 ResumeThread)与游戏创建(两段式属性列表 + PROC_THREAD_ATTRIBUTE_PARENT_PROCESS + EXTENDED_STARTUPINFO_PRESENT,StartupInfo.cb = size_of::<STARTUPINFOEXW>());Drop 只终止自己创建的进程并等 5s(对应 OfficialParent);release() 只关句柄不终止 —— 会话驻守接管生命周期后由应用进程调用 |
wait_for_game / write_status_file |
:1225-1250 | 等待游戏退出并读退出码(对应 WaitForGame);创建成功后写 pid=<n> 状态文件 |
LauncherJob |
:1253-1297 | CreateJobObjectW + JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE 兜底终止挂起父进程;句柄在游戏创建之后才创建/赋值,不会把游戏本身纳入 Job;会话驻守进程会继承这个句柄,因此 Job 的存活期跟随驻守进程而非应用进程 |
launch_in_process |
:1299-1378 | 直接启动路径:本进程创建「挂起官方父进程 + 游戏」,随后 spawn_session_keeper 把清理移交会话驻守进程并 release() 父进程句柄;驻守拉起失败时回退旧的进程内等待线程,返回 ElevatedLaunch { helper_pid: None } |
try_run_session_keeper / run_session_keeper |
:1382-1451 | 会话驻守入口:在 logger/Tauri 初始化前由 lib.rs 截获;wait_for_game 等游戏退出 → 显式终止挂起父进程并等 5s(与 OfficialParent::Drop 同款)→ 退出时关闭继承的 Job 句柄兜底 |
spawn_session_keeper(私有) |
:1453-1556 | 以 CreateProcessW 拉起自身:HANDLE_FLAG_INHERIT + PROC_THREAD_ATTRIBUTE_HANDLE_LIST 精确继承「游戏 + 挂起父进程 + Job」三个句柄(不泄漏日志/Webview 句柄),句柄数值经命令行传给驻守进程;CREATE_NO_WINDOW,结束后恢复句柄的非继承标记 |
try_run_kill_helper / run_kill_helper |
:1569-1664 | 提权结束游戏 helper 入口:在 logger/Tauri 初始化前由 lib.rs 截获,ensure_console_hidden + parse_kill_options → process::terminate_processes,退出码按 TerminateOutcome 映射:Terminated/Nothing → 0,AccessDenied/StillRunning → STILL_RUNNING |
try_run_helper / run_helper / launch |
:1606-1718 | helper 入口与完整流程;launch() 是唯一持有 RAII 的作用域,析构(终止挂起父进程)完成后调用方才 process::exit |
kill_existing_game(私有,helper) |
:1666-1683 | launch() 开头以管理员权限调用 process::terminate_processes(原生快照 + TerminateProcess,含子进程树),清理上一局残留(含应用未提权时无法结束的提权游戏进程) |
HelperProcess |
:1720-1789 | ShellExecuteExW 返回的 helper 进程句柄;wait_early_exit(2.5s) 宽限期探测、wait_to_exit(timeout) 阻塞取退出码、watch_to_completion() 分离线程收尾 |
shell_execute_elevated / helper_parameters |
:1793-1876 | ShellExecuteExW("runas", 自身 exe, ...),SW_HIDE + SEE_MASK_NOCLOSEPROCESS|NOASYNC|FLAG_NO_UI|NO_CONSOLE |
launch_via_official_parent(win) |
:1878-1930 | 入口:先验签(失败即 no_launcher,调用方回退直接启动)→ 已提权时 launch_in_process,否则 runas 重启自身 → 宽限期判定 |
kill_game_process / kill_helper_parameters |
:1942-2000 | 结束游戏入口:先就地 process::terminate_processes,按 TerminateOutcome 分流 —— Terminated 返回 Ok(true)、Nothing 返回 Ok(false)(这两条都不弹 UAC),AccessDenied/StillRunning 才 runas 重启自身跑 --endfield-kill-helper,阻塞等待退出码(KILL_HELPER_TIMEOUT = 10s),失败映射为 kill_failed(helper 退出码非 0 / 超时) |
shell_execute_game |
:2002-2042 | 回退路径:ShellExecuteW(SW_SHOWNORMAL) 直接启动游戏(旧实现的行为);arguments: &[String] 逐个经 quote_argument 拼接后作为 lpParameters 传入,用于转发 -force-d3d11 |
launch_via_official_parent(非 Windows 桩) |
:2045-2056 | 返回 unknown 错误 |
mod tests |
:2090- | 19 个单测:引号转义(结尾反斜杠 / 内嵌引号)、组织名比对、版本解析与数值比较、helper 参数解析、kill 参数解析与 <name>.exe 限制、keeper 参数解析(含缺省 --job-handle 与非法值拒绝) |
备注(提权模型 / 契约 / 限制):
- 两种启动路径:当前进程已提权时由
launch_in_process直接创建挂起父进程与游戏 —— 这是 Steam overlay 能进入游戏的前提:gameoverlayrenderer64.dll注入的是 Steam 拉起的本进程,只有保持同一条CreateProcess链,overlay 才能继续注入;未提权时才走runashelper(游戏与官方启动器 manifest 都要求管理员,未提权进程直接创建会得到 Win32 740)。helper 路径会引入提权边界,Steam(非管理员)的 overlay 无法跨边界注入到管理员游戏,因此命令层会在warning中返回overlay_unavailable。 runas两阶段(恰好一次 UAC):未提权一侧只做「查找 + 验签」,失败时不弹 UAC 就能给出结论;成功则runas重启自身,提权后的同一 exe 由lib.rs:40的try_run_helper()在 logger/Tauri 初始化之前截获(结束游戏的try_run_kill_helper()在lib.rs:48,会话驻守的try_run_session_keeper()在lib.rs:56)。process::exit不跑析构:helper 的完整流程必须先在一个函数内返回(RAII 析构 → 终止挂起的Games.exe),再由lib.rs退出进程;若在持有父进程句柄时直接退出,那个Games.exe会永久残留。- 应用与游戏生命周期解耦(会话驻守):挂起的
Games.exe必须存活到游戏退出——游戏会盯着父进程,父进程被终止时游戏会跟着退出。因此已提权路径在游戏创建后立即spawn_session_keeper拉起独立驻守进程:它继承「游戏进程 + 挂起父进程 + 清理 Job」句柄(HANDLE_FLAG_INHERIT+PROC_THREAD_ATTRIBUTE_HANDLE_LIST精确圈定),应用退出(关窗/崩溃/更新重启)不再终止挂起父进程,游戏可以继续运行;游戏退出后驻守进程显式TerminateProcess并退出,此时 Job 句柄全部关闭,内核按KILL_ON_JOB_CLOSE兜底。驻守进程拉起失败(极罕见)才回退旧的进程内等待线程——那时游戏仍随应用退出而结束,但不会留下残骸。未提权路径的 runas helper 本身就是独立进程,天然不受应用退出影响。 - 启动前清理旧游戏进程:helper 在
launch()开头调用process::terminate_processes(原生快照 +TerminateProcess)。应用未提权时命令层的同名清理会因ERROR_ACCESS_DENIED失败,残留的提权游戏进程只能由提权 helper 清理。若残留进程被游戏反作弊驱动保护(管理员也无法终止),则只能重启系统;is_process_running会通过窗口/启动宽限判定把这类无窗口残留排除在「游戏中」之外。 - 不许
FreeConsole:万一进程真的附有控制台(非正常路径),FreeConsole会让之后所有 stderr 写入直接失败、且 logger 里的console_available()检查也无济于事(句柄已失效);因此只隐藏窗口、不卸载控制台(main.rs全构建 GUI 子系统后,正常路径本就无控制台,裸eprintln!也已统一走safe_eprintln!)。 - 签名句柄不跨提权边界:helper 会重新验签并自己保持
FILE_SHARE_READ句柄直到进程创建完成;未提权一侧的校验只是「不想让用户白弹一次 UAC」的 UX 过滤,不要因为「重复」而删掉 helper 里的那次。 - 有意与上游一致的两处取舍:
WTD_REVOCATION_CHECK_NONE(不联网、不查吊销,离线可用)与只比对组织名不比指纹。 - 状态文件:
%LOCALAPPDATA%\cn.msk-network.endprotocol\launcher_helper_status(路径由调用方传入),用于区分「helper 启动阶段失败」与「游戏创建成功但很快退出」——helper 退出码与游戏退出码共用同一段数值区间。 - 结束游戏同样要提权:游戏进程由提权 helper 创建,未提权的 EndProtocol 调用
OpenProcess(PROCESS_TERMINATE)/TerminateProcess只会得到ERROR_ACCESS_DENIED。kill_game_process因此先就地试一次(本进程已提权时足以成功,不弹 UAC);terminate_processes会把「拒绝」与「仍存活」区分开返回,所以不需要再等一轮存活轮询就能断定要提权,还有残留才runas重启自身跑KILL_HELPER_FLAG(--endfield-kill-helper --name <Endfield.exe>),由lib.rs在 logger/Tauri 初始化前截获;helper 只做一次process::terminate_processes(内部最多等 1.5 秒确认进程消失),退出码0= 已结束、STILL_RUNNING= 仍存活。用户取消 UAC 会由shell_execute_elevated映射为cancelled,命令层把它作为Err("<token>: <detail>")交给前端展示。 - 旧实现的
taskkill/wmic兜底已移除:wmic在新版 Windows 已弃用,且同样跨不过完整性级别边界,留着只会掩盖真正的原因(权限不足);taskkill子进程则单次要 340–390 ms,一轮存活轮询(旧has_processes,6 次 × 500 ms)能白吃掉 10 秒,已全部由 Win32 快照(约 1–2 ms)替代,见utils/process.rs。 - kill helper 的命令行只接受
<name>.exe:这个提权入口若允许任意参数,就等于给应用开了一个「以管理员权限终止任意进程」的后门;parse_kill_options因此拒绝路径、引号与非.exe目标。 - 旧实现的
wmic兜底已移除:wmic在新版 Windows 已弃用,且同样跨不过完整性级别边界,留着只会掩盖真正的原因(权限不足)。 - 权限边界:未提权的本进程只能结束与它同权限的进程,因此
KILL_HELPER_FLAG用runas重启自身(见「结束游戏同样要提权」备注)。 - 非 Windows 平台:
launch_via_official_parent返回unknown错误、try_run_helper/try_run_kill_helper/try_run_session_keeper返回None、kill_game_process返回Ok(false)、process_is_elevated恒为false,模块仍可编译(CI 会构建 macOS/Linux)。
职责:集中定义应用数据目录与各业务文件/目录路径(约 137 行),统一基于 dirs::data_local_dir() + 应用目录名(桌面)或 Tauri 路径解析器注入的覆盖值(移动端),返回 Result<PathBuf, &'static str>。
导出:常量 APP_DIR(const,非 pub)、14 个 pub fn。
主要依赖:dirs、std::path::PathBuf。
常量:APP_DIR = "cn.msk-network.endprotocol"(paths.rs:3),即 Bundle ID 风格目录名。
| 符号 | 位置 | 返回路径(相对数据根目录) |
|---|---|---|
DATA_DIR_OVERRIDE(static) |
paths.rs:9 | OnceLock<PathBuf> 移动端数据目录覆盖值。Android/iOS 没有 $HOME,XDG 目录全部缺失,dirs 系列恒返回 None;lib.rs setup 最早一步用 app.path().app_data_dir()(Android = {filesDir}/cn.msk-network.endprotocol)注入。桌面永远不设置,历史数据位置不变 |
set_app_data_dir_override(dir) |
paths.rs:17 | 注入覆盖值(仅移动端由 lib.rs setup 调用;重复注入以首次为准) |
app_data_dir() |
paths.rs:22 | 优先返回覆盖值;桌面回退 <data_local_dir>/cn.msk-network.endprotocol,失败返回 "Failed to get local app data directory"。平台差异:Windows = %LOCALAPPDATA%\cn.msk-network.endprotocol(doc 注释 paths.rs:6,刻意用 Local 不用 Roaming,避免同步);macOS = ~/Library/Application Support/cn.msk-network.endprotocol;Linux = ~/.local/share/cn.msk-network.endprotocol(dirs::data_local_dir() 语义);Android = {filesDir}/cn.msk-network.endprotocol(覆盖值)。调用方:config_service.rs:19、game_launcher_service.rs:1918/1952/1970 |
image_cache_dir() |
paths.rs:14 | <app_data_dir>/image_cache。调用方:commands/image.rs:18、avatar_cache_service.rs:87 |
backgrounds_dir() |
paths.rs:19 | <app_data_dir>/backgrounds。调用方:commands/image.rs:143、154、192 |
wiki_detail_cache_dir() |
paths.rs:24 | <app_data_dir>/wiki_detail_cache。调用方:char_wiki_detail_service.rs:42 |
log_dir() |
paths.rs:29 | <app_data_dir>/logs。调用方:logger.rs:65(LoggerConfig 默认值) |
config_file_path() |
paths.rs:34 | <app_data_dir>/app_config.json。调用方:config_service.rs:25 |
secret_file_path() |
paths.rs:39 | <app_data_dir>/secrets.enc(机密降级存储:OS 凭据库不可用时的 AES-256-GCM 加密文件)。调用方:secret_store.rs:127 |
capture_dir() |
paths.rs:39 | <app_data_dir>/network_capture。调用方:utils/capture.rs:101(capture_root) |
gacha_records_file_path(user_id, server_id) |
paths.rs:44 | <app_data_dir>/gacha_records/gacha_records_{userId}_{serverId}.json。调用方:gacha_service.rs:162 |
gacha_weapon_records_file_path(user_id, server_id) |
paths.rs:52 | <app_data_dir>/gacha_records/gacha_weapon_records_{userId}_{serverId}.json。调用方:gacha_service.rs:242 |
gacha_total_catalog_file_path() |
paths.rs:65 | <app_data_dir>/gacha_records/total.json(全量 Wiki 目录,全局共用)。调用方:gacha_service.rs:335 |
arknights_gacha_records_file_path(uid) |
paths.rs:73 | <app_data_dir>/gacha_records/arknights_gacha_records_{uid}.json(《明日方舟》寻访记录,只按渠道绑定 uid 分文件)。调用方:arknights_gacha_service.rs。为什么不带 serverId:明日方舟的 /api/gacha/history 不接受 server_id,同一把 u8token(= 同一个 uid)就是一条连续流水;且官服明日方舟角色与终末地角色 serverId 都是 1,沿用 gacha_records_{userId}_{serverId}.json 会互相覆盖 |
gacha_records_file_path_legacy(user_id, server_id) |
paths.rs:84 | <app_data_dir>/gacha_records_{userId}_{serverId}.json(与 app_config.json 同级的旧版布局,仅供存量数据兼容读取)。调用方:gacha_service.rs:177 |
gacha_avatar_map_file_path() |
paths.rs:92 | <app_data_dir>/gacha_avatar_map.json。调用方:gacha_service.rs:301 |
arknights_cache_dir() |
paths.rs:102 | <app_data_dir>/arknights(《明日方舟》数据缓存目录:player_info_{uid}.json 与 raw_*.json 都在里面,目录内文件名由 ArknightsService 决定)。调用方:arknights_service.rs:63。为什么不进 app_config.json:单账号 player/info 实测几百 KB(B 服 242 名干员约 600 KB),塞进配置会让每次配置读写都搬运它 —— 与抽卡记录同一套做法 |
备注:全部函数只拼接路径、不创建目录(创建由调用方 create_dir_all 完成);除 app_data_dir 的底层查询失败外无其他错误来源,故错误类型是 &'static str。平台差异体现在根目录:桌面为 data_local_dir(),移动端为 Tauri 注入的覆盖值,子目录结构跨平台一致。移动端注意:lib.rs setup 之前的极早期调用(如 run() 里的 init_logger——移动端已推迟到 setup)会得到 "Mobile app data directory is not initialized yet" 错误。
职责:敏感信息脱敏工具(191 行)。在写入日志文件前把 URL query 中的令牌类参数替换为掩码,避免 cred / token / u8token 等凭证落盘到 logs/app-*.log。
导出:pub fn redact_url(url: &str) -> String、pub fn redact_text(text: &str) -> String。私有:SENSITIVE_QUERY_KEYS(常量数组)、is_sensitive_key、mask。
主要依赖:无(纯字符串处理)。
| 符号 | 位置 | 说明 |
|---|---|---|
SENSITIVE_QUERY_KEYS |
redact.rs:19 | 需要脱敏的 query 参数名:cred、token、u8token、u8_token、hytoken、hy_token、sign、password、passwd、secret、access_token、refresh_token、id_token、session、sessionid、code、device_token、devicetoken、phone、mobile。 |
is_sensitive_key |
redact.rs:42 | 参数名小写比较后匹配上表。 |
mask |
redact.rs:49 | 生成掩码:保留首尾各 4 字符,中间 ***;长度 ≤ 8 时整体隐藏为 ***。 |
redact_url |
redact.rs:65 | 拆 query 逐参数脱敏;fragment 也脱敏;无 query 时原样返回(去 fragment)。 |
redact_text |
redact.rs:111 | 扫描标识符 + =/: 形态,命中敏感参数名时替换值(支持引号包裹的 JSON 形态)。 |
备注:
- 调用方:
gacha_service.rs:773(抽卡 URL 含 584 字节 u8token)、skland_service.rs:567(森空岛 API URL)、avatar_cache_service.rs:174、commands/image.rs:103、char_detail_service.rs:455。 - 前端对应实现:
src/utils/redact.ts(maskSecret/redactText)。 - 单元测试 7 条,覆盖 query 脱敏、非敏感参数保留、无 query、fragment、短值、key=value、JSON 形态。
职责:网络请求录制器(580 行)。以全局单例维护一个「活动会话」,把经 send/send_stream 发出的 HTTP 请求(含响应体)追加写入 JSONL;并提供会话的开始/停止/状态/列表/分页读取/删除等管理能力,供开发者抓包面板使用。
导出:CaptureBody、CaptureEntry、CaptureSessionMeta、CaptureStatus、CapturePage(数据结构);is_recording、capture_root、status、start、stop、list_sessions、read_entries、delete_session、send、send_stream(函数)。私有:ActiveSession、CaptureService、service()、active_lock()、valid_id、write_meta、status_of、headers_to_vec、encode_body、RequestMeta、Draft、write_entry、rebuild_response、常量与 RECORDING。
主要依赖:base64、bytes、chrono、reqwest、http、serde、uuid、super::paths、crate::{log_info, log_warn}。
| 符号 | 位置 | 说明 |
|---|---|---|
MAX_BODY_BYTES |
capture.rs:19 | 16 MiB,单个 body 截断上限 |
MAX_PAGE_SIZE |
capture.rs:20 | 500,read_entries 的 limit 上限 |
META_FILE / EVENTS_FILE |
capture.rs:21-22 | "meta.json" / "events.jsonl" |
static RECORDING: AtomicBool |
capture.rs:24 | 录制总开关,Relaxed 读写;start 置 true(capture.rs:179)、stop 置 false(capture.rs:185)、写文件失败也会置 false(capture.rs:410) |
| 符号 | 位置 | 说明 |
|---|---|---|
CaptureBody |
capture.rs:27 | encoding: String("utf8" 或 "base64")、size: u64(原始字节数)、truncated: bool、data: String |
CaptureEntry |
capture.rs:35 | 单条请求记录:index、timestamp、method、url、request_headers: Vec<(String,String)>、request_body: Option<CaptureBody>、status: Option<u16>、response_headers、response_body、duration_ms、error、note;每行一条 JSON 序列化后写入 events.jsonl |
CaptureSessionMeta |
capture.rs:51 | 会话元数据:id、started_at、ended_at: Option、status("recording"/"completed")、count、size_bytes、path(会话目录绝对路径);以 pretty JSON 存 meta.json(capture.rs:114) |
CaptureStatus |
capture.rs:62 | recording、session_id、started_at、count、size_bytes(仅 Serialize) |
CapturePage |
capture.rs:71 | total: u64(全文件有效行数)+ entries: Vec<CaptureEntry>(当前窗口) |
struct ActiveSession |
capture.rs:76 | meta + writer: BufWriter<File>(events.jsonl 句柄) |
struct CaptureService |
capture.rs:81 | active: Mutex<Option<ActiveSession>>,OnceLock 单例(capture.rs:85-90),锁中毒用 into_inner 恢复(capture.rs:92-94) |
<app_data>/network_capture/ # paths::capture_dir()(capture.rs:101)
└── <YYYYMMDD-HHMMSS>-<uuid8>/ # 会话 id,start() 生成(capture.rs:152-155)
├── meta.json # CaptureSessionMeta,pretty 格式
└── events.jsonl # 每行一个 CaptureEntry(紧凑 JSON)
| 符号 | 位置 | 说明 |
|---|---|---|
is_recording() -> bool |
capture.rs:96 | 读 RECORDING |
capture_root() -> Result<PathBuf, String> |
capture.rs:100 | = paths::capture_dir(),错误转 String |
valid_id(id) -> bool(私有) |
capture.rs:104 | 非空、≤64 字节、仅 [0-9A-Za-z_-] —— 防路径穿越(测试 capture.rs:555 校验 ../escape 被拒) |
write_meta(meta)(私有) |
capture.rs:112 | meta.path + meta.json,serde_json::to_string_pretty 后 fs::write |
status_of(Option<&Meta>)(私有) |
capture.rs:118 | 由元数据组装 CaptureStatus,无会话时全零/false |
status() -> CaptureStatus |
capture.rs:137 | 读活动会话元数据 |
start() -> Result<CaptureStatus, String> |
capture.rs:142 | 已在录制则直接返回现状(capture.rs:144-147);否则建根目录 → 生成 id {%Y%m%d-%H%M%S}-{uuid4 前 8 位}(capture.rs:152-154)→ 建会话目录 → 写初始 meta(status=recording)→ 以 create+append 打开 events.jsonl 并包 BufWriter → 置 RECORDING=true |
stop() -> Result<CaptureStatus, String> |
capture.rs:184 | 先清 RECORDING → 取出会话 → flush writer → meta 置 completed、写 ended_at、用 fs::metadata 回填真实 size_bytes(capture.rs:194-196)→ 重写 meta(失败仅 log_warn) |
list_sessions() -> Result<Vec<CaptureSessionMeta>, String> |
capture.rs:205 | 扫根目录子目录,读 meta.json(缺失/解析失败跳过);活动会话用内存中的最新 meta 覆盖(capture.rs:226-232);非活动但状态仍为 recording 的残留记录被就地修复为 completed 并回写(capture.rs:234-237);按 id 倒序(新会话在前,capture.rs:241) |
read_entries(id, offset, limit) -> Result<CapturePage, String> |
capture.rs:245 | 校验 id → 打开 events.jsonl → limit.clamp(1, 500) → BufReader::lines() 顺序扫描,跳过空行,累计 total,从 offset 起收集至多 limit 条(单行 JSON 解析失败则静默丢弃,capture.rs:262);O(total) 全文件扫描 |
delete_session(id) -> Result<(), String> |
capture.rs:272 | 校验 id → 若正录制的就是该会话则报 Cannot delete the session being recorded(capture.rs:280)→ 目录不存在视为成功 → fs::remove_dir_all |
| 符号 | 位置 | 说明 |
|---|---|---|
headers_to_vec(&HeaderMap)(私有) |
capture.rs:291 | 保留重复头(如多个 set-cookie)为 Vec<(name, value)>,value 用 from_utf8_lossy |
encode_body(&[u8]) -> CaptureBody(私有) |
capture.rs:303 | 超 16 MiB 截断并标 truncated(size 仍为原始长度);切片是合法 UTF-8 → utf8 原文;否则若「完整 bytes 是 UTF-8、仅截断处切断」也用 lossy 还原为 utf8(capture.rs:313-317),否则 base64 |
RequestMeta::from_request(&reqwest::Request) |
capture.rs:340 | 抓 method/url/headers/body(body.as_bytes(),仅当 body 为内存字节时可得) |
struct Draft + Draft::record(self) |
capture.rs:353、364 | 把「请求元数据 + 响应状态/头/体 + 耗时 + 错误」组装成 CaptureEntry(timestamp 精确到毫秒)后交给 write_entry |
write_entry(mut entry)(私有) |
capture.rs:383 | 未录制直接返回;活动会话 count += 1 并赋 entry.index = count(index 从 1 开始)→ serde_json::to_string 紧凑单行 → writeln! + 立即 flush;成功则 size_bytes += 行长+1,失败 log_warn 并把 RECORDING 置 false 停止录制(capture.rs:409-411) |
rebuild_response(status, headers, body) -> Response(私有) |
capture.rs:415 | 因为 send 需要读完 body 才能录制,故用 http::Response::new(body) 重组再 .into() 回 reqwest::Response |
send(client, builder) -> Result<Response, reqwest::Error>(pub async) |
capture.rs:422 | 未录制时零开销直通(recording.then(...) 不构造 meta,capture.rs:426-431);录制时计时 → execute → 成功则读 bytes():读到则录制(body 一并 encode)并返回重建的 Response(capture.rs:450);读 body 失败则录制 error+note="response body could not be read" 并把原始 Err 传出(capture.rs:452-464);请求失败也录制(无 status/body)后透传 Err |
send_stream(client, builder) -> Result<Response, reqwest::Error>(pub async) |
capture.rs:483 | 流式变体:不读 body,录制 note="streaming response, body not recorded"(capture.rs:507),原样返回 Response(供下载/更新等流式消费) |
mod tests |
capture.rs:528-579 | 三个测试:encode_body 文本/二进制/空、valid_id 路径穿越、headers_to_vec 重复头 |
| Tauri 命令 | 位置 | 转发到 |
|---|---|---|
capture_start |
commands/capture.rs:4-6 | capture::start() |
capture_stop |
commands/capture.rs:9-11 | capture::stop() |
capture_status |
commands/capture.rs:14-16 | Ok(capture::status()) |
capture_list_sessions |
commands/capture.rs:19-21 | capture::list_sessions() |
capture_read_entries(id, offset, limit) |
commands/capture.rs:24-30 | capture::read_entries(&id, offset, limit) |
capture_delete_session(id) |
commands/capture.rs:33-35 | capture::delete_session(&id) |
capture_dir |
commands/capture.rs:38-42 | capture::capture_root() + 额外 create_dir_all 后返回路径字符串 |
备注:
- 启动自动录制:lib.rs:157-174 在
.setup()中读配置键capture_autostart(默认 false),在任何 API 请求发出之前调用utils::capture::start()。 send/send_stream的调用方遍布全后端:commands/updater.rs:35/70、commands/image.rs:105、services/skland_service.rs:341/569/780/867/961/1060/1121、services/account_service.rs:1862/1916/2016/2079/2144/2872/2952/3008、services/gacha_service.rs:780、services/char_detail_service.rs:631、services/avatar_cache_service.rs:176、services/game_launcher_service.rs:180/462/665/2016/2175/2822。- 会话 id 同时充当目录名,所有读写路径都先经
valid_id白名单校验,杜绝../穿越。 - 数据结构(
CaptureEntry等)同时被commands/capture.rs直接导入并返回给前端。
职责:Windows 可执行文件图标提取(约 250 行)。Steam 库条目的 icon 字段只接受图片文件路径,因此把 Endfield.exe 内嵌的 RT_GROUP_ICON / RT_ICON 资源重新组装成标准 .ico 文件,供 utils::steam 的默认图标使用。
导出:extract_icon;私有:load_icon_bytes(Windows / 非 Windows 两份)、内部 ResourceName、LoadedModule(Drop 时 FreeLibrary)、read_resource、collect_group_names、wide、read_group_icon。
主要依赖:std::fs、std::path、windows_sys::Win32::{Foundation, System::LibraryLoader, UI::WindowsAndMessaging}(仅 Windows)。
| 符号 | 位置 | 说明 |
|---|---|---|
extract_icon(exe_path, out_path) |
:13 | 校验源 exe 存在 → 提取字节 → 建父目录 → 写 *.ico.tmp 后 rename 覆盖,避免 Steam 读到半个文件;返回 out_path |
load_icon_bytes(Windows) |
:41 | LoadLibraryExW(..., LOAD_LIBRARY_AS_DATAFILE) 打开 exe(LoadedModule 负责 FreeLibrary)→ EnumResourceNamesW(RT_GROUP_ICON) 收集图标组名 → 取 ID 最小的组(字符串命名回退第一个)→ 按 GRPICONDIR 逐项读 RT_ICON → 组装 ICONDIR + ICONDIRENTRY + 图像数据 |
load_icon_bytes(非 Windows) |
:244 | 恒返回错误(Windows 专用) |
mod tests |
:250 起 | 仅验证源文件不存在时返回 Err |
备注:资源名同时支持整型 ID(IS_INTRESOURCE,指针低位即 ID)与字符串形式;LockResource 数据在模块卸载前有效,因此先拷贝成 Vec<u8> 再释放。图标缓存路径由 commands/startup.rs::steam_icon_path 决定(%LOCALAPPDATA%\cn.msk-network.endprotocol\steam\endfield.ico)。
职责:游戏运行时长统计(196 行)。作为进程级单例,只统计 EndProtocol 自身运行期间的游戏进程在线时长:后台每 5 秒探测一次游戏进程(Endfield.exe / Arknights.exe 任一在跑即算在线),进程出现即开始一段会话、消失即把该段累加进总时长并落盘;应用启动时若游戏已在运行则从启动时刻算起,应用退出时若游戏仍在运行则计到退出时刻。两个游戏共用同一个总时长键("本机游戏时长合计")。
导出:TOTAL_SECONDS_KEY、GamePlaytime、init、snapshot、finalize;私有:常量 POLL_SECONDS/FOLD_SECONDS/GAME_PROCESS_NAMES、Inner、STATE、CONFIG、state、now_secs、poll_loop、update、persist。
主要依赖:serde::Serialize、std::sync::{Arc, Mutex, OnceLock}、std::time::{SystemTime, UNIX_EPOCH}、crate::services::config_service::ConfigService、crate::utils::process::is_process_running、tauri::async_runtime、tracing。
| 符号 | 位置 | 说明 |
|---|---|---|
TOTAL_SECONDS_KEY |
:19 | "game_playtime_total_seconds",累计总时长在 app_config.json 中的键(u64 秒) |
POLL_SECONDS / FOLD_SECONDS |
:22 / :25 | 进程探测间隔 5s;运行中每累积 60s 把已过去时长折入总数并落盘(崩溃安全) |
GAME_PROCESS_NAMES |
:31 | ["Endfield.exe", "Arknights.exe"]:两个游戏都要探测,否则玩明日方舟的时段会被漏掉 |
GamePlaytime(struct,Serialize) |
:35-42 | 前端快照:total_seconds(不含当前会话)、session_seconds(未运行为 0)、running |
struct Inner |
:44-50 | 内存态:total_seconds、session_start、running、first_poll、app_start |
static STATE / CONFIG |
:52-53 | OnceLock<StdMutex<Inner>> 与 OnceLock<Arc<StdMutex<ConfigService>>> 单例 |
state() / now_secs() |
:55 / :67 | 惰性初始化单例;当前 Unix 秒(失败为 0) |
init(config_service) |
:75 | 从 config 读回 total_seconds,记录 app_start,置首轮探测标记,CONFIG.set 后 tauri::async_runtime::spawn(poll_loop)。lib.rs 在静默/完整两种 setup 中均调用 |
poll_loop()(私有 async) |
:94 | 循环:遍历 GAME_PROCESS_NAMES 调用 is_process_running,任一为真即 update(true),然后 sleep 5s |
update(running)(私有) |
:108 | 会话开始(首次探测到运行从 app_start 算、否则从此刻算);会话结束累加并落盘;运行中每满 60s 折叠落盘 |
snapshot() -> GamePlaytime |
:152 | 汇报当前总数 + 实时会话(命令 launcher_get_game_playtime 的返回) |
finalize() |
:171 | 应用退出(RunEvent::Exit)时若仍在运行则计到此刻并落盘;幂等 |
persist(inner)(私有) |
:183 | 把 total_seconds 写入 ConfigService(app_config.json) |
备注:
- 事件/命令关联:
launcher_get_game_playtime(commands/launcher.rs)→snapshot;lib.rs 的.setup()调用init,.run(|_, event| …)在RunEvent::Exit调用finalize。 - 仅统计 EndProtocol 运行期间;游戏在软件未运行时的时间段不计入。运行中每 60s 折叠落盘,进程被强杀最多丢 60s。
- 两个游戏共用
game_playtime_total_seconds一个键:同时开着两个游戏也只计一份时间。 - 存储位置:
%LOCALAPPDATA%\cn.msk-network.endprotocol\app_config.json的game_playtime_total_seconds。 - 驻守实例(
--silent --launch-game,游戏退出后自行退出)不调用init:避免与同时运行的完整版重复累计,也减少多实例并发写配置文件;该会话的应用内时长不计入,由 Steam 记录游戏时长。
职责:进程探测与结束辅助(约 470 行)。供 launcher_check_game_running / launcher_kill_game 命令、启动前清理、驻守等待与游戏运行时长统计共用:「进程是否真的在运行」查询(排除崩溃/挂起后残留的无窗口进程)与「结束同名进程(含子进程树)」的执行原语。全部走 Win32 进程快照(CreateToolhelp32Snapshot)+ TerminateProcess,不再起 tasklist / taskkill 子进程:一个 tasklist 实测 340–390 ms,而一次原生快照只要 1–2 ms;OpenProcess 直接返回 ERROR_ACCESS_DENIED,「需要管理员权限」这个结论无须等待即可得出(旧实现因此把「点停止 → UAC 弹出」拖到 10 秒开外)。
导出:TerminateOutcome、is_process_running(async)、exists_once(sync)、wait_until_gone(sync)、terminate_processes(sync);私有:TERMINATE_WAIT、TERMINATE_POLL、STARTUP_GRACE_SECONDS、running_pids、TerminateOne、terminate_one、ProcEntry、snapshot_processes、exe_name_from_wide、descendants_of、has_top_level_window、process_is_starting;mod tests(仅 Windows)。
主要依赖:tokio::task::spawn_blocking、windows-sys(Win32_System_Threading、Win32_System_Diagnostics_ToolHelp、Win32_UI_WindowsAndMessaging,仅 Windows)。
| 符号 | 位置 | 说明 |
|---|---|---|
TerminateOutcome |
:17 | Nothing(本无同名进程)/ Terminated(已终止并确认消失)/ AccessDenied(至少一个进程拒绝当前权限,需要提权)/ StillRunning(已发出终止但短等待后仍存活)。后两者是调用方决定「要不要弹 UAC」的依据 |
TERMINATE_WAIT / TERMINATE_POLL |
:30 / :32 | 发出终止后等待消失的上限 1500 ms 与轮询间隔 50 ms;进程一消失立刻返回,不再固定等满 3 秒 |
STARTUP_GRACE_SECONDS |
:36 | 90 秒;新进程尚未创建窗口时仍视为「正在启动」 |
is_process_running(process_name) -> bool(pub async) |
:46 | Windows:spawn_blocking 内取一次快照 → 同名 PID 任一拥有顶层窗口,或创建时间在 STARTUP_GRACE_SECONDS 内,即视为运行中;无窗口的陈旧进程(如 Application Hang 后仍 STILL_ACTIVE 的残留)返回 false。join 失败记 debug 日志并返回 false;非 Windows 恒 false。调用方:commands/launcher.rs(launcher_check_game_running)、utils/game_playtime.rs(poll_loop)、lib.rs(wait_for_game_session) |
running_pids(私有) |
:70 | is_process_running 的同步内核:快照 → 名称匹配 → 窗口/启动宽限过滤 |
exists_once(process_name) -> bool(pub sync) |
:81 | 单次快照判定同名进程是否存在,不轮询。与 is_process_running 不同,不做窗口/启动宽限过滤(结束流程要的是「还有哪些同名进程活着」,包括界面判定为未运行的残留)。非 Windows 恒 false |
wait_until_gone(process_name, timeout) -> bool(pub sync) |
:97 | 循环 exists_once,一消失即返回 true,超时返回 false;非 Windows 恒 true |
terminate_processes(process_name) -> TerminateOutcome(pub sync) |
:125 | 取一次快照 → 命中的 PID 连同其全部后代(descendants_of,等价 taskkill /T /IM)逐个 OpenProcess(PROCESS_TERMINATE) + TerminateProcess;ERROR_ACCESS_DENIED 记为拒绝,其它失败(进程刚退出等)忽略。随后 wait_until_gone(TERMINATE_WAIT):起始无进程 → Nothing,消失 → Terminated,仍在且有拒绝 → AccessDenied,否则 StillRunning。非 Windows 返回 Nothing |
TerminateOne / terminate_one(私有) |
:174 / :182 | 单 PID 结果:Killed / AccessDenied / Gone(u32 错误码)(句柄打不开或 TerminateProcess 失败时携带 Win32 码便于排查) |
ProcEntry / snapshot_processes(私有) |
:219 / :227 | 一次全表进程快照(TH32CS_SNAPPROCESS + Process32FirstW/NextW,CloseHandle 收尾);失败返回空表,调用方据此得到「无同名进程」的保守结论 |
exe_name_from_wide(私有) |
:266 | szExeFile(NUL 结尾 UTF-16)→ String |
descendants_of(私有) |
:276 | 按 th32ParentProcessID 反复扩展出 roots 的全部后代;不收集父进程(游戏由提权 helper 创建,杀父等于结束自己) |
has_top_level_window(私有) |
:292 | EnumWindows + GetWindowThreadProcessId 判断 PID 是否拥有顶层窗口(跨完整性级别可见) |
process_is_starting(私有) |
:321 | OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION) + GetProcessTimes 读取创建时间,与当前时间比较 |
mod tests(私有,cfg(all(test, windows))) |
:353 | 6 个单测:后代收集含整棵子树、不追随父进程、szExeFile 截断、真机快照命中 svchost.exe、名字不存在时 Nothing 即时返回、端到端终止真实进程树(把 cmd.exe 复制成唯一名 eptest<pid>.exe 跑 ping -n 30,验证 Terminated 且根进程与 ping 子进程一起从快照消失) |
备注:仅按镜像名判断会把杀不掉的无窗口挂起进程误报为「游戏中」;窗口/启动宽限判定修复了该误报。游戏正常运行时拥有主窗口,不受影响。terminate_processes / exists_once 被 commands/launcher.rs(launcher_kill_game、launch_game 的启动前清理)、utils/official_launcher.rs(kill_game_process、提权 kill helper 的 run_kill_helper、helper 的 kill_existing_game)复用。TerminateOutcome::AccessDenied 让未提权一侧立刻知道该走 UAC,不必再做一轮存活轮询——这是「停止」按钮响应速度的关键。
职责:安装目录占用检测与持有锁(Windows 专用,非 Windows 退化为空实现)。回答两个问题:任务开始前目录里有没有进程锁着关键文件(游戏本体、杀软扫描、索引工具…)——有的话直接拒绝并报出是谁,不等到写盘阶段才甩一个匿名的 os error 32;任务进行中由我们自己独占打开关键文件持有句柄(DirLock,drop 释放),后来的进程打不开、无法再产生新占用。占用检测走 Restart Manager API(rstrtmgr,资源监视器「哪个进程锁住了文件」同款),一次报出锁定文件的全部进程(PID + 友好名 + exe 路径)。
导出:LockingProcess(pid/name/path,serde 可序列化)、DirOccupancy(locked/processes)、check_files(files) -> DirOccupancy、acquire_lock(files) -> Result<DirLock, String>、DirLock(acquire_empty() 空锁占位;unsafe impl Send——owned HANDLE 无线程亲和性)、sample_critical_files(install_path, exe_name, data_dir_name) -> Vec<PathBuf>(抽样:exe + xlua.dll/globalgamemanagers/boot.config + hgdownloadsdk.dll/U8SDK.dll/hgsdk.dll,只返回存在的)。
主要依赖:windows-sys(Win32_System_RestartManager:RmStartSession/RmRegisterResources/RmGetList/RmEndSession;Win32_Storage_FileSystem:CreateFileW 独占打开;Win32_System_Threading:QueryFullProcessImageNameW 取 exe 路径)。
| 符号 | 说明 |
|---|---|
check_files |
开 RM 会话 → 登记文件 → RmGetList(ERROR_MORE_DATA 时倍增缓冲重试)→ 按 PID 去重;会话失败记 warn 返回空(调用方兜底:真写失败时报 os error 32) |
acquire_lock |
逐文件 CreateFileW(dwShareMode=0)(读权限、不共享)——文件不存在跳过、存在却打不开则关闭已拿句柄并报错(带文件路径,多为别人先占了);句柄存 DirLock,drop 全关 |
mod tests |
2 个端到端单测:起一个独占持锁 20s 的 PowerShell → check_files 报出该进程(断言 path 含 powershell——RM 报的是友好名 "Windows PowerShell 5.1" 而非 exe 名)、被占用时 acquire_lock 失败且错误含文件名、kill 后 acquire_lock 成功;空闲文件报 locked=false 且 acquire_lock 成功 |
备注:调用方是 commands/launcher.rs 的 check_and_lock_install_dir(spawn_blocking 包装)——launcher_install_or_update / launcher_verify_and_repair / launcher_install_preload / launcher_switch_channel 四个写安装目录的命令在 acquire_write_gate 之后调用它;launcher_preload_download 只写独立暂存目录、不碰游戏文件,不做检测(游戏可边玩边预下载)。被占用时的错误以 LOCKED_BY:进程名 (PID n)|… 前缀返回,前端 formatDirLockError 解析为可读 message。
职责:Steam 第三方游戏(非 Steam 快捷方式)注入与 Overlay 权限辅助(Windows 专用,约 800 行,含二进制 VDF 单元测试)。直接读写当前账户的 userdata/<accountId>/config/shortcuts.vdf(二进制 VDF):按显示名匹配已有条目,命中则更新、否则追加。显示名、图标与启动选项全部由调用方传入(见 SteamShortcut)。另外提供「以管理员身份运行」.lnk 的创建与改写,以及「开始」菜单 Steam 快捷方式的发现。
导出:TYPE_OBJECT、SteamShortcut、add_shortcut、steam_root、create_elevated_shortcut、find_start_menu_steam_shortcuts、elevate_shortcuts;私有:VdfValue、ShortcutsFile、upsert_shortcut、field_string、set_string、set_i32、next_entry_index、steam_app_id、parse_shortcuts、encode_shortcuts、write_value、write_cstring、Parser、write_atomically、collect_steam_shortcuts、mark_shortcut_as_admin、run_powershell、powershell_literal、find_steam_root、read_registry_string、wide、find_shortcuts_file、modified_time(注册表/路径/快捷方式相关均仅 Windows)。
主要依赖:std::fs、std::path、std::time、base64、windows_sys::Win32::System::Registry(仅 Windows)。
| 符号 | 位置 | 说明 |
|---|---|---|
TYPE_OBJECT |
:20 | 0x00,VDF 对象类型字节;同时被 utils::game_icon 之外的外部测试使用 |
VdfValue / ShortcutsFile |
:31 / :42 | 解析后的 VDF 值与 shortcuts.vdf 根对象(根键、条目、尾部结束字节数) |
SteamShortcut |
:49 | 写入参数:name(显示名,同时用于去重)、exe_path、launch_options、icon_path: Option<&Path>(None 回退 exe 自身) |
add_shortcut(shortcut) |
:61 | 定位 Steam 根目录与 shortcuts.vdf → 读取(缺失视为空)→ 解析 → upsert → 原子写回;返回 shortcuts.vdf 路径;非 Windows 直接返回错误 |
steam_root() |
:95 | find_steam_root 的 Result 包装,供 add_steam_shortcut 定位 steam.exe |
upsert_shortcut |
:107 | 按 AppName 命中则更新 Exe/StartDir/icon/LaunchOptions/appid,否则以递增数字键追加完整字段(含空 tags 对象) |
steam_app_id |
:201 | CRC32(Exe + AppName) | 0x80000000,与 Steam 为非 Steam 快捷方式生成 ID 的算法一致 |
parse_shortcuts |
:216 | 解析根对象 shortcuts;空文件返回空列表;保留文件尾部 0x08 结束字节数量;遇到未知类型/尾部非 0x08 数据即报错,避免写回损坏文件 |
encode_shortcuts |
:246 | 按二进制 VDF 规则重新编码根对象与全部条目 |
write_value / write_cstring |
:258 / :309 | 各 VDF 类型(object/string/int32/float/pointer/wstring/color/uint64)写出 |
Parser |
:314 (entries :358) | 严格二进制 VDF 解析器:entries(:366)循环读取键值直到 0x08,wstring 读取 UTF-16LE 字符串 |
write_atomically |
:410 | 先写 shortcuts.vdf.tmp 再 rename 覆盖原文件 |
create_elevated_shortcut |
:443 | 用 WScript.Shell 定位目标/参数/工作目录/备注/图标并保存 .lnk,再通过 Shell.Application 的 Verbs() 执行「以管理员身份运行」动词;返回 .lnk 路径 |
find_start_menu_steam_shortcuts |
:515 | 枚举用户级(%APPDATA%)与公共级(%PROGRAMDATA%)「开始」菜单,返回文件名为 steam 的 .lnk(不含 steam:// 协议快捷方式,它无法承载 RunAsAdmin) |
elevate_shortcuts |
:586 | 逐个调用 mark_shortcut_as_admin;已提升的跳过,单个失败只记 warn 日志;返回本次实际修改的路径 |
mark_shortcut_as_admin |
:610 | 用 Shell.Application 查「以管理员身份运行」动词,存在则 DoIt() 并返回 Ok(true);动词不存在视为已勾选(Ok(false)) |
run_powershell |
:628 | -NoProfile -STA -NonInteractive -EncodedCommand 执行脚本(隐藏窗口),失败时把 stderr/stdout 作为错误详情 |
find_steam_root |
:681 | 依次尝试注册表 HKCU\Software\Valve\Steam\SteamPath、HKLM\SOFTWARE\WOW6432Node\Valve\Steam\InstallPath、HKLM\SOFTWARE\Valve\Steam\InstallPath,再回退 %ProgramFiles(x86)%\Steam / %ProgramFiles%\Steam;要求存在 userdata 目录 |
find_shortcuts_file |
:787 | 枚举 userdata/<纯数字账户>/config,取最近修改的 shortcuts.vdf;不存在时取最近修改的 config 目录并以其下路径作为新文件 |
备注:允许 Steam 运行期间写入(旧实现会拒绝)——Steam 退出时会用内存数据覆盖 shortcuts.vdf,因此命令层在成功提示中要求用户完全退出并重启 Steam;appid 以 i32 位模式写入。多账户时只写最近修改的账户目录。图标字段只接受文件路径,默认值由 commands/startup.rs 配合 utils/game_icon 生成 .ico。
职责:API 连续失败熔断器(约 300 行)。记录森空岛接口连续失败次数、分类与服务器时间偏差;达到阈值后置位全局 BLOCKED,后续 call_skland_api 立即失败,避免前端无限等待,并通过 app:api-health 事件通知前端弹出提示。熔断带冷却期(到点自动放行一次探测),不再是只能靠用户手动解除的永久闩锁。
导出:ApiFailureKind、ApiHealthSnapshot、CLOCK_SKEW_THRESHOLD_SECONDS、init、is_blocked、ensure_available、clear_after_repair、record_success、record_failure、reset、snapshot、classify_error、is_benign_business_error、is_session_invalid。私有:BLOCK_THRESHOLD、SIGNATURE_BLOCK_THRESHOLD、DEVICE_FINGERPRINT_BLOCK_THRESHOLD、BLOCK_COOLDOWN_SECS、ATTENDANCE_ALREADY_SIGNED_CODE、SESSION_INVALID_CODE、APP_HANDLE、BLOCKED、BLOCKED_UNTIL_MS、STATE、state、now_millis、clear_block。
主要依赖:chrono、serde::Serialize、std::sync::{Mutex, OnceLock}、std::sync::atomic、tauri::{AppHandle, Emitter}、crate::utils::AppError。
| 符号 | 位置 | 说明 |
|---|---|---|
BLOCK_THRESHOLD / SIGNATURE_BLOCK_THRESHOLD / DEVICE_FINGERPRINT_BLOCK_THRESHOLD |
文件头常量 | 普通错误连续 5 次、签名类 3 次、数美设备指纹 3 次触发熔断 |
BLOCK_COOLDOWN_SECS |
文件头常量 | 熔断冷却 120 秒;到点后 ensure_available 自动解除并放行一次探测(半开恢复) |
CLOCK_SKEW_THRESHOLD_SECONDS |
文件头常量 | 服务器时间与本地时间偏差 ≥180 秒即判定为时钟异常,单次失败也直接熔断 |
SESSION_INVALID_CODE |
文件头常量 | 森空岛「数据接口拒绝当前会话」的业务码 10000(文案 请求异常) |
ApiFailureKind(Serialize、snake_case) |
枚举 | ClockSkew / Signature / Auth / Network / Server / Parse / DeviceFingerprint / Unknown,作为事件与导出清单的枚举值;DeviceFingerprint 对应数美设备指纹接口失败(前端提示重启电脑并同步时区) |
ApiHealthSnapshot(Serialize) |
结构体 | blocked、consecutive_failures、kind、message、clock_skew_seconds、last_failure_at;Default 为未熔断空状态 |
init(app) |
init |
保存 AppHandle 供事件广播;状态惰性初始化 |
is_blocked() |
is_blocked |
当前是否熔断中 |
ensure_available() |
ensure_available |
已熔断且冷却未到时返回 AppError::AuthError(消息含失败次数与最后一次错误);冷却已到则自动解除并放行。call_skland_api 每轮请求前调用 |
clear_after_repair(reason) |
clear_after_repair |
凭证自愈成功后调用:解除熔断并清零,使随后的重试能真正发出 |
record_success() |
record_success |
未熔断时把计数/分类/偏差清零(任一成功请求即解除连续失败累计) |
record_failure(kind, message, clock_skew_seconds) |
record_failure |
累计失败;确认时钟偏差或达到阈值时置 BLOCKED + 写冷却到期时间,并 emit("app:api-health", snapshot),否则只记 warn 日志 |
reset() |
reset |
用户修复问题后清空熔断与计数(命令 reset_api_health) |
snapshot() |
snapshot |
返回当前状态(命令 get_api_health、诊断 manifest) |
classify_error(code, message, clock_skew_seconds) |
classify_error |
按服务器时间偏差 → 会话失效(先判) → 数美/deviceprofile/device_id → sign/timestamp/签名/过期 → cred/token/401/403 → 5xx 顺序分类 |
is_benign_business_error(code, message) |
is_benign_business_error |
白名单:code=10001(已签到)或文案含 重复签到/已签到/已经签到/already signed 时返回 true,表示「目标状态已达成」的幂等成功,不应计失败、重试或告警 |
is_session_invalid(code, message) |
is_session_invalid |
code=10000 或文案含 请求异常/unauthorized(且不是幂等结果)时返回 true:表示该 cred 已对数据域失效,唯一解法是换 cred,而不是重试网络 |
备注:
- 由
services/skland_service.rs的call_skland_api调用:请求前ensure_available,成功置record_success,HTTP/JSON/业务错误按类型record_failure;并从响应头Date计算本地时钟偏差。 call_skland_api在计失败/重试之前先用is_benign_business_error拦截「请勿重复签到」这类结果:命中即record_success()并原样返回 JSON(Ok,code非 0),由调用方按幂等成功处理(commands/attendance.rs::do_attendance、AccountService::do_attendance_for_role)。- 数美设备指纹(dId 获取)失败的计数在
SklandService::fetch_new_did内部完成(DeviceFingerprint,阈值 3),call_skland_api中 dId 失败不再重复计Network。 - 事件名
app:api-health;payload 即ApiHealthSnapshot。前端src/utils/crashReporting.ts监听后收起 Splash 并把账户标记为不可用(src/utils/accountAvailability.ts),弹窗为非致命,可关闭后继续使用应用。 10000 请求异常必须归为Auth而不是Server:它是服务端轮换会话后数据接口的单点拒绝(同一时刻/api/v1/user/check仍返回code=0)。归成Server会把「换一把 cred 就好」的问题报成网络故障并白白重试。判定顺序上is_session_invalid必须早于通用关键字匹配。- 熔断不得挡住修复路径:
SklandService::refresh_cred_by_hytoken与check_cred都不调ensure_available()。换 cred 只依赖 hytoken,是熔断的解药;若也被拦,恢复链会被自己锁死(旧行为:必须手动重新登录才能恢复)。 - 静默模式不初始化该服务(不建立 WebView,也无业务请求)。
职责:崩溃捕获与崩溃报告管理(约 250 行)。安装全局 panic hook,把 panic 消息、线程、位置、回溯、应用版本与系统信息写入 logs/crashes/crash-*.log;运行中通过 app:crash 事件通知前端;启动时读取未确认报告供弹窗展示,并提供 .ack 标记。
导出:CrashReportInfo、CrashEventPayload、set_app_handle、install_panic_hook、crash_dir、pending_reports、acknowledge。私有:APP_HANDLE、HOOK_INSTALLED、IN_HOOK、handle_panic、panic_message、write_report、ack_path、truncate_chars。
主要依赖:chrono、serde::Serialize、std::backtrace::Backtrace、std::panic、tauri::{AppHandle, Emitter}、super::paths、super::logger::try_get_logger。
| 符号 | 位置 | 说明 |
|---|---|---|
CrashReportInfo(Serialize) |
:17-25 | path、file_name、timestamp、message、content(截断到 24000 字符)、acknowledged |
CrashEventPayload(Serialize) |
:27-35 | message、location、thread、backtrace、report_path、timestamp;app:crash 事件体 |
set_app_handle(app) |
:37 | 在 Tauri setup 中保存 AppHandle,供 hook 广播事件 |
install_panic_hook() |
:43 | 幂等替换全局 panic hook;lib.rs 在业务初始化前调用 |
handle_panic(info)(私有) |
:50 | IN_HOOK 防递归;捕获 payload/位置/线程/回溯;写报告、写后端日志、安全写 stderr;有 handle 时 emit("app:crash") |
crash_dir() |
:132 | %LOCALAPPDATA%\cn.msk-network.endprotocol\logs\crashes |
write_report(content)(私有) |
:138 | 文件名为 crash-YYYYMMDD-HHMMSS-<pid>.log |
pending_reports() |
:152 | 扫描 crash-*.log,跳过已有 .log.ack 的文件;按时间倒序取最近 5 条 |
acknowledge(paths) |
:211 | 仅接受崩溃目录内的 .log,写入 crash-*.log.ack 标记已读;防路径穿越 |
truncate_chars / ack_path(私有) |
:240 / :244 | 字符级截断;ack 文件路径 |
备注:崩溃目录与 app-YYYY-MM-DD.log 同属 logs/;export_diagnostics 会把所有 crash-*.log 一并打包。write_report 失败时仅通过 safe_eprintln 输出,不再递归触发 hook。
职责:诊断日志导出(约 163 行)。把前端日志、后端内存日志、当日 app-*.log / startup.log、崩溃报告与系统/API 状态清单打包成 zip,写入 logs/exports/。
导出:FrontendLogEntry、export。私有:DiagnosticsManifest、write_archive_contents、add_text、add_file。
主要依赖:chrono、serde、zip(ZipWriter / SimpleFileOptions / CompressionMethod)、super::{api_health, crash, logger, paths}、tauri::AppHandle。
| 符号 | 位置 | 说明 |
|---|---|---|
FrontendLogEntry(Deserialize/Serialize) |
:13-22 | 与 src/utils/logger.ts 的 LogEntry 对齐:timestamp、level(数字)、message、module、source、data? |
DiagnosticsManifest(Serialize) |
:24-32 | 应用名、版本(app.package_info())、ISO 时间、OS/架构、调用方上下文、ApiHealthSnapshot |
export(app, frontend_logs, context) |
:34 | 创建 endprotocol-diagnostics-YYYYMMDD-HHMMSS.zip;失败时删除半成品并返回错误 |
write_archive_contents(...)(私有) |
:62 | 依次写入 manifest.json、frontend-logs.json、backend-logs.txt、logs/app-*.log、logs/startup.log、crashes/crash-*.log |
add_text / add_file(私有) |
:143 / :155 | 向 zip 写入字符串 / 文件字节(Deflated 压缩) |
备注:不打包 app_config.json、网络抓包或图片缓存,避免泄露凭证;由命令 export_diagnostics(commands/diagnostics.rs:15)调用,前端在崩溃弹窗、Splash 错误面板与开发者页「导出诊断日志」按钮中使用。
- logger.rs 无日志轮转/清理:仅按启动日期命名
app-YYYY-MM-DD.log,文件句柄常驻不跨天切换,旧日志永不删除;同时文件与内存缓冲不做级别过滤(Debug 全量落盘)。 已修复(Android 适配):改为LoggerConfig::default()中current_dir().unwrap()在 cwd 不可用时会 panicpaths::log_dir()→current_dir()/logs→temp_dir()/endprotocol-logs的逐级回退,全程无 panic。- HTTP 客户端超时策略不统一:
http_client::create_client(30s)仅被 3 个 service 使用,多处仍直接reqwest::Client::new()(无显式超时),game_launcher_service 另建自定义 client。 - hg_crypto 的测试
test_decrypt_roundtrip_key_iv只断言常量长度(hg_crypto.rs:126-130),并未真正验证解密逻辑;AES key/IV 为明文硬编码(逆向常量)。 read_entries为全文件顺序扫描(capture.rs:256-267),大会话下分页读取开销 O(文件行数);单行 JSON 解析失败会被静默丢弃,可能导致total与前端可见条目不一致。