快速开始

这一页带你从零走到「用户能播放」，全程照做即可。默认走单机版三容器流程。

整条链路是：装单机版三容器 → 网页激活授权 → 确认两个内置节点自动在线 → 文件管理接盘并分类刮削 → 媒体管理建库并同步 → 建用户播放。

预计耗时：安装 10～15 分钟，全链路 40～90 分钟（主要取决于首次刮削的媒体数量）。

前置条件

项目	要求
服务器	一台 Linux 服务器，有公网 IP 或已解析的域名
Docker	Docker Engine + Docker Compose v2（docker compose version 能出版本号）
权限	能用 sudo 执行安装脚本
授权	发布方提供的一次性授权码，Edition 必须是 STANDALONE
端口	对用户开放 18080（Web 入口）与 19090（播放客户端直连）

单机版是默认路径，分布式版是另一条入口

单机版部署只有 三个容器（容器名 YiYi-media-standalone + -postgres + -redis，Compose 服务名 yiyi-app + postgres + redis），Storage 与 Play Agent 已经内置， 不需要安装任何节点。控制面负载要分散、或需要外部工作节点横向扩展时， 再走分布式部署——那是另一种部署模式，需要 edition=DISTRIBUTED 的许可证，不是改几个变量就能切过去的。

第 1 步：安装单机版三容器

在服务器上执行：

git clone https://github.com/YiYi-Product/YiYi-media-deploy.git /opt/YiYi-media-deploy
cd /opt/YiYi-media-deploy
cp .env.example .env
chmod 0600 .env

编辑 .env，单机版只需要填一项：

YIYI_SERVER_HOST=<你的服务器IP或域名>

其余保持模板默认即可：

变量	默认值	说明
YIYI_DB_USER	yiyi	数据库用户
YIYI_DB_PASSWORD	GENERATE_ON_INSTALL	安装脚本自动生成高熵随机值并回写 .env
YIYI_SERVICE_TOKEN	GENERATE_ON_INSTALL	同上，服务间鉴权令牌
YIYI_REDIS_PASSWORD	空	留空表示不启用 Redis 密码；也可填 GENERATE_ON_INSTALL
YIYI_DATA_DIR	空	留空则数据放在部署目录下的 data/
YIYI_PUBLIC_HOST	空	只有公网访问地址与服务器地址不同时才需要填

然后安装：

sudo ./install.sh

脚本会依次完成：

1. 用 openssl rand -hex 32 生成所有标记为 GENERATE_ON_INSTALL 的密钥并回写 .env
2. 从授权中心下载授权公钥并校验其合法性（必须是公钥、不含任何私钥字段）
3. 创建统一数据目录并设置最小必要权限
4. 确认四个数据库存在（只创建缺失的，不覆盖现有库）
5. compose pull 拉镜像
6. compose up -d --remove-orphans --wait 起服务并等健康检查
7. 检查所有内部服务、两个内置节点与许可证状态
8. 写入安装标记

装完 docker compose ps 应该恰好三个服务：yiyi-app、postgres、redis。

数据都在部署目录的 data/ 下：

data/
├── postgres/
├── redis/
├── license/{identity,lease}/
├── config/uploads/
├── storage/{mount-data,spool,read-cache}/
├── play-agent/{vfs-cache,image-cache}/
└── logs/{config,user,media,gateway,storage,play-agent,license}/

完整变量清单见环境变量参考，端口与防火墙见端口与网络。

单机版没有 join.env 与角色选择

单机版不生成 join.env，不用 YIYI_DEPLOY_ROLE=single，也没有 Control/User/Media/Edge 角色选择。那些属于分布式部署（按角色多机）。

第 2 步：激活授权并创建管理员

浏览器打开：

http://<你的服务器IP或域名>:18080

顺序是「先激活授权，再建管理员」

前端只在授权状态为 ACTIVE 或 GRACE 时才渲染初始化向导， 所以第一个页面是激活页。

1. 按页面提示输入发布方提供的一次性授权码，提交
2. 页面每 1.5 秒轮询授权状态，通过后自动跳到 #/setup
3. 三步向导创建首个管理员：用户名（≥ 2 字符）、密码（≥ 6 位）、二次确认
4. 用刚创建的账号登录

授权码只会发送给本机的授权代理，不写进浏览器或部署配置文件。 授权状态机、宽限期与断网行为见初始化与授权激活。

第 3 步：确认两个内置节点已在线

