跳到主要内容

插件沙箱化

不受信任的插件代码在每一层都被隔离：后端在单独的受限进程中运行， 前端在沙箱化的 iframe 中运行，主题则永远不会获得敏感访问权。

没有 JavaScript 沙箱​

node:vm 被刻意不用作安全沙箱。JavaScript 解释器沙箱无法阻止坚定的攻击者 到达宿主进程。相反，隔离由操作系统强制：具有受限能力的独立进程， 以及独立的浏览上下文。

后端隔离​

不受信任的后端插件在其自己的 Node.js 24 进程中运行，并带有限制：

  • 一个受限的加载器只解析包内 ESM 和 SDK API。
  • 该进程无法导入加载器允许范围之外的 node:* 内置模块、解析软件包根目录 之外的模块，或到达宿主数据库。
  • 所有能力都通过一个 IPC 通道到达；宿主在每次调用时强制权限。
  • 该进程只能通过 SDK 事件总线监听核心应用事件，并且只能在自己的命名空间 下发出。
  • 如果进程崩溃，宿主移除它拥有的每个注册。

插件进程永远不会收到 Fastify 根、SQLite 连接、绝对路径、完整环境或其他 提供商的 API 密钥。网络访问通过带权限检查的 fetch 限制到已授予的主机。

前端隔离​

原生前端插件在带 sandbox="allow-scripts" 且不带 allow-same-origin 的沙箱化 iframe 中运行：

  • iframe 对应用文档没有同源访问权。
  • 与宿主的通信通过一个单一的传输 MessagePort 进行，带引导 nonce、 结构化信封、截止时间和取消。
  • 宿主把每个注册的 UI 挂载到 iframe 内的一个隔离根中， 并通过 RPC 通信，因此插件永远不会触碰 React 组件树或内部 DOM。
  • 插件 UI 崩溃只会带走该插件的根和裁剪区域。

每个插件拥有一个全视口沙箱 iframe；宿主批量处理活动挂载的矩形， 并把可见和可交互的 iframe 区域裁剪到它们的并集， 因此插件界面之外的指针事件仍属于应用。

受信任旧版模式​

legacy.frontend 和 legacy.backend 入口是面向现有 SillyTavern 扩展的 单独受信任兼容模式 —— 不是原生沙箱的绕过。使用任一入口都需要 legacy.trusted 权限，界面会以增强警告显示它，用户必须显式确认。 旧版前端代码在主窗口中执行，旧版后端代码获得一个限定在自己 /api/plugins/{pluginId} 命名空间内的 Express 路由器。安全模式完全不 加载旧版入口点。

主题​

主题包受到更多限制：主题无法访问聊天记录、API 密钥或文件系统。主题只是 CSS 和声明式布局 —— 主题 SDK 中没有 JavaScript 入口点。 主题侧的故事请参阅主题 SDK 安全模式。

安全模式​

安全模式（URL 中的 ?safe=1）完全禁用第三方插件和主题。它在插件或主题 代码加载之前被处理：软件包 CSS 和令牌覆盖不会被添加到文档中， 第三方入口点永远不会运行。内置主题和内置插件运行时保留， 因此界面总是可以恢复。离开安全模式会恢复之前保存的活动插件和主题状态。

软件包校验​

每个软件包在任何代码可以运行之前都会被校验：路径遍历、符号链接、原生 二进制和可执行载荷被拒绝；清单字段、入口点和权限被检查；npm 依赖带 完整性检查获取，安装脚本绝不会被执行。从安装到拆除的完整故事， 请参阅生命周期。