系统配置
系统配置页把品牌白标、播放协议、MCP 与 Webhook 集成集中在一处，面向要把 YiYi Media 改成自己产品、或要和外系统打通的管理员。
系统配置
按分组维护品牌、播放协议和外部集成；各设置项独立保存并立即反馈结果。
- 3 个分组、12 项设置
- 分项保存，没有全局保存
- 未保存的修改会被拦截提示
三个分组，分项保存
| 分组 | 副标题 | 包含 |
|---|---|---|
| 常用设置 | 网页播放、品牌与日志 | 网页播放开关、新用户默认流量额度、新用户默认节点授权、活动日志保留期、系统名称、全局 Logo |
| 播放协议 | 协议、缓存与 Emby 信息 | 播放协议选择、响应缓存、Emby 协议配置 |
| 集成与高级 | MCP 与 Webhook | MCP 服务、入站 Webhook、出站 Webhook |
没有「全局保存」
本页采用分项保存：修改哪一组，就在该设置卡片内点它自己的保存按钮，不存在一次覆盖全部配置的入口。页头会显示「有未保存修改 / 所有修改已保存」；存在未保存修改时，关闭标签页（beforeunload）与站内跳转都会被弹窗拦截。
12 项配置一览
| # | 分组 | 设置项 | 生效范围 |
|---|---|---|---|
| 1 | 常用设置 | 网页播放全局开关 | 立即，全站 |
| 2 | 常用设置 | 新用户默认流量额度 | 只对之后新建的用户生效 |
| 3 | 常用设置 | 新用户默认节点授权 | 只对之后新建的用户生效 |
| 4 | 常用设置 | 用户活动日志保留期 | 下一次清理任务运行时按新阈值截断 |
| 5 | 常用设置 | 系统名称 | 立即，品牌下发 |
| 6 | 常用设置 | 全局 Logo | 立即，含 favicon |
| 7 | 播放协议 | 播放协议选择 | 播放节点下次策略刷新（约 30 秒）后生效 |
| 8 | 播放协议 | 响应缓存开关 | 播放节点下次策略刷新（约 30 秒）后生效 |
| 9 | 播放协议 | Emby 协议配置 | 立即 |
| 10 | 集成与高级 | MCP 服务开关 | 网关最多约 3 秒同步生效 |
| 11 | 集成与高级 | 入站 Webhook Token | 重新生成后旧 Token 立即失效 |
| 12 | 集成与高级 | 出站 Webhook 端点 | 保存后由调度任务投递 |
常用设置
1. 网页播放全局开关。 全局控制用户中心的网页媒体库播放入口。关闭后所有用户都无法访问；单个用户的网页播放权限配置会保留，重新开启后继续生效。默认开启。用户实际能否使用，取决于「系统开关 且 用户开关」。
2–4. 额度、授权与日志保留。
| 设置项 | 说明 |
|---|---|
| 新用户默认流量额度 | 总额度（开关 + 数值 + MB/GB + 每天/每周/每月）；按线路额度可添加「播放线路（nodeId）」或「手动线路（endpointId）」，每条独立设启用、额度、单位与周期，可删除，未列出的线路不限制。保存后页面明示：仅在此后新建用户时写入，现有用户的额度不会变更 |
| 新用户默认节点授权 | 三种模式：ALL 全部节点、ALLOW_LIST 指定名单、NONE 全部禁止。ALLOW_LIST 下勾选播放代理节点与手动反代地址（含已停用）。模式与名单一次性提交，避免中间态被同时进来的注册请求撞上。两条防误配黄色告警：名单里没勾任何播放代理节点，新用户将无法播放；选 NONE 则须逐个用户授权 |
| 用户活动日志保留期 | 控制用户活动日志保留多久，每日清理任务按此阈值删除更早的事件。范围与默认值由后端返回（前端兜底 7–3650 天、默认 90），另有 30 / 90 / 180 / 365 / 730 天快捷值。这一项直接决定播放报表能回看多久 |
5. 系统名称。 最长 128 字符，默认 YiYi Media。用于登录页、侧边栏、注册页与注册验证邮件，并同步写入浏览器标签标题（document.title）。
6. 全局 Logo。 上传图片（只接受 image/*、不超过 2 MB）或直接填 URL，带预览与清除，保存后同步替换 favicon。上传成功后需再点「保存 Logo」才生效。
播放协议
7. 播放协议选择。 见下节。
8. 响应缓存。 缓存播放节点的 Emby JSON 响应（Shows/Episodes、Shows/Seasons、Users/Items/Latest 等）以降低 media 服务负载。页面明确写出风险：这些接口包含用户级 UserData（如继续观看进度），启用后播放进度可能延迟最多 metadataCacheTtlSeconds（默认展示 300）秒才更新，多用户场景下还可能出现数据污染，建议默认关闭。
该开关目前不生效
界面上有这个开关与风险提示文案，但播放节点侧当前没有任何代码消费该配置项，打开也不会产生实际行为。JSON 层面的加速由 Redis 元数据缓存提供（见加载与播放速度），无需额外操作。
9. Emby 协议配置。 维护对外暴露给 Emby 客户端的系统信息字段。页面上只有两个输入控件：「服务名称」（serverName）与「产品名称」（productName），占位符都是 <系统名> Media。保存时接口还会带上其他协议字段，但页面上没有对应的输入控件，因此这里可配置的就是这两项。
集成与高级
10. MCP 服务。 见下文专节。
11 / 12. 入站与出站 Webhook。 见下文专节。
品牌白标能做到哪一步
| 能力 | 支持 | 说明 |
|---|---|---|
| 系统名称 | ✅ | 登录页、侧边栏、注册页、注册验证邮件、浏览器标签标题 |
| 全局 Logo | ✅ | 上传或 URL，同步替换 favicon |
| 网页播放开关 | ✅ | 全站级开关 |
| 主题色 | ❌ | 页面不提供主题色配置 |
| 登录页文案自定义 | ❌ | 页面不提供该项 |
品牌信息经公开接口 GET /api/auth/branding 下发，登录前即可取到，因此登录页能显示你自己的名称与 Logo。
播放协议：当前只有 Emby
| 协议 | 界面描述 | 状态 |
|---|---|---|
| Emby | 兼容 Emby/Jellyfin 客户端（当前已实现） | 可选，当前启用项标「● 当前启用」 |
| Jellyfin | 原生 Jellyfin 协议（开发中） | 禁用占位按钮，不可选 |
| Plex | Plex 媒体服务协议（开发中） | 禁用占位按钮，不可选 |
三个按钮同时只启用一个协议。Jellyfin 与 Plex 是标注「开发中」的禁用占位，当前不可用；play-agent 侧 supported_protocols 默认也只有 ["emby"]，请求其他协议返回 503。已实现的 Emby 兼容面同时可被 Jellyfin 生态客户端使用。保存后播放节点在下次策略刷新（约 30 秒，对应调度任务 policy.refresh）后生效。
MCP 服务：给 AI 助手用的管理接口
开关控制网关的 /mcp 端点：关闭后请求返回 404，重新打开无需重启服务，网关最多约 3 秒同步生效。MCP 工具的权限等于当前账号的菜单权限，不会越权。页面直接给出三步接入指引：
| 步骤 | 内容 |
|---|---|
| 1. 获取访问令牌 | 取当前账号的 accessToken |
| 2. 配置 MCP 客户端 | 传输方式 Streamable HTTP，地址 ${origin}/mcp，鉴权头 Authorization: Bearer <token> |
| 3. 验证连接 | 可复制的 curl initialize 示例，protocolVersion 为 2025-11-25 |
Webhook
入站：NAS 一有新文件就自动刮削
用途是接收 NAS（如群晖）的文件变更通知，匹配媒体库后分发刮削任务。
| 项 | 说明 |
|---|---|
| 地址 | http://<网关IP>:18080/api/webhook/{token}，POST 与 GET 均支持 |
| Token | 可生成 / 重新生成；重新生成需二次确认，旧 Token 立即失效。列表中掩码显示，明文只在生成后可见一次 |
data | string[]，必填。文件或剧目录的路径列表，禁止直接传分类根目录 |
replace_path | 可选。用 * 通配单个路径段剥离挂载前缀，例如 /gd*/ 可匹配 /gd1/，从而把 /gd1/短剧/圣临 归一成 /短剧/圣临 |
同一路径匹配到多个媒体库来源时，所有来源都会收到刮削任务。
出站：把媒体事件推给任意外部系统
端点可增删改，字段如下：
| 字段 | 说明 |
|---|---|
| 名称 | 端点标识，投递记录里显示它 |
| 请求方法 | 默认 POST |
| URL 模板 | 支持变量，例如 https://example.com/webhook/{{media.tmdbId}} |
| Content-Type | application/json / application/x-www-form-urlencoded / text/plain |
| 启用 | 端点开关 |
| URL 含敏感信息 | 勾选后 URL 在界面上脱敏显示 |
| 允许内网地址 | 默认禁止；仅在明确需要向局域网服务推送时开启 |
| Query 参数表 | 键值对，每项可标「敏感」 |
| Header 表 | 键值对，每项可标「敏感」 |
| 请求体模板 | 支持变量；默认模板标题为「新媒体入库」 |
| 按媒体库订阅 | 只推送选中媒体库的事件 |
标为敏感的 Query / Header 保存后只显示脱敏值。每个端点可一键测试投递；删除端点时，尚未发送的投递记录会一并删除。
页面保留最近 50 条投递记录：
| 字段 | 说明 |
|---|---|
| 端点名 | 哪个端点投的 |
| 事件类型 | 触发这次投递的事件 |
| 状态 | SUCCEEDED / DEAD / 其他 |
| 尝试次数 | 已重试几次 |
| 最后 HTTP 状态 | 对端返回的状态码 |
| 时间 | 创建时间与投递时间 |
| 错误 | 最后一次失败的原因 |
模板变量
语法是 {{变量名}}，在 URL 模板、Query、Header 与请求体模板里都能用。可用变量按前缀分组：
| 前缀 | 变量 |
|---|---|
event. | id、type、occurredAt |
library. | id、name |
media. | id、type、title、originalTitle、year、releaseDate、tmdbId、imdbId、posterPath、posterUrl、overview |
episode. | seasonNumber、episodeNumber、name |
item. | sourceItemId、name |
summary. | newTitles、newItems |
| 整体 | payloadJson（完整事件 JSON） |
共 24 个数据变量。任何变量都可加 urlencode. 前缀做 URL 转义，主要用于表单请求体，例如 title={{urlencode.media.title}}；变量选择器额外列出 urlencode.media.title 与 urlencode.payloadJson 两个示例，合计 26 项。
通知渠道
| 渠道 | 用途 | 在哪配 |
|---|---|---|
| Email（SMTP） | 注册验证码、账号找回、绑定验证码、密码重置、到期提醒 | 不在本页：SMTP 参数在注册设置页与部署 env |
| Telegram | 到期提醒、一次性登录码等 | 不在本页：Bot Token / 用户名 / Mini App URL / Webhook Secret 由 env 注入 user 服务 |
| Webhook | 入站（NAS 变更触发刮削）+ 出站（媒体事件推送） | 本页「集成与高级」 |
关于安全，这一页的真实情况
本页没有这些安全配置项
系统配置页不提供密码策略、会话时长、登录失败锁定阈值、二次验证（2FA / TOTP）的任何配置入口。YiYi Media 当前也没有 TOTP / 2FA 实现。
登录失败锁定是代码硬编码的，不可配置：PasswordAttemptLimiter 对「同一 IP + 同一用户名」连续失败 5 次锁定 60 秒，失败计数 TTL 为 120 秒，计数优先放 Redis 以便多节点部署下保持一致。
YiYi Media 自身不提供 IP 黑白名单（访问管控只有 User-Agent 一个维度）。需要这类边界请在部署层实现：反向代理层限流与来源限制、管理端口只对内网开放、给不同运营人员分配独立账号。
相关接口
GET /api/auth/branding # 公开，品牌下发
GET /api/auth/admin/branding
PUT /api/auth/admin/branding # 系统名称
PUT /api/auth/admin/branding/logo # 全局 Logo
PUT /api/auth/admin/branding/web-player # 网页播放全局开关
POST /api/config/uploads/image # Logo 图片上传
GET /api/auth/admin/traffic-quotas/default-policy
PUT /api/auth/admin/traffic-quotas/default-policy
GET /api/auth/admin/node-access-policy
PUT /api/auth/admin/node-access-policy
GET /api/auth/admin/activity-log/retention
PUT /api/auth/admin/activity-log/retention
GET /api/config/play-agent/policy # 协议选择与响应缓存
PUT /api/config/play-agent/policy
GET /api/media/protocol/emby/settings
PUT /api/media/protocol/emby/settings
GET /api/config/system-settings/mcp # MCP 开关
PUT /api/config/system-settings/mcp
GET /api/media/webhook/token # 入站 Token（掩码）
POST /api/media/webhook/token/regenerate # 生成 / 重新生成
GET /api/media/outbound-webhooks
POST /api/media/outbound-webhooks
PUT /api/media/outbound-webhooks/{id}
DELETE /api/media/outbound-webhooks/{id}
GET /api/media/outbound-webhooks/libraries
GET /api/media/outbound-webhooks/deliveries?limit=50
POST /api/media/outbound-webhooks/{id}/test