单机版固定内置一个 Storage 与一个 Play Agent，随主应用安装、启动、升级。 你不需要部署任何节点，也不需要复制任何安装命令。

内置节点	节点 ID	职责
文件管理节点	node-local-storage	文件浏览、挂载源、刮削入库、流代理
播放代理节点	node-local-play-agent	播放出口、直链与分段传输

打开后台 → 节点管理，确认两者状态都是「在线」，并显示「随系统部署 / 随主版本升级」。 Storage 会自动成为新浏览器会话的默认文件管理节点。

单机版只能新增手动反代地址

单机版的「节点管理」没有「新增节点」按钮，也没有服务类型选择框； 内置卡片上不显示节点令牌、安装命令、卸载与独立升级操作，外部节点部署配额表单也不出现。

这是设计如此，不是界面缺功能：单机版只允许在手动反代地址区域新增。 需要外部工作节点、配额与一键安装命令时，走分布式部署（控制面同机）。

手动反代地址在两种模式下都可用

需要给播放流量配独立域名、单独计账时，在节点管理里新增一条手动反代地址， 再把控制面给出的 nginx / Caddy 片段贴到你的反向代理里，见 反向代理与域名。它不占授权配额。

第 4 步：接入存储

进 文件管理 → 管理挂载源 → 新增，选择存储类型并填凭据：

类型	关键字段
本地磁盘	根路径（支持 inotify 实时监控变更）
Google Drive	Client ID / Secret、Refresh 与 Access Token、Root ID；支持多账号共享池与 CDN IP 优选
115 网盘	自定义 OpenAPI App ID；可用 115 手机客户端扫码自动填写 Access / Refresh Token；OpenAPI 与 Auth 基址、Root ID

115 扫码确认后，Token 只会填入当前表单，仍需点击保存。二维码过期、切换文件管理节点或 Storage 节点重启后，重新获取二维码即可。

挂载编码创建后不可修改

挂载编码（providerCode）是媒体库来源、访问控制与统计报表共同依赖的身份标识， 全局唯一且创建后不可改。改名等于换身份，会让已建媒体库的来源失联。

需要把网盘当本地目录用（例如让其它程序直接读写）时，再到 文件运维 → 挂载列表 创建 FUSE 挂载。只做刮削与播放的话这一步可以跳过。

单机版默认不提供主机 FUSE 挂载

单机版默认关闭主机 FUSE 挂载，聚合容器不使用 privileged，也不授予 SYS_ADMIN。 这不影响云盘管理、文件浏览、上传下载、媒体同步与刮削——它们照常可用。 文件运维页的能力徽章会显示 FUSE 不可用及原因。

字段差异详见文件管理。

第 5 步：分类刮削

这是把「网盘里的一堆文件」变成「有海报有简介的媒体」的关键一步。

模式与线程在另一个弹窗里配，不在刮削弹窗里

刮削模式和线程数属于挂载源级设置，入口是「挂载源管理 → 挂载配置 → 媒体库设置」。 点「加入任务」弹出的「目录刮削选项」里没有模式选项——它只有分类目录、刮削方式、 TMDB 匹配类型三项。所以下面分成 5a 配置与 5b 发起两步。

5a. 先确认刮削模式与线程（挂载源级，一次性配置）

进 文件管理 → 管理挂载源，打开对应挂载源的抽屉，右侧「挂载配置」里点 媒体库设置：

设置项	首次刮削建议	说明
刮削模式	轻刮削（LIGHT）	这也是默认值，通常不用改。轻刮削不逐个文件跑 ffprobe，速度快很多
刮削线程数	自动（按机器性能）	默认 0 即自动：2 核→2、4 核→4、8 核→6，更多核取 min(16, 核数)。代码注释说明 TMDB 刮削是网络 I/O 密集型，线程数不受 CPU 数限制、最低 2 线程。首次没必要手动调
刮削语言	按需	默认 zh-CN，另有 zh-TW / en-US / es-ES / ja-JP / ko-KR
使用 NFO 文件作为刮削输入	保持关闭	NFO 里的 tmdbId 会覆盖自动识别结果，优先级高于文件名。第三方工具生成的 NFO 可能不准（例如把演员 ID 写成电影 ID），界面自己也建议关闭
刷新目录缓存	默认	默认不刷新 / 目录下无文件刷新 / 全量刷新；选全量刷新会每个目录都强拉网盘，最慢

点 保存系统设置。

