feat: PromptX 上云架构改造计划

[deepracticexs]

背景

PromptX 需要全面上云，主要目标：

1. 支持云端部署（Cloudflare）
2. 多租户支持
3. 文件系统抽象，适配云存储

讨论结论

1. 认证方案：API Key

选择 API Key 而非 OAuth，原因：

• 实现简单，用户配置方便
• 主要面向开发者用户
• 参考 Context7 的做法

{
  "mcpServers": {
    "promptx": {
      "url": "https://your-server.com/mcp",
      "headers": {
        "X-API-Key": "pk_xxx_your_api_key"
      }
    }
  }
}

2. 部署架构：Cloudflare 全家桶

┌─────────────────────────────────────────────────────────────┐
│  Cloudflare Workers          Cloudflare Containers          │
│  ─────────────────          ─────────────────────           │
│  • MCP Server 入口           • ToolX 执行沙箱                │
│  • API Key 认证              • npm/bun 包安装                │
│  • 路由分发                  • 复杂工具运行                   │
│  • 简单工具执行                                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Cloudflare D1    Cloudflare KV    Cloudflare R2            │
│  ────────────    ─────────────    ─────────────             │
│  • Memory        • ToolStorage    • 资源文件                 │
│  • 记忆存储       • Network        • 用户上传                 │
│                  • Anchor                                    │
└─────────────────────────────────────────────────────────────┘

3. 文件系统改造映射

当前实现	Cloudflare 替代	改造工作量
better-sqlite3 (Memory.js)	D1	中
fs.writeFile JSON (ToolStorage, Network, Anchor)	KV	小
fs.readFile 资源文件 (各 Protocol)	R2	中
fs.readdir 目录扫描 (Discovery)	R2 + 元数据索引	大
npm install (PackageInstaller)	移至 Containers	-

4. ToolX 独立项目

决定将 ToolX 拆分为独立项目，理由：

• 关注点分离，工具执行是独立领域
• 独立部署到 Cloudflare Containers
• 可被其他项目复用
• 使用 Bun 开发，更快更现代

项目结构

@aspect/toolx/
├── src/
│   ├── sandbox/           # 沙箱隔离
│   │   ├── Sandbox.ts
│   │   ├── IsolationManager.ts
│   │   └── SecurityPolicy.ts
│   ├── runtime/           # 运行时
│   │   ├── PackageManager.ts   # bun install
│   │   ├── ModuleLoader.ts
│   │   └── DirectoryManager.ts
│   ├── api/               # 注入到沙箱的 API
│   │   ├── Storage.ts
│   │   ├── Logger.ts
│   │   └── Bridge.ts
│   └── server/            # HTTP 服务
│       ├── HttpServer.ts
│       └── routes/
├── Dockerfile
├── package.json
└── tsconfig.json

核心 API

// POST /execute
interface ExecuteRequest {
  toolId: string;
  toolCode?: string;
  params: Record<string, any>;
  context?: {
    tenantId?: string;
    timeout?: number;
    permissions?: string[];
  };
}

5. PackageInstaller 改造

从 @npmcli/arborist 迁移到 bun install

优势：

• 安装速度提升 10-20x（~10s → ~1s）
• 代码量减少（~100行 → ~20行）
• 零额外依赖（Bun 内置）

// 新的实现
const proc = Bun.spawn({
  cmd: ['bun', 'install', '--no-save'],
  cwd: workingDir,
  env: { BUN_CONFIG_REGISTRY: registry },
});
await proc.exited;

任务拆分

• Phase 1: ToolX 独立项目

  • 初始化 Bun 项目
  • 迁移沙箱核心逻辑
  • 实现 HTTP API
  • PackageManager 使用 bun install
  • Dockerfile 编写

• Phase 2: 存储层抽象

  • 设计存储抽象接口
  • 实现 Cloudflare KV 适配器
  • 实现 Cloudflare D1 适配器
  • 实现 Cloudflare R2 适配器

• Phase 3: MCP Server 云化

  • 适配 Cloudflare Workers
  • 实现 API Key 认证中间件
  • 集成 ToolX 远程调用

• Phase 4: 多租户支持

  • 设计租户隔离策略
  • 数据隔离实现
  • API Key 与租户绑定

参考资料

• Cloudflare Containers 文档
• Cloudflare D1 文档
• MCP Auth 规范
• Context7 API Key 实现