ALLinSSL 模块插件开发
模块插件是放进插件目录的一个文件夹,用 plugin.json 说明自己是什么、能做什么。它可以是纯前端的主题和页面,也可以带一个常驻后端进程,用来调用主服务业务、运行定时任务或提供工作流节点。
模块协议当前固定为数字 1。登录、Session、API Key 判定和插件管理始终由宿主处理,模块不接管这些入口。模块属于可信代码,与主服务使用同一系统用户。
1. 模块插件能做什么
把模块插件看成三层能力,按需要取用:
- 界面层:改样式、加主题、加页面、加菜单、插入组件、替换已有页面。
- 服务层:启动一个常驻后端,提供自己的接口,读写插件数据,或调用宿主业务接口。
- 流程层:在宿主接口前后插入处理,接管监控/工作流调度,增加工作流节点或替换默认节点。
对应到实际能力:
| 能力 | 是否需要后端 | 说明 |
|---|---|---|
| 主题和样式 | 不需要 | 通过 CSS 覆盖宿主外观,可随浏览器保存 |
| 新增页面、菜单、插槽 | 不需要 | 页面和菜单在清单声明,组件由前端入口导出 |
| 替换已有页面或根组件 | 不需要 | 保留原路由和参数,替换显示层 |
| 插件自有接口 | 需要 | 外部路径为 /v1/plugins/<id>/api/*,由宿主认证后转发到后端 /api/* |
| 调用主服务业务 | 需要 | 通过 permissions 声明允许调用的接口 |
| 保存插件自己的数据 | 需要 | 使用 ALLINSSL_MODULE_DATA 下的 SQLite |
| 修改主库表数据 | 需要 | 通过 data_permissions 声明,只支持参数化增删改 |
| 扩展宿主 HTTP 接口 | 需要 | 在业务接口前后执行处理,或整体替换响应 |
| 增加工作流节点 | 需要 | 后端注册执行器,前端注册节点表单 |
| 接管监控/工作流调度 | 需要 | 用 scheduler 钩子替换或包裹原任务 |
| 运行自己的定时任务 | 需要 | 直接在插件进程内启动 |
纯前端模块不能声明 backend、permissions、data_permissions 或 hooks。需要调用宿主数据或扩展流程时,必须使用含后端模块。
2. 先选插件类型
只需要换外观、加页面和菜单时,选纯前端模块。它没有进程、没有端口、没有数据库,改完刷新浏览器就能看到效果。
需要服务端逻辑时,选含后端模块。后端进程可以同时提供前端页面,也可以只提供接口。前端能力不是后端模块的必需项。
插件规模变大后,可以把后端和前端拆成两个模块:后端只声明 backend、权限和钩子,前端只声明页面、菜单和样式。两者各自安装、各自启用;前端需要调用后端接口时,直接请求后端模块的 /v1/plugins/<后端id>/api/*。
选择标准很简单:
| 你要做的事 | 选择 |
|---|---|
| 改颜色、字体、布局 | 纯前端 |
| 新增说明页、工具页、菜单 | 纯前端,除非页面要读写宿主数据 |
| 页面里调用主服务接口 | 含后端 |
| 定时检查、同步、清理数据 | 含后端 |
| 扩展工作流节点或接口行为 | 含后端 |
3. 目录和安装
纯前端模块最少需要两个文件:
my-theme/
plugin.json
frontend/
index.js
theme.css含后端模块:
my-module/
plugin.json
go.mod
main.go
sdk/ # 可选,协议辅助代码
frontend/
index.js
style.css
my-module.exeplugin.json.id 必须等于一级目录名。backend 是包内相对路径,必须是当前系统可执行的文件。frontend/ 放浏览器能直接加载的 JS 和 CSS。清单、入口和符号链接都不能越出插件目录。
安装步骤:
- 把完整插件目录复制到系统设置中的插件目录
plugin_dir。 - 打开“插件管理”,刷新列表;新模块默认停用。
- 启用模块,再刷新浏览器加载页面、菜单和样式。
- 更新时先停用,替换完整目录,刷新列表后重新启用。
插件自己的数据保存在 data/plugins/<id>/,停用、重启和升级都不会删除。已经启用的清单发生变化时,不能直接重启,必须先停用再启用。
模块状态:
| 状态 | 含义 |
|---|---|
disabled | 已发现,尚未启用 |
invalid | 清单或入口不符合协议 |
starting | 后端进程启动中 |
running | 已加载,可以访问页面或调用后端 |
stopping | 正在停用,等待在途调用结束 |
error | 启动失败、进程退出、包缺失或清单变化 |
4. 写清单 plugin.json
纯前端清单只需要声明前端资源。下面这个最小示例提供一个页面和一个菜单:
{
"type": "module",
"id": "my-pages",
"name": "我的页面",
"version": "1.0.0",
"protocol": 1,
"frontend": {
"entry": "frontend/index.js",
"styles": ["frontend/style.css"],
"pages": [
{"name": "plugin:my-pages:home", "path": "/plugins/my-pages/home", "title": "我的页面", "component": "HomePage"}
],
"menus": [
{"key": "plugin:my-pages:home", "title": "我的页面", "icon": "MenuIcon"}
]
}
}需要后端时,加上 backend、permissions,按需加 hooks:
{
"type": "module",
"id": "my-module",
"name": "我的模块",
"version": "1.0.0",
"protocol": 1,
"backend": "my-module.exe",
"permissions": [
"POST /v1/monitor/get_list",
"POST /v1/monitor/upd_monitor"
],
"hooks": [
{"kind": "http", "target": "POST /v1/monitor/get_list", "stage": "after", "handler": "monitor_after"}
],
"frontend": {
"entry": "frontend/index.js",
"pages": [
{"name": "plugin:my-module:console", "path": "/plugins/my-module/console", "title": "模块控制台", "component": "Console"}
],
"menus": [
{"key": "plugin:my-module:console", "title": "模块控制台", "icon": "MenuIcon", "order": 6}
]
}
}清单字段:
| 字段 | 说明 |
|---|---|
type | 固定为 module |
id | 目录标识,只能使用小写字母、数字、下划线和连字符 |
name、version | 显示名称和版本,不能为空 |
protocol | 固定为数字 1 |
backend | 可选;省略就是纯前端模块 |
permissions | 允许后端调用的主服务业务操作,格式为 方法 路径 |
data_permissions | 允许修改主库表的白名单,按 table 和 actions 声明 |
hooks | HTTP 或调度扩展,按 kind/target/stage/handler 声明 |
frontend | 前端入口、样式、页面、菜单、插槽和根组件 |
清单校验有几个明确边界:
backend、frontend.entry、frontend.styles必须是包内已存在的普通文件。- 前端入口和样式必须位于
frontend/目录。 - 新增页面名称必须以
plugin:<id>:开头,路径必须以/plugins/<id>/开头。 - 替换页面使用原路由名,仍需提供唯一的
name和component。 - 声明页面、插槽、根组件或菜单图标时必须有
frontend.entry。 - 菜单图标是入口导出的组件名,不是内置图标字符串。
- 纯前端模块不能声明后端能力。
5. 前端能力
frontend.entry 默认导出同步或异步工厂,接收宿主注入的 host,返回组件表:
export default function (host) {
const { defineComponent, h } = host.vue
const { NCard, NButton } = host.ui
const MenuIcon = defineComponent({
setup: () => () => h('svg', {
viewBox: '0 0 24 24',
fill: 'none',
stroke: 'currentColor',
'aria-hidden': 'true',
}, [h('path', { d: 'M4 4h16v16H4zM4 10h16' })]),
})
const HomePage = defineComponent({
setup() {
return () => h(NCard, { title: '我的页面' }, () =>
h(NButton, { onClick: () => host.router.push('/home') }, () => '回到首页'),
)
},
})
return { MenuIcon, HomePage }
}工厂在应用挂载前执行,新增页面可以在首次解析前注册,直接访问和刷新都能加载。需要 useRoute、Pinia、注入或组件生命周期的逻辑,放在组件的 setup 里,不要写在工厂顶层。
host 提供的主要能力:
| 字段 | 用途 |
|---|---|
vue | 宿主 Vue 的 h/ref/defineComponent 等导出 |
ui | Naive UI 组件,例如 NCard/NButton/NModal |
router | 当前路由实例 |
routing | vue-router 导出,例如 RouterLink/useRoute |
RouterView | 支持页面替换的路由出口 |
http | 宿主 Axios 实例,沿用当前认证和响应处理 |
api | 本模块接口前缀 /v1/plugins/<id>/api |
app | 宿主 Vue App |
Root | 原始应用根组件 |
views | 原路由名到原始页面的映射 |
load(path) | 加载宿主 views/、components/ 下的模块 |
workflow | 工作流节点界面注册接口 |
组件直接使用 host.vue 和 host.ui,不要再打包一份 Vue。入口必须是浏览器能直接加载的标准 ES 模块;TS、TSX 和 .vue 源码要先编译成 JS。
页面、菜单和插槽都在清单里声明:
{
"pages": [
{"name": "plugin:my-module:console", "path": "/plugins/my-module/console", "title": "模块控制台", "component": "Console"}
],
"menus": [
{"key": "plugin:my-module:console", "title": "模块控制台", "icon": "MenuIcon", "order": 6}
],
"slots": [
{"target": "layout:header", "component": "Header"}
]
}新增页面不会自动出现菜单,需要单独声明。替换已有页面时使用 replace:
{"name": "my-monitor", "replace": "monitor", "component": "MonitorPage"}替换会保留原路径、查询和参数,组件通过 host.routing.useRoute() 读取当前路由。插槽可用目标是 layout:header、page:<路由名>:before 和 page:<路由名>:after。
常用路由名:
| 路由名 | 页面 |
|---|---|
layout | 主布局 |
login、404 | 登录页和未找到页面 |
home、autoDeploy | 首页、自动化部署 |
workflow-view | 工作流编辑子页面 |
certManage、certApply | 证书管理、证书申请 |
privateCaManage、privateCaCert | 私有 CA、私有证书 |
authApiManage、monitor、settings、plugins | 授权、监控、设置、插件管理 |
detail | 监控详情 |
实际路由名可以用 host.router.getRoutes() 确认。页面、插槽或菜单图标没有导出时,插件管理页会显示前端加载错误,不会自动显示被替换的原页面。
前端资源由宿主从 /plugins/<id>/static/frontend/* 提供,只读取 frontend/ 下的文件,模块停用后返回 404。纯前端模块在登录前就会加载,所以 frontend/ 不能放凭据、私钥或内部令牌。
纯前端主题可以做 CSS 覆盖,也可以替换 root 根组件、layout 布局和 login 登录页。替换登录页只改变界面和交互,认证结果仍由宿主决定。
6. 后端能力
启用含后端模块时,宿主执行 backend,工作目录是插件目录,并传入:
| 环境变量 | 含义 |
|---|---|
ALLINSSL_MODULE_ID | 模块标识 |
ALLINSSL_MODULE_DATA | 插件数据目录的绝对路径 |
ALLINSSL_HOST_URL | 宿主内部业务地址 |
ALLINSSL_HOST_SOCKET | 可选,宿主内部 Unix socket;SDK 会优先使用 |
ALLINSSL_MODULE_TOKEN | 本次进程的通信凭据,重启后变化 |
后端要在 10 秒内监听 127.0.0.1 随机端口,并向标准输出写一行就绪 JSON:
{"protocol":1,"url":"http://127.0.0.1:41234"}这一行必须换行,标准输出只用于报就绪;日志和启动横幅写标准错误。宿主关闭标准输入表示要求退出,插件应停止自有任务并关闭数据库。
所有内部请求校验 Authorization: Bearer <本次凭据>。凭据每次重启轮换,停用后失效,不要传到浏览器。
宿主通过 POST /invoke 调用插件。请求包含 kind/target/stage/handler,以及对应的 request、response、params 或 result;插件返回 Reply,用 response、params、result 返回结果,用非空 error 表示失败。HTTP 请求和响应的 body 在 JSON 中是 base64,headers 是“名称到字符串数组”。
插件自己的接口直接挂在 /api/*。外部访问路径是 /v1/plugins/<id>/api/*,宿主认证后转发,并覆盖内部 Authorization、移除 Cookie。响应支持普通 JSON、文件下载和持续流。
协议本身是 HTTP/JSON,不使用 SDK 也能实现。Go 插件可以从示例中复制 sdk/,入口基本是:
func main() {
log.SetOutput(os.Stderr)
api := http.NewServeMux()
api.HandleFunc("/api/hello", func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("{\"status\":true}"))
})
if err := sdk.Serve(context.Background(), invoke, api); err != nil {
log.Fatal(err)
}
}
func invoke(ctx context.Context, call sdk.Invoke) sdk.Reply {
return sdk.Reply{Result: map[string]any{"handled": call.Handler}}
}在插件目录内构建,不依赖宿主源码:
go test ./...
go vet ./...
go build -o my-module.exe .Linux 交叉编译后修改清单 backend 的文件名并加执行权限:
$env:GOOS = 'linux'
$env:GOARCH = 'amd64'
$env:CGO_ENABLED = '0'
go build -o my-module .chmod +x my-module/my-module7. 调用宿主能力
调用主服务业务
permissions 是后端调用主服务的白名单,只能写已登记的业务操作,格式固定为 方法 路径。可以声明证书、授权、ACME 账户、工作流、监控、通知、私有 CA、概览,以及 get_setting、save_setting。
resp, err := modules.Call(ctx, "POST /v1/monitor/get_list", map[string]any{
"p": 1, "limit": 10, "search": "",
})非 Go 插件向宿主内部地址 POST /call:
{"operation":"POST /v1/monitor/get_list","params":{"p":1,"limit":10,"search":""}}外层 HTTP 200 只代表通道调用完成,还要检查返回的 status 和 body,以及原业务 JSON 的 status/code/message。错误凭据返回 401,未声明或未登记的操作返回 403。
业务调用直接执行原处理器,复用原参数校验和返回格式,不经过登录和模块 HTTP 扩展,避免插件调用自身形成递归。当前通道不传 multipart 文件。
不开放 SQL、任意 URL、主库连接、主库文件下载和恢复、登录、插件管理、服务启停。前端的 host.http 使用当前用户的外部认证,和后端 permissions 是两条不同的通道。
保存自己的数据
插件数据放在 ALLINSSL_MODULE_DATA,常用 plugin.db。宿主只创建目录,建表、迁移、索引和事务由插件自己维护。可以使用 modernc.org/sqlite,迁移版本放在 PRAGMA user_version。
不要把相对路径 data/... 当成插件数据目录,也不要修改主库表结构。停用、重启和替换程序都不会删除插件数据库。
修改主库表数据
只有确实需要直接改宿主表时,才声明 data_permissions:
{
"data_permissions": [
{"table": "workflow", "actions": ["update"]},
{"table": "monitor", "actions": ["insert", "update", "delete"]}
]
}宿主只执行参数化的 INSERT/UPDATE/DELETE,不接受原始 SQL,也不能建表、改表、删表或改索引。update、delete 必须带 where。非 Go 插件向 POST /data 提交:
{"table":"workflow","action":"update","values":{"active":"0"},"where":{"id":1}}成功返回 {"affected":1}。未声明的表或动作返回 403;字段不存在、无条件更新或删除返回 400。能通过业务接口完成的事情,优先走业务接口。
扩展 HTTP 接口和调度
hooks 在宿主已有接口或调度前后插入逻辑。kind=http 的目标必须是已登记的业务操作,不能接管登录和插件管理;kind=scheduler 的目标只能是 monitor 或 workflow。
HTTP 扩展里,before 可以改请求,replace 可以直接返回响应,after 可以改响应;调度扩展处理的是任务参数和结果。多个 before 按模块标识正序执行,多个 after 按逆序执行。同一个目标的整体替换只能有一个插件。
普通 POST 业务支持后置处理;GET 下载和大文件、SSE 这类持续输出,用 replace 返回 {"stream":true},宿主会转发到模块的 /api/_hooks/http,由插件直接写状态、响应头和正文。
插件自己的定时器、队列和后台任务,直接在进程内启动即可,随进程退出停止,不需要额外注册宿主调度目标。
工作流节点
后端提供 GET /api/workflow 注册节点和覆盖项:
{
"nodes": [
{"name": "pause", "handler": "pause", "title": "暂停执行", "order": 6}
],
"overrides": {
"apply": "apply"
}
}nodes 新增节点,宿主生成类型 plugin:<id>:<name>;overrides 可以替换 apply/deploy/upload/notify/private_ca,开始、分支和条件节点不能覆盖。返回 404 表示没有工作流扩展。
宿主在启用、启动或重启插件后读取注册表,执行节点时通过 /invoke 调用对应 handler。插件返回的 result 是节点输出,非空 error 表示失败。覆盖申请、部署节点时,要保留后续节点依赖的输出结构,例如证书的 cert/key。
前端用 host.workflow 注册节点界面:
host.workflow.addNode({
name: 'pause',
title: '暂停执行',
order: 6,
icon: 'apply',
defaultConfig: { seconds: 5 },
summary: config => '等待 ' + (config.seconds || 0) + ' 秒',
validate: config => Number(config.seconds) > 0 ? '' : '请输入暂停秒数',
form: PauseForm,
})addNode 必须提供 name、title 和 summary,表单可选。hideNode 只从添加菜单隐藏节点,replaceForm 替换编辑表单。节点表单接收 { node, save, close },save(config) 保存并关闭。
需要完全接管画布和交互时,可以用页面替换 workflow-view,由插件自己实现整个工作流编辑器。
8. 生命周期与故障
首次启用时,含后端模块只有在进程就绪、状态保存成功后才发布扩展;启动失败不会发布半成品。已经发布的模块在崩溃、宿主重启或包缺失后仍保留接管关系,受影响功能明确报错,不自动重启,也不会悄悄执行被替换的原业务。
同一页面、同一根组件、同一 HTTP 接口、同一工作流节点类型或同一调度目标的整体替换,只允许一个模块。后置处理可以叠加。
停用先阻止新调用,最多等待已有调用 5 秒;随后取消调用上下文并关闭标准输入,最多等待进程退出 5 秒;仍未退出则终止进程。模块应在退出前停止自有任务并关闭数据库。
更新插件时先停用,替换全部包文件,再刷新列表并启用。停用保留 data/plugins/<id>/,卸载前也应先停用再移走目录。
9. 调试与排查
先看“插件管理”里的状态和最近错误。纯前端问题看浏览器控制台和页面里的模块加载错误;后端问题看进程输出和插件自己的日志。日志不要写到标准输出,否则会破坏就绪协议。
| 现象 | 先检查什么 |
|---|---|
| 模块没有出现 | 目录名是否等于 id、plugin_dir 是否配置正确、一级目录里是否有 plugin.json |
| 清单无效 | protocol 是否为 1、入口文件是否存在、路径是否越出包目录 |
| 后端启动超时 | 10 秒内是否输出了带换行的就绪 JSON,标准输出是否混入日志 |
| 权限返回 403 | 操作名和请求方法是否完整、是否在 permissions 中 |
| 页面或组件缺失 | 页面 component、菜单 icon 是否在入口返回的对象里 |
| 新页面刷新 404 | 模块是否仍启用,宿主或反向代理是否把插件路径交给 SPA |
| 主题不生效 | 样式路径是否正确,清单变化后是否先停用再启用 |
| 停用后界面还在 | 刷新浏览器移除当前运行时,插件自己的 localStorage 要自行清理 |
10. 边界
- 模块插件是可信同源代码,不是操作系统沙箱;受控接口能拦住正常插件操作,但拦不住恶意程序直接访问同一用户的文件。
- 模块不能接管登录、Session/API Key 判定。插件管理的后端接口始终由宿主提供,不能被业务扩展替换;前端外观可以按主题调整。
- 插件市场、在线安装升级和全局服务器主题不在当前协议范围内。
- 主题依赖宿主 DOM 或组件类名时,宿主升级后需要重新验收。
- 前端插件停用后必须刷新页面才能完全移除;它写入的 localStorage 由插件自己管理。
- 模块协议当前固定为
1,原部署插件和模块插件是两套协议,清单和调用方式不要混用。