v1.0.2 — API 令牌所需权限说明 / documents the required API token permissions

说明 API 令牌所需权限 —— 默认新建的令牌权限不够。
Documents the required API token permissions — the default token preset is not enough.

---

中文

重要：新建 API 令牌时，默认权限不够

在 CloudDrive2 → 设置 → API 令牌 中新建令牌，默认勾选的是一组只读权限。其中插件需要的两项默认是关闭的，必须手动勾上：

权限（CloudDrive2 中的名称）	默认勾选	插件用它做什么
推送消息（Push Messages）	❌ 否	订阅文件系统变化推送 —— 媒体库实时更新的全部基础
获取挂载点（Get Mounts）	❌ 否	读取挂载点表 —— 路径映射与网盘账号列表
列出文件（List Files）	✅ 是	解析路径、强制重新列出目录
读取文件（Read Files）	✅ 是	播放预热

漏勾的后果比较隐蔽：插件能连上，状态页显示正常，但媒体库永远不会自动更新。

症状对照

• GET /CloudDrive/Status 显示 Connected: false，或 LastError 提到权限 → 多半漏了推送消息
• GET /CloudDrive/PathMappings 返回空或报错 → 漏了获取挂载点

其余权限一律不需要 —— 插件不会写入、删除或修改任何文件。

本次改动

• 插件设置页的「API 令牌」输入框下方直接列出所需权限，并标明哪两项默认不勾选
• README 增加权限说明表与症状对照

功能代码没有改动。

---

English

Important: the default API token preset is not enough

Creating a token under CloudDrive2 → Settings → API tokens gives you a read-only preset. Two of the four permissions this plugin needs are not in it and must be ticked by hand:

Permission (as named in CloudDrive2)	On by default	What the plugin uses it for
Push Messages (推送消息)	❌ No	Subscribing to the file-system change stream — all of the live library updates
Get Mounts (获取挂载点)	❌ No	Reading the mount table — path mappings and the cloud account list
List Files (列出文件)	✅ Yes	Resolving paths, forcing a folder re-list
Read Files (读取文件)	✅ Yes	Playback prefetch

Missing them fails quietly: the plugin connects, reports healthy, and simply never updates a library.

Symptom guide

• GET /CloudDrive/Status showing Connected: false, or a LastError mentioning permissions → Push Messages is missing
• GET /CloudDrive/PathMappings empty or erroring → Get Mounts is missing

Nothing else is needed. The plugin never writes, deletes or modifies a file.

Changes

• The plugin settings page now lists the required permissions directly under the API token field, marking which two are off by default
• README gained a permissions table and the symptom guide

No functional code changes.

v1.0.1 — 修复插件在 Emby 4.9.0.x 上不显示 / fixes the plugin not appearing on Emby 4.9.0.x

修复版本：解决插件在部分 Emby 版本上不显示的问题。
Fix release: the plugin failed to appear in the plugin list on some Emby versions.

---

中文

本次修复

有用户反馈：把插件放进插件目录、重启 docker 之后，插件设置里看不到 CloudDrive。

原因：v1.0.0 是按 Emby SDK 4.9.1.90 编译的，程序集引用被固定在这个版本上。.NET 在解析引用时，只接受版本相同或更高的已加载程序集，不接受更低的。所以在 Emby 4.9.1 及以上一切正常（我们测试的环境都是），但在 Emby 4.9.0.x 上所有 MediaBrowser 引用都会解析失败，插件类型加载不出来，插件就从列表里消失了 —— 而服务器本身照常启动，所以除了"插件不见了"没有别的现象。

服务器日志里会看到：

ReflectionTypeLoadException: Unable to load one or more of the requested types.
Could not load file or assembly 'MediaBrowser.Common, Version=4.9.1.90' ...

v1.0.1 改为按 Emby 4.8 的 SDK（4.8.0.80）编译，引用固定在 4.8.0.80，于是 4.8.0.80 及以上的所有 Emby 都能正常加载。已实测：在 Emby 4.9.5.0 上插件正常出现在列表中，各接口工作正常。

功能没有任何改动，只是编译目标不同。

最低服务器版本

• Emby 4.8.0.80 或更高（低于此版本会在日志里报 ReflectionTypeLoadException，插件不显示）
• Jellyfin 10.11

升级方法

直接用新的 DLL 覆盖旧的，然后重启服务器即可。

⚠️ 在容器里替换 DLL 请重启容器，只按服务器自身的「重启」按钮不够。

---

English

What this fixes

A user reported that after dropping the plugin in and restarting docker, CloudDrive never appeared in the plugin settings.

v1.0.0 was compiled against Emby SDK 4.9.1.90, which pins the assembly references to exactly that version. .NET binds a reference to an already-loaded assembly only when the loaded version is equal or higher, never lower. So 4.9.1+ worked — which is everything we tested — but on Emby 4.9.0.x every MediaBrowser reference fails to resolve, no plugin types load, and the plugin quietly disappears from the list while the server boots normally.

The server log shows:

ReflectionTypeLoadException: Unable to load one or more of the requested types.
Could not load file or assembly 'MediaBrowser.Common, Version=4.9.1.90' ...

