管理员手册

本页面向服主、管理组和 LuckPerms 配置人员。玩家操作请看玩家教程。

先记住一件事

影视功能暂时对全服关闭。不要在公告中引导玩家使用“影视”页、vod: 或瓜子链接。

上线检查

/pl 中 NekoVideoPlugin 必须为绿色；红色时检查启动日志。
plugins/NekoVideoPlugin/config.yml 的 api-key 不能为空或无效；授权服务器和数据库也必须可达。
不要使用 PlugManX 热加载。修改 api-key、存储类型或授权相关配置后整服重启。
多模组客户端出现 Too many channels registered 时，在 -jar 前加入 -Dpaper.disableChannelLimit=true 并重启。
玩家进服应完成握手，否则会看到“客户端尚未通过双向构建验证”。

权限模型

总开关与细分节点

节点	默认	作用
`nekovideo.use`	`true`（所有人）	插件命令和客户端功能；缺失后完全不能用
`nekovideo.*`	OP	全部功能的父节点
`nekovideo.admin`	OP	任意屏幕、重载、管控、强制音乐操作、音距最高 512；不限建屏数量
`nekovideo.admin.autoplay`	随管理节点	预留的开服自动播放源权限
`nekovideo.admin.rename`	随管理节点	`/nv screen rename <旧id> <新id>`
`nekovideo.download`	OP	`download` 缓存和 `loop` 循环；会占客户端磁盘与带宽
`nekovideo.music.room.use`	`true`（所有人）	创建/加入/邀请一起听房间
`nekovideo.music.room.admin`	随管理节点	处理异常房间

VIP 屏幕数量

nekovideo.screen.limit.0  # 明确 0 块
nekovideo.screen.limit.1  # 最多 1 块
nekovideo.screen.limit.N  # N 为 0～512

插件取玩家身上所有 limit 节点的最大数字；没给任何节点就是 0。OP/管理员不受数量上限和超限回收影响。

LuckPerms 示例：

/lp group default permission set nekovideo.use true
/lp group default permission set nekovideo.music.room.use true
/lp group vip permission set nekovideo.screen.limit.1 true
/lp group svip permission set nekovideo.screen.limit.3 true
/lp group admin permission set nekovideo.admin true
/lp group admin permission set nekovideo.download true

不要给普通玩家 nekovideo.admin，否则他们能管理全服屏幕和开关禁播。

屏幕到期回收

screen-limit:
  reclaim-mode: disable # off / disable / delete

玩家进服时启用屏幕超过新上限，插件按创建时间最早的 N 块保留：

模式	行为
`off`	不回收，只禁止继续新建
`disable`	多余屏幕停播并禁用，数据保留；续费后 `/nv screen active <ID>` 可恢复（推荐）
`delete`	直接删除多余屏幕，不可恢复

管理命令

/nv reload
/nv admin lockdown on|off
/nv config <视距>
/nv music setvotes <数字>
/nv music skip
/nv music bump <序号> force
/nv music stop

/nv reload：重载 config.yml、数据库 Cookie、音乐文案、直链白名单和播放源黑名单；授权/存储变更仍需重启。
lockdown on：全服播放管控，非管理员不能点播或创建屏幕；状态会保存，重启后仍有效。
/nv config <视距>：设置全局屏幕可见/播放距离，单屏可用 screen setrange 覆盖。
setvotes：修改投票通过所需票数并写入配置。
bump ... force：管理员强制把歌曲插到下一首。
music stop：停止全服音乐并清空队列。

管理员可以使用玩家的全部屏幕命令，且可以操作任意屏幕（包括无主旧屏幕）。普通玩家音距最高 128，管理员/OP 最高 512。

配置文件

关键项目位于 plugins/NekoVideoPlugin/config.yml：

项目	建议/说明
`api-key`	授权密钥；不要发到公告、群聊或工单
`debug`、`debug-plugin-messages`	排错时开启，平时关闭
`music.enabled`	`false` 关闭全部点歌
`music.skip-votes`	默认投票票数
`music.rooms.enabled`	一起听总开关
`music.rooms.invite-expire-ms`	默认 `120000` 毫秒
`direct-url-allowed-schemes`	允许的直链协议；`file://` 永远拒绝
`direct-url-whitelist`	直链域名/IP 白名单；`[]` 表示不限制
`blocked-sources`	只拦截新点播的播放源黑名单
`storage.type`	`sqlite`（默认）或 `mysql`
`screen-limit.reclaim-mode`	`off` / `disable` / `delete`
`screen.back-occlusion-pct`	默认 `0.30`，控制屏幕后方遮挡阈值

黑名单示例：

blocked-sources:
  - https://live.bilibili.com/1883358196
  - bili:1883358196
  - huya:123456
  - BV1xxxxxxxx

改完后执行 /nv reload。玩家只会看到“该播放源不可播放”，不会看到黑名单细节。

文件/来源	作用与流程
玩家扫码登录 B 站	只提升该玩家的高清/大会员解析能力
`bilibili-cookie.json`	粘贴后执行 `/nv reload` 导入全服游客兜底 Cookie；导入后文件清空
`cookie.json`	粘贴后执行 `/nv reload` 导入网易云全服 Cookie
`data.db` → `app_cookies`	实际存储位置，不要长期把明文 Cookie 放在投放文件中

没有全服 Cookie 时会走游客模式，档位可能较低，也更容易失败。

控制对照

操作	允许者
看屏幕	观看模式通过且在范围内；屏主/管理员始终可以
换源、暂停、跳转	屏主、管理员；或屏幕开启 `control` 且玩家在名单中
创建屏幕	有剩余 `screen.limit`；管控开启时仅管理员
删除屏幕	屏主删自己的；无主屏仅管理员
重命名	`nekovideo.admin.rename`
点播	`nekovideo.use`，且未被管控/黑名单拦截
下载/循环	`nekovideo.download`
强制切歌、强插队、改票数	`nekovideo.admin`
重载、视距、管控	`nekovideo.admin`

运维注意

不要公开 api-key 或全服 Cookie。
不要用 PlugManX 热加载 NekoVideo。
公共大厅可由管理员统一建屏，或给默认组 screen.limit.1；广场乱建时开启 lockdown。
nekovideo.download 只给可信玩家，循环缓存会消耗磁盘和带宽。
游戏内可执行 /nv help admin 或 /nv help all 查看完整列表；控制台也可执行 /nv，视为管理端。

上线检查​

权限模型​

总开关与细分节点​

VIP 屏幕数量​

屏幕到期回收​

管理命令​

配置文件​

Cookie 与账号​

控制对照​

运维注意​