YiYi Media

外观

单机版迁移到分布式版 ​

这一页讲两件事：旧同机多容器部署如何迁入三容器单机版，以及单机版如何升级为分布式版。两者都是有前置条件、有回滚点的受控操作，不是改配置文件。

一、旧同机多容器部署 → 单机版三容器 ​

如果你现在的部署是「一台机器跑多个应用容器」的旧形态（Config、User、Media、Gateway、Frontend 分开跑），可以迁入单机版三容器形态。

这不是「换个 profile」

旧形态的控制面拆成一堆容器，单机版把它们收进一个应用容器 （容器名 YiYi-media-standalone，Compose 服务名 yiyi-app），并把 Storage 与 Play Agent 变成内置节点。迁移涉及节点身份、数据目录与数据库的搬迁，必须按顺序执行。

前置条件 ​

项目要求
版本目标单机版镜像已发布，且你拿到了 edition=STANDALONE 的一次性授权码
节点数量现有 Storage 与 Play Agent 各不超过一个。任一类型存在多个节点时，自动迁移会停止
数据备份四个数据库、data/license/、上传目录与 Storage 数据已完整备份
停机窗口迁移需要停旧服务，数据量大时停机时间不短

多节点场景必须先做人工决策

安装程序检测到任一类型超过一个节点时会停止自动迁移，并先生成影响报告 （媒体源、用户授权、手动反代、任务引用数量）。管理员必须明确选择保留哪个 Storage 与哪个 Play Agent。未选中的节点会先被禁用并保留记录，不会立即删除。

本期不做自动合并多个 Storage 数据库，也不做多节点媒体库引用的自动重写。确实需要合并时， 另立专项迁移方案。

迁移步骤 ​

  1. 只读预检：确认版本、数据库与节点数量，确认两类节点各只有一个。 安装脚本会在启动应用容器前只读查询现有受管节点：
    • 两类节点各只有一个时，自动把原节点 ID 写进 .env 的 YIYI_EMBEDDED_STORAGE_NODE_ID / YIYI_EMBEDDED_PLAY_AGENT_NODE_ID，供内置节点沿用；
    • 任一类型超过一个时停止并提示，见上方「多节点场景必须先做人工决策」。
  2. 停止旧服务与外置节点：保留 PostgreSQL、Redis 与全部数据目录。
  3. 完整备份：四个数据库（pg_dump）、data/license/、data/config/uploads/、Storage 数据目录。
  4. 沿用原节点 ID 并提升为内置节点：把原有的 Storage / Play Agent 节点标记为内置节点 （system_managed / node_scope=EMBEDDED），必须沿用原节点 ID，避免破坏媒体源里的 nodeId 引用、用户播放线路授权、手动反代地址背后的节点授权关系，以及历史任务与日志关联。 这一步使用系统提供的只读影响报告 + 显式确认接口完成（仅单机版镜像提供， 需先把新镜像部署起来），不要手工改数据库： GET /api/config/deployment/legacy-nodes/report 先确认两类节点各不超过一个并取得候选 ID， 再用 POST /api/config/deployment/legacy-nodes/promote 按候选 ID 显式确认。 系统不会自动提升历史外部节点：提升会改变节点的生命周期语义（此后不能删除、 卸载或独立升级），必须由管理员明确确认。
  5. 迁移 Storage 数据库：如果 Storage 用的是独立 PostgreSQL，把它导入目标 yiyi_storage。
  6. 迁移 Storage 数据与 Play Agent 缓存配置：mount-data、spool、读缓存， 以及 Play Agent 的 VFS 缓存与图片缓存配置。
  7. 启动三容器：docker compose up -d --wait，等待全部数据库迁移完成。
  8. 验证：媒体源、用户线路授权、文件浏览与播放全部走通。
  9. 仅在验证成功后移除旧容器与旧进程。

节点 ID 是迁移的关键

