进阶指南:开发 Tier 2 Go 原生系统级插件
当插件需要独立关系型 SQL 建表与复杂迁移、连接外部数据库 / RCON / TCP 服务、HTTP/SSE/WebSocket 大流量流式代理,或替换底层对象存储 / 全文搜索 / 3D 渲染驱动时,可以使用基于 sdk/go 的 Tier 2 原生插件(runtime: "native")。
本指南以官方插件 bs-importer 为例说明完整开发流程。
1. 安全边界与架构约定(ADR 0049)
- 进程级隔离:原生插件以独立 OS 子进程运行(基于
hashicorp/go-plugin双向 gRPC);插件崩溃或 OOM 不会影响主站,宿主会自动指数退避重启并在连续崩溃时熔断。 - 核心表严禁裸 SQL:原生插件必须通过双向 gRPC
HostService(ctx.Users、ctx.Players、ctx.Textures、ctx.Score、ctx.Services.Call等)操作核心业务数据,严禁绕过宿主直接读写核心表。 - 三方言隔离 SQL 数据库(
sdk/go/plugindb):声明storage.sql权限和native.database.required: true后,宿主自动为插件分配专属数据库空间与强约束表前缀plg_<safe_id>_(SQLite 为独立<DataDir>/plugins-data/<id>/plugin.dbWAL 库;MySQL/PostgreSQL 支持独立[plugins.database]配置或主库前缀/Schema 隔离),卸载--purge时由宿主精准清理。 - 强供应链签名:生产环境下,宿主强制拒绝未携带官方市场公钥或超级管理员
plugins.trusted_keysEd25519 签名的native插件;提交至 skinloom-registry 后由官方隔离 Runner 统一交叉编译 5 个平台分包并加盖官方签名。
2. 声明清单 plugin.json
{
"$schema": "https://skinloom.cn/schema/plugin.v1.json",
"id": "my-native-plugin",
"kind": "plugin",
"runtime": "native",
"version": "1.0.0",
"name": { "zh-CN": "原生插件示例", "en": "Native Example" },
"apiVersion": 1,
"engines": { "skinloom": ">=0.1.0 <2.0.0", "go": ">=1.26.10" },
"web": "web/index.js",
"native": {
"protocolVersion": 1,
"executable": "bin/my-native-plugin",
"platforms": [
"linux/amd64",
"linux/arm64",
"windows/amd64",
"darwin/arm64",
"darwin/amd64"
],
"httpProxy": true,
"database": { "required": true }
},
"permissions": ["admin.ui", "native.exec", "storage.sql", "http.stream", "users.read"]
}
也可以运行 bunx create-skinloom-plugin my-native-plugin --template native-go 直接生成完整工程模板。
3. 三方言隔离 SQL 迁移
在 migrations/{sqlite,mysql,postgres}/001_init.sql 中使用 {{prefix}} 占位符编写标准 goose SQL 迁移:
-- +goose Up
CREATE TABLE IF NOT EXISTS {{prefix}}jobs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
status TEXT NOT NULL,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- +goose Down
DROP TABLE IF EXISTS {{prefix}}jobs;
在 Setup 中只需一行调用,SDK 会按当前宿主方言自动选取对应目录、展开 {{prefix}} 并执行迁移;后续执行查询时 db.Query / db.Exec 也会自动把 ? 绑定占位符在 PostgreSQL 上改写为 $1, $2, ...:
//go:embed migrations
var migrationsFS embed.FS
func (p *MyPlugin) Setup(ctx *plugin.Context) error {
db := ctx.DB()
if err := db.Migrate(context.Background(), migrationsFS, "migrations"); err != nil {
return err
}
// ...
}
4. 注册 JSON 接口、SSE 流式接口与跨插件调用
package main
import (
"context"
"fmt"
"net/http"
plugin "github.com/Entropy-Increase-Team/skinloom/sdk/go"
)
type MyPlugin struct{}
func (p *MyPlugin) Setup(ctx *plugin.Context) error {
// 1. 标准 JSON HTTP 路由(宿主已完成会话鉴权、CSRF 校验与限流)
ctx.HTTP.Post("/admin/run", func(reqCtx context.Context, req *plugin.HTTPRequest) (*plugin.HTTPResponse, error) {
// 调用另一个插件暴露的服务(如 invitation-codes.importCodes)
raw, err := ctx.Services.Call(reqCtx, "invitation-codes", "importCodes", []map[string]any{
{"code": "MIGRATED-001"},
})
if err != nil {
return nil, plugin.Reject("importCodes failed: " + err.Error())
}
return plugin.JSON(http.StatusOK, map[string]any{"result": string(raw)}), nil
}, plugin.WithAuth(plugin.AuthSuperadmin))
// 2. 流式 SSE / WebSocket 路由(需声明 native.httpProxy: true 与 http.stream 权限)
ctx.HTTP.StreamFunc(http.MethodGet, "/admin/jobs/:id/stream", func(w http.ResponseWriter, r *http.Request) {
params := plugin.StreamParams(r)
viewer := plugin.ProxyViewer(r)
w.Header().Set("Content-Type", "text/event-stream")
w.Header().Set("Cache-Control", "no-cache")
_, _ = fmt.Fprintf(w, "event: progress\ndata: {\"job\":%q,\"actor\":%d}\n\n", params["id"], viewer.UserID)
if flusher, ok := w.(http.Flusher); ok {
flusher.Flush()
}
}, plugin.WithAuth(plugin.AuthSuperadmin))
return nil
}
func main() {
plugin.Serve(&MyPlugin{})
}
可选底层基础设施驱动:只需在插件结构体上实现
plugin.StorageProvider、plugin.SearchProvider或plugin.RenderProvider接口并声明对应权限(provider.storage、provider.search、provider.render),plugin.Serve会自动将其注册为 gRPC Provider 服务。
5. 进程内单元测试(sdk/go/plugintest)
使用 sdk/go/plugintest 无需拉起子进程或真实宿主即可用标准 go test 完成全套单测(包含内存隔离 SQLite 库、Mock HostService 与流式 HTTP 路由测试):
func TestMyPlugin(t *testing.T) {
ctx := context.Background()
h := plugintest.New(t, &MyPlugin{},
plugintest.WithPluginID("my-native-plugin"),
plugintest.WithSQL(),
plugintest.WithPermissions("admin.ui", "native.exec", "storage.sql", "http.stream"),
)
req := httptest.NewRequest(http.MethodGet, "/admin/jobs/42/stream", nil)
req.Header.Set("X-SkinLoom-User-ID", "1")
req.Header.Set("X-SkinLoom-User-Role", "superadmin")
rec := h.DoStreamHTTP(req)
if rec.Code != http.StatusOK {
t.Fatalf("unexpected status %d", rec.Code)
}
}
6. 五平台交叉编译与分包打包
确保代码满足纯 Go(CGO_ENABLED=0)跨平台编译后,使用 @skinloom/cli 一键交叉编译并输出 5 个平台的独立分包与 artifacts.json:
# 本地编译当前平台与前端包
bunx skinloom-plugin build --native
# 交叉编译 5 大目标平台并输出独立分包 .slp(用于市场分发)
bunx skinloom-plugin pack --native --split-platforms \
--targets linux/amd64,linux/arm64,windows/amd64,darwin/arm64,darwin/amd64 \
--key ./keys/signing.key.pem \
--out-dir ./release
# 或打成一个包含全部平台二进制的离线胖包(适合离线内网部署)
bunx skinloom-plugin pack --native --fat --key ./keys/signing.key.pem