163 lines
9.5 KiB
Markdown
163 lines
9.5 KiB
Markdown
# 插件
|
||
|
||
插件是 WeKnora 扩展能力的打包与分发单元:模型厂商、数据源、联网搜索、文档解析、技能、MCP 服务等都可以由插件提供。内置能力本身也以内置插件的形式登记,和第三方插件共用一套目录与开关。
|
||
|
||
两类角色分工如下:
|
||
|
||
| | 系统管理员 | 空间管理员 |
|
||
| --- | --- | --- |
|
||
| 做什么 | 安装、升级、回滚、卸载插件,填写平台配置 | 在本空间启用或停用插件,填写空间配置 |
|
||
| 入口 | 「设置 → 插件管理」 | 「设置 → 插件」 |
|
||
|
||
安装后的插件对所有空间可见,但**默认停用**,由各空间管理员自行启用。停用插件后,它的集成不再出现在类型列表中、不能新建,已有实例照常工作。
|
||
|
||
## 插件的运行方式
|
||
|
||
插件包是一个 `.wkp` 文件(根目录带 `plugin.yaml` 的 zip)。`runtime.type` 决定插件代码在哪里运行:
|
||
|
||
| 运行方式 | 说明 | 适用 |
|
||
| --- | --- | --- |
|
||
| `declarative` | 没有代码,由 WeKnora 解释清单 | 技能、模型厂商定义、远程 MCP |
|
||
| `host` | WeKnora 的插件宿主拉起的子进程,`kind` 为 `binary` 或 `python` | 自托管的代码插件 |
|
||
| `remote` | 插件作者自行部署的 HTTP 服务,安装时登记地址 | SaaS 类插件、独立团队维护的服务 |
|
||
|
||
代码插件与 WeKnora 之间走统一的扩展协议 v1(HTTP + JSON,流式同步用 NDJSON)。
|
||
|
||
## 安装插件
|
||
|
||
1. 以系统管理员身份打开「设置 → 插件管理」,点击「安装插件」。
|
||
2. 上传 `.wkp` 或填写下载地址。WeKnora 先解析插件包,展示它提供的能力、申请的权限(可访问的外部域名、Host API 权限等)和包摘要。
|
||
3. 确认后安装。安装请求带着审阅时的摘要,下载地址在此期间换了内容会被拒绝。
|
||
|
||
同一插件再次安装更高版本即升级,旧版本保留,可在详情中回滚。
|
||
|
||
### 远程插件
|
||
|
||
`runtime.type: remote` 的插件在安装时还需填写服务地址:
|
||
|
||
- 服务在内网时,需把地址加入 `SSRF_WHITELIST`。
|
||
- 安装后 WeKnora 生成一个签名密钥,**只显示这一次**。把它配置为服务的 `WEKNORA_PLUGIN_SECRET` 环境变量,服务据此确认请求来自 WeKnora。
|
||
- 插件详情中可以修改服务地址或轮换密钥。轮换后,服务换上新密钥之前的调用都会失败。
|
||
- 服务版本必须与安装的插件包一致,否则插件显示为异常、调用被拒绝。升级时同时升级服务与插件包。
|
||
|
||
## 运行代码插件
|
||
|
||
### 内嵌宿主(默认)
|
||
|
||
默认情况下,每个 app 进程自带插件宿主,在本机运行已安装的 `host` 插件:
|
||
|
||
- 插件进程只拿到 `WEKNORA_PLUGIN_*` 环境变量,看不到数据库密码等 WeKnora 密钥。
|
||
- 出网流量经宿主的出口代理,只放行插件在 `permissions.egress` 中声明的域名,内网地址一律拒绝。
|
||
- 宿主检查运行的进程与安装的包一致,健康检查失败时按退避重启,并在插件详情中显示为「异常」。
|
||
- Python 插件使用本机的 `python3`(可用 `WEKNORA_PLUGIN_PYTHON` 指定解释器)。Docker app 镜像已带 Python。
|
||
- 在 Linux 上,插件进程按 `runtime.resources` 限制资源:
|
||
- 内存总是受限。插件没有声明时,按 `WEKNORA_PLUGIN_MEMORY_DEFAULT`(如 `1Gi`)限制,未设置则不限。
|
||
- CPU 需要把一个可写的 cgroup v2 目录委托给 WeKnora,并通过 `WEKNORA_PLUGIN_CGROUP` 指定。设置后,每个插件进程进入各自的子 cgroup。
|
||
|
||
### 独立插件宿主
|
||
|
||
插件较多、希望把插件与 app 隔开,或 app 节点不便运行 Python 时,可以单独运行 `WeKnora plugin-host`:
|
||
|
||
- 它与 app 使用同一镜像,共用数据库、Redis、对象存储和 `SYSTEM_AES_KEY`(或 `JWT_SECRET`)。
|
||
- 启动后每 5 秒在 Redis 中通告自己运行的插件。app 按版本挑选最空闲的宿主,用由 `SYSTEM_AES_KEY` 派生的密钥签名调用它。
|
||
- 宿主停止时先撤回通告,再等进行中的调用结束。
|
||
- 插件详情的「节点状态」中,`plugin-host:` 开头的就是独立宿主。
|
||
|
||
docker compose 启用方式:在 `.env` 中设置
|
||
|
||
```bash
|
||
WEKNORA_PLUGIN_EMBEDDED_KINDS=none
|
||
WEKNORA_PLUGIN_HOST_API_URL=http://app:8080
|
||
```
|
||
|
||
然后执行:
|
||
|
||
```bash
|
||
docker compose --profile plugin-host up -d
|
||
```
|
||
|
||
Helm 设置 `pluginHost.enabled=true` 即可。使用本地存储(`STORAGE_TYPE=local`)时,插件包存放在 data-files 卷中,该卷需支持多 Pod 读写(ReadWriteMany)。
|
||
|
||
相关环境变量:
|
||
|
||
| 变量 | 作用于 | 说明 |
|
||
| --- | --- | --- |
|
||
| `WEKNORA_PLUGIN_EMBEDDED_KINDS` | app | app 自己运行的 kind(`binary`、`python`,逗号分隔);`none` 表示全部交给独立宿主。默认本机能跑的都跑 |
|
||
| `WEKNORA_PLUGIN_HOST_API_URL` | app、plugin-host | 不在 app 本机运行的插件(远程插件、独立宿主上的插件)回调 Host API 的地址 |
|
||
| `WEKNORA_PLUGIN_HOST_KINDS` | plugin-host | 宿主运行的 kind,默认本机能跑的都跑 |
|
||
| `WEKNORA_PLUGIN_HOST_ADDR` | plugin-host | 监听地址,默认 `:8081` |
|
||
| `WEKNORA_PLUGIN_HOST_URL` | plugin-host | app 访问该宿主的地址,默认 `http://<主机名>:<端口>`;Helm 中为 Pod IP |
|
||
| `WEKNORA_PLUGIN_PYTHON` | 两者 | Python 插件的解释器,默认 `python3` |
|
||
|
||
独立宿主需要 Redis,且所有节点的 `SYSTEM_AES_KEY`(或 `JWT_SECRET`)必须一致。app 不运行某个 kind、又没有配置独立宿主时,该 kind 的插件在插件详情中显示为加载失败,并说明原因。
|
||
|
||
## 插件页面
|
||
|
||
插件可以在界面上加三种页面:
|
||
|
||
| 贡献点 | 出现在 | 默认最低角色 |
|
||
| --- | --- | --- |
|
||
| `pages` | 工具箱的一个标签页 | viewer |
|
||
| `settingsSections` | 设置窗口「插件」分组下的一节 | admin |
|
||
| `kbTabs` | 每个知识库的一个页签 | viewer |
|
||
|
||
页面是插件包 `ui/` 目录下的 HTML,WeKnora 通过 `/api/v1/plugin-ui/assets/...` 提供。
|
||
|
||
- **隔离**:页面在沙箱 iframe 中运行,没有同源权限,读不到 WeKnora 的登录状态和本地存储。严格的 CSP 禁止它访问网络。
|
||
- **通信**:页面只能经 [`@weknora/plugin-ui`](https://github.com/Tencent/WeKnora/tree/main/packages/plugin-ui) 桥与 WeKnora 通信,由 WeKnora 代发请求给插件后端,或者弹提示、确认框、跳转页面。
|
||
- **鉴权**:每次请求,WeKnora 都校验空间已启用该插件、用户满足页面的最低角色,并把用户角色一并交给插件后端。
|
||
|
||
## 事件与 Webhook
|
||
|
||
**事件**:插件在 `permissions.events` 中声明要订阅的事件,安装时由系统管理员审阅。
|
||
|
||
| 事件 | 时机 |
|
||
| --- | --- |
|
||
| `knowledge.ingested` | 文档处理完成、可被检索 |
|
||
| `knowledge.failed` | 文档处理最终失败 |
|
||
| `knowledge.deleted` | 文档被删除 |
|
||
| `chat.answered` | 一次回答完成,含问题与回答内容 |
|
||
|
||
- 只有启用了该插件的空间才会向它投递事件。
|
||
- 事件经后台任务队列(有 Redis 时为 asynq)异步投递,至少一次。
|
||
- 插件返回可重试错误时,同一事件会以相同 ID 重新投递,最多 10 次。
|
||
|
||
**Webhook**:插件在 `contributes.webhooks` 中声明入站地址。
|
||
|
||
- 每个空间得到各自的秘密地址 `/api/v1/plugin-callbacks/...`,空间管理员可在「设置 → 插件」的「配置」中复制。
|
||
- 第三方系统调用该地址时,WeKnora 先校验地址、确认空间已启用插件,再把请求转给插件。
|
||
- 插件自行用空间配置里的密钥校验调用方。
|
||
- 设置 `APP_EXTERNAL_URL` 后,插件还能拿到完整地址,自动向第三方注册。
|
||
|
||
## 动态选项与账号连接
|
||
|
||
插件的配置表单可以在填写时向插件取数据:
|
||
|
||
- **动态选项**:下拉框的选项由插件实时给出,例如用填好的令牌列出项目。
|
||
- 修改选项所依赖的字段后,列表会重新加载。
|
||
- 编辑已保存的配置时,表单上没改动的密钥由服务端补齐,不会发回浏览器。
|
||
- **账号连接**:字段显示为「连接账号」按钮,点击后在弹窗中完成第三方的 OAuth 授权。
|
||
- 令牌只保存在 WeKnora 服务端(加密)。每次调用插件时,WeKnora 换上有效的访问令牌,并在过期前自动刷新。
|
||
- 连接只属于发起它的空间。
|
||
|
||
使用账号连接前,系统管理员需要:
|
||
|
||
1. 在第三方平台注册 OAuth 应用,回调地址填 `<WeKnora 地址>/api/v1/plugin-oauth/callback`。
|
||
2. 在「设置 → 插件管理」的插件详情中,把应用的 Client ID 和 Secret 填进平台配置。
|
||
|
||
回调地址取自 `APP_EXTERNAL_URL`;未设置时,使用浏览器访问 WeKnora 所用的地址。
|
||
|
||
## 开发插件
|
||
|
||
- **Go**:[pluginsdk](https://github.com/Tencent/WeKnora/tree/main/pluginsdk),含协议定义、SDK、客户端和一致性测试工具 `weknora-plugin-conformance`。
|
||
- **Python**:[pluginsdk/python](https://github.com/Tencent/WeKnora/tree/main/pluginsdk/python),Python 3.9+,只依赖标准库。
|
||
- **示例**:[examples/plugins](https://github.com/Tencent/WeKnora/tree/main/examples/plugins):
|
||
- `rss`:数据源连接器,Go;
|
||
- `subtitles`:文档解析器,Go,使用 Host API;
|
||
- `notebooks`:Jupyter 笔记本解析器,Python;
|
||
- `links`:带三种页面的团队链接插件,Python;
|
||
- `activity`:订阅事件、接收 Webhook 的空间动态插件,Python;
|
||
- `jira`:Jira Cloud 问题同步,支持 OAuth 授权或 API 令牌,带动态选项、增量同步与问题分诊技能,Go。
|
||
|
||
同一个插件既可以打包成 `host` 插件由 WeKnora 运行,也可以作为 `remote` 服务独立部署,代码不用改。
|