部署模式与版本选择

YiYi Media 的安装入口只有一个：部署仓库 YiYi-media-deploy 加它自带的 install.sh。这一页讲清楚两种且只有两种正式部署模式、它们下面的三种部署方式怎么选、要准备什么、数据落在哪里、怎么升级。

两种模式，三种方式

模式决定产品能力边界，由签名租约里的 edition 强制；方式决定这些能力装在几台机器上。部署仓库用三个 Git 分支承载三种方式，每个分支根目录都是一套可直接 docker compose pull && docker compose up -d 的完整部署文件：

部署方式	分支	部署模式（`edition`）	拓扑	容器
单机版部署	`main`	`STANDALONE`	一台服务器	3 个（应用 + 数据库 + 缓存）
分布式·控制面同机	`v2-all-in-one`	`DISTRIBUTED`	一台服务器 + 外部工作节点	6～8 个（见下）
分布式·按角色多机	`v3-multi-host`	`DISTRIBUTED`	至少 4 台控制面 + 外部工作节点	每台 2～4 个

「控制面同机」与「按角色多机」是同一个模式（都是 DISTRIBUTED），只是控制面放在几台机器上的区别：前者是本页下面那张拓扑图全部塞进一台机器，后者是每类角色各占一台。两者的数据、许可证、工作节点完全通用，可以互相演进。

换分支只换方式，换模式要走授权升级

同机 ↔ 多机：都在 DISTRIBUTED 内，数据与许可证通用，按从同机扩到多机操作。
单机版 ↔ 分布式：跨模式，能力边界会变，必须走授权的版本升级与拓扑迁移，见单机版迁移到分布式版。不能靠换分支完成。

方式选错会被服务端拒绝

拿 STANDALONE 的许可证装分布式方式（或反之）时，系统保留激活、许可证状态、日志与备份能力，但不开放业务功能，也不删除任何数据。

两种模式的能力差异

Compose profile、控制面角色与节点安装方式都是模式内部的实现细节，不是第三种模式。下面是产品能力层面的差异——这些差异只由 edition 决定，与装在几台机器上无关：

维度	单机版部署（`STANDALONE`）	分布式部署（`DISTRIBUTED`）
标准拓扑	一台服务器，`YiYi-media-standalone` + `YiYi-media-standalone-postgres` + `YiYi-media-standalone-redis` 三个容器	控制面 6 个应用服务按 `control` / `user` / `media` / `edge` 角色拆分（同机或多机皆可），另加外部工作节点
服务器数量	1 台	1 台（控制面同机）起；按角色多机时至少 4 台，必须位于同一私有网络
存储与播放节点	一个内置 Storage（`node-local-storage`）与一个内置 Play Agent（`node-local-play-agent`），随主应用安装、启动、升级	外部工作节点，在「节点管理」里创建后自助部署，可按配额横向扩容
用户能新增什么	只能新增手动反代地址	外部 Storage / Play Agent 节点 + 手动反代地址，均受授权配额限制
节点二进制与安装命令	不提供	提供，支持二进制与 Docker 两种形态
适用规模	个人 / 小团队，一台机器起步	控制面负载要分散、网盘多、播放并发高
许可证 Edition	`edition=STANDALONE`	`edition=DISTRIBUTED`
迁移入口	只能经授权的专用版本升级操作升级为分布式版，见单机版迁移到分布式版	不支持降级为单机版

「一台服务器」不等于「单机版」

两种模式都能只跑一台服务器，别只看机器数量：

单机版：三容器聚合，节点内置，不能新增节点；
分布式·控制面同机：8 个服务，节点是外部的，可按配额新增。

按机器数量选会选错，请按是否需要外部工作节点与横向扩容来选。

跨模式不能只改配置原地互转

不允许只改 .env、Compose profile 或角色变量在两种模式之间切换。单机版升级到分布式版必须走授权的专用版本升级操作，并完成部署拓扑迁移与数据校验，详见单机版迁移到分布式版。

分布式·控制面同机拓扑

text

┌──────── 一台服务器（控制面，host 网络）────────┐
│ frontend      :18080   ← Web 入口              │
│ gateway       :18086   （本机内部）            │
│ config        :18085   ← 工作节点要连它         │
│ user          :18082   （本机内部）            │
│ media         :18083   （本机内部）            │
│ license-agent :18088   （只绑 127.0.0.1）      │
│ postgres      :5432    ← 可用外部实例          │
│ redis         :6379    ← 可用外部实例          │
└────────────────────────────────────────────────┘
                    ▲ 注册到 18085
                    │
   其他机器：Storage 节点 × N、Play Agent 节点 × M
   由网页「节点管理」新增，用页面给出的一键命令部署

postgres 与 redis 可以用 YIYI_DB_MODE / YIYI_REDIS_MODE 换成外部实例，两者独立选择，所以本机容器数在 6～8 个之间。详见分布式部署（控制面同机）。

单机版标准拓扑

text

