为什么我的服务端拒绝加载插件？（CNKD NEXT 插件锁 / Plugin Lock）

如果你在用新版本 CNKD NEXT 服务端，应该会发现根目录下多了一个 plugin-sdk 文件夹，同时往 data/plugins/ 丢插件后重启，插件并没有被正常加载。

这不是插件的问题，而是 CNKD NEXT 引入了一套插件审批机制——也就是“插件锁”。

什么是插件锁？

简单说，就是给插件安装增加了一道审批步骤：

你明确告诉服务端：“这个插件我确认过来源，我同意它运行”
服务端记录下插件的文件名、版本和 SHA-256 哈希值
以后每次启动，服务端都会核对：插件有没有被篡改、有没有被替换

这套机制主要是防止从不明渠道下载的插件带来安全风险——比如删库、窃取信息等。

首次批准插件的操作步骤

第一步：停止服务端

不急的话，在控制台输入 stop 正常关闭
如果服务端卡死退不出去，按几次 Ctrl + C 强制终止，直到控制台窗口关闭

⚠️ 强制关闭可能导致数据异常，能正常 stop 就尽量正常停。

第二步：把插件放对位置

将待批准的 .jar 或 .zip 文件放入 data/plugins/ 目录（不要放子目录）。

data/
- plugins/ —— 插件放这里
  - BindPlayer/ —— 这是插件运行时生成的目录，不要手动往里装
  - HttpApi/ —— 同上，不要手动往里装
  - your-plugin.jar —— 你要安装的插件
Server-All.jar
start.bat

第三步：打开终端

**方式一（推荐）**：在服务端根目录下，右键选择「在终端中打开」(Win11)

**方式二**：先打开终端，再用 `cd` 命令切换到服务端根目录(Win10及特殊)

cd E:\你的服务端路径\CNKDNEXT

第四步：运行审批脚本

在终端中执行以下命令：

powershell -ExecutionPolicy Bypass -File plugin-sdk/approve-plugin-lock.ps1

如果提示找不到 Python，请先安装 Python 3.x（搜索引擎搜索“python-3.14.7-amd64.exe”按提示安装即可）。

脚本会依次询问三个问题：

问题	说明	示例
PluginDirectory	plugins 文件夹路径	`.\data\plugins`
PluginArchives	要批准的插件路径(你可以批量输入，输入后回车打开下一行，直到输入完后点击回车提交一个空内容进行操作人填写)	`.\data\plugins\welcome.jar`（文件名可以从文件夹里复制）
ApprovedBy	操作人标识	`hachidong`（能代表你的名字即可）

全部填完后，会出现确认提示：

确认
是否确实要执行此操作?
正在目标“E:\...\data\plugins\plugin-lock.json”上执行操作“replace complete plugin approval lock with 1 explicit entries”。

Y并按回车确认，插件就被加入白名单了。

返回结果示例

审批成功后，终端会显示类似这样的信息：

Approved 1 plugin archive(s).
Lock: E:\...\data\plugins\plugin-lock.json
  SensitiveWordFilter 1.0.0 api=1 sha256=c231e9ffead6018beef2d65fc445b32c632342ca00975fd2aa22f067748fc514

看到这条输出，说明插件已成功写入插件锁，重新启动服务端即可加载。

⚠️ 特别注意

插件锁记录中包含了插件的 SHA-256 哈希值，文件名。这意味着：

哪怕插件更新时只改了一个空格，哈希值也会变化。如果你更改了插件的名字，与锁中的存储不一致。服务端就会拒绝加载锁中的版本。

因此每次更新插件时，都需要重新执行一遍全部插件的审批流程，生成更新锁记录。

具体请前往下一页阅读。

参考

服务端内置文档：plugin-sdk/PLUGIN-LOCK-OPERATIONS-CN.md