这些设置是「挂载源级优先、全局兜底」

同一个设置项有两个作用域：全局 key（如 scrape.mode）与挂载源级 key （如 provider.<挂载编码>.scrape.mode），挂载源级优先。 所以不同网盘可以用不同的刮削模式与线程数。

部分参数只对特定网盘显示

「目录扫描线程数」「音视频补全线程数」「API 调用间隔」三项只对 115 网盘显示， 因为它们是给风控敏感的网盘用的；「每次最多补全数量」「增量刮削联动补全」只在轻刮削模式下显示； 两个 ffprobe 参数只在直刮削模式下显示。看不到不代表功能缺失。

5b. 对分类文件夹发起刮削

回到 文件管理 的文件列表：

1. 顶部选中存储节点与挂载源

2. 浏览到媒体分类文件夹（例如 华语电影、国产剧、日本动漫）所在的上一级目录

3. 在目标行的「操作」列点 加入任务

4. 弹出 目录刮削选项，填三项：

   字段	首次建议	说明
   这是分类目录（递归刷新并刮削子目录中的影视文件）	勾选	声明这是一个分类容器（如 /国产剧），后端会对每个子目录独立匹配 TMDB，按层多线程并发遍历（扫描线程池硬上限 16；BFS 没有深度与目标数上限，所以超大目录树会扫很久，进度在任务中心看）。 不勾则表示「这个目录本身就是一部作品」，会先做一致性校验，父目录名 / TMDB 与文件名对不上就直接报错
   刮削方式	首次必须选「覆盖」	⚠️ 默认值是「增量」，但勾了「这是分类目录」再用增量，首次会什么都不刮——见下方警示。覆盖：重新扫描全部文件并重建这批刮削数据。增量：保留已有数据，只处理新增、变更或尚未完成刮削的文件，适合日常补新。清理旧残留只在覆盖模式且任务成功时发生（界面上「增量结束后顺带清理旧残留」的说法对目录任务并不成立）
   TMDB 匹配类型	自动；短剧选 剧集	自动会同时尝试电影与剧集。短剧容易被匹配成同名电影，界面明确建议选「剧集」

首次刮分类目录，「刮削方式」必须选覆盖

这是最容易踩的坑。「分类目录 + 增量」走的是完全不同的代码路径：后端不会创建刮削任务， 而是直接去重放该目录的文件变化日志。首次刮削时根本没有日志，于是返回 SKIPPED 加一句 「当前分类目录没有待处理的文件变化日志」—— 界面看起来像提交成功了，实际一个文件都没刮。

所以：

• 首次对一个分类文件夹刮削 → 勾「这是分类目录」+ 刮削方式选 覆盖
• 日常补新（该目录之前已经刮过）→ 才用默认的 增量，此时它会按变化日志只处理新增与变更

如果不小心用增量提交了首次刮削，到任务中心看不到任何任务行，重新发起一次并选覆盖即可。

5. 点 开始刮削。选覆盖时会提示 已添加刮削任务: <目录名>（分类目录）（任务 <jobId>）； 选增量且没有待处理日志时，会直接返回 SKIPPED 与「当前分类目录没有待处理的文件变化日志」

对话框会记住你上次选的「覆盖」

提交成功后弹窗只是关闭，不会重置「刮削方式」与「TMDB 匹配类型」。 下次再打开会沿用上一次的选择——如果你上次选了「覆盖」，这次想增量必须手动改回来。 只有点「取消」或右上角「关闭」才会重置。

115 网盘会多一个只读的「刮削参数」区块

只有 115 挂载源的弹窗里会显示当前的扫描线程 / 补全线程 / 请求延迟， 这是只读展示，要改得回 5a 的「媒体库设置」。

单个文件也能刮

对文件点「加入任务」不会弹窗，直接提交。成功后还会顺带刷新同一季其它集的 标题、简介与剧照。

5c. 看进度

进 任务中心 → 刮削任务：

• 列表按「挂载源 + 目录」聚合，一行可能合并多个任务
• 七列：挂载源 / 目录 / 类型 / 状态 / 进度 / 说明 / 操作
• 进度显示 已完成/总数 加百分比，以及成功、跳过、失败计数与当前正在处理的文件
• 类型列的小字会标出这一行实际用的是 轻刮削 还是 直刮削（补全任务标「补全」）
• 状态筛选：全部 / 进行中 / 排队中 / 已完成 / 失败 / 已暂停，各带计数
• 操作：单目录停止、恢复、删除已结束任务；全局停止全部、恢复全部、清理已结束
• 右栏可看子项进度与「音视频补全」区块，能跳过卡住的单个子项
• 刷新频率默认 2 秒，可改为关闭或 1～30 秒

