术语表
YiYi Media 的界面文案、配置文件、接口字段与日志用的是同一套词。这张表把它们对齐，方便你在读日志、改配置、看接口返回时能对上号。
怎么读这张表
- 每行是「中文术语 | 英文或代码标识 | 一句话解释」。代码标识会在配置文件、接口字段、日志与错误码里原样出现：日志里写
providerCode=gd1，接口返回license_status: "GRACE"，环境变量叫PLAY_AGENT_LISTEN。 - 表按主题分组：部署结构、存储、媒体、任务、播放、用户与运营、授权、调度。一个词只在你最常遇到它的那一组出现一次。
- 同一概念在不同资料里写法不一致时，这里取代码里实际使用的那个，必要时注明另一种常见叫法。
- 想按能力找模块，去功能总览与能力矩阵；想按端口与变量找配置，去端口与网络和环境变量参考。
部署模式与部署结构
| 中文术语 | 英文 / 代码标识 | 一句话解释 |
|---|---|---|
| 单机版部署 | Standalone Edition（STANDALONE） | 一台服务器、三个容器（YiYi-media-standalone + -postgres + -redis）；一个内置 Storage、一个内置 Play Agent；用户只能新增手动反代地址 |
| 分布式部署 | Distributed Edition（DISTRIBUTED） | Control/User/Media/Edge 可同机也可异机；Storage/Play Agent 为外部工作节点，可按配额新增与横向扩容。部署仓库对应 v2-all-in-one（同机）与 v3-multi-host（多机）两个分支 |
| 产品版本 | Edition（edition） | 许可证上的产品版本字段，取值 STANDALONE 或 DISTRIBUTED。由签名租约下发，是服务端强制执行的能力边界 |
| 部署模式 | Deployment Mode（YIYI_DEPLOYMENT_MODE） | 安装脚本固定的部署形态。它只用于收窄能力：版本边界始终以签名租约的 edition 为准 |
| 应用容器 | App Container（yiyi-app） | 单机版里承载全部服务进程的聚合容器；内部各服务仍作为独立进程运行，业务边界不变 |
| 内置节点 | Embedded Node（node_scope=EMBEDDED） | 随主应用安装、启动和升级的节点，固定为 node-local-storage 与 node-local-play-agent；禁用删除、卸载、独立升级与修改服务类型 |
| 外部工作节点 | External Worker Node（node_scope=EXTERNAL） | 用户在「节点管理」创建后自行部署的 Storage / Play Agent，只在分布式版可用 |
| 控制面 | Control Plane | 负责编排与统一入口的服务：config、user、media、gateway、frontend。单机版里它们共处一个应用容器 |
| 节点层 | Node Layer | 由工作节点（storage 与 play-agent）构成的层，与控制面相对，负责实际的存储与播放流量。只有分布式版允许节点多实例 |
| 工作节点 | Worker Node | 承担实际存储与播放流量的节点，可多实例、可异机。单机版固定各一个内置节点，不适用横向扩容 |
| 注册中心 | Service Registry（config 服务，18085） | 服务地址登记与自动发现的入口，节点只需要知道它的地址 |
| 网关 | Gateway（18086） | API 统一入口与授权执行点。单机版里它只监听应用容器内部的 127.0.0.1:18086，由容器内 nginx 反代 |
| 内部角色 | Role（control / user / media / edge） | 分布式部署内部的职责划分，不是独立的部署模式 |
| 文件管理节点 | Storage Node（YiYi-control-storage，18084） | 负责文件浏览、刮削与流代理的节点，也叫 storage 节点 |
| 播放代理节点 | Play Agent Node（YiYi-play-agent，19090） | Emby 协议出口与播放流代理节点 |
| 手动反代地址 | Manual Endpoint（manual-play-agent-endpoint） | 人工登记的反代入口，不参与部署与升级，系统只对它的 /health 做心跳。两种部署模式都可以新增，单机版里它是唯一可新增的项目 |
| 节点 ID 与节点令牌 | nodeId（YIYI_NODE_ID）/ Node Token | 节点唯一标识（手填须以 node- 开头）与注册凭据。内置节点使用全局服务令牌内部注册，不向用户展示节点令牌 |
| 对外地址与对外端口 | expectedHost / expectedPort | 客户端连接用的地址与端口，可以是反代的公网端口（例如 443） |
| 监听端口 | listenPort（PLAY_AGENT_LISTEN） | play-agent 进程实际绑定的端口；单机版固定为 19090 并由容器发布到宿主机 |
| 一键安装脚本 | Install Script（/api/config/nodes/install/{token}/{kind}） | 控制面生成的部署命令，kind 有 binary / binary-jdk / docker / uninstall / upgrade-binary / upgrade-docker。仅分布式版可用，单机版拒绝 |
存储
| 中文术语 | 英文 / 代码标识 | 一句话解释 |
|---|---|---|
| 挂载源 | Provider（providerCode） | 一个云盘或本地磁盘的接入配置，编码全局唯一且创建后不可改 |
| 挂载源类型 | ProviderType | 3 类：LOCAL_DISK、GOOGLE_DRIVE、ONE_ONE_FIVE（115 网盘）；WebDAV 与 S3 协议用于对外提供访问，不是接入类型 |
| 挂载 | Mount | 把挂载源以 FUSE 映射为本地文件系统，可设只读/读写、UID/GID、权限与自动挂载 |
| FUSE | — | 用户态文件系统；能力探测决定读、写、重命名是否可用，缺依赖时给出安装提示 |
| 持久暂存区 | Spool（STORAGE_MOUNT_SPOOL_DIR） | 写入先落本地再由任务链路上传，挂载卸载后仍可恢复 |
| 文件缓存 | Read Cache（STORAGE_MOUNT_DISK_CACHE_*） | 远端文件按分块落盘，前台读取与后台完整下载共享进度 |
| 云事件 | Change Feed（Provider Events） | Provider 原生变更流，带游标与跨节点租约；当前只有 Google Drive 声明原生支持。由调度中心「云事件拉取」任务定时拉取，文件管理页不再提供手动入口 |
| 秒传 | Instant Upload | 115 侧 hash 命中后 0 字节传输，任务上标「115 秒传命中」 |
| 账号池 | Google Drive 账号共享池 | 多账号分流与备用认证，账号级健康状态分 6 档（正常、配额受限、认证失效等） |
| CDN 优选 | CDN Optimization（gdrive-cdn.optimize） | 用 DoH 解析上游云盘候选 CDN IP 并测延迟择优，作用在节点内部，不是选播放节点 |
| 离线下载 | Remote Upload | 从 HTTP(S) 拉流到 spool，再经 Provider 续传会话上传到网盘 |
媒体
| 中文术语 | 英文 / 代码标识 | 一句话解释 |
|---|---|---|
| 中央媒体库 | Central Media Library | 聚合多个来源目录刮削结果的媒体库对象，本身不扫描磁盘 |
| 媒体类型 | mediaType | 只有三档：不限（空值）、电影（MOVIE）、剧集（SERIES） |
| 来源目录 | Library Source | 由「文件节点 + 挂载源 + 目录路径」确定的一条数据来源，一库可挂多个 |
| 同步项 | Sync Item | 单个来源目录同步进 media 服务的一条媒体记录 |
| 聚合项 | Aggregate Item | 多来源同一作品合并后的对外条目，也就是界面上的「个标题」 |
| 同步模式 | INCREMENTAL / FULL / FORCE_FULL | 增量、全量、强制全量覆盖三档；只有强制档会清除用户编辑 |
| 同步预览 | Dry-run | 只比对身份键不落库，给出增删改数量与逐条删除清单，可勾选保留 |
| 数据体检 | Orphan / Stale Source / Media Type Mismatch | 三类脏数据检查：孤儿资源、残留来源、类型异常，各自带清理或修复动作 |
| 元数据覆盖 | Override（ITEM / SEASON / EPISODE） | 人工改写标题、简介、海报、类型标签等字段，优先级高于刮削结果 |
| 刮削与补全 | Scrape（LIGHT / DIRECT）/ Backfill | 识别影视文件并抓取 TMDB 元数据，以及事后补齐缺失的音视频信息与剧集简介剧照 |
| 虚拟媒体库 | Virtual Library | 不绑目录、由 API 源或系统智能统计（SMART）动态生成的媒体库，只展示中央库已有的内容 |
| API 源 | Virtual Library API Config | 虚拟库的外部 HTTP 榜单配置，用 JSONPath 抽 TMDB ID，界面文案叫「API 拉取」 |
| 媒体整理 | Media Organizer | 重复检查 + 缺集检查 + 删除任务队列的合集页，可执行的整理动作只有删除重复版本文件 |
| 重复检查与缺集检查 | Duplicate Check / Missing Episodes | 前者按 7 条可排序保留规则找多版本并推荐保留项，后者用本地季集连续性对比 TMDB 数据 |
| 来源访问策略 | Source Access Policy（PUBLIC / RESTRICTED） | 按挂载源限制媒体可见与可播范围，查不到策略按受限处理（fail-closed） |
任务
| 中文术语 | 英文 / 代码标识 | 一句话解释 |
|---|---|---|
| 存储任务 | Transfer Task | 12 类持久化任务的统称，支持父子关系、依赖、重试与批量操作 |
| 任务类型 | READ / UPLOAD / DOWNLOAD / REMOTE_UPLOAD / COPY / MOVE / MERGE / BACKUP / MKDIR / RENAME / DELETE / ORGANIZER_DELETE | 12 类；其中读取、删除、重命名、新建目录四类不可暂停、恢复、取消与重试 |
| 任务状态机 | 16 态，聚合为 ACTIVE / ATTENTION / FINISHED | 主链是预处理 → 排队 → 运行/下载/上传 → 完成，旁路含暂停、取消、失败、部分失败、阻塞、忽略、跳过 |
| 任务来源 | origin（FILE_BROWSER / MOUNT / BACKUP / REMOTE_UPLOAD / WEBDAV / READ_CACHE / SYSTEM） | 标记任务由哪个入口产生，任务抽屉可按它筛选 |
| 链路 ID | Trace ID（traceId） | 贯通存储任务、文件日志与系统日志的追踪标识 |
| 预处理阶段 | preprocessStage | 扫描源、计算文件 hash、计算前 128KB hash、探测秒传、二次校验、提交 SignVal |
| Worker 租约 | Worker Lease | 每个运行中的任务由一个 storage 实例持有租约并续租，实例失联后其他实例只接管已过期任务 |
播放
| 中文术语 | 英文 / 代码标识 | 一句话解释 |
|---|---|---|
| 用户门户 | User Portal | 普通用户的个人中心：资料与签到、流量、网页播放、观影记录、邀请、客户端配置、绑定等 9 个 Tab |
| 网页播放器 | Web Player | 门户「网页播放」Tab 的内嵌播放器，仍在完善中；日常观片推荐 Emby 生态客户端 |
| Emby 协议 | Emby Protocol | 唯一已实现的播放协议出口，现有 Emby 生态客户端填地址与账号即可用 |
| 直连播放 | Direct Stream | 不做转码与转封装，直接把原文件流交给客户端，能否播放取决于客户端自身能力 |
| 播放入口线路 | Route（NODE / MANUAL） | 用户可用的播放出口，分节点线路与手动反代线路，流量分开计账 |
| 入口令牌 | Endpoint Token（X-YiYi-Endpoint-Token） | 手动反代地址必须注入的请求头，决定请求归属哪个分发入口 |
| 多版本源选择 | Media Source / browserSourceScore | 同一作品的多份文件按浏览器能力打分择优，播放失败时逐个自动换源 |
| 播放上报 | Playback Report（Playing / Progress / Stopped） | Emby 三段式进度上报，Progress 节流 15 秒，流量由 play-agent 按实际写出字节计量 |
| 智能启播缓存 | Smart Startup（SMART_STARTUP） | 用 ffprobe 定位容器元数据真实位置，只持久化基础头部、必要索引与少量开场字节；另一种模式是按固定缓冲区顺序缓存的传统预读（READ_AHEAD，也是内置默认） |
| 视频文件缓存 | VFS Cache | play-agent 的本地磁盘缓存，稀疏文件加 Range 写盘，按 LRU 与最长保留时间淘汰 |
| 签名直链缓存 | Link Cache（键 providerCode:itemId，多账号网盘再加 accountID） | 复用云盘签名直链以降低风控概率。TTL 从直链自带的过期参数推算，兜底 30 分钟；Google Drive 这类本地拼装的直链不设 TTL，仅在 401/403 时重新获取 |
用户与运营
| 中文术语 | 英文 / 代码标识 | 一句话解释 |
|---|---|---|
| 管理员 | isAdmin | 拥有全部菜单，并豁免限速、流量配额与节点授权（流量仍计入统计） |
| 委派菜单权限 | allowedMenuKeys | 把部分后台菜单交给普通用户；可委派 key 只有 8 个，留空表示只能进用户门户 |
| 用户标签 | User Tag（GRANT / REVOKE） | 8 色固定色板的运营分层标签，不参与任何权限判定 |
| 注册码 | Registration Code（含 accountDurationDays） | 决定「能否注册」与「新账号多久到期」，可批量生成并预设标签，核销路径 5 条 |
| 续期码 | Renewal Code | 只延长已有账号有效期，时长粒度仅「天」，由用户在门户自助激活 |
| 邀请名额 | Invitation Quota（GRANT / CONSUME 流水） | 只能由管理员发放，每生成 1 个邀请码消耗 1 个名额且未使用不退回 |
| 邀请树 | Invitation Tree（treeRootUserId / depth / inviterUserId） | 真实递归的邀请层级展示，不表示返佣层级或奖励层级 |
| 链路禁用 | Link Ban（UP / DOWN / CHAIN） | 向上、向下或整条链路批量禁用，执行前先出影响预估 |
| 客户端访问控制 | clientAllow（WHITELIST / BLACKLIST、uaPattern） | 只有客户端 User-Agent 一个维度的准入控制，带优先级 |
| 到期宽限期 | graceDaysAfter | 账号到期后仍可登录并被引导续费的天数，结束后无法登录；播放行为达阈值还能自动续期 |
| 播放流量配额 | Traffic Quota（USER / ROUTE，DAY / WEEK / MONTH） | 用户总额度与单入口额度两层，按周期重置，耗尽返回 429 且只影响该入口 |
| 带宽限速 | bandwidthLimitKbps | 用户级令牌桶限速，由 play-agent 执行并支持热更新 |
| 节点访问模式 | nodeAccessMode（ALL / ALLOW_LIST / NONE） | 用户能用哪些播放入口，管理员豁免 |
授权
| 中文术语 | 英文 / 代码标识 | 一句话解释 |
|---|---|---|
| 授权代理 | License Agent（18088） | 客户机上的本地代理，生成部署身份、换取并保管租约，默认只绑 127.0.0.1。单机版里它作为应用容器内的一个进程运行 |
| 许可证租约 | License Lease（data/license/lease/ 下的租约文件） | 授权中心签发的短期授权凭证，验签完全在本地离线完成，因此断网也能继续运行 |
| 部署身份 | Deployment Identity（data/license/identity/） | 这套部署的唯一身份。明确不使用 MAC 地址、容器 ID 或 CPU 序列号，因此允许受控迁移 |
| 一次性授权码 | Activation Code | 激活部署用的短效码，只发送给本机授权代理，不落浏览器与配置文件 |
| 授权状态机 | UNACTIVATED / ACTIVE / GRACE / EXPIRED / SUSPENDED / REVOKED / INVALID / CLOCK_SKEW | 8 个状态，只有 ACTIVE 与 GRACE 允许业务操作 |
| 断网宽限期 | Offline Grace Period | 续期失败后仍可正常提供业务的时间窗，界面用黄色横幅明示截止时间 |
| 授权期限 | License Term | 商业授权的到期时间。越过这个时间后宽限期也救不回来 |
| 节点配额 | Node Quota | 授权分别限制 Storage 与 Play Agent 两类节点的数量；新增时占用名额、删除时释放。单机版的配额固定为 1/1，只代表两个内置节点，不代表允许用户新增节点 |
| 节点范围 | Node Scope（EMBEDDED / EXTERNAL） | 节点分配请求里区分内置与外部身份。单机版只接受 EMBEDDED，分布式版只接受 EXTERNAL；普通节点不得伪装成内置节点 |
| 版本匹配 | Edition Match | 部署形态与许可证 Edition 必须严格一一匹配。不匹配时保留激活、许可证状态、日志与备份能力，不开放业务功能，也不删除客户数据 |
| 受限模式 | Restricted Mode | 越过宽限截止后的状态：不删数据、不卸卷、保留管理员登录，但拒绝新播放会话、文件写入、调度任务与新节点注册 |
调度
| 中文术语 | 英文 / 代码标识 | 一句话解释 |
|---|---|---|
| 调度中心 | Scheduler Center | 统一管理 25 个内置业务调度任务的页面 |
| 调度任务 | Scheduled Task（taskKey / taskGroup / taskLevel） | 一条可启停、可改触发方式的定时任务，等级分业务（BUSINESS）与系统（SYSTEM，只读） |
| 一次触发 | Fire（fireId） | 任务的单次执行记录，可查详情、终止与重试 |
| 执行器 | Executor（instanceId） | 实际执行任务的服务实例，手动触发时可指定 |
| 触发方式 | Trigger Type（MANUAL / CRON / FIXED_DELAY） | 手动、6 段 cron（含秒）或固定延迟 |
| 路由策略 | Route Strategy（FAILOVER_ONCE / ROUND_ROBIN） | 选择执行实例的方式；一期以单实例派发为主，轮询属配置层预留 |
| 阻塞策略 | Block Strategy（SERIAL / DISCARD_LATER / COVER_EARLY） | 上一次还没跑完时怎么处理新触发 |
| 进度上报 | Progress Report（progressPercent / progressText） | 任务执行中回写的百分比与文本，由计划总数自动推算，收尾固定 100% |
| 任务执行日志 | TaskExecutionLog | 四个服务共用的日志规范，写「做了多少」而不是「处理中」，逐条带序号、结果、耗时与处理条数 |