Skip to content

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. 目录和安装 ​

纯前端模块最少需要两个文件:

text
my-theme/
  plugin.json
  frontend/
    index.js
    theme.css

含后端模块:

text
my-module/
  plugin.json
  go.mod
  main.go
  sdk/                 # 可选,协议辅助代码
  frontend/
    index.js
    style.css
  my-module.exe

plugin.json.id 必须等于一级目录名。backend 是包内相对路径,必须是当前系统可执行的文件。frontend/ 放浏览器能直接加载的 JS 和 CSS。清单、入口和符号链接都不能越出插件目录。

安装步骤:

  1. 把完整插件目录复制到系统设置中的插件目录 plugin_dir。
  2. 打开“插件管理”,刷新列表;新模块默认停用。
  3. 启用模块,再刷新浏览器加载页面、菜单和样式。
  4. 更新时先停用,替换完整目录,刷新列表后重新启用。

插件自己的数据保存在 data/plugins/<id>/,停用、重启和升级都不会删除。已经启用的清单发生变化时,不能直接重启,必须先停用再启用。

模块状态:

状态含义
disabled已发现,尚未启用
invalid清单或入口不符合协议
starting后端进程启动中
running已加载,可以访问页面或调用后端
stopping正在停用,等待在途调用结束
error启动失败、进程退出、包缺失或清单变化

4. 写清单 plugin.json ​

纯前端清单只需要声明前端资源。下面这个最小示例提供一个页面和一个菜单:

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:

json
{
  "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 声明
hooksHTTP 或调度扩展,按 kind/target/stage/handler 声明
frontend前端入口、样式、页面、菜单、插槽和根组件

清单校验有几个明确边界:

  • backend、frontend.entry、frontend.styles 必须是包内已存在的普通文件。
  • 前端入口和样式必须位于 frontend/ 目录。
  • 新增页面名称必须以 plugin:<id>: 开头,路径必须以 /plugins/<id>/ 开头。
  • 替换页面使用原路由名,仍需提供唯一的 name 和 component。
  • 声明页面、插槽、根组件或菜单图标时必须有 frontend.entry。
  • 菜单图标是入口导出的组件名,不是内置图标字符串。
  • 纯前端模块不能声明后端能力。

5. 前端能力 ​

frontend.entry 默认导出同步或异步工厂,接收宿主注入的 host,返回组件表:

javascript
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 等导出
uiNaive UI 组件,例如 NCard/NButton/NModal
router当前路由实例
routingvue-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。

页面、菜单和插槽都在清单里声明:

json
{
  "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:

json
{"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:

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/,入口基本是:

go
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}}
}

在插件目录内构建,不依赖宿主源码:

sh
go test ./...
go vet ./...
go build -o my-module.exe .

Linux 交叉编译后修改清单 backend 的文件名并加执行权限:

powershell
$env:GOOS = 'linux'
$env:GOARCH = 'amd64'
$env:CGO_ENABLED = '0'
go build -o my-module .
sh
chmod +x my-module/my-module

7. 调用宿主能力 ​

调用主服务业务 ​

permissions 是后端调用主服务的白名单,只能写已登记的业务操作,格式固定为 方法 路径。可以声明证书、授权、ACME 账户、工作流、监控、通知、私有 CA、概览,以及 get_setting、save_setting。

go
resp, err := modules.Call(ctx, "POST /v1/monitor/get_list", map[string]any{
    "p": 1, "limit": 10, "search": "",
})

非 Go 插件向宿主内部地址 POST /call:

json
{"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:

json
{
  "data_permissions": [
    {"table": "workflow", "actions": ["update"]},
    {"table": "monitor", "actions": ["insert", "update", "delete"]}
  ]
}

宿主只执行参数化的 INSERT/UPDATE/DELETE,不接受原始 SQL,也不能建表、改表、删表或改索引。update、delete 必须带 where。非 Go 插件向 POST /data 提交:

json
{"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 注册节点和覆盖项:

json
{
  "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 注册节点界面:

javascript
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,原部署插件和模块插件是两套协议,清单和调用方式不要混用。

基于 AGPL-3.0 许可发布