同一目录有任务在跑时不能再发起

该目录已有排队中、刮削中或停止中的任务时，「加入任务」按钮会被禁用， 提示「任务已暂停，请到任务中心恢复或清理后再刮削」。必须先到任务中心停掉或清理。

为什么首次推荐轻刮削

轻刮削与直刮削的 TMDB 匹配准确度完全相同，区别不在「有没有技术元数据」， 而在技术元数据是推断的还是实测的：

• 轻刮削：从文件名推断分辨率、编码、位深、HDR 类型，落库时标记 inferredFrom: filename
• 直刮削：对每个媒体文件实际跑一次 ffprobe，拿到真实的容器、码率、音轨与字幕轨

直刮削用网盘直链加 -probesize 限制读取字节，不会下载整个文件 （115 走本地代理时还会被强制截断到 5 MB），但逐文件探测在几千部的库上仍然慢得多， 单个子项的硬超时也从 300 秒放宽到 600 秒。

所以合理的做法是：首次用轻刮削把库快速建起来，技术元数据交给补全任务慢慢补， 或者等播放节点在用户实际播放时用内嵌 ffprobe 异步补全。

轻刮削还有防退化保护：本次没有实测流数据、而库里已有时，只合并外挂字幕、不覆盖， 所以之后改回轻刮削重刮一遍，不会抹掉此前直刮削拿到的真实数据。

三个容易踩的坑

1. 「已完成」不等于「全部成功」。只要成功数大于 0，任务状态就是已完成， 失败明细只在子项里。一定要看进度列的「失败 N」计数。
2. 失败后 30 秒内重新点「加入任务」会被静默吞掉，提示「已有相同任务在队列中，已合并」。 去重逻辑把刚结束的失败任务也算作活跃。等半分钟再试。
3. 「恢复」不会重刮已失败的子项。恢复只是让任务断点续跑，已终态的子项（含失败）不重做。 要重刮失败项，必须用覆盖方式重新发起。

刮削完成后

技术元数据不会一直是空的。有三条补全路径：

路径	触发方式	补什么
音视频补全	调度任务 scrape.probe-backfill（每 3600 秒，默认停用，需在调度中心手动启用）	本地技术元数据。要求挂载源是轻刮削模式，补全任务自身会以直刮削方式执行
播放时补全	用户实际播放时，播放节点内嵌 ffprobe 异步执行	容器格式、时长、音视频轨道。不阻塞播放
剧集元数据补全	调度任务 scrape.episode-metadata-backfill（每天 04:30，Asia/Shanghai）	TMDB 侧缺失的剧集简介与剧照

完整的模式对比、参数清单、元数据优先级与排障见刮削与元数据。

第 6 步：建媒体库并同步

刮削完成后，进 媒体管理：

1. 点 新增媒体库
2. 填名称、类型（不限 / 电影 / 剧集 三档）、封面（可选）
3. 添加来源目录：选文件节点 → 选挂载源 → 用目录选择器逐级选到刚才刮削过的分类文件夹
4. 保存后在来源卡片上点 全量同步

同步会先给你看预览

全量与强制同步都会先跑 Dry-run：算出新增多少、更新多少、哪些聚合条目会消失、 哪些含用户编辑，可以逐条勾选保留。确认无误再执行。

媒体库不扫描磁盘

中央媒体库只聚合存储侧已经刮削好的结果。所以必须先刮削、再建库同步—— 顺序反了会得到一个空库。

同步完成后，库卡片会显示标题数与上次同步时间。此后新增文件由调度任务自动跟进： file-change-log.scrape（15 秒）重放文件变更、scrape.queue（15 秒）执行刮削、 sync.queue.process（30 秒）消费变更队列、central-media.sync（300 秒）增量同步已启用的库。

一个媒体库可以同时挂多个来源目录（多挂载源、多目录；分布式版还可以跨多个文件管理节点）， 同一部作品的多份文件会自动合并成一个条目。单机版只有一个内置 Storage，来源选择里不会出现节点切换。 详见媒体管理。

第 7 步：创建用户并播放

进 用户管理 → 新建用户，或到 注册码管理 批量生成注册码让用户自助注册。

