plugin: ship JFVR as a real Jellyfin plugin (self-hosted catalog)

Replaces the deploy.py approach (which sed-patched index.html inside the
container, and was therefore lost on every jellyfin/jellyfin upgrade) with a
proper plugin installable from a Jellyfin plugin repository.

The web bundle is unchanged: the same src/*.js -> dist/jfvr.js is now embedded
in Jellyfin.Plugin.JFVR.dll and served from /JFVR/jfvr.js with a content-hash
cache key. index.html is rewritten at request time by an IStartupFilter
middleware, so nothing on disk is touched.

Verified before this commit:
  - dotnet build: 0 warnings, 0 errors (net10.0, Jellyfin.Controller 12.1.0)
  - the DLL embeds dist/jfvr.js byte for byte
  - 19/19 checks on the rewrite logic (injection, idempotency, legacy-tag
    takeover, no </body> safety, other scripts preserved, URL override)
  - manifest.json passes Jellyfin's PackageInfo/VersionInfo expectations
  - the packaged zip's MD5 matches the checksum the manifest advertises

Details that were checked against the Jellyfin source rather than assumed:
  - a catalog version survives when targetAbi <= serverVersion, so a single
    targetAbi 12.0.0.0 package covers all of 12.x (server is 12.1.0)
  - Jellyfin writes meta.json itself at install time, so the zip needs only
    the DLL
  - Jellyfin verifies the MD5 at install time

Also adds pack.py (build -> package -> manifest -> Gitea release) and documents
the plugin route in README/HANDOFF, keeping deploy.py as a fallback.
This commit is contained in:
2026-10-17 23:17:00 +08:00
parent 0713f35513
commit f4fe3d61fc
15 changed files with 1256 additions and 9 deletions
+15 -6
View File
@@ -386,7 +386,13 @@ cd /home/cat/Desktop/myProject/jelllyfin_vr_web_plugin
# 语法检查(全部模块)
python3 build.py --check
# 构建 + 部署(自动构建 → 上传 → 注入 script 标签)
# ---- 插件路线(推荐)----
python3 pack.py # 构建 + 打包 + 更新 manifest.json
python3 pack.py --bump --publish # 版本号 +1,建 Gitea Release,上传 zip,推 manifest
python3 pack.py --print-urls # 只打印 Jellyfin 要填的仓库地址
# 需要 GITEA_TOKEN(write:repository),从环境变量或 secrets.local.md 读
# ---- 老路线:直接注入容器内文件(兜底)----
# 密码从环境变量读;真实值放在本地 secrets.local.md(不入库)
export JF_PW='<NAS 密码>'
python3 deploy.py
@@ -401,7 +407,8 @@ python3 deploy.py --legacy
./quest.sh
```
**部署后必须让用户刷新页面**(脚本按页面加载缓存,URL 里的 `?r=<md5前6位>` 是破缓存用的)。
**插件路线**:Jellyfin 里点更新/重装 → 重启 → 刷新浏览器。
**老路线**:部署后必须让用户刷新页面(脚本按页面加载缓存,URL 里的 `?r=<md5前6位>` 是破缓存用的)。
### 诊断信息
@@ -432,10 +439,12 @@ errors[] 最近错误
## 10. 长期隐患
1. **注入写在容器内文件**(`/jellyfin/jellyfin-web/index.html`)→
`jellyfin/jellyfin:latest` 一升级就没了,需重跑 `deploy.py`。
正式版应改用 **JavaScript Injector**(`n00bcodr/jellyfin-plugins` 的 `12/manifest.json`,
targetAbi 12.0.0.0)或 **File Transformation**(`IAmParadox27/jellyfin-plugin-file-transformation`,554⭐)。
1. ~~**注入写在容器内文件**(`/jellyfin/jellyfin-web/index.html`)→ `jellyfin/jellyfin:latest`
一升级就没了~~ —— **已解决**:现在是插件 `Jellyfin.Plugin.JFVR`,在请求时改写
`index.html`,磁盘上的 web 目录一个字节都不动。见 `plugin/` 和 `pack.py`,
安装地址 `https://git.cat-shark.xyz/cat-shark/jellyfin_vr_web_plugin/raw/branch/main/manifest.json`。
`deploy.py` 保留作为兜底(两者不要同时用)。
剩下的维护成本:Jellyfin 升大版本时可能要重新编译(插件对 `Jellyfin.Controller 12.1.0` / net10.0)。
2. **Three.js 从 CDN 加载**(1.27MB)→ 依赖外网。可改为本地托管。
3. **Quest 浏览器版本会随系统更新变化** → 能力探测(诊断信息里的能力段)是唯一的自检手段。