┌────────── YiYi-media-standalone 容器 ──────────┐
│ nginx/frontend :18080      ← Web 入口          │
│ gateway        :18086      （仅容器内部）      │
│ config         :18085      （仅容器内部）      │
│ user           :18082      （仅容器内部）      │
│ media          :18083      （仅容器内部）      │
│ storage        :18084      （仅容器内部）      │
│ play-agent     :19090      ← 播放客户端直连     │
│ license-agent  :18088      （仅容器内部）      │
└────────────────────────────────────────────────┘
           │                         │
YiYi-media-standalone-postgres  YiYi-media-standalone-redis

docker compose ps 在标准单机版安装中只会出现三个服务：yiyi-app、postgres、redis；对应的容器名分别是 YiYi-media-standalone、YiYi-media-standalone-postgres、 YiYi-media-standalone-redis。前者用于 docker compose 命令，后者用于 docker 命令。

宿主机上发布两个端口：前端 18080（Web 入口）与 Play Agent 19090（播放客户端直连）。其余端口不发布到宿主机。

分布式部署拓扑

txt

控制面 —— 由 YiYi-media-deploy 安装，同一私网（可同机，也可按角色分机）
  control   config(18085) + postgres(5432) + redis(6379) + license-agent(18088，集群中继 18089)
  user      user(18082)   + license-sync
  media     media(18083)  + license-sync
  edge      gateway(18086) + frontend(18080) + license-sync   ← 用户只访问这一台的 18080

  同一台机器跑全部控制面服务 = v2-all-in-one 分支（8 个服务，无需 join.env）
  按角色分散到多台机器       = v3-multi-host 分支（需分发 join.env 与中继证书）

工作节点层 —— 不由部署包安装，在网页「节点管理」创建后一键自助部署
  Storage 节点 × N     文件管理、挂载源、刮削入库
  Play Agent 节点 × M  播放出口、直链与分段传输
  可以放在任意多台服务器上，只连 control 的 18085

控制面各服务本身不做多副本

注册中心、账号、媒体、网关都是单实例设计。分布式解决的是「把不同服务放到不同机器」，不是「同一个服务跑多份」——需要横向扩展的永远是工作节点。

怎么选

先回答一个问题：你需要外部工作节点（多台 Storage / Play Agent）吗？

不需要 → 选单机版。一台服务器、三个容器，内置的 Storage 与 Play Agent 随主应用升级，是最省事的入门路径。缺点是不能加节点扩容，要扩容得先做授权升级与拓扑迁移。

需要 → 选分布式，再用一个标准决定同机还是多机：

你的情况	选
控制面只想占一台机器；网盘多、播放并发高，靠加工作节点扩容	分布式·控制面同机
控制面本身要分散到多台（合规、隔离、单机资源不够）	分布式·按角色多机
数据库或缓存要用你现有的实例	两者都支持；同机形态配置更简单

从同机起步，之后再拆

两种分布式方式通用同一份数据与许可证。不确定时就先用控制面同机——一台机器就能跑起来，工作节点照样可以扩到任意多台；将来控制面压力大了，再按从同机扩到多机拆开。

前置条件

项目	要求
操作系统	单机版与分布式·控制面同机：一台 Linux 服务器。按角色多机：多台，且必须在同一私有网络
Docker	Docker Engine + Docker Compose v2，且 `docker info` 可用
命令行工具与权限	`install.sh` 启动即检查 `docker`、`openssl`、`curl`、`python3`，缺任何一个直接退出；要能用 `sudo` 运行脚本（建数据目录、改属主与权限）
地址	服务器 IP 或域名，不带 `http://` 前缀和路径
授权材料与出站网络	一个发布方提供的一次性授权码，且授权 Edition 必须与部署模式匹配；授权公钥由 `install.sh` 自动下载校验，不需要手工放置文件。安装时要能访问 `YIYI_LICENSE_SERVER_URL` 指向的授权中心（HTTPS）
端口	单机版：`18080`（Web 入口）与 `19090`（播放直连）发布到宿主机。分布式见下方端口表
磁盘	留出数据库、上传文件、Storage 数据与日志的空间；数据目录默认在部署目录下的 `data/`

端口

端口	服务	单机版	分布式·同机	分布式·多机
`18080`	`frontend`，Web 入口	对用户开放	对用户开放	只在 `edge` 机器，对用户开放
`19090`	`play-agent`	发布到宿主机，播放客户端直连（可收窄为回环配合反代）	节点机上按需对客户端开放	节点机上按需对客户端开放
`18082`	`user`	容器内部	本机（host 网络）	私网内可达
`18083`	`media`	容器内部（不发布到宿主机）	本机（host 网络）	私网内可达
`18085`	`config`，注册中心	容器内部	对工作节点开放	私网内放行，控制面各服务与所有工作节点都要访问
`18086`	`gateway`	容器内部	本机（host 网络）	只在 `edge` 机器，同机 `frontend` 经 `127.0.0.1` 访问
`18084`	`storage`，节点	容器内部	节点机上按需对客户端开放	节点机上按需对客户端开放
`18088`	`license-agent` / `license-sync`	容器内部	只绑 `127.0.0.1`	只绑 `127.0.0.1`
`18089`	集群许可证同步（relay）	不使用	不使用（同机不需要同步）	`control` 监听 `0.0.0.0:18089`，私网内放行
`5432`	PostgreSQL	Compose 私有网络	绑 `127.0.0.1`（或用外部实例）	绑 `control` 的内网地址，私网内放行
`6379`	Redis	Compose 私有网络	绑 `127.0.0.1`（或用外部实例）	绑 `control` 的内网地址，私网内放行

