YiYi Media

外观

授权与版本 ​

YiYi Media 是授权软件，分单机版与分布式版两个 Edition。这一页讲运维授权： Edition 与部署形态怎么匹配、状态怎么读、过期了会怎样、限制什么、备份要带哪个目录。

首次激活的操作步骤见初始化与授权激活。

两个 Edition，与部署形态严格匹配 ​

许可证里带一个 Edition 声明，标识你买的是哪个产品版本：

Edition对应部署模式节点模型
STANDALONE单机版部署（三个容器：YiYi-media-standalone + -postgres + -redis）固定一个内置 Storage 与一个内置 Play Agent
DISTRIBUTED分布式部署（Control / User / Media / Edge + 外部工作节点）外部 Storage / Play Agent，按配额新增与扩容

Edition 写在签名租约里，由服务端强制执行，不是前端开关，也不能靠改 Compose 环境变量扩大能力。

部署形态与 Edition 严格一一匹配：

部署形态许可证 Edition结果
单机聚合镜像STANDALONE允许
分布式部署DISTRIBUTED允许
分布式部署STANDALONE拒绝
单机聚合镜像DISTRIBUTED拒绝并提示使用对应部署包

版本不匹配时不会删你的数据

不匹配时系统保留激活、许可证状态、日志与备份能力，不开放业务功能，也不删除任何客户数据。 配错部署包时换回正确的包并用匹配的许可证重新激活即可。

历史许可证按分布式版兼容

升级前签发、没有 Edition 声明的历史许可证，一律按 DISTRIBUTED 处理， 避免现有客户升级后发生非预期的能力收缩。需要单机版请向发布方申请 STANDALONE 许可证。

你需要做的事很少 ​

授权由部署包自动接管：

  • install.sh 会从授权中心下载签名公钥并校验，写入部署目录
  • 授权代理服务随应用一起启动，定期续期
  • 部署包统一给各服务注入授权文件路径

你不需要手工放置密钥文件、不需要写额外的 compose 配置、 不需要在命令行激活。首次授权与后续状态管理都在网页里完成。

日常唯一可能要做的是：授权快到期时联系发布方续期，以及备份时带上授权状态目录。

三种状态，对应界面上的横幅 ​

后台顶部的横幅每 60 秒刷新一次，只在非正常状态时出现。

状态界面表现业务你要做什么
正常没有横幅全部可用无
宽限期黄色横幅，明示宽限截止时间全部可用检查服务器能否访问授权中心，在截止前恢复即可
受限模式红色横幅部分功能被拒联系发布方处理，或恢复授权中心连通性

受限模式：还能做什么，不能做什么 ​

进入受限模式后的设计原则是保护数据、避免雪崩——不会因为你暂时联系不上授权中心就毁掉部署。

仍然允许一律拒绝
管理员登录新建播放会话
查看授权状态、重新激活文件写入
日志导出调度任务执行
数据备份新节点注册（分布式版）
健康探针（避免编排系统反复重启容器）—

不删数据、不卸卷

受限模式不会删除任何业务数据，也不会卸载 FUSE 挂载。 授权恢复后一切照旧，不需要重新初始化。

授权限制什么 ​

单机版与分布式版的限制不同：

能力单机版（STANDALONE）分布式版（DISTRIBUTED）
内置 Storage固定 1 个无固定内置节点
内置 Play Agent固定 1 个无固定内置节点
新增外部 Storage禁止按配额允许
新增外部 Play Agent禁止按配额允许
手动反代地址允许允许
多服务器部署禁止允许
节点二进制与安装命令禁止允许
节点配额内置节点固定占用，管理台不可覆盖授权中心配置

单机版的 maxStorageNodes=1 不代表可以新增节点

单机版的这两个配额值只代表两个内置节点本身，不代表允许用户新增节点。 单机版后台没有「新增节点」入口，直接调用接口也会被服务端拒绝。

分布式版在「节点管理」里新增节点时会校验配额，表单上直接显示「部署配额 已用 / 上限」； 配额用满时新增按钮被禁用，提示「授权配额已满」。删除节点会释放名额。 需要扩容时联系发布方提升节点上限。

手动反代地址在两种模式下都不占配额——它只是登记一个已存在的反向代理入口，不是部署的节点。

授权不限制什么 ​

