YiYi Media

外观

分布式部署（控制面同机） ​

一台服务器承载全部控制面服务，播放与存储能力由外部工作节点提供。对应部署仓库的 v2-all-in-one 分支，许可证要求 edition=DISTRIBUTED。

这一页是分布式部署（DISTRIBUTED）的两种形态之一。分布式部署内部把控制面分成 control / user / media / edge 四类角色，这些角色可以全部放在一台机器上（本页）， 也可以各占一台机器（分布式部署（按角色多机））。

它和「单机版」不是一回事

两者都是「一台服务器」，但产品能力边界完全不同：

单机版（STANDALONE）控制面同机（DISTRIBUTED）
容器数3 个（应用容器 + 数据库 + 缓存）8 个（6 个应用服务 + 数据库 + 缓存）
Storage / Play Agent内置，随主应用升级，不能新增外部工作节点，按授权配额新增
一键安装节点命令不提供提供
许可证 EditionSTANDALONEDISTRIBUTED

选错分支会怎样，见部署模式与版本选择。

与多机形态的关系 ​

本页与分布式部署（按角色多机）是同一个产品版本、同一套许可证、 同一个控制面，只是把这 6 个应用服务放在几台机器上的区别：

分支控制面布置需要 YIYI_DEPLOY_ROLE需要 join.env
v2-all-in-one（本页）6 个应用服务全在一台机器不需要（写了也会被忽略）不需要
v3-multi-host每类角色各一台机器需要（control / user / media / edge）需要，由 control 生成后分发

从同机扩到多机时，两个分支的数据与许可证完全兼容——迁移方法见 控制面同机迁移到多机。

本机跑什么 ​

text
┌──────── 一台服务器（控制面）────────┐
│ frontend      :18080   Web 入口     │
│ gateway       :18086   API 网关     │
│ config        :18085   注册中心      │
│ user          :18082   账号与线路    │
│ media         :18083   媒体库        │
│ license-agent :18088   许可证租约    │
│ postgres      :5432    ← 可选       │
│ redis         :6379    ← 可选       │
└─────────────────────────────────────┘

其他机器（工作节点，不由本分支的 Compose 安装）
├── Storage 节点      ← 网页「节点管理」新增，用页面给出的一键命令部署
└── Play Agent 节点   ← 同上，可多台

6 个应用服务使用 host 网络（直接绑定宿主机端口），因此 18080、18082、18083、 18085、18086、18088 都会在本机监听；其中只有 18080 需要对用户开放。

postgres 与 redis 走 Compose 私有网络，端口发布到 YIYI_INFRA_BIND_HOST （同机形态自动写 127.0.0.1），应用服务经 127.0.0.1 访问它们。

前置条件 ​

项目要求
机器一台 Linux 服务器；播放与存储节点可以是另外的机器
授权一个 edition=DISTRIBUTED 的一次性授权码
出站网络能访问 YIYI_LICENSE_SERVER_URL 指向的授权中心（HTTPS）
命令行工具docker、openssl、curl、python3，能用 sudo
端口18080 对用户开放；18085 需对所有工作节点开放（它们在别的机器上）
磁盘数据目录默认在部署目录下的 data/

工作节点在别的机器上，所以 18085 必须可达

config 的 18085 是注册中心。工作节点（Storage / Play Agent）要从它们所在的机器连上它， 才能注册、心跳与拉取安装脚本。如果工作节点和本机在同一个私网，放行私网即可； 不要把 18085 直接暴露到公网，正确做法是走私网或 VPN。

第 1 步：克隆并准备 .env ​

bash
git clone -b v2-all-in-one 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

第 2 步：填写 .env ​

必填项：

dotenv
YIYI_SERVER_HOST=<本机内网地址，工作节点要能访问到>
YIYI_PUBLIC_HOST=<对外域名或公网 IP，浏览器访问用>
变量怎么填说明
YIYI_SERVER_HOST必填本机地址，不带协议与路径。不要填 127.0.0.1，否则工作节点连不上
YIYI_PUBLIC_HOST必填用户浏览器访问的地址；留空会回退为 YIYI_SERVER_HOST
YIYI_DATA_DIR留空留空 = 部署目录下的 data/
YIYI_DB_PASSWORD、YIYI_SERVICE_TOKEN保持 GENERATE_ON_INSTALL脚本用 openssl rand -hex 32 生成并回写
YIYI_LICENSE_SERVER_URL保持模板值发布方提供的授权中心地址
YIYI_IMAGE_TAG建议填留空使用可变的 latest；生产建议锁定不可变版本标签
YIYI_USER_HOST不用填安装脚本会自动写 127.0.0.1（同机形态下 user 就在本机）

本分支不需要角色选择

.env 里的 YIYI_DEPLOY_ROLE 会被忽略（并打印提示）；install.sh 固定按 控制面同机处理。真正决定启停的是 COMPOSE_PROFILES，由安装脚本按下面的 数据源选择自动写入，不要手工改。

第 3 步：选择数据库与缓存 ​

两个选择互相独立，所以支持任意组合：

变量取值效果
YIYI_DB_MODEbundled（默认）本机启动 postgres 容器
external不启动，用你的 PostgreSQL
YIYI_REDIS_MODEbundled（默认）本机启动 redis 容器
external不启动，用你的 Redis
组合本机容器数
都自带（默认）8
外部数据库 + 自带 Redis7
自带数据库 + 外部 Redis7
都用外部6
dotenv
# 例：用你自己的 PostgreSQL，缓存仍用本机的
YIYI_DB_MODE=external
YIYI_DB_HOST=db.internal      # 不带协议与端口
YIYI_DB_PORT=5432
YIYI_DB_USER=yiyi
YIYI_DB_PASSWORD=<外部库口令>
YIYI_REDIS_MODE=bundled