v1.0.1 is compiled against the Emby 4.8 SDK (4.8.0.80) instead, so the references satisfy every server from 4.8.0.80 upwards. Verified in both directions: the 4.8-compiled build lists correctly and answers all endpoints on a live Emby 4.9.5.0.

No functional changes — only the compile target.

Minimum server version

• Emby 4.8.0.80 or newer (older logs a ReflectionTypeLoadException and the plugin never appears)
• Jellyfin 10.11

Upgrading

Replace the DLL and restart the server.

⚠️ Replacing the DLL inside a container? Restart the container, not just the server.

v1.0.0 — CloudDrive companion plugin for Emby & Jellyfin

⚠️ 此版本在 Emby 4.9.0.x 上无法加载（插件不会出现在插件列表中）。请改用 v1.0.1。
This build fails to load on Emby 4.9.0.x — the plugin will not appear in the list. Use v1.0.1 instead.

CloudDrive2 companion plugin for Emby & Jellyfin — first release.
CloudDrive2 媒体服务器伴侣插件 —— 首个正式版本。

---

中文

把 Emby / Jellyfin 与同一主机上的 CloudDrive2 连接起来。

功能

• 媒体库实时更新，且可把"实时监控"全部关掉 —— 没有启动时的递归遍历，不占用 inotify watch，也没有开机时的云端列目录风暴。第三方刮削器（tinyMediaManager / MoviePilot / MDCx 等）在挂载目录里刮削、重命名、生成 nfo 和封面后，影片会自动出现在媒体库中。
• 按播放行为预热 —— 起播预热文件头尾，接近片尾预热同目录下一个文件，停止播放时释放网盘连接。所有客户端一并受益，不限于 CloudDrive2 App。
• 免配置路径映射 —— CloudDrive2 App 自动推算直连播放的路径映射。此项需要 CloudDrive2 App 1.0.14 或更高版本（尚未发布，即将推出）。

前两项是纯服务端功能，不需要安装 CloudDrive2 App。只要在跑 Emby/Jellyfin + CloudDrive2，装上插件即刻生效。

⚠️ 文件系统变化通知是 CloudDrive2 会员（Pro）功能。 非会员账号收不到变化推送，媒体库不会自动更新。

安装

• Emby —— 解压后把 CloudDrive.MediaServer.dll 直接放进插件目录（不要建子文件夹，也不需要 meta.json）：

  <emby-programdata>/plugins/CloudDrive.MediaServer.dll
  

• Jellyfin —— 把整个压缩包解压到插件目录下的一个子文件夹，保持 meta.json 和 thumb.png 与 DLL 放在一起：

  <jellyfin-config>/plugins/CloudDrive/CloudDrive.MediaServer.dll
  <jellyfin-config>/plugins/CloudDrive/meta.json
  <jellyfin-config>/plugins/CloudDrive/thumb.png
  

重启服务器，然后在 控制台 → 插件 → CloudDrive 中填写 CloudDrive2 地址与 API 令牌。详见 README。

在运行中的容器里替换 DLL，请重启容器，只按服务器自身的"重启"按钮不够 —— 直接覆盖同名 DLL 可能让容器仍按旧文件长度读取，导致插件加载失败。

已验证版本

Emby 4.9.5.0 与 Jellyfin 10.11.11（均为 docker 部署）。构建自 03e9840。

---

English

Connects Emby / Jellyfin to a CloudDrive2 instance on the same host.

Features

• Live library updates with real-time monitoring switched off — no recursive walk at startup, no inotify watches, no burst of cloud listings when the server boots. Third-party scrapers (tinyMediaManager / MoviePilot / MDCx) that scrape, rename and write .nfo + artwork on the mounted folder now land in the library by themselves.
• Playback-aware prefetch — warms the file head and tail at start, the next file in the same cloud folder near the end, and releases cloud readers on stop. Benefits every client the server serves, not just the CloudDrive2 App.
• Zero-config path mapping — the CloudDrive2 App discovers direct-play path mappings automatically. Needs CloudDrive2 App 1.0.14 or later (not yet released — coming soon).

The first two are server-side only and need no CloudDrive2 App. If you run Emby/Jellyfin + CloudDrive2, installing the plugin is the whole install.

⚠️ File-system change notification is a CloudDrive2 Pro (membership) feature. Without it no change pushes arrive and the library will not update by itself.

Install

• Emby — unzip CloudDrive.MediaServer.dll directly into the plugin directory (no subfolder, no meta.json):

  <emby-programdata>/plugins/CloudDrive.MediaServer.dll
  

• Jellyfin — unzip the whole archive into a subfolder of the plugin directory, keeping meta.json and thumb.png beside the DLL:

  <jellyfin-config>/plugins/CloudDrive/CloudDrive.MediaServer.dll
  <jellyfin-config>/plugins/CloudDrive/meta.json
  <jellyfin-config>/plugins/CloudDrive/thumb.png
  

Restart the server, then set the CloudDrive2 address and API token under Dashboard → Plugins → CloudDrive. See the README for details.

Replacing the DLL inside a running container? Restart the container, not just the server — overwriting in place can leave the container reading at the old file length, which fails to load.

Verified on

Emby 4.9.5.0 and Jellyfin 10.11.11 (both docker). Built from 03e9840.