插件沙箱

EmDash 支持以两种执行模式运行插件：trusted 与 sandboxed。本文说明各模式如何工作、提供哪些保护，以及不同部署目标下的安全含义。

执行模式

Trusted 模式

Trusted 插件与 Astro 站点在同一进程中运行，从 npm 包或本地文件加载，并在 astro.config.mjs 中配置：

import myPlugin from "@emdash-cms/plugin-analytics";

export default defineConfig({
	integrations: [
		emdash({
			plugins: [myPlugin()],
		}),
	],
});

在 Trusted 模式下：

• Capabilities 是文档而非强制策略。 声明了 ["read:content"] 的插件仍可能访问进程内任意资源。capabilities 字段向管理员说明插件 打算 使用什么。
• 无资源上限。 CPU、内存与网络使用不受限，异常插件可能拖住整个请求。
• 完整进程访问。 插件与 Astro 站点共享 Node.js/Workers 运行时，可导入任意模块、读取环境变量，并在 Node.js 上读写文件系统。

Sandboxed 模式（Cloudflare Workers）

Sandboxed 插件在 Cloudflare Dynamic Worker Loader API 提供的隔离 V8 isolate 中运行；每个插件拥有带强制限制的独立 isolate。

要启用沙箱，请在 Astro 配置中设置 sandbox runner：

export default defineConfig({
	integrations: [
		emdash({
			sandboxRunner: "@emdash-cms/cloudflare/sandbox",
			sandboxed: [
				{
					manifest: seoPluginManifest,
					code: seoPluginCode,
				},
			],
		}),
	],
});

沙箱强制内容

架构

Sandboxed 插件通过 RPC 桥与 EmDash 通信：

┌─────────────────────┐     RPC      ┌──────────────────────┐
│  Plugin Isolate     │ ◄──────────► │  PluginBridge        │
│  (Worker Loader)    │   (binding)  │  (WorkerEntrypoint)  │
│                     │              │                      │
│  ctx.kv.get(k)      │──────────────│► kvGet(k)            │
│  ctx.content.list() │──────────────│► contentList()       │
│  ctx.http.fetch(u)  │──────────────│► httpFetch(u)        │
└─────────────────────┘              └──────────────────────┘
                                            │
                                            ▼
                                     ┌──────────────┐
                                     │  D1 / R2     │
                                     └──────────────┘

插件代码在 V8 isolate 中运行，收到的 ctx 上每个方法都是指向桥接的代理。桥接运行在主 EmDash worker 中，在验证 capabilities 后执行实际的数据库/存储操作。

Wrangler 配置

沙箱需要 Dynamic Worker Loader。在 wrangler.jsonc 中加入：

{
	"worker_loaders": [{ "binding": "LOADER" }],
	"r2_buckets": [{ "binding": "MEDIA", "bucket_name": "emdash-media" }],
	"d1_databases": [{ "binding": "DB", "database_name": "emdash" }]
}

Node.js 部署

部署到 Node.js（或任何非 Cloudflare 平台）时：

• 使用 NoopSandboxRunner，返回 isAvailable() === false。
• 尝试加载 Sandboxed 插件会抛出 SandboxNotAvailableError。
• 所有插件必须在 plugins 数组中注册为 Trusted。
• Capability 声明仅供参考，不会被强制。

对安全意味着什么

Node.js 部署建议

1. 只从可信来源安装插件。 安装前审查源码，优先选择知名维护者的插件。
2. 把 capability 当作审查清单。 即使不强制，也能记录预期范围。不需要网络却声明 ["network:fetch"] 很可疑。
3. 监控资源使用。 使用进程级监控（例如 --max-old-space-size、健康检查）发现失控插件。
4. 若需运行不可信插件，考虑 Cloudflare。 若插件来源不明（如市场），请部署到提供沙箱的 Cloudflare Workers。

相同 API，不同保证

无论执行模式如何，插件代码相同。definePlugin() API、ctx 形态、hooks、routes、storage 用法一致；变化的是 是否强制：

// This plugin works in both trusted and sandboxed mode
export default definePlugin({
	id: "analytics",
	version: "1.0.0",
	capabilities: ["read:content", "network:fetch"],
	allowedHosts: ["api.analytics.example.com"],
	hooks: {
		"content:afterSave": async (event, ctx) => {
			// In trusted mode: ctx.http is always present (capabilities not enforced)
			// In sandboxed mode: ctx.http is present because "network:fetch" is declared
			await ctx.http.fetch("https://api.analytics.example.com/track", {
				method: "POST",
				body: JSON.stringify({ contentId: event.content.id }),
			});
		},
	},
});

目标是让作者在本地以 Trusted 模式快速迭代、便于调试，在生产以 Sandboxed 模式部署而无需改代码。