steam-frame/LisherSong--ps5-web-file-manager
1
0 Fork 0
mirror of https://github.com/LisherSong/ps5-web-file-manager.git synced 2026-10-06 08:00:23 +02:00
Code Issues Packages Projects Releases 2 Wiki Activity
Files
f85e60ed8c7374bc48b7d72295ef11ecfaad010a
LisherSong--ps5-web-file-ma…/docs/USER-GUIDE-zh-CN.md
T
Songlx516 ba668ade50 release: v1.9.3M -- encrypted archives, plus the UI round that followed 
First release under the fork-marker convention: VERSION_TAG carries a trailing
`M`, so /api/version, the PS5 start-up notification, the stdout banner, the UI
footer and the ELF file name all read "v1.9.3M" in one move -- and a fork build
can no longer collide with an upstream artifact of the same version, a mix-up
that already happened twice. The footer carries a tooltip spelling the marker
out.

Two bodies of work.

1. Encrypted archives (ZIP / RAR / 7z)

   - ZIP: ZipCrypto (traditional PKWARE) and WinZip AES-256, through
     minizip-ng plus a vendored crypto layer (mz_crypt_wfm.c,
     mz_strm_pkcrypt.c, mz_strm_wzaes.c).
   - RAR: RARSetPassword, wired after RAROpenArchiveEx and before the first
     RARReadHeaderEx. The ordering is load-bearing, not stylistic.
   - 7z: 7zAES including -mhe=on encrypted headers, via a virtual
     ISeekInStream that splices a pseudo-header + the real archive + the
     decrypted header, so no offset stored inside the archive has to move.

   A wrong password is reported as ZIPX_ERR_PASSWORD, and a failed attempt
   leaves no staging directory behind.

2. Reporting, and the UI round that on-device testing produced

   - A RAR whose dictionary exceeds what the build supports now gets its own
     extract_dict_too_large code instead of being mis-reported as "entry too
     large"; the message names both the required and the supported size. The
     behaviour is deliberately unchanged -- such archives are still refused,
     because admitting one means allocating the whole window up front, which
     is why rarlab's own CLI refuses them by default.
   - The upload entry is a menu again: one "Upload" button opening "Upload
     files / Upload folder". The previous main-button-plus-small-arrow made
     "upload folder" effectively undiscoverable.
   - A drag-and-drop hint sits in the footer (hidden on the console browser,
     where drag is not how anyone uploads).
   - The extract button is now always present and merely disabled until
     exactly one archive is selected, instead of appearing out of nowhere.
   - Upload-and-extract on an encrypted archive now prompts for the password
     directly. The retry table used to be keyed by PATH, and for a non-ASCII
     directory the string the page holds and the string the server reports
     are not the same bytes -- the lookup missed, so the user got a bare
     error box and had to press Extract by hand before the prompt appeared.
     It is now keyed by task id, which the server assigns and echoes back
     verbatim.
   - Error text passes through decodeFsText(), so a GBK entry name no longer
     surfaces as `â®…ç§.psd`.
   - Local names are encoded with encodeFsText() before being joined onto a
     server-side path. fs_path_value() declines to rewrite a path if ANY code
     point exceeds 0xFF, so concatenating a local name onto a server directory
     produced a mixed representation and a silently dead path.
   - The menu row highlight was losing the cascade to the generic button rule
     (identical specificity, later in the file) while inheriting the toolbar's
     3px focus ring, which overflowed a 46px row. Both rules are now scoped to
     the panel and the keyboard cue is an inset ring, so it cannot escape the
     row at any line height.
   - The footer status line is clamped to a single line; a long
     "uploading 3/12: some-name.zip" used to wrap out of the 46px footer.
   - A first failed password attempt now says the archive is encrypted,
     instead of blaming a password the user was never asked for.

Artifact
  web-file-mgr-v1.9.3M.elf
  903,448 B
  sha256 8ca47d5aaca75085b32641300cce30fadb7df7749cb6b53d04f129bcecc286b7
  e_machine 0x003e (x86-64 / PS5)

  The file size is identical to the four builds before it, and every one of
  them carries a different sha256: only .rodata moved, and by less than the
  16 KiB section alignment absorbs. Compare sections with `readelf -SW` --
  never infer "nothing changed" from the byte count.