用外部 PostgreSQL 要先建库

外部实例需预先建好 yiyi_config、yiyi_user、yiyi_media、yiyi_storage 四个库，并授权上述用户连接与建表。可参考部署仓库里的 postgres-init.sql。

YIYI_DB_MODE=external 时安装脚本会强制校验 YIYI_DB_HOST（必须是不带协议和端口的主机名）、 YIYI_DB_USER、YIYI_DB_PASSWORD 非空，缺一项直接退出。

从 bundled 切到 external 不会搬数据

安装脚本不迁移数据。切换前必须先 pg_dump 那四个库，切完再导入外部实例。

第 4 步：安装 ​

bash
sudo ./install.sh

脚本会：检查 .env 与工具 → 按数据源选择写入 COMPOSE_PROFILES → 准备数据目录 → 下载并校验授权公钥 → docker compose pull → up -d 并等健康检查 → 探测各服务。

安装完成后访问：

text
http://<YIYI_PUBLIC_HOST>:18080

第一个页面是授权激活页。输入发布方提供的一次性授权码，激活成功后自动进入创建管理员向导 （顺序是先激活、再建管理员）。

第 5 步：部署外部工作节点 ​

控制面装好后，「节点管理」里就能新增节点了。流程：

  1. 到后台「节点管理」新增节点，选择服务类型（Storage 或 Play Agent）；
  2. 页面给出一行安装命令；
  3. 复制到目标机器执行，节点自动注册到 config 的 18085。

完整参数（二进制 / Docker、ffmpeg、卸载与升级）见 分布式工作节点部署。

节点数量受授权配额限制

maxStorageNodes 与 maxPlayAgentNodes 由许可证决定，新增前会向授权中心原子占用名额， 超限返回 NODE_LIMIT_REACHED。单机版没有这套能力，见授权与版本。

端口 ​

端口服务是否对外开放
18080frontend（Web 入口）是，唯一对用户的入口
18085config（注册中心）对工作节点开放（私网/VPN），不要直接暴露公网
18082user私网或本机
18083media私网或本机
18086gateway只被同机 frontend 经 127.0.0.1 访问
18088license-agent只绑 127.0.0.1
5432 / 6379PostgreSQL / Redis只在本机或私网（用外部实例时不存在）

工作节点自己还会监听 18084（Storage）与 19090（Play Agent）， 需要对控制面与播放客户端可达，详见端口与网络。

验证 ​

bash
cd /opt/YiYi-media-deploy

# 1. 容器数与前面选的数据源组合一致
docker compose ps

# 2. 授权状态（未激活时返回 UNACTIVATED，正常）
curl -fsS http://127.0.0.1:18085/api/license/status

# 3. 各服务健康
for p in 18085 18082 18083 18086; do
  curl -fsS -o /dev/null -w "$p %{http_code}\n" http://127.0.0.1:$p/actuator/health
done

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

激活后到「节点管理」新增并部署工作节点，两者都「在线」后即可使用文件管理与播放。

从同机扩到多机 ​

同机形态是分布式部署的子集：控制面 6 个服务本来就分属 control / user / media / edge 四类角色，v2-all-in-one 只是把它们放在一台机器上。要拆成多机：

  1. 准备目标机器，克隆 v3-multi-host 分支；
  2. 按分布式部署（按角色多机）的顺序安装 control → user → media → edge；
  3. control 的目标机要能接管现有数据库与 data/license/（或指向你已有的外部实例）；
  4. 工作节点不用重装：它们只连 config 的 18085，把 YIYI_SERVER_HOST/注册中心地址 指到新的 control 即可；节点 ID 与令牌不变。

许可证与数据无需变更

两种形态都是 edition=DISTRIBUTED，同一份许可证在两边通用，不涉及版本升级操作。 注意：从单机版（STANDALONE）换到本形态则完全不同——那需要走授权的版本升级与 拓扑迁移，见单机版迁移到分布式版。

常见问题 ​

现象原因处理
只有 6 个容器，没有 postgres/redis这是预期的——你把数据库和缓存都设成了 external确认 YIYI_DB_MODE / YIYI_REDIS_MODE 的值是否符合预期
少了 postgres 或 redis 中的一个两个开关是独立的同上，分别检查两个变量
工作节点注册不上节点的机器连不到本机 18085，或 YIYI_SERVER_HOST 填了 127.0.0.1从节点机器 curl http://<本机地址>:18085/actuator/health；改对地址后重跑安装
external 模式必须填写...YIYI_DB_MODE=external 但地址或凭据没填补齐 YIYI_DB_HOST / YIYI_DB_USER / YIYI_DB_PASSWORD
切到 external 后数据不见了脚本不搬数据从 pg_dump 备份导入外部实例
激活被拒绝、提示版本不匹配用了 STANDALONE 的授权码本形态需要 edition=DISTRIBUTED
「节点管理」里没有「新增节点」授权 Edition 或部署形态不匹配，能力被收窄查 GET /api/config/deployment/capabilities
docker compose ps 什么也没列出COMPOSE_PROFILES 被手工改坏重跑 sudo ./install.sh，它会重新写入该变量

相关文档 ​

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

Copyright © 2026 YiYi Media