webMAN MOD 的 wm_proxy XMB 代理插件:绕过浏览器直挂游戏与执行 Web 命令的完整原理与实战解析
webMAN MOD 的 wm_proxy XMB 代理插件:绕过浏览器直挂游戏与执行 Web 命令的完整原理与实战解析
本篇技术指南以
_Projects_/wm_proxy/README.md为核心,深入讲解 webMAN MOD 中wm_proxy这一非驻留式(non-resident)sprx 插件的工作机制:它如何由 XMB 上的 XML 游戏菜单调用、如何通过 Cobra 的sys_map_path映射为系统idle_plugin绕过模块引用限制、如何把module_action参数构造成 GET 请求发给 webMAN 内置 Web 服务器(127.0.0.1:80),以及在 Web 服务器不可用时如何回退为直接调用 Cobra 命令挂载各类镜像。读完本文,你将掌握 wm_proxy 的调用约定(XMBML 中module/module_action的写法)、支持与不支持的挂载类型边界、底层源码调用链,以及它在 webMAN MOD 中的集成方式与编译方法。
一、wm_proxy 是什么
wm_proxy 是 webMAN MOD 集成的一个非驻留式(non-resident)sprx 插件,它的作用由项目根目录 README.md 概括为:“Proxy that redirects XMB menu actions to web commands”(把 XMB 菜单动作重定向为 Web 命令的代理)。
根据 Projects/wm_proxy/README.md 的定位描述,该插件由 webMAN MOD 生成的 XMB 菜单调用,用于完成两件事:
- 挂载游戏(mount games);
- 执行 Web 命令(perform web commands)。
其核心价值在于:无需加载 PS3 内置的 Internet 浏览器(webbrowser)。传统的做法是 XMB 菜单项通过 webrender_plugin 打开一个指向 xmb://localhost/... 的浏览器页面来间接触发挂载,而 wm_proxy 直接在本机发起 HTTP 请求,避免浏览器进程带来的内存占用与加载延迟。
wm_proxy 并非从零编写,而是基于 DeanK 为 webMAN / sMAN 发布的同名 wm_proxy 改造而来(README 中明确标注 “It's based on wm_proxy released by DeanK for webMAN / sMAN”,并由 aldostools 进行修改、扩展与优化,Mysis 提供了 VSH exports)。
二、工作原理总览
README 以 “How it works” 一节概括了整体流程,结合源码可以拆解为以下五个环节:
- 菜单加载:wm_proxy 插件由 XMB 上的 XML 游戏列表菜单加载(“The wm_proxy plugin is loaded by XML game list menu on XMB”)。
- 模块映射:为了绕过
xmb_plugin对模块引用的限制,wm_proxy 被映射到系统的idle_plugin模块,映射手段是 Cobra 的sys_map_path,而idle_plugin是一个索引化模块(indexed module)。 - 命令传递:插件通过所选菜单项的
module_action参数接收到 Web 命令字符串。 - 本地 HTTP 请求:插件据此构造一条 GET 请求,通过回环地址
127.0.0.1、端口80发送给 webMAN 的 Web 服务器。 - 回退挂载:如果 webMAN 的 Web 服务器没有运行,XMB 代理会尝试使用 Cobra 命令直接挂载文件;只有特定文件类型支持这种直挂方式,否则屏幕上显示 “webMAN not ready!” 提示。
2.1 为何要映射到 idle_plugin
xmb_plugin 对哪些模块可以被 XMB 菜单引用有严格限制。webMAN MOD 的编译开关 flags/flags_full.h 对此做了明确注释:
#define WM_PROXY_SPRX "idle_plugin" // plugin used as xmb proxy to mount games (idle_plugin, xai_plugin, wboard_plugin, bdp_disccheck_plugin)
注释列出了可选的替代模块名:idle_plugin、xai_plugin、wboard_plugin、bdp_disccheck_plugin。默认选择 idle_plugin,是因为该模块是系统中“常驻引用”的索引化模块,把 wm_proxy 的 sprx 路径映射到它上面,就能让 XMB 在解析菜单 XML 时找到并加载这个自定义插件,而不触碰系统限制。该限制同样可以在 vsh/xmb_plugin.h 的模块枚举中看到(idle_plugin=0x36)。
2.2 请求构造与发送
wm_proxy 的入口处理函数是 main.c 中的 wm_plugin_action()。它首先对 module_action 传来的字符串做规范化处理:
static void wm_plugin_action(const char * action)
{
if(*action == 'G') action += 4; // skip GET
if(*action != '/') action += 16; // using http://127.0.0.1/ or http://localhost/
if(*action != '/') return;
这段代码说明 module_action 可以携带两种形式的命令:一种是 裸路径(如 /mount.ps3/dev_hdd0/PS3ISO/xxx.iso),另一种是 完整 URL(如 http://127.0.0.1/mount.ps3/... 或 http://localhost/mount.ps3/...)。如果以 GET 开头会跳过 4 个字符,如果以 http://127.0.0.1/(16 个字符)或 http://localhost/ 开头则会跳过 16 个字符,最终都收敛到以 / 开头的命令路径。
随后调用 connect_to_webman()(见 main.c)建立到 webMAN Web 服务器的 TCP 连接,其关键细节如下:
- 使用
AF_INET/SOCK_STREAM创建 TCP socket; - 目标地址硬编码为
0x7F000001,即 127.0.0.1(localhost); - 端口硬编码为 80(
htons(80)); - 连接阶段设置
SO_SNDTIMEO为 3 秒,连接建立后放宽到 60 秒,避免长时间阻塞。
连接成功后,把 module_action 中的命令串逐字节复制进 GET 请求缓冲区(见 main.c),并进行两类字符转义:
- 空格(
0x20)转换为+(0x2B); - 当路径不含
.ps/_ps时(即不是.ps3这类命令关键字),+字符再转义为%2B,防止路径中的加号被误解码。
最终组装出形如 GET /mount.ps3/dev_hdd0/PS3ISO/GAME.iso\r\n 的请求头发送出去,然后立即 shutdown 并关闭 socket(sclose,见 main.c)。注意,这里发送的是未带 HTTP 版本号和 Host 头的最小化 GET 请求,足以让 webMAN 服务器识别并执行对应命令——这正是“不加载浏览器即可执行 Web 命令”的关键。
三、在 XMBML 菜单中的用法
README 的 Usage 一节给出了插件的使用方式:
Using XMBML, create an XML item with
idle_pluginasmoduleand a web command asmodule_action
即:用 XMBML 创建一个 XML 菜单项,把 idle_plugin 作为 module(模块名),把一条 Web 命令作为 module_action(模块动作)。
这条约定在 webMAN MOD 的菜单生成器 include/scan/games_xml.h 中有完整的实现佐证。该文件顶部定义了两种“菜单项公共片段”:
#define XAI_LINK_INC "<T key=\"inc\">" XML_PAIR("module_name", WM_PROXY_SPRX) XML_PAIR("bar_action", "none") "</T>"
#define WEB_LINK_INC "<T key=\"inc\">" XML_PAIR("module_name", "webrender_plugin") "</T>"
XAI_LINK_INC:把菜单项的module_name设为WM_PROXY_SPRX(即idle_plugin),对应 wm_proxy 代理模式;WEB_LINK_INC:把module_name设为webrender_plugin,对应传统的浏览器模式。
webMAN MOD 在生成游戏列表时(games_xml.h)会根据运行环境自动选择:
#ifdef WM_PROXY_SPRX
if((cobra_version > 0) && file_exists(WM_PROXY) && !(webman_config->wm_proxy)) {proxy_include = (char*)XAI_LINK_INC, *localhost = NULL;}
#endif
条件包括:Cobra 版本可用、wm_proxy.sprx 文件存在、且用户在设置中没有显式禁用 wm_proxy。满足条件时每个游戏条目都会带上 XAI_LINK_INC 片段,并把 localhost 前缀置空(直接以 / 开头的裸路径作为 module_action)。
实际生成的游戏条目模板(games_xml.h)形如:
<T key="0000" include="inc">
<P key="icon"><>…/ICON0.PNG</></P>
<P key="title"><>游戏标题</></P>
<P key="module_action"><>0/mount_ps3/dev_hdd0/PS3ISO/Game.iso</></P>
…
</T>
其中 module_action 的值为 0/mount_ps3 + 挂载路径,0 在这里即“localhost”的代称(源码中 char localhost<a href="https://link.gitcode.com/i/cfa25499d7fb596f74724f1aee3c36fd" target="_blank">2]; strcopy(localhost, "0");)。同理,卸载条目使用 0/mount_ps3/unmount(见 [games_xml.h)。在菜单项被激活时,XMB 会把 module_action 的值传给 idle_plugin(即 wm_proxy),从而触发上述的本地 GET 请求流程。
四、webMAN 不可用时的直接挂载:支持与不支持的边界
README 明确指出:如果 webMAN 的 Web 服务器没有运行,XMB 代理会尝试使用 Cobra 命令直接挂载文件。这一回退逻辑对应 main.c:
sclose(&s);
}
else if(mount(action))
{
show_msg("webMAN not ready!");
}
即 connect_to_webman() 失败(返回 -1)时进入 mount() 分支(实现在 Projects/wm_proxy/mount.h),只有挂载失败时才弹出 “webMAN not ready!” 提示。
4.1 可以直接挂载的文件类型
README 列出以下类型可以由代理直接挂载(在显示 “webMAN not ready!” 之前):
| 类型 | 说明 | 对应源码分支 |
|---|---|---|
| GAMES / GAMEZ | JB(jailbreak)文件夹格式 | cobra_map_game(path, "TEST00000", 1)(mount.h) |
| PS3ISO | 含多分卷 ISO(.iso.0 序列) |
cobra_mount_ps3_disc_image(files, count) |
| PS2ISO | 含多分卷 ISO | cobra_mount_ps2_disc_image(...) |
| PS2 Classics | PS2 经典游戏 | .enc + CONFIG 软链到 PS2U10000 |
| PSXISO | — | cobra_mount_psx_disc_image(iso_file, tracks, num_tracks) |
| PSPISO | — | cobra_set_psp_umd(path, NULL, "/dev_hdd0/tmp/wm_icons/psp_icon.png") |
| BDISO | 含多分卷 ISO | cobra_mount_bd_disc_image(files, count) |
| DVDISO | 含多分卷 ISO | cobra_mount_dvd_disc_image(files, count) |
| ROMS | 复古 ROM | 映射到 PKGLAUNCH / RetroArch |
这些分支在 mount() 中按路径关键字依次匹配(mount.h):
- GAMES / GAMEZ:调用
cobra_map_game(),本质是通过sys_map_path把/dev_bdvd、/app_home映射到游戏目录,并用build_blank_iso()(cobra/cobra.c)生成一个空白 ISO 作为占位光盘,随后触发假光盘插入事件。 - PS3ISO / PS2ISO / PSXISO / PSPISO / BDISO / DVDISO:按路径段分发到对应的
cobra_mount_*_disc_image()系列函数,这些函数最终调用sys_storage_ext_mount_*_discfile()系统调用(见 cobra/storage_ext.h)。 - PS2 Classics:把
.enc加密镜像与对应.CONFIG通过 LV2 的fs_link(syscall 810,见 mount.h)链接到 PS2 启动器固定路径/dev_hdd0//game/PS2U10000/USRDIR/ISO.BIN.ENC与CONFIG,随后提示 “Use PS2 Launcher to play the game”。 - PSXISO:会先尝试解析同名
.cue文件(read_cue(),实现在 cue_file.h),解析出的音轨(TrackDef)连同 LBA 一起传给cobra_mount_psx_disc_image(),以正确模拟 CD 的多音轨结构。 - ROMS:映射 PKGLAUNCH 为
/dev_bdvd,并把 ROM 路径写入launch.txt与PARAM.SFO,再借助 RetroArch 核心运行。 - 多分卷 ISO:当路径以
.iso.0/.ISO.0结尾时,mount()会从.iso.0开始依次探测.iso.1、.iso.2……直到cellFsStat失败为止(mount.h),把所有分卷路径收集到files[]数组中一并交给 Cobra 挂载。
挂载成功后,插件通过 explore_plugin 的 ExecXMBcommand("close_all_list", 0, 0) 关闭列表(mount.h,接口定义见 explore_plugin.h),等待 500ms 后调用 cobra_send_fake_disc_insert_event() 触发“光盘已插入”事件,让系统识别刚挂载的镜像。
4.2 不能直接挂载的类型与限制
README 明确列出以下类型无法由代理直接挂载(即必须依赖 webMAN 服务器在线处理):
- 远程网络文件(ps3netsrv):注意,源码 mount.h 中其实保留了针对
/netX/路径读取/dev_hdd0/tmp/wm_config.bin中 ps3netsrv 服务器配置并加载netiso.sprx的逻辑,但其中/PS2ISO、/PSPISO分支直接返回失败,且 README 将该类列为不支持直挂,属于“保留实现、限定行为”的边界情况。 - 存储在 exFAT / NTFS / ext2/3/4 分区上的外部 ISO 或 FakeISO:源码中对
.ntfs<a href="https://link.gitcode.com/i/83fe9c0441627c248ccecbf3f98815a8" target="_blank">...]路径(FakeISO,[mount.h)有“读取头部并加载 raw_iso.sprx”的实现,但整体仍归入不支持直挂之列,需要 webMAN 在线。 - GAMEI:已解包(PKG 安装内容)的游戏数据目录。
- PS2ISO 与 PS2 Classics 的 Auto-CONFIG:自动配置不参与直挂。
- PS2 的 Cue/CCD 与 PS1 的 CCD cuesheet:不支持。
- webMAN MOD 的 Web 命令:除
/mount.ps3、/restart.ps3、/shutdown.ps3之外的 Web 命令都无法在 webMAN 离线时直挂执行。
后三个“例外命令”在 mount.h 中有专门实现:
/restart.ps3:调用system_call_3(SC_SYS_POWER, SYS_SOFT_REBOOT, NULL, 0)软重启;/shutdown.ps3:调用system_call_4(SC_SYS_POWER, SYS_SHUTDOWN, 0, 0, 0)关机;/mount.ps3:走上述完整的挂载分发流程;- 另有
/dev_blind(通过 syscall 837 挂载CELL_FS_FAT到/dev_blind,见 mount.h)与/remap.ps3?path&to=dest(sys_map_path路径重映射)两个辅助命令。
五、从源码看实现细节
5.1 插件生命周期与 VSH 接口挂钩
wm_proxy 是一个标准 PRX 插件,入口在 main.c:
SYS_MODULE_INFO(wm_proxy, 0, 1, 1);
SYS_MODULE_START(prx_start);
SYS_MODULE_STOP(prx_stop);
SYS_MODULE_EXIT(prx_stop);
prx_start() 把参数中的视图句柄交给 setInterface(),后者通过 getNIDfunc() 从 paf 模块导出表中取回 plugin_SetInterface / plugin_SetInterface2,注册 4 个回调函数(init / start / stop / exit),其中核心是 wm_plugin_init,它把 wm_plugin_action 作为 ACT0(0x41435430)接口动作注册给对应视图(main.c)。当 XMB 菜单项被选中时,module_action 的值就会通过 ACT0 回调进入 wm_plugin_action()。
5.2 VSH 导出表解析与屏幕提示
getNIDfunc()(main.c)直接读取 0x1008C 处的 VSH 模块表地址,遍历每个导出结构,按模块名与 FNID 匹配函数指针——这是 PS3 homebrew 中常见的“无链接动态取函数”手法。show_msg() 借此取得 vshtask 模块的 0xA02D46E7 函数,用于在屏幕上弹出 “webMAN not ready!” 之类的提示信息。
5.3 命令串的 URL 解码
直挂流程中,mount() 首先对 module_action 里的 URL 编码做解码(mount.h):
if(*c == '+') *t = ' ';
else if(*c == '%') {*t = (h2b(c[1])<<4) + h2b(c[2]); c += 2;}
h2b()(mount.h)把十六进制字符转成字节,因此 /mount.ps3/dev_hdd0/PS3ISO/My%20Game.iso 会被正确还原为带空格的真实路径。
六、在 webMAN MOD 中的集成方式
6.1 编译开关与文件名
- 模块名开关:
WM_PROXY_SPRX定义于各 flags 文件(如 flags/flags_full.h、flags/flags_lite.h、flags/flags_noncobra.h),默认值为字符串"idle_plugin"。 - 插件文件路径:include/init/paths.h 定义
WM_PROXY为资源目录下的wm_proxy.sprx。 - 资源分发:更新器把
res/wm_proxy.sprx复制到 webMAN 的资源目录(见 Projects/updater/source/main.c),并在 Projects/updater/README.md 中将 wm_proxy 列为 webMAN MOD 的资源文件之一(与 slaunch、vsh menu、netiso、raw_iso、video_rec 并列)。
6.2 用户开关:wp 参数
webMAN MOD 提供了在浏览器设置页切换“使用 wm_proxy 还是 webbrowser 插件”的开关:
- 配置结构体 include/init/wm_config.h 中的
u8 wm_proxy; // [15] 0=use wm_proxy, 1=use webbrowser_plugin; - 设置解析 include/setup.h:
webman_config->wm_proxy = IS_UNMARKED("wp=1");,即 URL 参数wp=1表示禁用 wm_proxy; - 设置界面 include/setup.h:
add_checkbox_line("wp", "wm_proxy", !(webman_config->wm_proxy), buffer);生成 “wm_proxy” 复选框。
VSH 菜单(Projects/vsh_menu/main.c)中也复用了同一个 wm_proxy 字段:0=use wm_proxy, 1=use webbrowser_plugin。也就是说,用户可以在不重新编译的情况下,通过设置页或 VSH 菜单在“代理直连”与“浏览器中转”两种模式间切换。
6.3 与浏览器模式的对比
两种模式的差异集中体现在 XML 的 module_name 上:
- wm_proxy 模式:
module_name=idle_plugin,module_action为裸路径或0/mount_ps3/...,由 wm_proxy 直接向 127.0.0.1:80 发 GET; - 浏览器模式:
module_name=webrender_plugin,module_action通常为xmb://localhost...形式的 URL,由 PS3 浏览器渲染并间接触发 Web 命令。
wm_proxy 模式省去了浏览器进程,启动更快、内存占用更低,这正是 README 强调 “without load the PS3 Internet browser” 的出发点。
七、编译与构建
wm_proxy 独立于 webMAN MOD 主工程构建,其 Makefile 要点如下:
- 源文件:
libc.c cobra/cobra.c main.c(PPU_SRCS),目标是wm_proxy.prx; - 链接库:
-lfs_stub -lstdc_export_stub -lnet_stub -lio_stub,并链接仓库根目录lib/下的导出桩库; - 编译选项:
-Os -fno-builtin-printf -nodefaultlibs -std=gnu99等; - 加密:构建完成后调用仓库根目录的
scetool把裸 PRX 加密打包为wm_proxy.sprx(-0 SELF ... -e $(PPU_PRX_TARGET) $(PPU_SPRX_TARGET)); - 需要 PS3 官方 SDK(
CELL_SDK)环境(include $(CELL_SDK)/samples/mk/sdk.makedef.mk),并使用ppu-lv2-gcc交叉工具链。
构建产物 wm_proxy.sprx 由更新器随 webMAN MOD 一起分发,最终通过 paths.h 定义的位置被主程序检测并启用。
八、局限性与适用前提
- 依赖 Cobra:直接挂载路径依赖 Cobra 扩展的系统调用(
sys_map_path、sys_storage_ext_*、syscall8等),因此仅在支持 Cobra 的自制固件(CFW)环境下生效。games_xml.h 中启用代理的前置条件也是cobra_version > 0。 - 依赖 webMAN 在线:除直挂支持的文件类型与三个例外命令外,其余 Web 命令都要求 webMAN Web 服务器运行在 80 端口;离线时只弹 “webMAN not ready!”。
- 格式边界明确:ps3netsrv 远程文件、exFAT/NTFS/ext 外部 ISO 与 FakeISO、GAMEI、Auto-CONFIG、PS2 Cue/CCD、PS1 CCD 等不在直挂范围内,需要走 webMAN 服务器路径。
九、致谢与归属
按照 Projects/wm_proxy/README.md 的 Credits 一节,wm_proxy 的贡献者包括:
- DeanK:原始 sLaunch GUI 概念与编码(也是原始 wm_proxy 的发布者);
- aldostools:修改、新增功能与优化(webMAN MOD 的维护者,将插件整合进本项目);
- Mysis:VSH exports(VSH 导出符号,供
getNIDfunc()解析使用)。
参考文件索引(均可从仓库根目录直接打开):
- 核心文档:wm_proxy/README.md
- 插件主程序:wm_proxy/main.c、wm_proxy/mount.h、wm_proxy/cue_file.h
- Cobra 封装层:wm_proxy/cobra/cobra.c、wm_proxy/cobra/cobra.h、wm_proxy/cobra/storage_ext.h
- 菜单生成与集成:include/scan/games_xml.h、include/init/paths.h、include/init/wm_config.h、include/setup.h、flags/flags_full.h
- 构建脚本:wm_proxy/Makefile