Verification
  - host suites: 140 ZIP + 37 RAR = 177 checks, 0 failures
  - 7z suite: 27 cases, 0 failures. The `aeshe` entry that used to sit in
    KNOWN_GAPS is gone -- the -mhe=on fixture now passes both the folder
    decoder and the extraction facade
  - frontend: .build/ui_retry_test.mjs (40 checks), .build/ui_upload_menu_test.mjs
    (40 checks), .build/preview_check.mjs (12 assertions in headless Chromium
    against the real page and a fixture API). Two layout regressions and the
    highlight cascade bug were caught by the last one and by nothing else --
    reading the source, both CSS rules "look correct"
  - built twice from this tree: byte-identical (cmp clean). rsync refreshes
    every asset mtime, so this is a genuine recompile, not make short-circuiting
    on unchanged sources
  - embedded assets verified in place with .build/check-elf-gzip.py, because
    gen-asset-module.py gzips them and plain `strings` finds none of their text
  - exercised end to end on a real PS5; the checklist is
    docs/DEVICE-TEST-v1.9.3M.md

Docs
  - docs/USER-GUIDE-zh-CN.md (new, simplified Chinese user guide)
  - docs/DEVICE-TEST-v1.9.3M.md (new, on-device acceptance checklist)
  - docs/REAL-CONSOLE-PROFILE.md (new, measured console behaviour)
  - docs/archive/HANDOVER-v1.8-planning.md (superseded v1.8 design notes)
  - CHANGELOG / README (both languages) / HANDOVER updated with the artifact
    fingerprint, the section deltas and the new test counts
2026-09-24 21:07:12 +08:00

13 KiB
Raw Blame History

简体中文 · 开发者文档见 README

PS5 网页文件管理器 · 新手使用说明

适用版本：v1.9.3M（版本号末尾的 M = 改版，文末有解释） 本文不假设你懂任何技术名词，照着做即可。

一、它到底是什么

一句话：在你的 PS5 上开一个"网页版文件管理器"。只要设备和 PS5 连着同一个 WiFi，用手机、电脑、甚至 PS5 自带的浏览器打开一个网址，就能像在电脑上一样管理 PS5 里的文件和插在 PS5 上的 U 盘。

能做的事

想干什么 可以吗
看文件、建文件夹、改名、复制、移动 ✅
电脑 ↔ PS5 互传文件 ✅
解压 ZIP / RAR / 7z（带密码的也行） ✅
改小的文本文件（.txt .json .ini 等） ✅
看图片（.png .jpg .gif .webp 等） ✅
安装 PKG ✅
改文件权限 ✅

不能做的事（先说清楚，省得白试）

想干什么 可以吗 说明
把一堆文件打包成压缩包 ❌ 它只会"解"，不会"压"。下载多个文件时会自动打成一个 .tar 包，那只是下载用的
同时做两件事 ❌ 一个任务在跑的时候，其它操作会被拒绝（提示"有任务正在执行"）
删错了找回 ❌ 删除是永久的，没有回收站
解压 ZIP / RAR / 7z 以外的格式 ❌ 比如 .tar.gz、.iso、.xz 现在不行，见第七节

二、三步把它跑起来

第 1 步：PS5 上先运行一个"ELF 加载器"（常见端口是 9021）。这一步取决于你用的越狱方案，这里不展开。

第 2 步：在电脑上把程序发过去。 打开终端（Windows 用 Git Bash / PowerShell 都行），执行：

nc -q0 你的PS5的IP 9021 < web-file-mgr-v1.9.3M.elf

例如你的 PS5 是 192.168.1.50：

nc -q0 192.168.1.50 9021 < web-file-mgr-v1.9.3M.elf

第 3 步：看 PS5 左上角的通知。 它会显示程序名、版本和一个网址，通常是：

http://192.168.1.50:8888/

在浏览器里打开这个网址就行。如果通知显示的端口不是 8888（比如 8889），以通知为准 —— 端口不是写死的，程序会自动挑一个能用的。

第一次运行时，它还会在 PS5 主屏装一个「PS5 Web File Manager」快捷方式（Media 分类）。已有的不会被覆盖。

三、界面上都是些什么

打开页面后大致是这样：

  • 最上面 / 侧边：选"去哪儿"。会看到 内部存储、USB存储、M2扩充存储、扩展存储、根分区 这几项，点哪个就进哪个。
  • 中间的大列表：当前文件夹里的内容，可以按名称、类型、大小、修改时间、权限排序（排序方式会被记住）。
  • 列表每一行的按钮：下载、解压（压缩包才有）、安装（.pkg 才有）、文本编辑、改权限、删除等。
  • 上方工具条：复制、移动、重命名、下载、删除、解压、上传（点开选"上传文件 / 上传文件夹"）、新建目录、新建文本、刷新、退出。
    • 解压按钮一直都在，只是没选中压缩包时是灰色的、点不动。选中一个压缩包（.zip / .rar / .7z）它才会变亮可点。鼠标停在灰色按钮上会告诉你为什么不能点。
  • 右下角：版本号（这里应该显示 v1.9.3M）。

