10 · 双轨插件架构(JS 沙箱 + Go 原生系统级)与官方插件市场实施方案
状态:全部落地完成(2026-11-19,随 SkinLoom
v1.1.0及官方市场首批 5 个扩展上架闭环)。
前置基线:P2-1 ~ P2-4(轻量级 TS/JS 沙箱运行时、前端共享模块与 20 插槽、主题 Level ⑤ 覆盖、.slpEd25519 签名与热加载)已完成,见 ADR 0046、ADR 0047、ADR 0048。
执行铁律:严格先完成第一部分「全部基建工作(Phase A → B → C → D)」并通过基建总验收门禁后,再开工第二部分「第一批官方插件与文档冻结(Phase E → F → G)」。
一、 架构定位与核心决策总览
为了突破纯 JS/TS 沙箱在原生网络协议(外部 DB/RCON/TCP/WS)、复杂关系型 SQL 数据表、高吞吐算力与底层基础设施驱动扩展方面的天花板,同时保留轻量化插件的跨平台零门槛优势,SkinLoom 升级为 双轨混合插件架构(Dual-Tier Plugin Architecture):
| 维度 | Tier 1:轻量级沙箱插件(runtime: "js",已有) | Tier 2:系统级原生插件(runtime: "native",新增) |
|---|---|---|
| 开发语言与 SDK | TypeScript(@skinloom/plugin-sdk) | 后端 Go(sdk/go)+ 前端可选 TypeScript/React(100% 复用 @skinloom/plugin-sdk/web) |
| 执行引擎 | 进程内 QuickJS-NG/WASM 实例池(internal/jsrt) | 独立 OS 子进程(hashicorp/go-plugin 双向 gRPC + 可选本地 HTTP/WebSocket 流式反代) |
| 隔离与稳定性 | WASM 线性内存硬限(64 MiB)+ 抢占超时中断 | OS 进程级崩溃隔离(插件 panic/OOM 绝不拖垮主站,宿主自动指数退避重启 + 熔断) |
| 核心业务数据 | 通过 ctx.* 宿主 API 访问 | 严格通过双向 gRPC HostService 访问(绝不直接写核心表,守住积分/UUID/缓存/审计不变量) |
| 插件自有数据 | plugin_kv + plugin_docs(预置索引槽位) | 支持完整 SQL 关系库 + 专属前缀 plg_<safe_id>_,覆盖 SQLite / MySQL / PostgreSQL 三种模式 |
| 底层扩展能力 | 32+ Hook、认证/验证码/CDN/Yggdrasil、前端全扩展点 | 除上述全部能力外,新增 StorageProvider、SearchProvider、RenderProvider、StreamHTTP/WS |
| 包分发策略 | 单文件跨平台 .slp(<= 20 MiB) | 按 OS/Arch 分平台 .slp(推荐三平台:linux、windows、darwin;amd64/arm64;宿主按环境自动筛选拉取;同时兼容离线胖包) |
| 安全与信任策略 | 沙箱隔离 + 三级权限确认;超管可按告警安装社区自签包 | 强供应链信任:默认强制由官方 GitHub 市场(skinloom-registry)审计源码后由官方 CI 统一交叉编译并加盖 Ed25519 签名;生产环境默认拒绝未带官方签名的 native 插件 |
| 热加载机制 | 原子替换实例池,旧池排空 ≤ 30s | 同样支持热加载:先拉起新版子进程完成握手与 OnUpgrade → 原子切换 gRPC 客户端与路由 → 旧子进程排空在途请求(≤ 30s)后退出 |
二、 系统架构详细设计
2.1 总体分层架构
flowchart TB
subgraph Frontend["Next.js 前端(双轨插件 100% 复用同一套前端体系)"]
WebUI["React 19 共享表 · 20 个 Slot · 插件页面 · 声明式表单 · 首页 Block · 主题 L5 Overrides"]
end
subgraph Host["SkinLoom 主进程(Go 单二进制)"]
GW["Gateway / 路由分流<br/>• /api/plugins/{id}/* (JSON RPC 或 Native HTTP/WS 反代)<br/>• /plugins-assets/* (前端 ESM & 静态资源)"]
MGR["internal/plugin.Manager(统一管理器)<br/>• Manifest 校验 & 环境兼容性引擎<br/>• 统一权限门禁 & 审计日志 & 熔断器<br/>• 原子替换注册表 (Hook / Route / Menu / Cron / Providers)<br/>• 多架构集群同步 (storage.Store + config_version)"]
MKT["RegistryClient(模式 A 静态签名市场客户端)<br/>• 多源拉取 (官方国内镜像 + GitHub 源 + 自定义源)<br/>• 按 OS/Arch · SkinLoom版本 · Go版本 · 依赖智能筛选<br/>• 官方 Ed25519 验签 & blocked 恶意阻断自动巡检"]
subgraph Drivers["后端双轨驱动抽象(PluginDriver 接口)"]
JS["<b>JSDriver</b> (runtime: js)<br/>internal/jsrt (QuickJS-NG/WASM)"]
NAT["<b>NativeDriver</b> (runtime: native)<br/>hashicorp/go-plugin (双向 gRPC + 本地 ReverseProxy)"]
end
subgraph DBAlloc["双层数据库隔离分配器 (PluginDBAllocator)"]
SQLITE["SQLite: 独立 data/plugins/{id}/plugin.db (WAL)"]
MYSQL["MySQL/MariaDB: 专属前缀 plg_{safe_id}_"]
PG["PostgreSQL: 专属前缀 plg_{safe_id}_ / 可选 Schema"]
end
end
subgraph SubProc["系统级原生 Go 插件子进程(独立 OS 进程)"]
SDK["sdk/go (Plugin Server + Host gRPC Client)<br/>• 任意第三方 Go 库 (外部 MySQL/PG/Redis/RCON/TCP/图像)<br/>• 业务表直连专属隔离 DB (支持 database/sql / goose / ent)<br/>• 核心数据回调 HostService gRPC<br/>• 可选监听本地 UDS/127.0.0.1 端口承接 WebSocket 与大文件流"]
end
subgraph MarketRepo["官方 GitHub 市场仓库(Entropy-Increase-Team/skinloom-registry)"]
CI["源码 PR 审计 + CodeQL/govulncheck + 官方 CI 三平台交叉编译 + Ed25519 签名 → R2 / 国内镜像"]
end
Frontend <--> GW
GW <--> MGR
MKT <--> MGR
MarketRepo -. "签名 index.v1.json + 分平台 .slp" .-> MKT
MGR --> JS
MGR --> NAT
MGR --> DBAlloc
NAT <== "双向 gRPC (Unix Socket / Loopback)<br/>+ 本地流式 HTTP/WS ReverseProxy" ==> SDK
DBAlloc -. "下发隔离连接参数与专属前缀" .-> SDK
2.2 plugin.json 清单扩展设计(完全兼容现有 apiVersion: 1)
在现有 internal/plugin/manifest.go 的 Manifest 结构体上进行增量扩展(所有新字段均有默认值,现有 runtime 缺省即 "js"):
{
"$schema": "https://skinloom.cn/schema/plugin.v1.json",
"id": "bs-importer",
"kind": "plugin",
"runtime": "native", // 新增:"js"(默认)| "native"
"version": "1.0.0",
"name": { "zh-CN": "Blessing Skin 迁移助手", "en": "Blessing Skin Importer" },
"apiVersion": 1,
"engines": {
"skinloom": ">=1.0.0 <2.0.0", // 宿主机 SemVer 约束
"go": ">=1.26" // 新增(native 可选):编译/运行 Go 基线标注
},
"native": { // 新增(runtime == "native" 必填)
"protocolVersion": 1, // 双向 gRPC 协议大版本
"executable": "bin/bs-importer", // 包内基名:自动匹配 _linux_amd64 / _windows_amd64.exe 等,或单平台直接匹配
"platforms": [ // 本包包含的平台列表(分包时长度=1;胖包时长度>=1)
"linux/amd64"
],
"httpProxy": true, // 是否开启本地流式 HTTP/WebSocket 反代数据面
"database": { // 是否申请隔离关系型数据库空间(需配合 "storage.sql" 权限)
"required": true
}
},
"web": "web/index.js", // 前端入口,与 JS 插件完全一致!
"permissions": [
"storage.sql", // 新增(敏感/高危分级见 §2.4)
"http.stream", // 新增:启用本地 HTTP/WS 流式反代
"users.read",
"textures.write"
]
}
2.3 双层数据隔离与三方言专属前缀设计(SQLite / MySQL / PostgreSQL)
为确保核心业务数据零污染,同时赋予原生 Go 插件完整的 SQL 关系建模能力:
- 核心业务表(严格隔离):
users、players、textures、blobs、closet_items、score_ledger、ygg_tokens、oauth_*、settings、audit_logs等核心表绝不开放裸 SQL 写入,原生插件只能通过双向 gRPCHostService调用宿主领域服务。
- 插件专属关系库与表前缀规范(三方言统一):
- 专属安全前缀推导规则:将插件
id(kebab-case,如bs-importer)中的-转为_,生成不可伪造的规范前缀plg_<safe_id>_(例如plg_bs_importer_),长度上限严格校验,杜绝 SQL 注入。 - SQLite 模式:
- 宿主为该插件创建独立数据库文件
<DataDir>/plugins-data/<id>/plugin.db(开启WAL、busy_timeout=5000、foreign_keys=ON),下发给插件子进程。 - 优势:彻底消除多进程同时写主库
skinloom.db导致的SQLITE_BUSY锁死;卸载选择--purge时直接安全清理该目录;skinloom backup/restore自动打包plugins-data/,数据零丢失! - 插件表名依然使用 SDK 的
db.Table("tasks")(产出plg_bs_importer_tasks),保持三方言 SQL 写法 100% 统一。
- 宿主为该插件创建独立数据库文件
- MySQL / MariaDB 模式:
- 在
config.toml支持可选配置[plugins.database](允许大站运维为原生插件配置单独的 MySQL 数据库或仅授予plg_%权限的独立账号);未单独配置时复用站点主库连接,下发driver: "mysql"、dsn与强制前缀plg_<safe_id>_。 - 卸载选择
--purge时,宿主查询information_schema.tables中匹配table_name LIKE 'plg_<safe_id>_%'的表并执行安全DROP TABLE。
- 在
- PostgreSQL 模式:
- 同理支持独立
[plugins.database]配置或复用主库,默认使用plg_<safe_id>_表前缀(并可选支持独立 Schemaplg_<safe_id>+search_path)。 - 卸载
--purge时精准清理该前缀/Schema 下属对象,绝不误伤核心表。
- 同理支持独立
- 专属安全前缀推导规则:将插件
- Go SDK 封装(
sdk/go/plugindb):- 提供
ctx.DB()返回开箱即用的*plugindb.DB(封装*sql.DB、Dialect() string、Prefix() string、Table(name string) string与三方言迁移运行器Migrate(fs.FS))。
- 提供
2.4 权限模型扩展与强信任边界
在现有 internal/plugin/permissions.go 三级权限表上新增系统级权限:
| 权限名 | 风险等级 | 说明 | 仅限 Native |
|---|---|---|---|
storage.sql | 敏感(橙色) | 访问宿主分配的插件专属 SQL 数据库空间(带 plg_<id>_ 前缀) | ✓ |
http.stream | 敏感(橙色) | 启用本地 HTTP / WebSocket 流式反向代理通道(突破 1MB/10MB 缓冲限制) | ✓ |
provider.storage | 高危(红色) | 注册自定义材质对象存储驱动(StorageProvider) | ✓ |
provider.search | 敏感(橙色) | 注册自定义皮肤库全文搜索引擎驱动(SearchProvider) | ✓ |
provider.render | 敏感(橙色) | 注册自定义 2D/3D 头像与预览图渲染引擎驱动(RenderProvider) | ✓ |
native.exec | 高危(红色,隐式必带) | 所有 runtime: "native" 插件自动附带该高危标识,明确告知超管该插件将以原生子进程运行 | ✓ |
runtime: "native" 安全强制规则:
- 生产模式(默认):
InstallPackage遇到runtime == "native"时,必须验证pkg.Verification.Official == true(由官方 GitHub 市场私钥签发)或位于超级管理员在plugins.trusted_keys中明确添加的自托管信任公钥;默认禁止跳过签名安装未验签的原生二进制(仅web.mode == "dev"或SKINLOOM_PLUGINS__ALLOW_UNSIGNED_NATIVE=true且超管输入插件 ID 二次确认后才允许本地调试)。 - 单包体积限制调整:
runtime == "js"维持MaxPackageBytes = 20 MiB;runtime == "native"允许单平台.slp归档上限50 MiB(解压上限100 MiB,单二进制文件上限64 MiB),同时支持胖包上限150 MiB。
2.5 双向 gRPC 协议与本地流式 HTTP/WS 反代设计
创建 api/proto/plugin/v1/(使用标准 Protobuf v3 生成 Go 代码,不引入重量级外部框架):
- 控制面(Host → Plugin:
PluginServicegRPC):Init(InitRequest) → InitResponse:下发plugin_id、version、settings、granted_permissions、data_dir、隔离数据库配置(DatabaseConfig)、宿主 gRPC 回调 broker ID,返回注册的 Hooks、Routes、Cron、Services、Providers 以及可选本地 HTTP 反代地址(Unix Socket 路径或127.0.0.1:port+ 随机proxy_secret)。Lifecycle(LifecycleRequest) → LifecycleResponse:onInstall/onEnable/onDisable/onUpgrade(from)/onUninstall(purge)。InvokeGuard / InvokeFilter / InvokeEvent:执行注册的同步/异步 Hook。InvokeHTTP:常规轻量 JSON 请求(若插件未启用httpProxy)。InvokeCron / InvokeService / NotifySettingsChanged。HealthCheck:宿主周期性探活(失败触发退避重启与熔断)。- 底层 Provider RPC:
StorageService(Get/Put/Delete/Stat/URL)、SearchService(Index/Delete/Search)、RenderService(RenderAvatar/RenderPreview)。
- 回调面(Plugin → Host:
HostServicegRPC,复用go-pluginGRPCBroker):- 完整映射现有全部 25 个
ctx.*宿主能力(Users、Players、Textures、Closet、Score、Notify、Mail、KV、Docs、Files、Settings、Site、Audit、EmitEvent、CallPluginService、Log),全部经过与 JS 插件完全相同的PermissionSet.Check权限校验!
- 完整映射现有全部 25 个
- 数据面(可选本地 HTTP/WS 流式反代):
- 当插件启用
httpProxy: true时,子进程监听独立 Unix Domain Socket(Linux/macOS 位于<DataDir>/run/plugin-<id>-<nonce>.sock,权限0600;Windows 监听127.0.0.1:0),在InitResponse返回地址与一次性 256-bitproxy_token。 - SkinLoom 宿主收到
/api/plugins/<id>/*或routes.public请求后:先在宿主侧完成会话认证、CSRF 校验、权限级别检查(public/user/admin/superadmin)与限流,再剥离原始 Cookie,注入可信内部头(X-SkinLoom-Proxy-Token、X-SkinLoom-User-ID、X-SkinLoom-User-Role、X-SkinLoom-Locale、X-Request-ID),通过httputil.ReverseProxy透明转发给插件(原生支持 WebSocket Upgrade、SSE 与大文件流)。
- 当插件启用
2.6 官方插件市场(模式 A)与多维环境筛选规范
1. index.v1.json 扩展规范(支持双轨 + 三平台分包 + 环境依赖筛选)
{
"schemaVersion": 1,
"generatedAt": "2026-11-19T12:00:00Z",
"registryId": "official",
"mirrors": [
"https://registry.skinloom.cn",
"https://raw.githubusercontent.com/Entropy-Increase-Team/skinloom-registry/dist"
],
"packages": [
{
"id": "bs-importer",
"kind": "plugin",
"runtime": "native",
"category": "migration",
"official": true,
"name": { "zh-CN": "Blessing Skin 迁移助手", "en": "Blessing Skin Importer" },
"description": { "zh-CN": "直连数据库或桥接导入 BS 扩展插件数据", "en": "Import BS plugin extension tables via direct DB or bridge" },
"authors": ["Entropy-Increase-Team"],
"license": "MIT",
"repository": "https://github.com/Entropy-Increase-Team/skinloom",
"latest": "1.0.0",
"versions": [
{
"version": "1.0.0",
"apiVersion": 1,
"nativeProtocolVersion": 1,
"engines": { "skinloom": ">=1.0.0 <2.0.0", "go": ">=1.26" },
"permissions": ["storage.sql", "http.stream", "users.read", "textures.write"],
"dependencies": {},
"optionalDependencies": { "invitation-codes": "^1.0.0", "mojang-verification": "^1.0.0" },
"publishedAt": "2026-11-19T12:00:00Z",
"yanked": false,
"artifacts": {
"linux/amd64": { "urls": ["..."], "sha256": "...", "size": 4520100, "signature": "..." },
"linux/arm64": { "urls": ["..."], "sha256": "...", "size": 4310200, "signature": "..." },
"windows/amd64": { "urls": ["..."], "sha256": "...", "size": 4680900, "signature": "..." },
"darwin/arm64": { "urls": ["..."], "sha256": "...", "size": 4410500, "signature": "..." },
"darwin/amd64": { "urls": ["..."], "sha256": "...", "size": 4550300, "signature": "..." }
}
}
]
}
],
"blocked": []
}
注:对于
runtime: "js"与纯静态主题,artifacts仅需一个"any"键即可全平台通用;对于runtime: "native",推荐开发者配置官方提供的 GitHub Action 矩阵,自动构建并产出三平台(Linuxamd64/arm64、Windowsamd64、macOSarm64/amd64)分包。
2. 多维环境与依赖兼容性筛选引擎(internal/plugin/compat.go)
宿主拉取 index.v1.json 后,自动基于本机运行环境进行五维校验并计算每个插件的推荐可安装版本:
- 平台匹配:
runtime == "js"匹配"any";runtime == "native"精确匹配runtime.GOOS + "/" + runtime.GOARCH(若该版本无本机平台构建产物,标记incompatible_platform并在市场默认折叠/灰显)。 - SkinLoom 版本匹配:解析 SemVer 范围(
engines.skinloom)对比buildinfo.Version。 - API 与协议版本匹配:校验
apiVersion == 1且nativeProtocolVersion == 1。 - Go 基线版本检查:展示/校验
engines.go与当前宿主编译的 Go 版本(runtime.Version())。 - 依赖树解析:检查
dependencies是否已安装或在当前市场可一键级联安装,检测版本冲突与循环依赖。
3. 官方市场供应链安全流程(skinloom-registry)
- 提交:开发者向
skinloom-registry提 PR,提交manifests/<id>.yaml(含开源 Git 仓库 URL、Tag/Commit SHA、权限说明、构建入口)。 - 分级审核:
runtime: "js"且非首次上架、未新增敏感/高危权限 → CI 自动验证构建、跑skinloom-plugin lint& 恶意规则扫描,全绿自动合并。- 首次上架、新增敏感/高危权限、或所有
runtime: "native"原生插件 → 强制人工源码 Review + CodeQL +govulncheck扫描。
- 官方受控编译与签名:PR 合并后,官方 GitHub Actions Runner 拉取固定 Commit SHA,使用
CGO_ENABLED=0交叉编译三平台分包(linux/amd64,linux/arm64,windows/amd64,darwin/arm64,darwin/amd64),使用存放在受保护 GitHub Environment Secrets 中的官方 Ed25519 私钥对每个.slp包及总索引index.v1.json签名,并自动同步至 Cloudflare R2 主源与国内 CDN 镜像。
三、 完整开发任务清单(Checklist,便于检查与调整)
执行顺序声明:必须严格按 第一部分(基建:Phase A → B → C → D) 全部完成后,再进入 第二部分(官方插件与收官:Phase E → F → G)。
第一部分:核心基建工作(Infrastructure First —— 必先全部完成)
阶段 A(P2-5A):双轨驱动抽象、双向 gRPC 协议、原生进程引擎与隔离 DB 基建
- A1. 扩展数据库 Schema 与三方言迁移
- 修改 ent/schema/plugin.go:新增字段
runtime(enum: "js", "native", default"js")、platform_packages(JSON: map[string]string,记录多架构集群下linux/amd64 -> sha256映射)、registry_source(string, 记录安装来源市场 URL 以便多架构节点回源拉取)。 - 运行
go generate ./ent,补齐migrations/{sqlite,mysql,postgres}/三方言增量迁移并跑通go run ./internal/tools/migdiff。
- 修改 ent/schema/plugin.go:新增字段
- A2. 扩展
Manifest、权限表与兼容性校验引擎- 修改 internal/plugin/manifest.go:新增
Runtime、Engines.Go、NativeSpec字段及严格校验。 - 修改 internal/plugin/permissions.go:新增
storage.sql、http.stream、provider.storage、provider.search、provider.render、native.exec权限定义与分级。 - 新增
internal/plugin/compat.go+compat_test.go:实现 SemVer 范围解析器与 5 维环境兼容性筛选(OS/Arch、SkinLoom 版本、API 版本、Native 协议版本、Go 版本、依赖检查)。
- 修改 internal/plugin/manifest.go:新增
- A3. 定义并生成双向 gRPC 协议(
api/proto/plugin/v1/)- 编写
plugin.proto(PluginService、HostService、StorageProviderService、SearchProviderService、RenderProviderService)。 - 生成 Go gRPC 桩代码并纳入
go generate校验(通过纯 Gointernal/tools/protogen)。
- 编写
- A4. 重构
internal/plugin后端执行层为统一PluginDriver接口- 将现有 internal/plugin/runtime.go 中与
jsrt耦合的调用抽离为internal/plugin/driver.go(Driver接口:Init,Lifecycle,InvokeGuard,InvokeFilter,InvokeEvent,InvokeHTTP,InvokeCron,InvokeService,NotifySettings,ProxyHandler,Stats,DrainAndClose)与internal/plugin/driver_jsrt.go(因 Go 工具链将*_js.go固定视为GOOS=js构建约束,故命名为driver_jsrt.go;保留现有全部 JS/TS 测试 100% 绿色)。
- 将现有 internal/plugin/runtime.go 中与
- A5. 实现
internal/plugin/driver_native.go(hashicorp/go-plugin原生进程引擎)- 引入
github.com/hashicorp/go-plugin与google.golang.org/grpc。 - 实现子进程生命周期管理:自动识别平台二进制并设置 Unix
0755可执行权限;启动握手、stdout/stderr 归集至插件slog日志缓冲;GRPCBroker反向注册HostService(复用现有host_*.go业务能力与权限检查)。 - 实现异常崩溃监管(指数退避自动重启 + 接入
CircuitBreaker连续崩溃熔断)与热升级平滑排空(先启新版握手 → 原子切换 → 旧进程排空 ≤ 30s 后Kill)。 - 实现本地流式 HTTP/WebSocket 反代数据面(Unix Socket /
127.0.0.1+ 一次性X-SkinLoom-Proxy-Token鉴权头 + 剥离原始 Cookie 注入可信用户头)。
- 引入
- A6. 实现双层隔离数据库分配器(
internal/plugin/db_allocator.go)- 实现
SafeSQLPrefix(pluginID)(严格正则生成plg_<safe_id>_)。 - 支持三种数据库模式:
- SQLite:自动初始化
<DataDir>/plugins-data/<id>/plugin.db(WAL 模式),并在internal/backup/备份恢复流程中自动包含plugins-data/; - MySQL / MariaDB:支持
[plugins.database]独立配置或复用主库 + 专属前缀plg_<safe_id>_; - PostgreSQL:支持
[plugins.database]独立配置或复用主库 + 专属前缀plg_<safe_id>_(可选 Schema)。
- SQLite:自动初始化
- 实现卸载
--purge时三方言精准清理本插件专属表/独立库文件(附带三方言集成测试)。
- 实现
- A7. 接入原生底层基础设施扩展点
- 在
internal/platform/storage/internal/modules/texture/internal/modules/render中预留可原子热替换的StorageProvider、SearchProvider、RenderProvider钩子,供拥有对应高危/敏感权限的native插件注册与卸任回收。
- 在
阶段 B(P2-5B):Go 插件 SDK、多平台打包签名工具链与管理后台升级
- B1. 实现官方 Go 插件 SDK(
sdk/go)- 独立模块或子包
sdk/go(对外导入路径github.com/Entropy-Increase-Team/skinloom/sdk/go):plugin.Serve(p Plugin)一行启动go-plugingRPC 服务端 + 可选本地 HTTP/WS 服务;- 强类型
Context(映射全部 Hook、Users/Players/Textures/Score/Notify/Mail/KV/Docs/Files/Settings/ServicesgRPC 客户端); sdk/go/plugindb:封装三方言隔离 SQL 连接池、Table(name)自动加前缀、内置goose迁移辅助;sdk/go/plugintest:提供内存模拟宿主(MockHostService+ 内存 SQLite),支持标准go test直接单测原生插件。
- 独立模块或子包
- B2. 升级
.slp解包器、签名策略与多架构集群同步- 修改 internal/plugin/package.go:
- 放宽
runtime == "native"归档大小上限(单平台 50 MiB / 胖包 150 MiB),校验二进制路径安全与当前GOOS/GOARCH可执行文件存在性; - 强化原生二进制安全策略:生产环境未带官方签名(或超管自定义受信任公钥)的
native包默认硬拒绝,返回明确错误码与提示; - 更新 internal/modules/texture/upkeep.go 孤儿清扫逻辑,兼容保护
plugins.platform_packages中所有架构的 SHA-256 归档对象。
- 放宽
- 修改 internal/plugin/packages_mgr.go:
SyncCluster按本机GOOS/GOARCH选取对应架构的包(本地对象存储缺失本架构包且来源为市场时,自动按registry_source拉取本机平台包并验签)。
- 修改 internal/plugin/package.go:
- B3. 升级 CLI、脚手架与单源生成器
- 更新
internal/tools/plugingen:同步生成包含runtime、native、engines.go、新权限的plugin.v1.json与 TS 类型,通过plugingen -check。 - 扩展
web/packages/cli(skinloom-plugin):- 支持
skinloom-plugin build --native --targets linux/amd64,linux/arm64,windows/amd64,darwin/arm64,darwin/amd64(自动调用go buildCGO_ENABLED=0交叉编译,并同时打包前端web/index.js); - 支持
skinloom-plugin pack --split-platforms(按推荐策略输出三平台分包.slp+artifacts.json清单,也支持--fat离线胖包); - 支持
skinloom-plugin dev监听.go与.tsx变更,自动重编子进程并通过dev-reload热替换。
- 支持
- 扩展
web/packages/create-plugin:新增native-go(Go 后端 + React 前端 + 隔离 SQL 迁移)模板。
- 更新
- B4. 升级管理后台「插件管理」UI
- 修改
web/apps/web/src/components/admin/plugins-*.tsx与 API 契约:- 列表与安装预检框清晰展示双轨标识:「轻量沙箱 (JS)」 vs 「系统原生 (Go)」,标注适用平台与官方源码编译认证徽章;
- 详情抽屉针对
native插件展示:子进程 PID、存活时间、重启次数、内存/RSS 占用、隔离数据库模式与表前缀、本地反代状态; - 高危确认框:针对
native插件明确提示「原生子进程权限」,未带官方签名时在生产模式禁用安装按钮并给出原因说明。
- 修改
阶段 C(P2-5C):官方 GitOps 静态签名插件市场(模式 A)完整落地
- C1. 实现宿主多源 Registry 客户端(
internal/plugin/registry_client.go)- 新增站点设置
plugin.registries(支持多个源:官方主源/国内镜像默认预置,支持超管增删自定义源、配置自定义源公钥与启用开关)。 - 实现
FetchIndex(ctx):- 并行/故障转移拉取
index.v1.json与index.v1.json.sig(优先国内镜像,超时/失败自动切换 GitHub 源); - 对官方源强制使用内置
OfficialPublicKeyPEM验签,防中间人篡改索引或伪造阻断名单; - 内存 + 本地文件短缓存(默认 15 分钟),支持管理员手动强制刷新。
- 并行/故障转移拉取
- 集成
compat.go环境筛选:返回每个市场插件的compatibility状态、适配当前GOOS/GOARCH的推荐下载 artifact、本地是否已安装及是否有可升级版本。 - 实现
blocked恶意阻断定时巡检任务(每 6 小时 + 刷新市场时触发):命中官方签名索引blocked名单的已启用插件,立即热禁用、写审计日志并向所有超级管理员发站内通知。 - 实现一键从市场下载安装/升级(
InstallFromMarket):按 artifact 的urls故障转移下载对应本机平台的.slp→ 校验sha256与signature→ 复用InspectPackage/InstallPackage走完整三级权限确认与热加载流程。
- 新增站点设置
- C2. 新增市场管理 REST API 与 CLI
GET /api/v1/admin/market/packages(支持按q、kind、runtime、category、compatibleOnly筛选,返回宿主环境摘要hostEnv与筛选后包列表)。POST /api/v1/admin/market/refresh(强制刷新市场索引并执行阻断检查)。POST /api/v1/admin/market/inspect(按{ registryId, id, version }拉取本机平台包并返回预检与权限 diff)。POST /api/v1/admin/market/install(超管确认权限后完成一键安装/升级,支持自动级联提示依赖插件)。- CLI 扩展:
skinloom plugin search <query>、skinloom plugin market-install <id>[@version]、skinloom plugin upgrade <id|--all>。
- C3. 实现后台「插件与主题市场」UI
- 在
/admin/plugins增加「插件市场」Tab,并在/admin/appearance主题页增加「浏览主题市场」入口。 - 页面功能:
- 顶部展示当前服务器环境胶囊(如
linux/arm64 · SkinLoom 1.x · Go 1.26)与「仅显示兼容插件」默认勾选开关; - 分类筛选(全部 / 官方推荐 / 轻量沙箱 / 系统原生 / 主题 / 登录安全 / 运营积分 / 迁移工具)+ 关键字搜索;
- 卡片展示双轨标签(JS 沙箱 / Go 原生)、官方认证徽章、支持平台图标(Linux / Windows / macOS)、兼容状态提示、一键安装/升级按钮(复用权限确认弹窗)与版本更新日志抽屉。
- 顶部展示当前服务器环境胶囊(如
- 在
- C4. 产出官方市场独立仓库(
Entropy-Increase-Team/skinloom-registry)- 已独立初始化并推送至
Entropy-Increase-Team/skinloom-registry(主仓库不再保留冗余副本):manifests/示例结构与 JSON Schema 校验脚本;.github/workflows/pr-check.yml(PR 阶段:校验清单、对 JS 插件跑lint/打包测试、对 Native Go 插件跑go vet/govulncheck/CodeQL 并强制打上needs-security-review标签);.github/workflows/publish.yml(合并后:按固定 Commit SHA 在隔离 Runner 中自动交叉编译三平台分包 → 生成checksums.txt→ 官方 Ed25519 私钥签名 → 生成并签名index.v1.json→ 同步 R2 主源与国内镜像)。
- 已独立初始化并推送至
阶段 D(基建总验收门禁 —— 全部通过后方可开工官方插件!)
- D1. 代码质量、静态分析与安全扫描
gofmt -l $(git ls-files '*.go')go vet ./...go run honnef.co/go/tools/cmd/staticcheck@latest ./...go run golang.org/x/vuln/cmd/govulncheck@latest ./...
- D2. 三方言迁移与双层数据隔离回归
go run ./internal/tools/migdiffgo test -race ./internal/hook/... ./internal/jsrt/... ./internal/plugin/... ./internal/httpapi/... ./sdk/go/...
- D3. 单源契约无漂移校验
go generate ./api && git diff --exit-code -- api/go run ./internal/tools/plugingen -checkcd web && bun run gen:api && git diff --exit-code -- packages/api-client/src/gen
- D4. 前端与工具链构建测试
cd web && bun run check:styles && bun run typecheck && bun run test && bun run build
- D5. 基建端到端冒烟场景(必须全部实测通过)
- 搭建本地静态测试 Registry,同时托管 1 个最小 JS 插件、1 个最小 Native Go 插件(含三平台分包 + 隔离 SQL 建表 + 本地 HTTP/WS 反代)、1 个 Level ⑤ 主题;
- 验证宿主自动按
GOOS/GOARCH过滤并拉取正确平台包、拒绝未签名的native包、确认权限后不重启热安装并生效; - 模拟杀死
native插件子进程,验证主站无感存活且子进程自动拉起恢复服务; - 模拟
index.v1.json加入blocked阻断条目,验证宿主巡检后自动禁用并通知超管; - 补写架构决策记录:ADR 0049(双轨插件架构、双向 gRPC 与隔离关系数据库) 与 ADR 0050(GitOps 静态签名插件市场与三平台官方编译分发)。
第二部分:第一批官方插件落地与 API 1.0 冻结(基建验收后开工)
第二部分架构定稿约束(2026-11-19 确认):
- 官方插件独立单仓(
Entropy-Increase-Team/skinloom-plugins):所有官方插件与官方市场主题均统一维护在独立仓库Entropy-Increase-Team/skinloom-plugins(本地并行目录../skinloom-plugins),不再放入skinloom主仓库;主仓库只保留核心服务、前端、内置默认/织锦主题以及官方 SDK/CLI 工具链(sdk/go、@skinloom/plugin-sdk、@skinloom/cli、create-skinloom-plugin)。三仓职责彻底解耦:skinloom(宿主与 SDK)·skinloom-plugins(官方插件与主题源码)·skinloom-registry(GitOps 静态签名索引与受控编译分发)。- Blessing Skin 迁移采用方案 A(两层职责分离):
- 核心数据迁移保留在主程序系统代码(
internal/importer/bs/):继续承接 Pre-Core 首次安装向导(/setup)与离线 CLI(skinloom import bs/compare),保障原始主键 ID 保留、旧算法密码哈希迁移、Yggdrasil RSA 私钥导入与整库原子--dry-run,且进入正常 Core 模式后零路由、零任务、零内存开销,绝不向插件HostService开放高危核心表后门。- BS 第三方插件生态数据迁移做成可卸载 Tier 2 原生插件(
skinloom-plugins/bs-importer):站长完成核心迁移并按需从市场安装invitation-codes、mojang-verification等官方插件后,再安装bs-importer补导旧 BS 第三方插件表数据;迁移完成后可直接在后台禁用或remove --purge彻底卸载,不残留任何后台菜单与隔离表。
阶段 E(P2-6A):初始化 skinloom-plugins 独立仓库、轻量级 TS 沙箱官方插件与 Level ⑤ 示例主题
- E0. 初始化官方插件仓库(
Entropy-Increase-Team/skinloom-plugins)- 已在独立并行目录
../skinloom-plugins建立多插件工作区(根目录README.md/README.en.md、LICENSE、package.json、tsconfig.base.json、vitest.config.mjs、scripts/run-all.mjs及.github/workflows/ci.yml),零冗余依赖复用主仓库工具链与 Go SDK。
- 已在独立并行目录
- E1. 官方插件 ①:
skinloom-plugins/invitation-codes(Tier 1 · TS 沙箱)- 清单声明
forms["auth.register"]附加invite_code字段;storage.collections.codes(code: string:unique,status: string,creatorId: number,usedBy: number,createdAt: time,expiresAt: time)。 - 后端:
auth.registerGuard 校验邀请码有效性;user.registeredEvent 消费计数并触发邀请人与新用户积分奖励;支持管理员批量生成/撤销/删除/防公式注入 CSV 导出、玩家积分兑换邀请码;暴露importCodes服务;附完整createTestHost单测并实测lint/typecheck/test/pack(9.1 KB.slp)通过。
- 清单声明
- E2. 官方插件 ②:
skinloom-plugins/mojang-verification&skinloom-plugins/texture-description(Tier 1 · TS 沙箱)mojang-verification:实现 Microsoft OAuth → XBL → XSTS → Minecraft Services 正版档案校验、同名角色冲突回收退分 + 站内信/邮件通知、改名同步、user.badgesFilter 颁发「正版认证」徽章、user.dashboard.widgets/user.profile.sections插槽卡片与importVerifications服务,附完整fetchMock端到端单测并打包验证(7.2 KB.slp)。texture-description(同步补齐第 3 张 BS 扩展表闭环):声明forms["texture.upload"]、texture.uploadGuard /texture.uploaded/texture.deletedEvent、skinlib.detail.below插槽展示与作者/管理员在线编辑、私有权限隔离与importDescriptions服务,附单测并打包验证(4.5 KB.slp)。
- E3. 官方 Level ⑤ 示例主题:
skinloom-plugins/theme-atelier(kind: "theme")- 展示 L1 亮暗
oklchToken + L2 分栏/标签布局与首页 + L3theme.settings+ L4 无 Layertheme.css+ L5overrides(覆盖site.footer与texture.card),lint/typecheck/test/pack(4.1 KB.slp)全部通过。
- 展示 L1 亮暗
阶段 F(P2-6B):系统级原生 Go 官方插件 skinloom-plugins/bs-importer 与官方市场闭环实战
- F1. 官方插件 ③:
skinloom-plugins/bs-importer(Tier 2 · 原生 Go 系统级插件,按需安装、迁完即卸)- 遵循方案 A:仅承接核心迁移完成后的 BS 第三方插件生态数据补迁(
invitation_codes、mojang_verifications、textures_description),支持 Go 原生直连 MySQL / PostgreSQL / SQLite(严格正则表前缀防注入)以及 HTTP 对接blessing-skin-export-bridge(已同步升级blessing-skin-export-bridge/src/Controllers/BridgeController.php开放三张扩展表分页读取)。 - 使用
sdk/go/plugindb隔离 SQL 库(三方言迁移migrations/{sqlite,mysql,postgres}/001_init.sql)持久化任务历史与报告,通过ctx.HTTP.StreamFunc提供实时 SSE 进度流,经由跨插件ctx.Services.Call幂等写入三大目标插件。 - 前端 UI(
admin:/bs-importer)展示方案 A 卸载指引、数据源切换测试、Dry-Run 预览、分表勾选、SSE 实时日志与历史任务表;通过plugintest双模式(SQLite 直连 + HTTP Bridge + SSE)单测,并实测skinloom-plugin pack --native --split-platforms交叉编译生成linux/amd64、windows/amd64、darwin/arm64分包(约 8.2–8.7 MiB)与artifacts.json。 - 已同步更新主仓库 internal/importer/bs/plugins.go 与 internal/importer/bs/tables.go 迁移报告提示文案并通过全部
internal/importer/bs回归测试。
- 遵循方案 A:仅承接核心迁移完成后的 BS 第三方插件生态数据补迁(
- F2. 官方市场 GitOps 实战上架与云端 Runner 闭环验证(已完成)
- 已推送至 GitHub
Entropy-Increase-Team/skinloom-plugins(ec43098),并在主仓库切换正式生产 Ed25519 公钥(v1.1.0-rc.5/v1.1.0); - 已在
Entropy-Increase-Team/skinloom-registry配置production-signingEnvironment 与正式SKINLOOM_REGISTRY_PRIVATE_KEYSecret; - 已通过 PR #1(
bacb091)完成 5 个官方扩展1.0.0上架,云端publish.yml已完成 5 平台交叉编译并签发origin/dist分支的index.v1.json与.sig。
- 已推送至 GitHub
阶段 G(P2-6C):文档站定稿与插件 API v1 冻结
- G1. 文档站「插件与主题开发」栏目补齐(
website/docs/plugins/)- 新增 quickstart-ts.md(15 分钟写一个 TS 轻量级插件);
- 新增 native-go.md(开发 Go 系统级原生插件:
sdk/go、双向 gRPC、隔离 SQL、流式 SSE、五平台打包); - 新增 reference.md(API v1.0 参考手册:29 项权限分级、47 个 Hook、20 个插槽、5 处表单、7 个主题覆盖目标与
.slp市场规范); - 完善 overview.md、themes.md 与 website/sidebars.ts。
- G2. CI 验收与 API v1.0 冻结
cd website && bun run build零死链构建通过;- 更新 CHANGELOG.md 并发布里程碑开发日志 2026-11-19-dual-tier-plugins-and-market.md;
- 正式冻结
apiVersion: 1与native.protocolVersion: 1。