写清楚边界，避免选型时误解：

  • 不限制用户数。你可以创建任意数量的用户账号。
  • 不做功能模块开关授权。功能能力由 Edition 与 features 决定，不存在「某个模块需要单独购买解锁」。
  • 不绑定硬件。部署身份不使用 MAC 地址、容器 ID 或 CPU 序列号， 因此允许受控迁移与重新绑定——换服务器、换容器、迁移数据目录都不会因为硬件指纹失效。
  • 不是永久离线可用。断网后在宽限期内业务照常，但越过宽限截止就会进入受限模式。

部署身份不保证绝对不可破解

客户完全掌握宿主机 root 与 Docker 权限时，产品不承诺绝对不可破解。 Edition 的作用是明确能力边界与合规使用范围，不是防篡改的硬件锁。

换机迁移 ​

产品不绑定硬件，所以换服务器有两条路径。先判断该用哪条，不要在本可直接迁移时误做反激活。

优先考虑「复制身份目录」

如果旧机器还能正常操作，且你愿意整机迁移：

  1. 停止旧机器上的服务；
  2. 把 data/license/（身份 + 租约）随其他数据一起复制到新机器；
  3. 在新机器启动并确认续租正常。

新机器沿用的是同一个部署身份，不需要反激活，也不占用新的部署名额。 要求是不要让复制了同一份部署私钥的两台机器长期同时运行。

自助反激活（全新部署迁移） ​

适用于新机器要作为一个全新部署重新安装、不准备复制旧身份目录的场景。 入口在「系统配置 → 授权与迁移」，仅完整管理员可见——菜单委派身份不能执行。

流程是两阶段的，顺序不能颠倒：

阶段操作此时的状态
1生成迁移码，复制或下载保存授权中心状态不变，本机继续正常运行
2勾选「已安全保存」并输入确认词「反激活」后提交本机业务立即停止，迁移码生效

提交成功后：

  • 本机进入 DEACTIVATED 状态，页面提示「当前部署已反激活」；
  • 当前部署名额与节点占用立即释放，可以给新机器用；
  • 旧机器不会再续租，不再提供业务；
  • 不删除任何业务数据（数据库、媒体文件、配置、缓存都在）。

到新机器的首次激活页输入迁移码即可完成激活，Edition、授权期限、功能与配额都保持不变。

迁移码的约束

  • 只能使用一次，默认 24 小时后到期（且不会超过许可证自身的到期时间）。
  • 页面不在 URL、浏览器存储或日志里保留它；请自行安全保存。
  • 丢失或过期后无法自助恢复，需联系发布方重新绑定。

三种「停用」状态含义完全不同

它们都会停止业务，但原因和处理方式都不一样：

状态含义能否恢复
DEACTIVATED只有当前部署被主动停用，许可证本身仍然有效用迁移码在新机器激活，或联系发布方重新绑定
CONFLICTED同一份授权在多台机器上同时运行，被服务端自动阻断停掉多余的机器，再由发布方解除阻断
REVOKED整份许可证被发布方撤销需发布方处理

看到「当前部署已反激活」时不要误以为整份授权作废。 看到「检测到多机并发使用」时也不要以为授权损坏——去检查是不是有旧机器还在跑。

同一授权不能同时跑在多台机器上 ​

授权不绑定硬件，所以把 data/license/ 复制到另一台机器后，两台机器持有的是 同一份部署身份。如果它们同时运行，授权中心会发现两个启动会话的时间区间重叠， 于是把这份身份标记为冲突，两台机器一起停止业务（状态 CONFLICTED）。

这是有意的：一台授权同时服务多台机器属于超范围使用，服务端无法区分 「迁移中的短暂重叠」与「长期并行」，因此按重叠即阻断处理。

迁移时必须先停旧机器

顺序是先停旧机、再起新机，不能反过来。先起新机的话，只要旧机还在续租一次， 时间区间就会重叠并被判定为并发——即使你打算稍后就停掉它。

已经被阻断时：停掉多余的机器，只保留一台，然后联系发布方解除阻断。 解除后需要重新启动服务；数据不会被删除。

旧机器已损坏或丢失 ​

这种情况没有旧部署的私钥可用于证明身份，不提供匿名自助重置—— 否则任何拿到许可证标识的人都能踢掉合法部署。请走发布方人工流程： 核验客户身份后，在授权管理台停用旧部署并重新签发激活码。

