webMAN MOD 的 wm_proxy XMB 代理插件:绕过浏览器直挂游戏与执行 Web 命令的完整原理与实战解析

原创2026-10-14 18:41:181,755 阅读
文章标签:嵌入式后端网络

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 菜单调用,用于完成两件事:

  1. 挂载游戏(mount games);
  2. 执行 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” 一节概括了整体流程,结合源码可以拆解为以下五个环节:

  1. 菜单加载:wm_proxy 插件由 XMB 上的 XML 游戏列表菜单加载(“The wm_proxy plugin is loaded by XML game list menu on XMB”)。
  2. 模块映射:为了绕过 xmb_plugin 对模块引用的限制,wm_proxy 被映射到系统的 idle_plugin 模块,映射手段是 Cobra 的 sys_map_path,而 idle_plugin 是一个索引化模块(indexed module)。
  3. 命令传递:插件通过所选菜单项的 module_action 参数接收到 Web 命令字符串。
  4. 本地 HTTP 请求:插件据此构造一条 GET 请求,通过回环地址 127.0.0.1、端口 80 发送给 webMAN 的 Web 服务器。
  5. 回退挂载:如果 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_plugin as module and a web command as module_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 编译开关与文件名

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() 解析使用)。

参考文件索引(均可从仓库根目录直接打开):

登录后查看全文
webMAN-MOD