节点 ID 一旦改变，媒体源、用户授权、手动反代与历史任务里对它的引用就全部失联。 所以迁移的目标是保留 ID，而不是新建节点。

迁移后的检查清单 ​

  • [ ] docker compose ps 恰好三个服务
  • [ ] 节点管理里两个内置节点都是「在线」，且节点 ID 与迁移前一致
  • [ ] 媒体源能正常同步，没有出现大量失联来源
  • [ ] 用户播放线路授权仍然有效
  • [ ] 手动反代地址状态正常，入口令牌与迁移前一致
  • [ ] 文件浏览、上传下载、媒体同步与刮削可用
  • [ ] 云盘管理正常（FUSE 主机挂载默认关闭不影响这些能力）

二、单机版升级为分布式版 ​

必须走授权的专用版本升级操作

单机版升级到分布式版不允许只改 .env、Compose profile 或角色变量原地切换。 必须完成：

  1. 管理台执行「升级为分布式版」，或调用 POST /api/admin/licenses/{id}/edition
  2. 获得新的 edition=DISTRIBUTED 签名租约
  3. 完成部署拓扑迁移与数据校验

YIYI_DEPLOY_ROLE 之类的旧角色变量不表达 Edition，也绕不过签名租约的能力边界。

前置条件 ​

项目要求
授权发布方已同意版本升级，且你能在管理台执行版本升级操作
目标拓扑已准备好分布式部署所需的至少 4 台服务器，位于同一私有网络
网络私网内可放行 5432、6379、18085、18089
数据备份四个数据库、data/license/、上传目录、Storage 与 Play Agent 数据目录已完整备份
节点计划已想清楚内置节点保留为 ID 后如何成为外部节点，以及后续是否需要按配额新增节点

升级步骤 ​

  1. 备份：按升级、备份与回滚的清单做一次完整备份，尤其是四个数据库与 data/license/。
  2. 执行版本升级：在管理台执行「升级为分布式版」，或调用 POST /api/admin/licenses/{id}/edition。 这会签发带 edition=DISTRIBUTED 的新租约，并产生审计记录。
  3. 确认能力变化：GET /api/config/deployment/capabilities 应显示 edition=DISTRIBUTED， 且 deploymentMode 已不再是单机版。此时「节点管理」才会出现新增外部节点的入口与配额表单。
  4. 准备分布式部署包：按分布式部署（按角色多机）的顺序安装 control → user → media → edge。
  5. 迁移数据：把原单机版 PostgreSQL 的四个库按分布式口径落到 control； Storage 的 yiyi_storage 随节点走，Play Agent 缓存按需迁移。
  6. 迁移内置节点：原内置 Storage / Play Agent 转为分布式版的外部工作节点， 在目标机上按分布式工作节点部署安装，并沿用原节点 ID。
  7. 验证：两台内置节点对应的外部节点在线，媒体源、用户线路授权、手动反代与播放链路全部走通。
  8. 仅在验证成功后停用旧单机版部署。

原有内置节点不会自动变成外部节点

内置节点是随主应用启动的进程，分布式版没有这个机制。升级后必须在目标机上把对应的 工作节点真正部署起来，并沿用原节点 ID，否则媒体源与用户授权会失联。

回滚点 ​

阶段回滚方式
执行版本升级前直接放弃升级，单机版部署不受影响
版本升级后、拓扑迁移前联系发布方处理许可证；单机版数据未被改动，可继续以单机版运行
拓扑迁移中保留原单机版部署与环境，不要在验证通过前拆除；数据库回滚用升级前的 pg_dump
验证失败恢复升级前的数据库转储与 data/license/，回到单机版部署继续运行

不支持自动降级

不支持自动从分布式版降级为单机版。一旦完成 Edition 升级与拓扑迁移， 回到单机版形态需要联系发布方另行处理，且不在本期自动流程范围内。

相关文档 ​

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

Copyright © 2026 YiYi Media