mirror of
https://github.com/RaisFast/raisfast.git
synced 2026-09-24 08:02:36 +00:00
610 lines
20 KiB
Markdown
610 lines
20 KiB
Markdown
# Plugin 开发指南
|
||
|
||
## 概述
|
||
|
||
Plugin 系统是 rust-blog 的运行时扩展机制，支持三种语言运行时，可独立于 Content Type 运行。Plugin 可以注册钩子、定时任务、自定义路由，并通过 Host API 访问数据库、HTTP、配置等受控资源。
|
||
|
||
## 架构
|
||
|
||
```
|
||
plugins/
|
||
└── {plugin-id}/
|
||
├── manifest.toml # 插件清单
|
||
└── main.js # 入口文件（JS/Lua/WASM）
|
||
↓ 启动加载
|
||
PluginManager（Arc 共享）
|
||
├─ 拓扑排序（依赖顺序）
|
||
├─ 实例池（round-robin 并发）
|
||
└─ 热重载（文件系统监听）
|
||
↓ Hook 派发
|
||
Host API（沙箱权限控制）
|
||
├─ Host.dbQuery / dbExecute
|
||
├─ Host.dbBegin / dbCommit / dbRollback
|
||
├─ Host.httpGet / httpPost
|
||
├─ Host.getConfig
|
||
├─ Host.getData / setData（KV 存储）
|
||
├─ Host.fsRead / fsWrite / fsDelete / fsExists / fsList（VFS）
|
||
├─ Host.log / emitEvent
|
||
└─ Host.newId
|
||
```
|
||
|
||
### 核心模块
|
||
|
||
| 模块 | 文件 | 职责 |
|
||
|------|------|------|
|
||
| PluginManager | `src/plugins.rs` | 加载/卸载/hook 派发/热重载/事件总线 |
|
||
| Manifest | `src/plugins/manifest.rs` | TOML 清单解析 |
|
||
| Permissions | `src/plugins/permissions.rs` | 权限校验 + SQL 注入防护 + SSRF 防护 |
|
||
| JS Engine | `src/plugins/engine_js.rs` | QuickJS 运行时 + 实例池 |
|
||
| JS Host | `src/plugins/js_host.rs` | JS → Rust Host API 桥接 |
|
||
| Lua Engine | `src/plugins/engine_lua.rs` | Lua 5.4 运行时 + 实例池 |
|
||
| Lua Host | `src/plugins/lua_host.rs` | Lua → Rust Host API 桥接 |
|
||
| WASM Engine | `src/plugins/engine.rs` | wasmtime 运行时 |
|
||
| WASM Host | `src/plugins/host.rs` | WASM → Rust Host API 桥接 |
|
||
| Host Common | `src/plugins/host_common.rs` | 共享 Host 逻辑 |
|
||
| VFS | `src/plugins/vfs.rs` | 插件隔离虚拟文件系统 |
|
||
| HTTP Client | `src/plugins/http_client.rs` | 插件 HTTP 请求 |
|
||
| CLI | `src/cli/plugin_cmd.rs` | `plugin new` / `plugin check` |
|
||
|
||
## 三种运行时
|
||
|
||
| 运行时 | Cargo Feature | 入口文件 | 引擎 |
|
||
|--------|--------------|----------|------|
|
||
| JavaScript | `plugin-js` | `main.js` | rquickjs (QuickJS) |
|
||
| Lua | `plugin-lua` | `init.lua` | mlua (Lua 5.4) |
|
||
| WASM | `plugin-wasm` | `plugin.wasm` | wasmtime |
|
||
|
||
三种运行时可同时编译、同时加载。
|
||
|
||
### 实例池
|
||
|
||
每个插件创建多个运行时实例（由 `PLUGIN_JS_POOL_SIZE` / `PLUGIN_LUA_POOL_SIZE` / `PLUGIN_WASM_POOL_SIZE` 控制），以 round-robin 方式分发请求，避免并发瓶颈。
|
||
|
||
## Manifest 文件 (`manifest.toml`)
|
||
|
||
### 最小示例
|
||
|
||
```toml
|
||
[plugin]
|
||
id = "com.example.my-plugin"
|
||
name = "My Plugin"
|
||
version = "0.1.0"
|
||
runtime = "js"
|
||
entry = "main.js"
|
||
|
||
[permissions]
|
||
max_memory_mb = 16
|
||
timeout_ms = 5000
|
||
```
|
||
|
||
### `[plugin]` 字段
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| `id` | string | 是 | — | 插件唯一 ID（建议反向域名格式） |
|
||
| `name` | string | 是 | — | 显示名称 |
|
||
| `version` | string | 是 | — | 语义版本号 |
|
||
| `description` | string | 否 | `""` | 描述 |
|
||
| `author` | string | 否 | — | 作者 |
|
||
| `license` | string | 否 | — | 许可证 |
|
||
| `runtime` | string | 否 | `"wasm"` | 运行时：`js` / `lua` / `wasm` |
|
||
| `language` | string | 否 | `"rust"` | 语言标识 |
|
||
| `entry` | string | 否 | `"index.js"` | 入口文件名 |
|
||
| `wasm` | string | 否 | `"plugin.wasm"` | WASM 文件路径 |
|
||
|
||
### `[permissions]` 权限声明
|
||
|
||
```toml
|
||
[permissions]
|
||
max_memory_mb = 16
|
||
timeout_ms = 5000
|
||
http = ["api.example.com", "*.github.com"]
|
||
config = ["app.*", "jwt.*"]
|
||
database = ["read:products", "write:orders", "categories"]
|
||
filesystem = ["read-write"]
|
||
```
|
||
|
||
| 字段 | 类型 | 默认 | 说明 |
|
||
|------|------|------|------|
|
||
| `max_memory_mb` | int | 配置默认值 | 单实例内存上限 |
|
||
| `timeout_ms` | int | 配置默认值 | Hook 执行超时 |
|
||
| `http` | string[] | `[]`（禁止） | HTTP 白名单 |
|
||
| `config` | string[] | `[]`（禁止） | 配置读取白名单 |
|
||
| `database` | string[] | `[]`（禁止） | 数据库权限 |
|
||
| `filesystem` | string[] | `[]`（禁止） | 文件系统权限 |
|
||
|
||
#### 数据库权限格式
|
||
|
||
| 格式 | 权限 |
|
||
|------|------|
|
||
| `"read:TABLE"` | 只读 |
|
||
| `"write:TABLE"` | 只写 |
|
||
| `"TABLE"` | 读写 |
|
||
| `"*"` | 所有表（受保护表除外） |
|
||
|
||
#### HTTP 白名单
|
||
|
||
- 精确域名：`api.example.com`
|
||
- 通配符子域：`*.github.com`
|
||
- 路径通配：`api.example.com/v1/*`
|
||
|
||
内置 SSRF 防护：自动阻止 localhost、127.x、10.x、172.16-31.x、192.168.x、169.254.x、::1。
|
||
|
||
#### 受保护表
|
||
|
||
以下系统表即使声明 `"*"` 也不可访问：
|
||
|
||
```
|
||
users, roles, permissions, audit_log, plugin_storage, options,
|
||
rbac_roles, rbac_permissions, rbac_role_permissions, tenants
|
||
```
|
||
|
||
### `[hooks.XXX]` 钩子注册
|
||
|
||
```toml
|
||
[hooks.on-content-created]
|
||
priority = 50
|
||
|
||
[hooks.on-content-updating]
|
||
priority = 100
|
||
|
||
[hooks.render-markdown]
|
||
priority = 10
|
||
```
|
||
|
||
| 字段 | 类型 | 默认 | 说明 |
|
||
|------|------|------|------|
|
||
| `priority` | int | 100 | 优先级，数字越小越先执行 |
|
||
|
||
钩子名使用连字符（`on-content-created`），系统自动转换为下划线（`on_content_created`）。
|
||
|
||
### 17 种钩子
|
||
|
||
| 钩子名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| `on-content-creating` | filter | 内容创建前，可修改数据 |
|
||
| `on-content-created` | action | 内容创建后 |
|
||
| `on-content-updating` | filter | 内容更新前，可修改数据 |
|
||
| `on-content-updated` | action | 内容更新后 |
|
||
| `on-content-deleted` | action | 内容删除后 |
|
||
| `on-content-viewed` | action | 内容被浏览 |
|
||
| `on-post-creating` | filter | 文章创建前（兼容） |
|
||
| `on-post-created` | action | 文章创建后（兼容） |
|
||
| `on-post-updating` | filter | 文章更新前（兼容） |
|
||
| `on-post-updated` | action | 文章更新后（兼容） |
|
||
| `on-post-deleted` | action | 文章删除后（兼容） |
|
||
| `on-comment-creating` | filter | 评论创建前（兼容） |
|
||
| `on-comment-created` | action | 评论创建后（兼容） |
|
||
| `render-markdown` | filter | Markdown 渲染覆盖（第一个返回 wins） |
|
||
| `filter-html` | filter | HTML 过滤 |
|
||
| `on-login` | action | 用户登录后 |
|
||
| `on-cron-tick` | action | 定时任务触发 |
|
||
|
||
**filter 类型**：可修改数据，返回值传递给下一个插件。
|
||
**action 类型**：仅副作用，返回值忽略。
|
||
|
||
### `[[cron]]` 定时任务
|
||
|
||
```toml
|
||
[[cron]]
|
||
label = "每日统计"
|
||
job_type = "daily_stats"
|
||
cron_expr = "0 0 * * *"
|
||
payload = """{"type": "full"}"""
|
||
enabled = true
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `label` | string | 是 | 任务名称 |
|
||
| `job_type` | string | 是 | 任务类型（传给 `on_cron_tick`） |
|
||
| `cron_expr` | string | 是 | Cron 表达式 |
|
||
| `payload` | string | 否 | 附带数据 |
|
||
| `enabled` | bool | 否 | 默认 true |
|
||
|
||
### `[[routes]]` 自定义路由
|
||
|
||
```toml
|
||
[[routes]]
|
||
method = "GET"
|
||
path = "/api/v1/plugins/crm/pipeline"
|
||
handler = "getPipeline"
|
||
auth = "admin"
|
||
|
||
[[routes]]
|
||
method = "GET"
|
||
path = "/api/v1/plugins/crm/contacts/:contactId"
|
||
handler = "getContact"
|
||
auth = "public"
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 默认 | 说明 |
|
||
|------|------|------|------|------|
|
||
| `method` | string | 是 | — | HTTP 方法 |
|
||
| `path` | string | 是 | — | 路由路径，支持 `:param` 占位符 |
|
||
| `handler` | string | 是 | — | 对应 Plugin 对象的函数名 |
|
||
| `auth` | string | 否 | `default` | `none` / `public` / `member` / `admin` |
|
||
| `description` | string | 否 | — | 描述 |
|
||
| `permission` | string | 否 | — | 额外权限要求 |
|
||
|
||
自定义路由的响应由框架统一包装为 `{ code: 0, message: "success", data: ... }` 格式。
|
||
|
||
## Host API
|
||
|
||
所有运行时通过统一的 `Host.*` 接口访问宿主功能：
|
||
|
||
### 数据库
|
||
|
||
```javascript
|
||
// 参数化查询（防注入）
|
||
const rows = JSON.parse(Host.dbQuery("SELECT * FROM products WHERE price > ?", JSON.stringify([100])));
|
||
const affected = Host.dbExecute("UPDATE products SET stock = stock - 1 WHERE id = ?", JSON.stringify([id]));
|
||
|
||
// 事务
|
||
Host.dbBegin();
|
||
Host.dbExecute("INSERT INTO orders ...", null);
|
||
Host.dbExecute("UPDATE products ...", null);
|
||
Host.dbCommit(); // 或 Host.dbRollback()
|
||
```
|
||
|
||
| 函数 | 说明 | 权限 |
|
||
|------|------|------|
|
||
| `Host.dbQuery(sql, params?)` | SELECT 查询 | `database` read |
|
||
| `Host.dbExecute(sql, params?)` | INSERT/UPDATE/DELETE | `database` write |
|
||
| `Host.dbBegin()` | 开启事务 | 需要 pool |
|
||
| `Host.dbCommit()` | 提交事务 | 活跃事务 |
|
||
| `Host.dbRollback()` | 回滚事务 | 活跃事务 |
|
||
|
||
> **注意**：`dbQuery` 返回的整数列是 `null`，需用 `CAST(col AS TEXT)` 转为字符串后再 `parseInt`。
|
||
|
||
### HTTP
|
||
|
||
```javascript
|
||
const html = Host.httpGet("https://api.example.com/data");
|
||
const result = Host.httpPost("https://api.example.com/webhook", JSON.stringify({event: "test"}));
|
||
```
|
||
|
||
### KV 存储
|
||
|
||
```javascript
|
||
Host.setData("last_sync", "2026-01-01");
|
||
const val = Host.getData("last_sync");
|
||
```
|
||
|
||
每个插件有独立命名空间，互不干扰。
|
||
|
||
### 配置
|
||
|
||
```javascript
|
||
const host = Host.getConfig("app.host");
|
||
const env = Host.getConfig("app.env");
|
||
```
|
||
|
||
允许的配置键（需在 `permissions.config` 白名单中）：
|
||
`app.host`, `app.port`, `app.env`, `app.base_url`, `jwt.access_expires`, `jwt.refresh_expires`, `upload.dir`, `upload.max_size`
|
||
|
||
### 文件系统（VFS）
|
||
|
||
```javascript
|
||
Host.fsWrite("/reports/daily.json", reportJson);
|
||
const data = Host.fsRead("/reports/daily.json");
|
||
const exists = Host.fsExists("/reports/daily.json");
|
||
const files = Host.fsList("/reports");
|
||
Host.fsDelete("/reports/old.json");
|
||
```
|
||
|
||
每个插件在 `{VFS_ROOT}/{plugin_id}/` 下有隔离沙箱，路径不能包含 `..`。
|
||
|
||
### 其他
|
||
|
||
```javascript
|
||
Host.log("info", "Processing order " + orderId);
|
||
Host.log("warn", "Low stock detected");
|
||
Host.log("error", "Payment failed: " + error);
|
||
Host.emitEvent("order.created", JSON.stringify({orderId: id}));
|
||
const id = Host.newId(); // UUID v7
|
||
```
|
||
|
||
| 函数 | 说明 |
|
||
|------|------|
|
||
| `Host.log(level, msg)` | 日志输出（level: `info`/`warn`/`error`） |
|
||
| `Host.emitEvent(type, data)` | 发射事件到事件总线 |
|
||
| `Host.newId()` | 生成 UUID v7（时间排序，与系统主键一致） |
|
||
|
||
## 编写 JS 插件（ES Module + SDK）
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
plugins/my-plugin/
|
||
├── manifest.toml
|
||
└── main.js
|
||
```
|
||
|
||
### 代码模板
|
||
|
||
```javascript
|
||
import { dbQuery, dbExec, ok, fail, extractJson, logInfo, newId } from 'sdk';
|
||
|
||
// ── Hook ──
|
||
|
||
export function on_content_created(input) {
|
||
const data = extractJson(input, "body");
|
||
if (data?.content_type === "product") {
|
||
logInfo("[my-plugin] new product: " + data.id);
|
||
}
|
||
return ok(data);
|
||
}
|
||
|
||
// ── 自定义路由 ──
|
||
|
||
export function getProduct(input) {
|
||
const id = extractJson(input, "params.id");
|
||
if (!id) return fail(400, "id required");
|
||
const rows = dbQuery("SELECT * FROM products WHERE id = ?", [id]);
|
||
if (!rows || rows.length === 0) return fail(404, "product not found");
|
||
return ok(rows[0]);
|
||
}
|
||
|
||
// ── 定时任务 ──
|
||
|
||
export function on_cron_tick(input) {
|
||
const data = extractJson(input, "body");
|
||
if (data?.job_type === "daily_cleanup") {
|
||
dbExec("DELETE FROM sessions WHERE expires_at < datetime('now')");
|
||
logInfo("[my-plugin] daily cleanup done");
|
||
}
|
||
}
|
||
```
|
||
|
||
### SDK v1 API（`import { ... } from 'sdk'`）
|
||
|
||
| 函数 | 说明 |
|
||
|------|------|
|
||
| `dbQuery(sql, params?)` | 参数化 SELECT 查询，返回对象数组；错误时抛异常 |
|
||
| `dbExec(sql, params?)` | INSERT/UPDATE/DELETE，返回 `{ error?, rows_affected }` |
|
||
| `dbBegin()` | 开启事务（失败时抛异常） |
|
||
| `dbCommit()` | 提交事务（失败时抛异常） |
|
||
| `dbRollback()` | 回滚事务 |
|
||
| `ok(data)` | 成功响应：返回数据，框架自动包装为 `{code:0, data}` |
|
||
| `fail(status, msg)` | 错误响应：框架包装为 `{code:N, message}` |
|
||
| `extractJson(input, field?)` | 从 JSON 中提取指定字段（支持 `params.id` 点号路径），不存在返回 `null` |
|
||
| `logInfo(msg)` / `logWarn(msg)` / `logError(msg)` | 日志输出 |
|
||
| `newId()` | 生成 UUID v7（时间排序，与系统一致） |
|
||
| `eventEmit(type, data)` | 发射事件到事件总线 |
|
||
| `httpGet(url)` | HTTP GET 返回原始字符串 |
|
||
| `httpGetJson(url)` | HTTP GET 并解析 JSON |
|
||
| `httpPost(url, body)` | HTTP POST 返回原始字符串 |
|
||
| `httpPostJson(url, body)` | HTTP POST 并解析 JSON |
|
||
| `configGet(key)` | 读取配置（需 `config` 权限） |
|
||
| `storeGet(key)` / `storeSet(key, val)` | KV 存储 |
|
||
| `vfsRead(path)` / `vfsWrite(path, content)` | 虚拟文件系统读写 |
|
||
| `vfsDelete(path)` / `vfsExists(path)` | 虚拟文件系统删除/判断存在 |
|
||
| `vfsList(path)` | 列出目录下文件，返回数组 |
|
||
|
||
### 关键约定
|
||
|
||
- **必须使用 `export function`** 导出 handler（ES Module 模式，引擎自动收集到 Plugin 对象）
|
||
- 路由处理：`input` 包含 `{ path, method, body, headers, params }`，直接 `return ok(data)` 或 `return fail(status, msg)`
|
||
- Filter 钩子：接收 JSON 字符串 `input`，用 `extractJson(input, "body")` 提取数据
|
||
- Action 钩子：接收 JSON 字符串，返回值被忽略
|
||
- 支持 ES2024 完整语法（`let`/`const`、箭头函数、`async/await`、可选链等）
|
||
- `dbQuery()` 查询失败时抛异常，可用 `try/catch` 捕获
|
||
- `dbQuery()` 返回的整数列为 `null`，必须用 `CAST(col AS TEXT)` 转为字符串后再 `parseInt`
|
||
|
||
### 相对路径导入
|
||
|
||
```javascript
|
||
import { helper } from './utils.js';
|
||
```
|
||
|
||
## 编写 Lua 插件（SDK 模式）
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
plugins/my-plugin/
|
||
├── manifest.toml
|
||
└── init.lua
|
||
```
|
||
|
||
### 代码模板
|
||
|
||
```lua
|
||
local sdk = require("sdk")
|
||
|
||
Plugin = {}
|
||
|
||
Plugin.on_content_created = function(input)
|
||
local data = sdk.extractJson(input, "body")
|
||
if data and data.content_type == "product" then
|
||
sdk.logInfo("[my-plugin] new product: " .. tostring(data.id))
|
||
end
|
||
return sdk.ok(data)
|
||
end
|
||
|
||
Plugin.on_cron_tick = function(input)
|
||
local data = sdk.extractJson(input, "body")
|
||
if data.job_type == "daily_cleanup" then
|
||
sdk.dbExec("DELETE FROM sessions WHERE expires_at < datetime('now')")
|
||
sdk.logInfo("[my-plugin] cleanup done")
|
||
end
|
||
end
|
||
|
||
Plugin.getStats = function(input)
|
||
local result = sdk.dbQuery("SELECT CAST(COUNT(*) AS TEXT) as cnt FROM products WHERE status = 'published'")
|
||
return sdk.ok({ total = tonumber(result[1].cnt) or 0 })
|
||
end
|
||
```
|
||
|
||
### SDK v1 API（`local sdk = require("sdk")`）
|
||
|
||
| 函数 | 说明 |
|
||
|------|------|
|
||
| `sdk.dbQuery(sql, params?)` | 参数化 SELECT 查询，返回数组表；错误时抛异常 |
|
||
| `sdk.dbExec(sql, params?)` | INSERT/UPDATE/DELETE，返回结果表 |
|
||
| `sdk.dbBegin()` | 开启事务（失败时抛异常） |
|
||
| `sdk.dbCommit()` | 提交事务（失败时抛异常） |
|
||
| `sdk.dbRollback()` | 回滚事务 |
|
||
| `sdk.ok(data)` | 成功响应：返回数据，框架自动包装 |
|
||
| `sdk.fail(status, msg)` | 错误响应：框架包装为 `{code:N, message}` |
|
||
| `sdk.extractJson(input, field?)` | 从 JSON 中提取指定字段（支持点号路径），不存在返回 `nil` |
|
||
| `sdk.logInfo(msg)` / `sdk.logWarn(msg)` / `sdk.logError(msg)` | 日志输出 |
|
||
| `sdk.newId()` | 生成 UUID v7（时间排序，与系统一致） |
|
||
| `sdk.eventEmit(type, data)` | 发射事件 |
|
||
| `sdk.httpGet(url)` | HTTP GET 返回原始字符串 |
|
||
| `sdk.httpGetJson(url)` | HTTP GET 并解析 JSON |
|
||
| `sdk.httpPost(url, body)` | HTTP POST 返回原始字符串 |
|
||
| `sdk.httpPostJson(url, body)` | HTTP POST 并解析 JSON |
|
||
| `sdk.configGet(key)` | 读取配置 |
|
||
| `sdk.storeGet(key)` / `sdk.storeSet(key, val)` | KV 存储 |
|
||
| `sdk.vfsRead(path)` / `sdk.vfsWrite(path, content)` | 虚拟文件系统读写 |
|
||
| `sdk.vfsDelete(path)` / `sdk.vfsExists(path)` | 虚拟文件系统删除/判断存在 |
|
||
| `sdk.vfsList(path)` | 列出目录下文件，返回数组 |
|
||
|
||
### 关键约定
|
||
|
||
- 必须导出全局 `Plugin` 表（Lua 不强制 ESM，但仍需 `Plugin = {}`）
|
||
- 使用 `local sdk = require("sdk")` 导入 SDK 模块
|
||
- Filter 钩子：接收 Lua table，返回 Lua table
|
||
- 路由处理：`input` 包含 `{ path, method, body, headers, params }`，直接 `return sdk.ok(data)` 或 `return sdk.fail(status, msg)`
|
||
- 沙箱环境：仅暴露 `table`, `string`, `math`, `utf8`, `coroutine` 标准库（无 IO/OS/debug）
|
||
- 指令限制：5,000,000 条
|
||
- `sdk.dbQuery()` 查询失败时抛异常，可用 `pcall` 捕获
|
||
- `sdk.dbQuery()` 返回的整数列在 Lua 中可能为 `nil`，建议用 `CAST(col AS TEXT)` 转换
|
||
|
||
## 错误恢复
|
||
|
||
- 连续 **5 次** 错误自动禁用插件
|
||
- 错误计数在成功执行时重置
|
||
- 可通过 Admin API 手动重新启用
|
||
- 插件超时/崩溃时自动回滚未提交的事务
|
||
|
||
## 热重载
|
||
|
||
当 `PLUGIN_HOT_RELOAD=true`（默认开启）时：
|
||
|
||
1. 文件系统监听器监控插件目录的 `.js` / `.lua` / `.wasm` 文件变化
|
||
2. 1 秒防抖
|
||
3. 自动卸载 + 重新加载变化的插件
|
||
4. 发出 `PluginReloaded` 事件
|
||
|
||
## 管理 API
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/v1/admin/plugins` | 列出所有插件（含状态/健康/指标） |
|
||
| GET | `/api/v1/admin/plugins/{id}` | 插件详情 |
|
||
| POST | `/api/v1/admin/plugins/{id}/enable` | 启用 |
|
||
| POST | `/api/v1/admin/plugins/{id}/disable` | 禁用 |
|
||
| POST | `/api/v1/admin/plugins/{id}/reload` | 热重载 |
|
||
| DELETE | `/api/v1/admin/plugins/{id}` | 卸载 |
|
||
|
||
## CLI 命令
|
||
|
||
```bash
|
||
# 创建新插件
|
||
rust-blog plugin new my-plugin --runtime js # JavaScript
|
||
rust-blog plugin new my-plugin --runtime lua # Lua
|
||
rust-blog plugin new my-plugin --runtime wasm # WASM
|
||
|
||
# 校验插件
|
||
rust-blog plugin check # 校验默认目录
|
||
rust-blog plugin check ./plugins/my-plugin # 校验指定目录
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `PLUGIN_DIR` | `./extensions/plugins` | 插件目录 |
|
||
| `PLUGIN_VFS_ROOT` | `./plugins-data` | VFS 根目录 |
|
||
| `PLUGIN_VFS_MAX_FILE_SIZE` | `1048576` | 单文件最大 1MB |
|
||
| `PLUGIN_VFS_MAX_TOTAL_SIZE` | `10485760` | 总配额 10MB |
|
||
| `PLUGIN_WASM_POOL_SIZE` | `4` | WASM 实例池大小 |
|
||
| `PLUGIN_JS_POOL_SIZE` | `4` | JS 实例池大小 |
|
||
| `PLUGIN_LUA_POOL_SIZE` | `4` | Lua 实例池大小 |
|
||
|
||
## 完整示例：CRM 插件
|
||
|
||
```
|
||
plugins/crm/
|
||
├── manifest.toml
|
||
└── main.js
|
||
```
|
||
|
||
**manifest.toml：**
|
||
|
||
```toml
|
||
[plugin]
|
||
id = "com.rust-blog.crm"
|
||
name = "CRM API"
|
||
version = "0.1.0"
|
||
description = "CRM 销售漏斗、Pipeline 管理、联系人时间线"
|
||
runtime = "js"
|
||
entry = "main.js"
|
||
|
||
[permissions]
|
||
max_memory_mb = 16
|
||
timeout_ms = 5000
|
||
database = ["crm_contacts", "crm_companies", "crm_deals", "crm_activities", "crm_notes"]
|
||
config = ["app.*"]
|
||
|
||
[hooks.on-content-created]
|
||
priority = 50
|
||
|
||
[hooks.on-content-updated]
|
||
priority = 50
|
||
|
||
[[routes]]
|
||
method = "GET"
|
||
path = "/api/v1/plugins/crm/pipeline"
|
||
handler = "getPipeline"
|
||
|
||
[[routes]]
|
||
method = "GET"
|
||
path = "/api/v1/plugins/crm/pipeline/:dealId"
|
||
handler = "getDealDetail"
|
||
|
||
[[routes]]
|
||
method = "POST"
|
||
path = "/api/v1/plugins/crm/deals/:dealId/stage"
|
||
handler = "updateDealStage"
|
||
```
|
||
|
||
**main.js（节选）：**
|
||
|
||
```javascript
|
||
import { dbQuery, dbExec, ok, fail, extractJson, logInfo, eventEmit, newId } from 'sdk';
|
||
|
||
export function getPipeline() {
|
||
const stages = ["prospecting", "qualification", "proposal", "negotiation", "closed_won", "closed_lost"];
|
||
const pipeline = [];
|
||
for (const stage of stages) {
|
||
const rows = dbQuery(
|
||
`SELECT id, title, amount FROM crm_deals WHERE stage = ? ORDER BY amount DESC`,
|
||
[stage]
|
||
);
|
||
pipeline.push({ stage, deals: rows || [] });
|
||
}
|
||
return ok({ stages: pipeline });
|
||
}
|
||
|
||
export function getDealDetail(input) {
|
||
const dealId = extractJson(input, "params.dealId");
|
||
if (!dealId) return fail(400, "deal id required");
|
||
const deals = dbQuery(`SELECT * FROM crm_deals WHERE id = ?`, [dealId]);
|
||
if (!deals || deals.length === 0) return fail(404, "deal not found");
|
||
return ok(deals[0]);
|
||
}
|
||
|
||
export function on_content_created(input) {
|
||
const data = extractJson(input, "body");
|
||
if (data.content_type === "contact") {
|
||
logInfo(`[crm] new contact: ${data.id}`);
|
||
eventEmit("crm.lead_created", JSON.stringify({ contact_id: data.id }));
|
||
}
|
||
return ok(data);
|
||
}
|
||
```
|