界面截图（点击看大图）：

界面截图 1 界面截图 2 界面截图 3

小提示：用 PS5 自带浏览器 打开时，"上传"和"下载"按钮是隐藏的（PS5 浏览器不支持）；要用电脑或手机浏览器才能传文件。

四、六个最常用操作

1. 把电脑上的文件传到 PS5

  1. 用电脑或手机浏览器打开那个网址（不要用 PS5 浏览器）。
  2. 进入你想放到的文件夹。
  3. 点 上传，在弹出的列表里选 上传文件（可多选）或 上传文件夹（整个目录一起传）。
  4. 也可以直接把文件或文件夹拖进网页——页脚那行灰字就是提醒这件事的。拖进来后会提示"松开即上传到当前目录"。
  5. 看到全屏进度条就是开始传了，可以随时取消。

2. 在 PS5 内部搬运文件（比如 U 盘 → 内置存储）

  1. 选中要搬的项目 → 点 复制（保留原文件）或 移动（不保留）。
  2. 进入目标文件夹 → 点 粘贴。
  3. 会有几秒到几十秒的"准备中"（它在统计大小和检查目标空间够不够），别急。

3. 解压一个压缩包

  1. 在列表里找到那个包，点它右边的 解压。
  2. 问你"若目标已存在同名文件或目录"时：
    • 确定 = 同名文件覆盖掉（同名文件夹会合并进去）
    • 取消 = 只要目标已经有同名东西就直接失败（这是默认，最安全）
  3. 如果包是加密的，会弹出密码框，输入密码即可。密码错了会让你重填，最多 3 次。
    • 上传压缩包时如果你选了"上传后自动解压"，加密包会自己弹密码框，不用先手动点一次"解压"。
    • 第一次弹框写的是"此压缩包已加密"（因为还没输过密码）；之后才写"密码不正确"。

⚠️ 强烈建议每次解压都新建一个空文件夹作为目标。 已知问题：往同一个文件夹里第二次用"覆盖"解一个含文件夹的压缩包，会失败。换个空文件夹就没事。

4. 分卷压缩包怎么解

一个文件被切成好几段的那种（比如 xxx.part1.rar / xxx.part2.rar，或 xxx.z01 + xxx.zip，或 xxx.7z.001 …）：

  • RAR：必须点第一个分卷（xxx.part1.rar 或 xxx.part01.rar）。点到后面的卷，按钮是灰的，会提示"请改选主卷"。
  • ZIP / 7z：点第一卷即可，其余会自动接上。
  • 整卷必须在同一个文件夹里，少一个都会失败（提示"压缩包损坏或不完整"）。

5. 改一个文本文件

点文本文件右边打开编辑器即可。限制：文件 小于 1 MiB，且是纯文本（UTF-8）。太大或不是文本会被拒绝。

6. 安装 PKG

点 .pkg 文件右边的 安装，会先显示这个包的标题等信息，确认后提交给系统安装。

五、解压的"规矩"（为什么有的包不给解）

它不是拿到包就解，而是先检查，不符合规矩会直接拒绝。这是为了保护你的 PS5 不被一个恶意压缩包搞崩。默认规矩：

规矩 上限
包里的文件/文件夹数量 20 万个
解压后的总大小 2 TiB
单个文件最大 512 GiB
压缩比（解压后 ÷ 压缩包） 500 倍
文件夹最多嵌套多少层 32 层

包特别大时（磁盘上超过 480 GiB），它会问你要不要开「大文件模式」：开了之后上限放宽到 50 万个 / 4 TiB / 单个 1 TiB / 1000 倍。

还有一条最容易踩的：硬盘要留出大约"两份"空间。 它是先把东西解到一个临时地方，确认全部成功后才整体搬过去 —— 所以一个解压后 50 GB 的包，你得有大约 100 GB 可用空间。空间不够会直接告诉你"需要 X，可用 Y"。

六、看到这句话，是什么意思

