7.2 KiB
小组件只读接口
MoviePilot App 的系统小组件直接读取用户连接的 MoviePilot 实例。中央 MoviePilot Server 不接收业务快照或小组件凭据。这些接口不改变普通 Web/PWA 的请求和登录行为。
启用与移除
前台 App 先使用既有主登录读取 GET /api/v1/widget/context。标准响应的 data 只包含
version=1、不可变 owner 和当前 availableContents，不会创建、轮换或列出任何登记。
没有可用内容时返回空集合。App 用不可变身份核对组件资料与当前网页账号，不能仅比较可复用的
数字用户 ID 或显示名；组件专用凭据不能调用该接口。此响应禁止缓存，不能用旧上下文替代当前校验。
前台 App 在用户明确启用后，使用既有登录调用
POST /api/v1/widget/registrations，请求体只包含随机 UUID installationId。
标准响应的 data 包含 version=1、registrationId、installationId、不可变 owner、
secret、expiresAt 和 availableContents。secret 只返回这一次，数据库只保存 SHA-256 摘要。
凭据有效期为 30 天，每个账号最多 10 个有效安装。同账号同安装再次登记会在一个事务中 撤销旧凭据并保存新凭据，安装名额不变。登记必须串行执行；响应丢失后可以重新登记， 但会再次轮换，不能恢复旧密钥，也不应由 HTTP 客户端自动重放写请求。并发登记按提交顺序覆盖。 扩展不能自行续期；主 App 通过现有登录更新授权。
主登录可调用 DELETE /api/v1/widget/registrations/{registrationId} 移除自己的单个登记。
专用凭据可调用 DELETE /api/v1/widget/registration 撤销自身，不能指定其他安装。
没有公开的凭据列表，不返回其他用户的登记存在性。
刷新与权限
GET /api/v1/widget/snapshot 只接受 Authorization: Bearer <secret>，不接受 URL 查询、
Cookie、主登录 JWT、资源令牌或 API_TOKEN。小组件凭据也不能用于普通 REST/MCP 业务 API。
快照直接返回下述模型，不额外包裹标准响应的 data。成功和鉴权错误均禁止共享缓存。
每次请求都重新检查登记、到期、激活账号、不可变身份及最新权限；来源读取完成后再次检查， 等待中的撤销、改名或权限变化会阻止旧快照返回。账号删除时级联清理；即使主键复用或旧库 存在残留登记，新建账号也不能继承旧授权。
| 内容 | 授权和数据范围 |
|---|---|
overview |
仅超级管理员；复用 CPU、系统内存与网络收发采样 |
downloads |
manage，且 manage.downloading 未禁用；普通用户按网页相同的 userid / username 精确匹配本人 |
imports |
manage，且 manage.history 未禁用；原历史查询的最近成功入库记录 |
subscriptions |
subscribe，且至少一个订阅类型未禁用；合并本人有权限的电影、剧集和音乐订阅 |
管理员沿用原页面的全局数据范围。普通用户的分类权限必须明确为 true，缺省功能权限继承
分类；设置中的 admin 标记不能授予管理员权限。订阅按数据库 owner/type 分页并返回真实总数，
不把展示的六项摘要当作全部数量。
下载状态对管理员额外返回 downloadSpeed（下载速度）、uploadSpeed（上传速度）和
freeSpace（剩余空间），之后保留 count（任务数量）。速率直接汇总原下载器的字节采样，
包含做种上传；不解析任务列表中的格式化速度。空间沿用仪表盘的本地下载目录与
BTRFS_FSID_DEDUP 去重口径。无下载任务但统计有效时仍可显示真实的零下载和上传速度。
磁盘未配置、目录缺失或容量读取失败时，空间显示 —；有效的零剩余空间显示 0 B。
速率来源缺失或非法时，该节为 unavailable。普通用户继续只返回本人任务及数量，
不读取或暴露实例全局速度和磁盘信息。App 小尺寸优先显示两种速度，中大尺寸增加剩余空间。
快照协议 v1
根字段为 version、owner、generatedAt、expiresAt、availableContents、sections。
时间均为 UTC Unix 秒；展示有效期最长 24 小时，且不晚于凭据到期。
可用内容与 section 一一对应，权限不足的内容不返回。
每个 section 包含 content、title、state、可选 updatedAt、metrics、items 和可选 message。
ready 表示成功，empty 表示成功但没有记录，unavailable 表示来源不可用。
失败来源没有数据或伪造的采样时间，不会被转换成成功的零值；其他成功来源仍可展示。
旧记录的时间没有明确时区时，不猜测为 UTC。
每类最多八个指标和六条摘要，完整 JSON 不超过 32 KiB。标题、辅助文字和值按 UTF-8 字节限制， 移除控制字符。下载摘要展示当前采样的速度和自然进度；进度为 0…1。 不返回下载 hash、完整路径、tracker、图片 URL、插件配置、主登录令牌或业务命令。
客户端须验证版本、账号、内容枚举、体积和期限，使用系统调度刷新并显示实际更新时间。 401/403 时立即清理本地授权和快照，引导在 App 中重新启用；网络错误可按客户端明确的 过期策略暂用旧快照，不能把失败时刻改成“刚刚更新”。退出时先尝试撤销，断网不能阻止本地清理。 反向代理应保留 Authorization、使用 HTTPS，并避免记录凭据；不应把密钥放入 URL。
按尺寸显示的统计与明细
系统概览只含 CPU 占用、系统内存使用百分比（总内存减可用内存）、网络接收/发送速率、已用/总内存；不是 MoviePilot 进程内存比例，不包含媒体库数量。系统采样在受管工作线程完成，网络与 CPU 的区间约一秒；组件显示采样值，不承诺实时。
订阅合为一个 subscriptions 内容：count 为本人所有可用类型的总数，typeMOVIE/typeTV/typeMUSIC 分别计数，禁用类型完全不返回。stateN/stateR/stateS/stateP 是原持久化状态的未开始/订阅中/暂停/待定数量，不是进度或运行任务状态。所有计数来自原有数据库筛选的完整范围，不从六条摘要推算。剧集摘要复用公开响应的已完成集数派生，提供季号、完成/总集数、目标规格和可确认的自然进度。音乐缺少累计曲目事实时只显示目标曲目数，不能伪造进度。旧分类枚举仍可解析历史缓存，新的内容列表不再分开登记三个订阅。
入库保留成功历史的总数，追加按媒体类型计数及最近六条成功记录的季集、年份和原时间文字。小卡片显示总数，中卡片显示类别/状态统计，大卡片才显示真实名称和列表进度；媒体名称默认显示，可由用户关闭。下载小尺寸保留上传/下载速度，中大尺寸增加剩余空间、任务/状态数量，大尺寸追加任务名称、进度、单任务速度与预计剩余时间。
更新后的 App 和前端须一起升级以识别合并订阅内容、系统图标与八指标投影；旧客户端不能把未知指标当媒体数量显示。普通 Web/PWA 业务请求不变。