用户登录后，推荐走 Emby 生态客户端：

• 用户门户的「客户端配置」Tab 会给出专属播放地址与用户名，填进客户端即可， 也可以一键生成带凭据的导入链接
• 门户里另有「网页播放」Tab，仍在完善中，格式兼容性不如原生客户端， 日常观片优先用 Emby 生态客户端

需要限制流量、并发或客户端时，见访问管控 与用户管理与标签。

验证清单

cd /opt/YiYi-media-deploy

# 单机版恰好三个服务，全部 Up
docker compose ps

# Web 入口
curl -fsSI http://127.0.0.1:18080/ | head -1

# 授权状态与部署能力
curl -sS http://127.0.0.1:18085/api/license/status
curl -sS http://127.0.0.1:18085/api/config/deployment/capabilities

在后台确认：

• [ ] 节点管理里 node-local-storage 与 node-local-play-agent 都是「在线」
• [ ] 仪表盘没有待处理事项
• [ ] 文件管理能浏览到挂载源下的目录与文件
• [ ] 任务中心 → 刮削任务 里没有持续失败项
• [ ] 媒体管理的库卡片标题数大于 0，上次同步时间正常
• [ ] 用户门户「客户端配置」能列出播放入口地址与凭据

常见问题

install.sh 报「配置仍包含占位值」.env 里还有 GENERATE_ON_INSTALL 没被替换，或者有 example.invalid。 必填项交给脚本生成即可，不要手工留占位符。

报「缺少 YIYI_XXX」 单机版预检要求这 5 项非空：YIYI_SERVER_HOST、YIYI_DB_USER、YIYI_DB_PASSWORD、 YIYI_SERVICE_TOKEN、YIYI_LICENSE_SERVER_URL。其中后四项保持 GENERATE_ON_INSTALL 或模板默认值即可，脚本会自动生成并回写。

（YIYI_ADVERTISE_HOST、YIYI_LICENSE_CLUSTER_TOKEN 等属于 分布式部署，单机版不需要。）

授权公钥下载失败 检查服务器能否访问 YIYI_LICENSE_SERVER_URL（必须是 HTTPS 且不带路径）。 脚本会校验返回的公钥合法且不含私钥字段，校验不过会直接失败。

页面一直停在「正在检查系统状态」 授权代理没起来或还没就绪。看 docker compose ps 里 yiyi-app 的健康状态， 再 docker compose logs --tail=200 yiyi-app 看授权相关进程的日志。

激活后跳不到创建管理员页 授权状态不是 ACTIVE 或 GRACE。服务器时间不准会报 CLOCK_SKEW，先校 NTP。

docker port 只有 18080，别的端口都没有 正常。单机版默认只把前端 18080 发布到宿主机；Play Agent 19090 绑在宿主机回环上供本机反代， 其余端口只在容器内部。PostgreSQL 与 Redis 走 Compose 私有网络，不发布。

内置节点显示离线 内置节点进程由应用容器监管。先在容器内探测，再看应用容器日志：

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

建了媒体库但没有内容 九成是顺序问题：必须先刮削，再建库同步。媒体库不扫描磁盘， 它只聚合存储侧已经刮削好的结果。回到第 5 步先跑分类刮削。

刮削很慢 先分清慢在哪一层。「API 调用间隔」是网盘目录列表接口的 sleep（只对 115 显示）， 与 TMDB 无关——代码里对 TMDB 没有任何限流或退避处理。 所以：目录列举慢就调「刷新目录缓存」与「API 调用间隔」； 逐文件探测慢说明用的是直刮削，改回轻刮削或等补全任务慢慢补。 详见刮削与元数据的排障章节。

刮削报「疑似分类目录」 说明你没勾「这是分类目录」，但这个目录下的子目录各自是不同作品。 按提示勾上再刮削即可。反过来，如果对一个分类容器不勾选， 后端的一致性校验会拦住你，不会把整个分类误当成一部作品。

更多见常见问题。

下一步

• 刮削与元数据：两种模式的差异、参数怎么调、自动增量怎么触发
• 单机版部署（三容器）：完整安装参数、数据目录与排查
• 分布式部署（控制面同机）：控制面一台机器，外部工作节点横向扩展
• 分布式部署（按角色多机）：控制面拆成四台
• 单机版迁移到分布式版：什么时候需要换模式、怎么换
• 系统架构：一次播放请求是怎么走完的
• 功能总览：18 篇模块文档的能力矩阵