界面上显示 说人话 怎么办
密码错误，或压缩包未使用所提供的密码加密 密码不对，或者这个包根本没加密你却填了密码 重填（最多 3 次）；确认密码大小写
此压缩包已加密，密码不正确 同上，重试提示 输入正确密码，或取消
目标空间不足，需要 X，可用 Y 硬盘不够 记住要留两份空间；删东西或换更大的盘
压缩包内单个文件过大 包里有个超大文件，超过默认 512 GiB 出现提示时选「大文件模式」；或拆包
压缩比异常（疑似压缩炸弹） 一个很小的包声称能解出一大堆东西，被判定为危险 基本是恶意包，别解
目标已存在同名文件或目录 目标位置已经有同名东西了 换一个空文件夹（推荐），或在提示时选"确定"覆盖
压缩包损坏或不完整 包坏了，或分卷少了一卷 重新下载/拷贝，确认所有分卷都在同一目录
不支持的压缩包 不是 ZIP / RAR / 7z，或用了它处理不了的特性 在电脑上解好再传
压缩包需要的字典超出本机可承受范围 极少数用超大设置压的 RAR，PS5 解不动 在电脑上用普通设置重新压一次
请改选主卷 你点的是分卷的后面几卷 点第一个分卷（.part1.rar / .part01.rar）
有任务正在执行 已经有一个活儿在干 等它结束，或先取消它
操作失败 其它错误 记下原文，反馈时带上

七、和原版（上游）有什么不一样

这个程序是从开源项目 owendswang/ps5-web-file-manager 改来的。下面是和你有关的差别，说人话：

对你意味着什么 原版（上游 v1.8） 本版（v1.9.3M）
要装几个东西 两个：主程序 + 一个上百 MB 的 7-Zip 辅助程序，还得放到固定目录 /data/wfm/。辅助文件丢了，解压功能直接全废 就一个文件，拷上去就能用
能解多少种格式 约 30 种（.tar.gz .xz .cab .iso 类……） 3 种：.zip .rar .7z
带密码的压缩包 靠 7-Zip 支持 三种格式都支持，密码错了会弹框让你重填（最多 3 次）
RAR 分卷 支持 支持（要点第一个分卷）
防"压缩炸弹"/防硬盘写满 ❌ 没有，交给 7-Zip 自己看着办 ✅ 有：压缩比筛查、提前算空间够不够
失败后会不会留下一堆半成品 会（直接解到目标目录，中断就留在那儿） 不会：先解到临时地方，全部成功才整体搬过去，失败自动清理
程序被重启后，正在解的任务 还能接着跑（辅助程序是独立进程） 会丢（关掉浏览器再打开还能看到进度，但程序本身重启就没了）
出错时的提示 比较笼统 会告诉你具体是哪个文件、差多少字节
版本号长什么样 v1.8、v1.9 这样纯数字 v1.9.3M，末尾多一个 M

一句话总结

  • 原版赢在"格式多"：.tar.gz、.xz 这类它也能解，本版不行。如果你经常遇到这三种以外的格式，原版更方便。
  • 本版赢在"省心和安全"：一个文件就完事，不会因为你少放一个辅助文件就整个不能用；也不会被一个恶意压缩包写满你的内置存储、或者在半路留一堆垃圾。

M 是什么意思

版本号末尾的 M = Modified（改版）。上游原版是纯数字（如 v1.8），所以：

  • 看到 v1.9.3M → 这是本仓的改版
  • 看到 v1.9.3（没有 M）→ 那不是本仓出的

这个字母会同时出现在：文件名、PS5 启动通知、网页右下角。网页右下角把鼠标悬停在版本号上，会弹出说明文字。

八、怎么确认你装的是哪一版

看哪里 应该显示
网页右下角 v1.9.3M
PS5 启动时的通知 程序名 + v1.9.3M + 监听端口
浏览器打开 http://<PS5的IP>:<端口>/api/version JSON 里的版本号 = v1.9.3M

只要界面上显示带 M 的版本号，就说明装对了。

九、几条重要提醒

  1. 解压时别断电、别重启 PS5。 它为了速度不做逐文件强制落盘，如果在最后搬运阶段断电，可能出现"文件在，但内容不完整"。
  2. 解压前确认空间够，而且是两份（见第五节）。
  3. 每次解压用新的空文件夹，别往同一个目录连解两次（见第四节第 3 条）。
  4. 删除不可恢复。 删文件夹会把它里面所有东西都删掉，弹窗会提醒。
  5. 一次只做一件事，有任务在跑时其它操作会被拒绝。
  6. 这是自制程序。如果遇到 PS5 内核崩溃，请换更新的越狱方式 / ELF 加载器，或回到你常用的稳定方案。
Reference in new issue View Git Blame Copy Permalink