管理台的审计日志会区分「管理员停用」与「自助反激活」两种来源。

断网与离线 ​

场景结果
短暂断网无影响。授权状态在本机校验，不依赖联网
断网超过续期周期进入宽限期，黄色横幅显示截止时间，业务照常
断网超过宽限截止进入受限模式，红色横幅
授权被发布方撤销联网时立即生效；完全离线的情况下，最迟在「最后有效授权 + 宽限期」之后停止授权功能
本机被自助反激活立即生效（收到停用租约后本机不再续租），不需要等租约自然过期
检测到多机并发使用立即生效，两台机器一起停止业务
服务器时间不准会被判为时钟异常并拒绝授权。先校 NTP

备份要带上授权状态目录 ​

不要把授权状态目录弄丢

部署目录下的 data/license/ 保存着这套部署的身份与授权状态。 丢了等于部署身份丢失，需要联系发布方重新绑定。

备份时务必带上它，权限建议 700：

text
data/license/
├── identity/      # 部署身份
└── lease/         # 当前授权状态

分布式部署下，user / media / edge 机器另有 data/license/sync-state/。

从单机版升级到分布式版 ​

单机版升级到分布式版必须走授权的专用版本升级操作：

  1. 在管理台执行「升级为分布式版」，或调用 POST /api/admin/licenses/{id}/edition
  2. 获得新的 edition=DISTRIBUTED 签名租约
  3. 完成部署拓扑迁移与数据校验
  4. 按分布式部署安装控制面与外部工作节点（同机或按角色多机皆可，见部署模式与版本选择）

不允许只改配置原地切换

不允许只改 .env、Compose profile 或角色变量在两种模式间切换。 YIYI_DEPLOY_ROLE 之类的旧角色变量不表达 Edition，也绕不过签名租约的能力边界。

不支持自动从分布式降级为单机版；单机版的多节点自动合并与多节点媒体库引用重写也不在本期范围内。 完整前置条件、迁移顺序与回滚点见单机版迁移到分布式版。

界面上的部署能力 ​

GET /api/config/deployment/capabilities 是管理员可读的部署能力接口，返回 edition、 deploymentMode、editionMatchesDeployment、editionMismatchMessage、 externalManagedNodesAllowed、nodeBinaryDistributionAllowed、embeddedNodes， 以及两个内置节点 ID。前端的能力展示只消费后端派生结果，不自行判断是否允许节点操作。

一次性授权码 ​

  • 由发布方提供，激活即失效，不能重复使用
  • 已经激活过的部署不能用新码覆盖
  • 输入框是密码类型，不回显；要求至少 24 个字符
  • 只在网页里输入。不要通过命令行参数、URL、环境变量或日志传递， 那样会留在 shell 历史与进程列表里

排查 ​

现象原因处理
页面一直停在「正在检查系统状态」授权代理没起来看 docker compose ps 里授权相关进程的状态与日志
提交授权码后不跳转状态没变成正常或宽限期依次查：服务器时间、授权码是否已用过、能否访问授权中心
提示部署形态与版本不匹配许可证 Edition 与部署模式不一致单机版用 STANDALONE、分布式版用 DISTRIBUTED，向发布方确认
黄色横幅长期不消失服务器访问不到授权中心检查出网与 DNS；.env 里的授权中心地址必须是不带路径的 HTTPS
红色横幅已越过宽限截止，或被撤销联系发布方；恢复后自动回到正常状态，不需要重装
新增节点提示「授权配额已满」节点数达到授权上限（仅分布式版）删除不再使用的节点释放名额，或联系发布方扩容
单机版找不到「新增节点」按钮设计如此，单机版只允许新增手动反代地址需要外部节点请走单机版迁移到分布式版
时钟异常服务器时间偏差过大校准 NTP 后重启服务
迁移或恢复后授权失效没带上 data/license/ 目录从备份恢复该目录；确实丢了就联系发布方重新绑定
横幅提示「检测到多机并发使用」同一份授权在不止一台机器上同时运行（常见于迁移后旧机没停）停掉多余的机器，只保留一台，再联系发布方解除阻断

相关文档 ​

自托管媒体管理系统（单机版 / 分布式版） · 想先体验或有问题，加 Telegram 群：t.me/yiyi_media_group

Copyright © 2026 YiYi Media