常见问题
没找到答案
到 Telegram 交流群 提问，带上部署模式（单机版还是分布式）、 docker compose images 输出、报错原文（docker compose logs <服务名> --tail 200， 或任务中心「说明」列文案）与已经试过什么。排查思路见 单机版部署（三容器）与授权与版本。
选型与体验
有公开的演示环境吗，加群之前能先确认什么
没有公开演示——真实环境涉及实际媒体库与用户数据。想看效果加 Telegram 群 联系安排，选型问题也可以在群里问。
看文档就能定三件事：网盘接不接得上（三类挂载源：本地磁盘、Google Drive、 115 网盘，见文件管理）、客户端能不能用（Emby 兼容协议面，见 Emby 协议兼容）、明确不做什么 （不做服务端转码、只有 Emby 协议、没有 2FA、授权不限用户数，完整清单见 功能总览的「明确不支持的能力」一节）。
加载与播放速度
换了封面 / 重新刮削后，页面还是旧海报
图片缓存没有按条目失效的能力。旧图会继续命中，直到 7 天保留期到期。
到播放设置对该播放节点点 清空全部缓存，再让用户刷新即可立刻生效。 同一操作也会清掉 VFS 视频缓存，但不会改动你的缓存配置。
第一次播放某个片要等，第二次就很快
这是设计如此。智能启播缓存只保证开场所需的字节在本地， 第一次播放时这些数据还不存在，必须从网盘读。
重复播放或多人同时看才会体现收益。想减少等待，可以在播放设置里把空间档位从 「智能平衡」调成「更稳启播」（单文件上限从 32 MB 提到 64 MB）。详见加载与播放速度。
我在网盘里加了文件，但页面上看不到
先到文件管理点一次刷新。如果经常这样，把挂载源配置里的 **「目录缓存过期时间」**从默认的「永久（仅手动刷新）」调成 5 分钟或 30 分钟—— 缓存越久浏览越快，但新文件越晚才出现。
媒体库列表改了数据但页面没更新
元数据缓存是永不过期的，靠主动失效：媒体同步完成后、或媒体库被修改/删除时才会清。 绕过系统直接改数据库不会自动反映，走一次同步即可。
系统配置里的「响应缓存」打开了没反应
这个开关目前不生效——开关与提示文案都在界面上， 但播放节点侧没有任何代码消费它。JSON 层面的加速实际由元数据缓存提供， 不需要额外打开这个开关。见加载与播放速度的「哪些没有缓存」。
部署与启动
单机版和分布式版怎么选，用哪个部署包安装
两种模式都用独立部署包 YiYi-media-deploy， 但拓扑与许可证 Edition 不同：
单机版部署（STANDALONE） | 分布式部署（DISTRIBUTED） | |
|---|---|---|
| 拓扑 | 一台服务器，三个容器（YiYi-media-standalone + -postgres + -redis） | 控制面按 control → user → media → edge 拆分，可同机也可多机 |
| 节点 | 一个内置 Storage + 一个内置 Play Agent，随主应用安装 | Storage / Play Agent 是外部工作节点，按配额自助部署 |
| 用户能新增 | 只能新增手动反代地址 | 外部节点 + 手动反代地址 |
| 许可证 | edition=STANDALONE | edition=DISTRIBUTED |
单机版是官方推荐的默认入门路径：
git clone https://github.com/YiYi-Product/YiYi-media-deploy.git /opt/YiYi-media-deploy
cd /opt/YiYi-media-deploy && cp .env.example .env # 单机版只填 YIYI_SERVER_HOST
sudo ./install.sh装完后单机版在部署目录里直接跑 docker compose 命令即可，docker compose ps 应该恰好三个服务。
两种模式不能靠改配置互转
只改 .env、Compose profile 或角色变量不会切换部署模式，也不会改变许可证 Edition。 单机版升级到分布式版必须走授权的专用版本升级操作并完成拓扑迁移，见 单机版迁移到分布式版。分布式版不支持自动降级为单机版。
install.sh 预检报错怎么办
- 「配置仍包含占位值」：
.env里还有占位符（例如example.invalid）没替换。 数据库口令、服务令牌、Redis 口令保持GENERATE_ON_INSTALL即可，脚本会生成随机值回写 - 「缺少 YIYI_XXX」：单机版预检要求
YIYI_SERVER_HOST、YIYI_DB_USER、YIYI_DB_PASSWORD、YIYI_SERVICE_TOKEN、YIYI_LICENSE_SERVER_URL非空且不以REPLACE_开头，其中口令与令牌交给脚本生成即可。分布式版的清单另含YIYI_ADVERTISE_HOST、YIYI_DB_HOST、YIYI_DB_PORT与YIYI_LICENSE_CLUSTER_TOKEN（≥ 32 位） - 授权公钥下载失败：脚本从
YIYI_LICENSE_SERVER_URL下载公钥并校验格式， 先确认这台机器能出网访问那个 HTTPS 地址
升级后容器还是旧版本
docker compose pull 只下载镜像，不会更新运行中的容器，必须重新创建：
cd /opt/YiYi-media-deploy
docker compose pull
docker compose up -d --remove-orphans --wait
docker compose ps单机版是整镜像升级：一次替换应用容器内全部八个服务，两个内置节点也随之升级， 没有独立的节点升级步骤。分布式版是按机器、按服务升级，四台机器各自执行。
安装脚本不会自动生成升级备份，数据备份由你自己管理。
哪些端口需要对外开放
单机版把前端 18080 与 Play Agent 19090 都发布到宿主机；19090 是播放客户端直连端口，默认绑 0.0.0.0，也可改成 127.0.0.1 由本机 nginx / Caddy 反代。 Config、User、Media、Gateway、Storage、License Agent 的端口不发布到宿主机； PostgreSQL 与 Redis 走 Compose 私有网络，应用容器内用 postgres:5432 / redis:6379 访问。
分布式版另需在私网内放行 5432、6379、18085（注册中心）、18089（集群许可证同步）， 外部工作节点的 18084 / 19090 按需对客户端可达。
这些端口绝不要开放到公网
5432、6379、18085、18089 只应在私网内可达。
单机版 docker port 应该只列出 18080（以及你自己显式配置过的端口）。完整表见端口与网络。
第一次打开后台：卡在「正在检查系统状态」，或先看到激活页
卡在**「正在检查系统状态」**通常是授权服务没起来或还没就绪，查 docker compose ps 里应用容器的健康状态与它的日志。
先看到激活页而不是创建管理员页是设计如此：顺序是「先激活授权 → 再创建首个管理员」， 全程在网页完成，见初始化与授权激活。
frontend 能单独部署到另一台机器吗
不能。frontend 内置的反代把 /api/* 指向写死的 127.0.0.1:18086，所以它与 gateway必须同机。单机版里它们在同一个 yiyi-app 容器内；分布式版两者同属 edge 角色。
数据放在哪里，用的是哪个数据库
数据默认在部署目录下的 data/。改到独立磁盘设 YIYI_DATA_DIR=/var/lib/yiyi， 相对路径以部署目录为基准。
单机版用内置 PostgreSQL，同一个实例承载四个数据库： yiyi_config、yiyi_user、yiyi_media、yiyi_storage，不需要你预建任何库。 数据目录布局见单机版部署（三容器）。
分布式版默认在 control 上装内置 PostgreSQL；要共用已有的外部实例， 在 control 的 .env 里设 YIYI_DB_MODE=external 并填连接变量。 此时必须预先创建 yiyi_config、yiyi_user、yiyi_media 三个库并授权建表； yiyi_storage 由 Storage 工作节点自己的部署配置管理。 见部署模式与版本选择。
切换数据库模式不会迁移数据
从 bundled 切到 external 前要自行迁移那三个库，脚本不复制数据库内容。 日常备份用 pg_dump；迁移物理目录必须先停 PostgreSQL。
节点与网络
单机版要自己装 Storage 和 Play Agent 吗
不需要，也不允许。单机版固定内置一个 Storage（node-local-storage）与一个 Play Agent（node-local-play-agent），随主应用安装、启动、升级。
单机版的「节点管理」只能新增手动反代地址：没有「新增节点」按钮，没有服务类型选择框， 内置卡片上不显示节点令牌、安装命令、卸载与独立升级操作。后台服务端同样会拒绝新增外部节点 （403 NODE_CREATION_DISABLED）、拒绝修改或卸载内置节点（403 SYSTEM_NODE_IMMUTABLE）， 并关闭节点二进制分发（403 BINARY_DISTRIBUTION_DISABLED）。所以这不是靠隐藏按钮实现的。
需要外部工作节点时，走单机版迁移到分布式版。
内置节点起来了但后台显示离线
先在应用容器内探测，再看容器日志：
docker compose exec -T yiyi-app curl -fsS http://127.0.0.1:18084/api/storage/ping
docker compose exec -T yiyi-app curl -fsS http://127.0.0.1:19090/health
docker compose logs --tail=200 yiyi-app内置节点进程由应用容器监管，单个子进程异常退出会被重启；连续失败时应用容器会进入 unhealthy 或退出，不会停在「容器在跑但服务消失」的假健康状态。
单机版能加节点扩容吗
不能。单机版是一台服务器、三个容器的固定形态，maxStorageNodes=1 与 maxPlayAgentNodes=1 只代表两个内置节点，不代表允许你新增节点，配额在管理台也不可覆盖。
单机版要扩容只能纵向提升服务器资源。需要横向扩容时先完成 单机版迁移到分布式版，在分布式版里按授权配额新增外部工作节点。
分布式版：节点要配哪些变量，一台机器能跑多个实例吗
本问只适用于分布式版。 节点侧只配注册中心地址 YIYI_CONFIG_HOST 与节点 ID YIYI_NODE_ID； 不需要配 YIYI_SERVER_HOST（节点凭 ID 向注册中心查自己的对外地址，即节点管理里登记的 expectedHost），也不需要手工配媒体与用户服务地址。多个 Storage 节点各建一条记录、各用不同的 ID。
一台机器可以跑多个播放代理节点：「监听端口」（PLAY_AGENT_LISTEN）同机必须不同， 如 19090、19091；「对外端口」是客户端连接用的，可以都填 443，各走自己的反代域名。
手动反代地址是什么，为什么我的授权不生效
「手动反代地址」只登记一个已存在的反向代理入口，不参与部署与远程升级，系统只对它的 /health 做心跳。它靠入口令牌区分请求归属：反代必须注入 X-YiYi-Endpoint-Token 请求头，否则请求按直连处理，该地址上的用户级授权与流量配额都不生效。编辑抽屉里给出 nginx 与 Caddy 片段。
存储与挂载
支持哪些网盘
三类挂载源：本地磁盘、Google Drive、115 网盘。 WebDAV 与 S3 的协议能力是对外提供访问用的（如 storage 的 /dav/* WebDAV 出口）， 不作为接入类型。
其他网盘的文件：能同步或下载到本机目录的，用本地磁盘挂载源接入； 需要文件变更自动入库的，用入站 Webhook 推送（见系统配置）。
文件管理能预览内容、下载文件吗
不能。只有列表视图：没有网格缩略图、没有右键菜单、没有在线解压；行内「预览」按钮打开的是 媒体识别结果统计，不是内容播放器。下载只在全局搜索结果里对单条结果可用。 想播放请用 Emby 生态客户端。
FUSE 挂载不可用，或挂载点被卸载了会丢文件吗
「文件运维」页头有 FUSE 能力徽章，不可用时给出缺失依赖与安装提示。挂载点被卸载 不会丢正在上传的文件：写入先落本地 spool（持久暂存区）再由任务链路上传， 未完成的持久 spool 在「挂载诊断」里可见并可恢复。
删掉一个挂载源会怎样
会连带清理关联的媒体库来源、刮削记录与元数据，不可恢复，界面会警示。若只是重建了同名 挂载源导致播放 403，用「推送凭证到 Media 端」修复；「检测 Media 端孤儿 providerCode」 能提示你能否复用原编码恢复播放直链。
媒体库与刮削
支持动漫库、音乐库、照片库吗
不支持。媒体类型只有三档：不限、电影（MOVIE）、剧集（SERIES）。 动漫、综艺通常归到「剧集」或「不限」，靠媒体库命名与目录结构区分。
建了媒体库为什么是空的
九成是顺序问题：先在文件管理里分类刮削，再到媒体管理建库同步。中央媒体库 不扫描磁盘，只聚合存储侧已刮削好的结果，见 快速开始第 6 步。
建库时绑定来源目录（文件节点 + 挂载源 + 目录路径），再在来源卡片上点同步。仍然空着就查： 来源目录是否真有文件 → Storage 节点是否在线 → 刮削任务是否在跑（「任务中心」） → 同步是否执行过（增量 / 全量 / 强制三档）。
第一次刮削选什么模式，元数据从哪来
轻刮削（LIGHT）+ 默认线程数，「刮削方式」选覆盖；库稳定后再对识别不准的目录 单独跑直刮削（DIRECT）补精度。详见刮削与元数据。
首次刮分类目录，「刮削方式」必须选覆盖
勾了「这是分类目录」再用默认的增量，首次会一个文件都不刮，界面提示 「当前分类目录没有待处理的文件变化日志」。日常补新才用增量。
元数据四个来源：TMDB（作品元数据与海报，语言可选）、NFO（系统设置里开启）、 文件名解析（含 [tmdbid-xxx] / [imdbid-xxx] 后缀）、播放时补全（播放节点内嵌 ffprobe 异步补全容器格式、时长与音视频轨道）。
刮削很慢，或者大量失败
- 一直「扫描中」 → 「刷新目录缓存」是否选了全量刷新；115 另看「API 调用间隔」是否过大
- 担心 TMDB 压力 → 调小「刮削线程数」；刮削链路对 TMDB 没有限流退避，被限流的子项直接记失败
- 大量条目识别不出来 → 文件名信息太少，先用批量重命名规整，或在文件名里带
[tmdbid-xxx]后缀 - 个别目录一直失败 → 在任务中心对该目录暂停后单独重试；⚠️ 失败后 30 秒内重新点 「加入任务」会被去重静默吞掉
- 任务「已完成」不等于全部成功 → 失败明细在子项里，看进度列的「失败 N」
新加的文件会自动入库吗
会。文件变更重放与刮削各每 15 秒跑一次，同步队列每 30 秒消费一次变更，媒体库增量同步 每 300 秒一次，都能在调度中心里手动触发。往挂载点里写文件也会 自动触发刮削，开关在文件运维的「传输设置」里。
手工改过的标题和海报会被同步冲掉吗
不会。条目详情支持作品 / 季 / 集三级元数据覆盖：标题、日期、简介、类型标签、封面 都能改，剧集另有季与集两级；覆盖值优先于刮削结果。
普通增量与全量同步保留用户编辑，只有强制全量覆盖（FORCE_FULL）会清除。 同步前先跑 Dry-run，含用户编辑的项会标出字段名，可逐条勾选保留。
条目列表能排序、筛选、批量操作吗
不能。只有关键词搜索、分页（每页 24/48/60/96/120）、网格与列表双视图；没有排序控件、 没有类型筛选、没有批量选择，条目详情也不展示评分与演员表。批量需求到「用户管理」找。
媒体整理与虚拟库分别只做什么
媒体整理只做删除重复版本文件（可先演练），另有重复检查与缺集检查两个只读分析。 重命名与移动在「文件管理」里做。虚拟库不会把外部榜单里你没有的片子变出来—— 它靠 TMDB ID 与中央媒体库求交集，只展示你已有的内容。
播放
支持 Jellyfin 或 Plex 客户端吗，有服务端转码吗
只有 Emby 协议已实现，系统配置里的 Jellyfin、Plex 是标注「开发中」的禁用占位按钮， 同时只能启用一个协议。Emby 生态客户端（Infuse、VidHub、Sviewer、Fileball 等）填地址与 账号即可用，端点级覆盖见Emby 协议兼容。
没有服务端转码，也不做转封装，以直连播放为主，自带 ffprobe 只用于元数据探测； 客户端能不能播某个文件，取决于它自身对该容器与编码的支持。
用户说客户端连不上、放不出来，怎么查
先分清是「连不上」还是「放不动」：客户端和格式不兼容时连得上但播不出来（服务端不转码， 见上一条）。连不上查三件事：该用户是否有节点授权（用户详情「节点」Tab）、 流量配额是否耗尽（耗尽的入口不会下发给用户）、手动反代地址是否注入了 X-YiYi-Endpoint-Token。管理员在门户看到「全量视图」并有警示横幅， 不要用管理员账号验证普通用户的授权效果。
有基于负载的自动节点调度吗
没有。用户端是并发对所有可用入口发健康探测（2400ms 超时）取第一个可达的，都不可达就取 列表第一个，工具栏可以手动切换。「CDN 优选」是节点内部对上游网盘 CDN IP 的测速优选， 不是节点之间的调度。
用户与权限
支持哪些登录方式
六种：账号密码、Telegram Login Widget、Telegram 数字 ID + 验证码、Telegram Mini App （免密）、Telegram Bot 一次性令牌、Google 账号。
能把部分后台菜单交给非管理员吗
可以，但只有 8 项可委派：节点管理、文件管理、媒体管理、调度中心、系统配置、用户管理、 邀请管理、播放设置。文件运维、访问管控与播放报表不可委派；委派留空的用户只能进用户门户。
有 2FA 吗，能按用户限制存储空间或封 IP 吗
三件都做不到。没有二次验证（2FA / TOTP），登录失败锁定固定为同一 IP + 用户名连续失败 5 次锁定 60 秒，阈值不可配置。没有存储空间配额，配额只有播放流量（用户级 + 入口级， 按日/周/月重置）、带宽限速、并发流数（0 不限 / 1 / 2 / 3 路）三类。不能封 IP， 访问管控只有 User-Agent 一个维度（白/黑名单 + 优先级 P1 最高），IP 只在会话列表与 报表里作展示。
邀请有返佣吗，用户标签会影响权限吗
都不会。邀请管理提供名额发放、可视化邀请树、链路禁用与码使用记录，但没有任何返佣、提成 或奖励发放逻辑，邀请树只表示「谁邀请了谁」；积分与每日签到是用户侧独立的一套。 用户标签是纯运营分层工具（8 色、可单个与批量打标与筛选、注册码可预设标签并继承）， 不参与任何权限判定。
报表与观测
播放报表能看到什么，看不到什么
能看到：时间、用户、媒体、会话、客户端与设备平台维度，概览六卡都带环比。
看不到：没有节点维度与地域维度，没有播放成功率与错误分布，不能导出 Excel—— 只有前端生成的 CSV（带 BOM，Excel 打开不乱码）。播放设置页也没有缓存命中率展示。
授权
断网了会停服吗，受限模式下还能做什么
不会立刻停。租约存在本地、校验完全离线，续租失败时进入宽限期（GRACE），后台顶部显示 黄色横幅与宽限截止时间，业务照常；越过宽限截止才进入受限模式。
受限模式下保留管理员登录、授权激活与状态查询、日志导出、数据备份，不会删数据也不会卸载 挂载；拒绝新建播放会话、文件写入、调度任务与新节点注册。完整清单见 授权与版本。
授权限制什么，不限制什么
限制取决于 Edition：
单机版（STANDALONE） | 分布式版（DISTRIBUTED） | |
|---|---|---|
| 内置 Storage | 固定 1 个 | 无固定内置节点 |
| 内置 Play Agent | 固定 1 个 | 无固定内置节点 |
| 新增外部节点 | 禁止 | 按配额允许 |
| 手动反代地址 | 允许 | 允许 |
| 多服务器部署 | 禁止 | 允许 |
| 节点二进制与安装命令 | 禁止 | 允许 |
不限制的：用户数不限、不做功能模块开关（所有功能随授权一起可用）、不绑硬件 （不使用 MAC 地址、容器 ID 或 CPU 序列号，允许受控迁移与重新绑定）、不是永久离线可用 （越过宽限截止即进入受限模式）。备份记得带上 data/license/。
许可证 Edition 和部署形态对不上会怎样
会被拒绝：单机聚合镜像只接受 STANDALONE，分布式部署只接受 DISTRIBUTED。 此时系统保留激活、许可证状态、日志和备份能力，不开放业务功能，不删除客户数据。 换回匹配的部署包或许可证即可。历史许可证（没有 Edition 声明）一律按 DISTRIBUTED 兼容， 避免现有客户升级后发生非预期能力收缩。见授权与版本。
能从单机版直接改成分布式版吗
不能直接改。不允许只改 .env、Compose profile 或角色变量原地切换。 必须走授权的专用版本升级操作（管理台「升级为分布式版」，或 POST /api/admin/licenses/{id}/edition），并完成部署拓扑迁移与数据校验。 分布式版也不支持自动降级为单机版。完整前置条件、步骤与回滚点见 单机版迁移到分布式版。
集成
能接 NAS 的文件变更通知吗
可以。系统配置里的入站 Webhook 接收群晖等 NAS 的变更通知，匹配媒体库后分发刮削任务， 命中多个来源时全部下发。地址形如 http://<网关地址>:18080/api/webhook/<token>， POST 与 GET 都支持；data 是必填的字符串数组（不要传分类根目录），replace_path 可选、 支持 * 通配单个路径段（如 /gd*/）用来剥离挂载前缀。
能把媒体事件推给别的系统吗，有给 AI 用的接口吗
出站 Webhook 支持自定义方法、URL 模板、Header、Query 与请求体模板，24 个数据变量 可按媒体库订阅，敏感值可掩码，有一键测试与最近 50 条投递记录，失败持久化重试。
系统配置里还能开关MCP 服务（端点是网关的 /mcp，Streamable HTTP），让 AI 助手直接 管理媒体库；工具权限与账号菜单权限一致，关闭返回 404，重开无需重启。配置页给出 accessToken 与 curl 验证命令。