节点管理
节点管理把控制面之外的服务实例登记在一处。单机版与分布式版的界面差异很大：单机版只有两个内置节点，只能新增手动反代地址；分布式版才有节点创建、配额、部署与远程升级。
一个后台管住所有节点
节点只需要知道注册中心地址，服务地址全自动发现。
- 卡片按文件管理节点、播放代理节点、手动反代地址分组展示
- 分布式版新增节点时按服务类型显示「部署配额 已用/上限」，配额用满则按钮禁用
- 分布式版远程升级自带安全网：升级前备份旧版本、30 秒健康检查轮询、失败自动回滚
上图仍是旧版节点页截图，待重拍
这张截图拍的是旧版节点管理页（可新增三类记录的形态），不能代表单机版界面。 单机版页面只有两个内置节点 + 手动反代地址，没有「新增节点」按钮与服务类型选择框。
替换计划见 site/scripts/capture.mjs 的 nodes-standalone 目标：单机版与分布式版各出一张。 在重拍之前，单机版流程一律以本页文字说明为准。
两种模式的界面差异
| 能力 | 单机版（STANDALONE） | 分布式版（DISTRIBUTED） |
|---|---|---|
| 文件管理节点 | 固定内置 1 个（node-local-storage），显示健康、版本与运行状态，卡片标注「随系统部署」 | 外部节点，可新增、可多实例 |
| 播放代理节点 | 固定内置 1 个（node-local-play-agent），卡片标注「随系统部署」 | 外部节点，可新增、可多实例 |
| 「新增节点」按钮与服务类型选择框 | 不显示 | 显示 |
| 节点令牌、安装命令 | 不显示 | 显示，凭据默认遮罩 |
| 卸载、独立升级、删除 | 不显示 | 显示 |
| 外部节点部署配额表单 | 不显示 | 显示「部署配额 已用/上限」 |
| 手动反代地址 | 可以新增，编辑、启停、删除、令牌轮换、nginx/Caddy 片段全部保留 | 同左 |
| 远程升级（一键 / 检测版本） | 不提供，随主版本升级 | 提供 |
| 网络诊断 | 提供 | 提供 |
单机版的服务端限制不是靠隐藏按钮实现的
直接调用接口同样会被拒绝：
POST /api/config/nodes→403 NODE_CREATION_DISABLED- 内置节点删除、卸载、独立升级或改关键元数据 →
403 SYSTEM_NODE_IMMUTABLE - 节点二进制分发与安装命令 →
403 BINARY_DISTRIBUTION_DISABLED
手动反代地址的 CRUD、启停与令牌轮换在两种模式下都保持可用。
能做什么
- 查看节点状态与心跳，做网络诊断（两种模式）。
- 新增与管理手动反代地址，轮换入口令牌（两种模式）。
- 单机版：查看两个内置节点的健康、版本与运行状态。
- 分布式版：登记外部节点记录、生成一键安装命令、检查版本、远程升级与卸载，按授权配额限制节点数。
界面与操作
卡片网格（1 / 2 / 3 列响应式）而非表格，按组展示；页头统计总计、在线、待注册。 卡片含节点名、serviceName、状态徽章、地址、端口、版本徽章与最近心跳；播放代理组带启用 / 停用开关。
三类节点记录
| 类型 | 服务名 | 默认端口与协议 | 说明 |
|---|---|---|---|
| 文件管理节点 | YiYi-control-storage | 18084 / http | 文件浏览、刮削与流代理 |
| 播放代理节点 | YiYi-play-agent | 19090 / http | 播放协议出口，当前实现 Emby |
| 手动反代地址 | manual-play-agent-endpoint | https，端口可选 | 分发给用户的反代入口，不参与部署与升级，只检测 /health |
新增节点字段（仅分布式版）
服务类型、节点 ID（可留空自动生成，手填须以 node- 开头）、节点名称、对外 IP 或域名、协议、端口、监听端口、备注。播放代理节点的端口标为「对外端口（客户端连接）」；监听端口指进程实际绑定端口，留空默认 19090，同机多节点须不同，安装脚本注入 PLAY_AGENT_LISTEN。
手动反代地址改用：地址名称、反代 IP / 域名、反代端口（可选）、备注、启用开关；保存后组合 baseUrl 并检测 /health。
一键安装命令（仅分布式版）
命令由 Config 服务按节点下发，前端不含模板文本，形态统一是一行：
curl -fsSL http://<config-host>:18085/api/config/nodes/install/<token>/<kind> | bash<kind> 取 6 种：binary、binary-jdk、docker、uninstall、upgrade-binary、upgrade-docker；安装类可追加 ?ffmpeg=true。
| 界面命令项 | kind | 限制 | 说明 |
|---|---|---|---|
binaryDeployCommand | binary | — | 以二进制 / Jar 运行 |
binaryDeployCommandWithJdk | binary-jdk | 仅文件管理节点 | 附带装 JDK 21 |
binaryDeployCommandWithFfmpeg | binary + ?ffmpeg=true | 仅播放代理节点 | 宿主机装 ffmpeg / ffprobe |
dockerDeployCommand | docker | — | 以 Docker 运行，二进制仍从配置中心拉取 |
dockerDeployCommandWithFfmpeg | docker + ?ffmpeg=true | — | ffmpeg / ffprobe 内置进镜像 |
uninstallCommand | uninstall | — | 停进程并删工作目录（含日志缓存） |
upgradeBinaryCommand | upgrade-binary | — | 升级二进制部署 |
upgradeDockerCommand | upgrade-docker | — | 升级 Docker 部署 |
凭据默认遮罩为 [凭据已隐藏]，点「显示完整命令」才可见；复制在非 https 环境回退 execCommand。
单机版下这些字段为空或不返回，不泄露无效安装入口。
状态与心跳
后端只有 ONLINE / PENDING，界面按序判定：未启用 → 已停用；ONLINE → 在线；有 lastSeenAt → 离线；其余 → 待注册；手动反代地址有 lastError → 异常，另显示 healthUrl、最近检测与最近成功时间。
「网络检测」返回注册状态、目标 host:port、TCP 可达性、HTTP 状态码与响应体。
版本检查与远程升级（仅分布式版）
version-check 六态：LATEST 已最新、UPDATE_AVAILABLE 有新版本、UNSUPPORTED 无法识别部署方式（可手动选）、UNREACHABLE 不可达、UNKNOWN 未知、BINARY_UNAVAILABLE 无可用二进制。
显示「控制面最新」与「节点当前」的 SHA256 与体积，页头横幅提示「N 个节点有新版本可用」。一键升级自动识别 Docker 或二进制部署，三项安全机制：升级前备份旧版本、30 秒健康检查轮询、失败自动回滚。
单机版的内置节点随主应用整镜像升级，不提供这些入口。
节点配额
分布式版：/api/license/status 返回 maxStorageNodes 与 maxPlayAgentNodes；表单显示「部署配额 已用/上限」，用满时禁用按钮并提示「授权配额已满」，错误码 LICENSE_NODE_QUOTA_EXCEEDED。
单机版：这两个值固定为 1，只代表两个内置节点本身，不代表允许新增节点；管理台不提供配额覆盖表单。
手动反代地址在两种模式下都不占配额。
手动反代地址与入口令牌
入口令牌 accessToken 须由反代注入 X-YiYi-Endpoint-Token，否则请求按直连处理，该地址的用户级授权不生效。「反代配置」抽屉给出 nginx 与 Caddy 片段，另支持令牌轮换、启用 / 停用、编辑与删除。
单机版里这是节点管理页唯一可以新增的项目。上游地址填 127.0.0.1:19090（内置 Play Agent 由容器发布在宿主机上），见反向代理与域名。
关键规则
- 批量能力只有「检查全部更新」与「刷新列表」，没有批量启停或批量删除。
- 删除文件管理节点前先查媒体库来源引用数并提示；删除后同步数据保留旧节点 ID，同一 ID 重新部署可继续。（分布式版）
- 删除在线节点可勾选「同时发送卸载命令」并二次警示本机数据不可恢复；离线节点只删控制面记录。卸载与删除都在危险操作区。（分布式版）
- 单机版的内置节点不可删除、不可卸载、不可独立升级、不可改服务类型。