完整端口矩阵与排查路径见端口与网络。

数据目录

三种方式的数据根目录都是部署目录下的 data/（可用 YIYI_DATA_DIR 改）。单机版的布局最全，因为数据库、缓存与两个内置节点的数据都在本机：

txt

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}/

单机版的同一个 PostgreSQL 实例承载四个数据库：yiyi_config、yiyi_user、yiyi_media、 yiyi_storage。首次初始化由数据库初始化脚本建库；升级旧数据目录时，安装脚本会在 PostgreSQL 健康后做幂等存在性检查，只创建缺失的库，不覆盖现有库。

分布式方式下，data/ 只放本机服务的日志与许可证租约；数据库是独立的 postgres 容器（data/postgres/）或你自己的外部实例，工作节点的数据在各自的节点机器上。

要放到独立磁盘或别的目录，在 .env 里设置数据根目录（相对路径以部署目录为基准）：

dotenv

YIYI_DATA_DIR=/var/lib/yiyi

install.sh 会把它规范化成绝对路径写回 .env。备份清单见升级、备份与回滚。

升级方式概览

方式	升级粒度
单机版	整镜像升级：一次 `pull` + `up -d` 把应用容器内八个服务一起换版本
分布式·控制面同机	整机升级：一次 `pull` + `up -d` 重建本机的 6～8 个控制面容器
分布式·按角色多机	按机器升级：每台机器在自己的部署目录里执行同样命令，建议 `control` → `user` → `media` → `edge` 顺序

bash

cd /opt/YiYi-media-deploy
docker compose pull
docker compose up -d --remove-orphans --wait
docker compose ps

pull 不等于升级

docker compose pull 只下载镜像，不会更新正在运行的容器。必须再执行 docker compose up -d --remove-orphans --wait 才会用新镜像重建容器。

安装脚本不自动生成升级备份

数据备份与保留周期由你自己管理。升级前先按升级、备份与回滚做一次备份。

验证

装完之后在部署目录里按这个顺序确认：

bash

cd /opt/YiYi-media-deploy

# 1. 单机版必须恰好三个服务，且全部 Up / healthy
docker compose ps

# 2. 授权状态与部署形态匹配。未激活时返回 UNACTIVATED，这是正常的
curl -fsS http://127.0.0.1:18085/api/license/status

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

浏览器打开 http://<你的服务器IP或域名>:18080，第一个页面应该是授权激活页，不是创建管理员页 —— 初始化顺序是先激活授权、再创建首个管理员。完整流程见初始化与授权激活。

激活成功后到「节点管理」确认两个内置节点已经自动在线，不需要安装任何东西。

安全红线

不要公开或提交 .env、config/cluster-relay.key 与 backups/；.env 权限设 0600。
单机版默认关闭主机 FUSE 挂载，聚合容器不使用 privileged，不授予 SYS_ADMIN。
生产环境应为网页入口配置 HTTPS，见反向代理与域名。

常见问题

现象	原因与处理
`docker compose ps` 什么也没列出	不在部署目录，或 `COMPOSE_PROFILES` 被手工改坏。`cd` 回部署目录后重跑 `sudo ./install.sh`；该变量由脚本维护
单机版 `docker compose ps` 出现了 `yiyi-app` 以外的业务容器	混用了分布式分支的部署文件。单机版只应运行 `yiyi-app`、`postgres`、`redis` 三个服务
控制面同机少了 `postgres` / `redis`	你把 `YIYI_DB_MODE` / `YIYI_REDIS_MODE` 设成了 `external`，这是预期行为。两个开关独立，逐个确认
按 `YiYi-media-standalone` 找不到容器	那是容器名；`docker compose` 命令要用服务名 `yiyi-app`。用 `docker compose exec yiyi-app ...`，或 `docker exec YiYi-media-standalone ...`
打开 `18080` 是激活页，输入管理员账号没用	还没激活授权。先填一次性授权码，成功后才会出现创建管理员向导
激活被拒绝，提示版本不匹配	部署方式与许可证 Edition 不匹配。单机版只接受 `STANDALONE`；两种分布式方式都只接受 `DISTRIBUTED`，见授权与版本
分布式方式里「节点管理」没有「新增节点」	授权 Edition 或部署形态不匹配，能力被收窄；查 `GET /api/config/deployment/capabilities`

部署模式与版本选择 ​

两种模式，三种方式 ​

两种模式的能力差异 ​

分布式·控制面同机拓扑 ​

单机版标准拓扑 ​

分布式部署拓扑 ​

怎么选 ​

前置条件 ​

端口 ​

数据目录 ​

升级方式概览 ​

验证 ​

安全红线 ​

常见问题 ​

相关文档 ​