工作节点部署（仅分布式版）
本页仅适用于分布式部署（
DISTRIBUTED）。 节点层有两类工作节点：文件管理节点storage与播放代理节点play-agent。流程都一样——先在控制面登记节点记录，再把一行安装命令复制到目标机执行。
单机版部署没有这一步
单机版部署固定内置一个 Storage（node-local-storage）与一个 Play Agent（node-local-play-agent）， 随主应用安装、启动、升级，不需要也不允许你部署外部节点。单机版的「节点管理」只能新增手动反代地址。
如果你用的是单机版，请跳过本页，直接看单机版部署（三容器）与 授权与版本。需要外部工作节点能力时，必须先完成 单机版迁移到分布式版的版本升级与拓扑迁移。
节点不需要知道 user、media、gateway 在哪。它只连注册中心 config，其余地址自动发现。节点也可以有多个实例、分布在不同机器上，客户端直连节点而不经过控制面。
节点不由部署包安装
YiYi-media-deploy 的 compose.yaml 里没有 storage 与 play-agent 服务，install.sh 也不会安装它们。 节点是独立于 control / user / media / edge 这套角色划分之外的横向扩展单元： 先在网页「节点管理」里创建节点记录，再把页面给出的一行安装命令复制到目标机执行。
前置条件
| 项目 | 要求 |
|---|---|
| 控制面 | 已按分布式部署（控制面同机或按角色多机）部署完成，授权状态为 ACTIVE 或 GRACE，且许可证 edition=DISTRIBUTED |
| 网络 | 节点机能访问 config 的 18085；客户端能访问节点的 18084 / 19090 |
| 配额 | 授权里还有剩余的节点名额，见授权与版本 |
| 二进制 | 用官方 config 镜像时已内置；自建镜像时需要自己准备，见下文 |
| 目标机 | Linux，curl 与 bash；Docker 形态另需 Docker Engine |
未激活授权时无法新增节点
新增节点前控制面会先刷新授权状态、再向授权中心申请占用一个名额。授权不是 ACTIVE / GRACE 时直接拒绝，配额用满时返回「授权配额已满」。
第 1 步：在控制面登记节点记录
打开后台 → 节点管理 → 新增节点：
| 字段 | 说明 |
|---|---|
| 服务类型 | YiYi-control-storage（文件管理节点，默认 18084 / http）、YiYi-play-agent（播放代理节点，默认 19090 / http）、manual-play-agent-endpoint（手动反代地址，不是部署对象） |
| 节点名称 | 展示用，随便起 |
| 节点 ID | 留空自动生成（形如 node- + 12 位随机串）；手填必须匹配 node-[A-Za-z0-9_-]{3,60} |
| 对外 IP / 域名 | expectedHost，客户端与其他服务访问这个节点用的地址，必须是可达地址 |
| 端口 | expectedPort，按服务类型给默认值 |
| 监听端口 | 仅 play-agent。同机跑多个播放节点时用 19090 / 19091 区分，留空用默认 19090 |
| 备注 | 可选 |
保存后节点卡片会给出 nodeId、节点令牌与部署命令。状态先是 PENDING（待注册），节点启动并报到后变 ONLINE。
手动反代地址不是节点
manual-play-agent-endpoint 只是登记一个你自己搭的反代入口，系统只对它的 /health 做心跳检测，不参与部署、不参与远程升级、不占授权配额。配置方式见 反向代理与域名。
第 2 步：复制一键安装命令到目标机
节点详情里的「部署命令」有两种形态可切换，命令本身就是一行：
curl -fsSL http://<config 地址>:18085/api/config/nodes/install/<node-token>/binary | bash命令里的令牌默认是掩码显示的，点「显示完整命令」才展开。复制出来的是含令牌的完整命令，等同于节点凭据，不要贴到公开渠道。
| 形态 | 目标机上做什么 | 适合 |
|---|---|---|
| 二进制 | 下载 jar / 二进制到工作目录，注册成 systemd 服务（unit 名就是节点 ID）并启动；检测不到 systemd 时回退 nohup 后台运行，此时没有开机自启 | 裸机、NAS、不想引入 Docker 的机器 |
| Docker | 同样从配置中心下载二进制，在目标机就地构建一个运行镜像并以 --network host 启动容器，容器名就是节点 ID，宿主机工作目录挂到容器内 /opt/yiyi | 已有 Docker 环境，希望节点与宿主机隔离 |
两种形态的二进制都来自配置中心，不是从 ghcr.io 拉节点镜像。
命令族全集
安装脚本接口是 GET /api/config/nodes/install/{token}/{kind}，kind 有六种，另有可选 query ?ffmpeg=true：
kind | 用途 | 谁提供 |
|---|---|---|
binary | 二进制形态首次安装 | storage、play-agent |
binary-jdk | 二进制安装并附带 JDK 21 | 仅 storage（目标机没有 Java 时勾选） |
docker | Docker 形态首次安装 | storage、play-agent |
uninstall | 停止节点并清理工作目录 | storage、play-agent |
upgrade-binary | 二进制形态升级（带回滚） | storage、play-agent |
upgrade-docker | Docker 形态升级（带回滚） | storage、play-agent |
?ffmpeg=true 只对 play-agent 提供：二进制形态会把 ffmpeg / ffprobe 装到宿主机，Docker 形态则装进节点运行镜像、不动宿主机的软件包。play-agent 需要执行播放触发的元数据探测时才需要它。
# play-agent 二进制安装并一并装好 ffmpeg / ffprobe
curl -fsSL 'http://<config 地址>:18085/api/config/nodes/install/<node-token>/binary?ffmpeg=true' | bash脚本失败会告诉你哪一行
下发的脚本统一带 set -Eeuo pipefail 与 ERR trap，任何一步失败都会打印 「哪一步、哪一行、退出码」并提示把输出截图给管理员。非交互式终端下自动关闭彩色输出， 所以 | bash 与重定向到日志文件都能正常读。
脚本内容由 Config 服务下发
脚本正文是 Config 服务按节点记录动态生成的，前端只显示那一行 curl … | bash。 排查时请以目标机上实际拿到的脚本为准：
curl -fsSL 'http://<config 地址>:18085/api/config/nodes/install/<node-token>/binary' -o install.sh
less install.sh令牌不对时接口返回 403 与一行 # invalid token。
节点二进制文件的准备流程
使用官方镜像时整节可以跳过
从 ghcr.io/yiyi-product/yiyi-media-config:latest 起的 config 容器已经内置这两个节点二进制，一键安装命令直接就能下载到。本节只面向自建 Config 镜像或要分发自己节点版本的场景。
一键安装命令从 GET /api/config/binaries/{service}?token=<node-token> 下载文件，service 取 YiYi-control-storage 或 YiYi-play-agent。缺令牌返回 401，令牌与节点记录的服务类型不匹配返回 403，文件不存在返回 404。
官方 config 镜像由发布方构建并推送，已经内置 Storage 与 Play Agent 两个节点二进制 （构建时按目标架构交叉编译），你不需要准备任何东西——一键安装命令会直接从配置中心下载。
只有当你要自建 Config 镜像或分发自己编译的节点版本时，才需要自行构建这两个产物 （Storage 用 Maven 打 fat-jar，Play Agent 用 Go 交叉编译到 linux/amd64）， 并把它们放进 Config 镜像的 binaries 目录。绝大多数部署用不到这一步。
play-agent 的三种配置方式
方式一：一键安装（推荐）。 上面那条 curl … | bash 会把二进制、节点 ID、节点令牌、监听端口与注册中心地址全部注入，不用手写配置。
方式二：config.json。 手工部署时复制模板，只改两个字段：
cp config.example.json config.json
vi config.json{
"listen_address": ":19090",
"public_base_url": "http://203.0.113.20:19090",
"service_name": "YiYi-play-agent",
"config_base_url": "http://198.51.100.10:18085",
"node_id": "<节点管理里的节点 ID>",
"service_token": "<你的服务令牌>",
"registry_token": "<该节点的注册 Token>"
}./yiyi-play-agent配了 node_id 时，public_base_url 里的地址可以省略——节点会向 config 查自己在节点管理里登记的对外地址。指定配置文件路径用 PLAY_AGENT_CONFIG=/path/to/config.json。
play-agent 的两个令牌不是同一个变量
service_token（环境变量 YIYI_SERVICE_TOKEN）用于服务间调用与向 config 查自己的对外地址； 注册心跳读的是 registry_token（环境变量 PLAY_AGENT_REGISTRY_TOKEN 或 YIYI_REGISTRY_TOKEN）， 两者不通用。一键安装会自动注入 registry_token；手工部署时也要填上——填该节点的注册 Token， 或填全局服务令牌（控制面对全局令牌直接放行）。仓库 README.md 的手工部署示例只给了 YIYI_SERVICE_TOKEN，注册请求因此不带令牌头。
方式三：环境变量。 环境变量优先级高于 config.json：
export PLAY_AGENT_PUBLIC_BASE_URL=http://203.0.113.20:19090
export PLAY_AGENT_CONFIG_BASE_URL=http://198.51.100.10:18085
export YIYI_SERVICE_TOKEN=<你的服务令牌>
export PLAY_AGENT_REGISTRY_TOKEN=<该节点的注册 Token>
export YIYI_NODE_ID=<节点 ID>
export PLAY_AGENT_LISTEN=:19091 # 同机第二个实例才需要
./yiyi-play-agentmedia 与 user 的地址由注册中心自动发现，不需要配。确实要写死时用 PLAY_AGENT_MEDIA_BASE_URL 与 PLAY_AGENT_USER_BASE_URL 覆盖。
验证
# storage 节点
curl -fsS http://127.0.0.1:18084/api/storage/ping
# play-agent 节点
curl -fsS http://127.0.0.1:19090/health
# 从控制面机器确认节点可达
curl -fsS http://<节点地址>:18084/api/storage/ping
curl -fsS http://<节点地址>:19090/health
# 二进制形态：systemd 服务与日志
systemctl status <节点 ID>.service
journalctl -u <节点 ID>.service -n 50回到后台「节点管理」，卡片状态应从 PENDING 变成 ONLINE 并显示最近心跳。之后才能进「文件管理」配挂载源、进「媒体管理」建库。
节点升级与卸载
- 远程升级：节点详情里点「检测版本」或「一键远程升级」。控制面先探测节点是二进制还是 Docker 部署，再下发匹配的
upgrade-binary/upgrade-docker命令。升级自带安全网：升级前备份旧版本 → 重启 → 最多 30 秒健康检查轮询 → 通过则删备份，失败则自动回滚旧版本。细节见升级、备份与回滚。 - 卸载：
uninstall命令会停止服务并删除工作目录（含日志与缓存）。删除节点记录时也可以勾选「同时向节点发送卸载命令」。
卸载会删掉节点本机数据
storage 节点的工作目录里有挂载数据、spool 与读缓存。勾选远程卸载后这些数据 无法通过「恢复节点」找回。控制面记录与媒体库绑定不受影响，但节点本机数据没了就是没了。
常见问题排查
| 现象 | 原因 | 处理 |
|---|---|---|
| 安装脚本卡在下载二进制 | config 镜像里没有对应二进制，或 YIYI_BINARIES_DIR 目录为空 | 后台版本状态会显示「Config 未提供二进制」；按上文准备二进制并升级 config 容器 |
| 下载返回 403 | 令牌与节点记录的服务类型不匹配（用 storage 的令牌下 play-agent） | 用对应节点详情里的命令 |
节点起来但后台一直是 PENDING | 节点连不上 config:18085，或令牌不一致 | curl http://<config 地址>:18085/actuator/health 验证连通性；storage 看 YIYI_SERVICE_TOKEN，play-agent 还要看 PLAY_AGENT_REGISTRY_TOKEN |
注册返回 403 registry token does not match service instance | 注册心跳带的令牌与控制面记录不匹配 | 用该节点的注册 Token，或用全局服务令牌 |
| 节点在线但客户端播不了 | 节点管理里登记的对外地址不可达，或 19090 / 18084 没放行 | 从客户端所在网络 curl 一次节点地址 |
| 同机第二个 play-agent 起不来 | 端口冲突 | 登记时填监听端口 19091，脚本会注入 PLAY_AGENT_LISTEN |
| Docker 形态挂载功能不可用 | 宿主机没有 /dev/fuse | 脚本会打印提示；需要 FUSE 挂载时给宿主机装 fuse3 |
| storage 报数据库连接失败 | yiyi_storage 库不存在，或节点连错了数据库实例 | YIYI_DB_MODE=bundled 时内置 PostgreSQL 首次初始化已由 postgres-init.sql 建好 yiyi_storage；external 模式下这个库由 Storage 节点自己的部署配置管理，要在它实际使用的实例上创建 |
| 新增节点报「授权配额已满」 | 授权里 maxStorageNodes / maxPlayAgentNodes 用尽 | 见授权与版本 |