Anheyu插件使用与管理
安知鱼插件的安装、启用禁用、配置与卸载指南
插件用于扩展站点能力：接入外部搜索引擎、把文章发布/评论创建等事件推送到第三方服务等。插件以独立进程运行，安装、更新、卸载均无需重启主程序。
想自己开发插件请阅读插件开发。
📦 安装插件
方式一：管理后台上传（推荐）
- 打开管理后台「插件管理」页面；
- 点击「安装插件」，上传插件安装包（zip 格式，不超过 100MB）；
- 安装成功后插件自动加载并显示在列表中。
安装包会被解压到 data/plugins/<插件id>/ 目录。重复上传同一插件视为升级：插件文件被替换，已保存的配置与禁用状态保留。
方式二：手动放置
- 目录式插件：把解压后的插件目录（含
plugin.json）放入data/plugins/，系统自动发现并加载； - 裸二进制插件（旧式）：把插件可执行文件直接放入
data/plugins/根目录。
提示
裸二进制插件不支持后台配置下发（只能读主程序环境变量），也没有安装包校验，建议优先使用 zip 安装包。
🎛️ 管理插件
「插件管理」页面对每个插件提供以下操作：
| 操作 | 说明 |
|---|---|
| 重新加载 | 重启插件进程（更新二进制或排查异常后使用） |
| 禁用 | 停止插件进程；状态持久化，应用重启后保持禁用 |
| 启用 | 重新启动已禁用的插件 |
| 配置 | 编辑插件配置（仅声明了配置项的插件显示）；保存后插件自动重载生效 |
| 卸载 | 停止进程并删除插件文件、配置与状态，不可恢复 |
插件状态
| 状态 | 含义 |
|---|---|
| 运行中 | 插件进程正常运行 |
| 已禁用 | 被管理员禁用，进程未运行 |
| 已停止 | 插件文件被移除或进程已退出 |
| 异常 | 加载失败或运行出错，卡片上会显示错误信息 |
主程序每 60 秒对运行中的插件做健康检查，异常插件会自动重启。
插件配置
声明了配置项的插件会显示「配置」按钮，表单按插件声明自动生成（文本、数字、开关、下拉选择），敏感项以密码框显示。保存后运行中的插件自动重载，无需手动操作。
配置数据保存在 data/plugins/plugins-state.json 中，备份站点数据时建议一并备份。
🔌 官方插件
Meilisearch 搜索引擎
将站点全文搜索切换为 Meilisearch，支持中文分词与高亮。插件启用后自动接管搜索（优先级高于内置搜索）。
配置项：
| 配置 | 说明 |
|---|---|
| host | Meilisearch 服务地址（如 http://localhost:7700） |
| api_key | Meilisearch API Key（可选） |
旧部署方式（主程序环境变量 ANHEYU_MEILISEARCH_HOST / ANHEYU_MEILISEARCH_API_KEY）继续有效。
Webhook 通知
把站点事件（文章发布、评论创建等）以 JSON POST 到自定义 Webhook 地址，可用于对接企业微信/钉钉/飞书机器人网关或自建服务。
配置项：
| 配置 | 说明 |
|---|---|
| webhook_url | 接收事件的完整 URL（必填） |
| events | 订阅事件，逗号分隔（如 article.published,comment.created），* 表示全部 |
推送的 JSON 结构见插件开发 - 事件参考。
🔒 安全提示
只安装可信来源的插件
插件以独立进程运行，拥有与主程序相同的服务器执行权限，主程序不提供沙箱隔离。安装来历不明的插件可能导致数据泄露或服务器被入侵。
- 插件管理操作仅限管理员；
- 安装前确认插件来源（官方发布或可审计源码的开源项目）；
- 不需要的插件建议卸载而不是仅禁用。
❓ 常见问题
上传安装包提示「安装包缺少 plugin.json」？
plugin.json 必须位于 zip 根目录。如果打包时把整个项目文件夹压缩进去（zip 内多了一层目录），请调整为直接压缩 plugin.json 和 bin/。
安装提示「插件不支持当前平台」？
安装包内没有服务器平台对应的二进制。请联系插件作者提供对应平台（如 linux-amd64）的版本。
插件状态一直是「异常」？
查看卡片上的错误信息与主程序日志（[Plugin] 前缀）。常见原因：二进制与服务器架构不匹配、插件依赖的外部服务不可达、配置缺失。修复后点「重新加载」。
禁用的插件重启后又运行了？
不会。禁用状态持久化在 data/plugins/plugins-state.json，应用重启后保持禁用。如果出现该现象请检查该文件是否被清理。
Last updated on