沙盒 📦🪄 (案例研究)

Sandbox 是一个开源的基于云的代码编辑环境，具备自定义的 AI 代码补全功能和实时协作能力。

快来看看包含演示视频的 Twitter 帖子 吧！

还有 @jamesmurdza 制作的这篇 指南，教你如何在本地搭建它！

本地运行

注意：.env 文件中的链接不要加尾部斜杠

前端

安装依赖

cd frontend
npm install

在 .env 文件中添加所需的环境变量（示例文件位于 .env.example）。你需要在 Clerk 和 Liveblocks 上注册账号以获取 API 密钥。

然后，在开发模式下运行：

npm run dev

后端

后端由一个主 Express 和 Socket.io 服务器，以及三个 Cloudflare Workers 微服务组成，分别用于 D1 数据库、R2 存储和 Workers AI。D1 数据库还包含一个指向 R2 存储 Worker 的 服务绑定。每个打开的沙盒都会在 E2B 上实例化一个安全的 Linux 沙盒，用于终端和实时预览。

你需要在 E2B 上注册账号以获取 API 密钥。

Socket.io 服务器

安装依赖

cd backend/server
npm install

在 .env 文件中添加所需的环境变量（示例文件位于 .env.example）。

项目文件将存储在 projects/<project-id> 目录下。中间件包含用于连接到服务器的基本授权逻辑。

在开发模式下运行：

npm run dev

该目录已容器化，因此你可以随意将其部署到任何你选择的平台上！由于成本和安全性考虑，我没有将此项目部署为公开访问，但自行部署供个人使用应该没有任何问题。

Cloudflare Workers（数据库、存储、AI）

目录结构：

• /backend/database: D1 数据库
• /backend/storage: R2 存储
• /backend/ai: Workers AI

安装依赖

cd backend/database
npm install

cd ../storage
npm install

cd ../ai
npm install

阅读 文档 以了解更多关于 Workers 的信息。

对于每个目录，在 wrangler.toml 文件中添加所需的环境变量（示例文件位于 wrangler.example.toml）。对于 AI Worker，你可以为 CF_AI_KEY 定义任意值——在其他 .env 文件中设置此值以授权访问。

在开发模式下运行：

npm run dev

使用 Wrangler 部署到 Cloudflare：

npx wrangler deploy

---

贡献

感谢你对贡献的兴趣！在提交你的第一个 Pull Request 之前，请先阅读本节内容。如果你需要任何帮助，欢迎随时联系 @ishaandey_。

请优先处理现有的问题，但如果你有认为有用的特性或 bug 的想法，也欢迎提出新的议题。

结构

frontend/
├── app
├── assets
├── components
└── lib
backend/
├── server
├── database/
│   ├── src
│   └── drizzle
├── storage
└── ai

路径	描述
frontend	前端的 Next.js 应用程序。
backend/server	Express WebSocket 服务器。
backend/database	用于与 D1 数据库（SQLite）交互的 API。
backend/storage	用于与 R2 存储交互的 API。与 /backend/database 服务绑定。
backend/ai	用于向 Workers AI 发送请求的 API 。

开发

分支这个仓库

你可以通过点击页面右上角的“Fork”按钮来分叉这个仓库。

克隆仓库

git clone https://github.com/<your-username>/sandbox.git
cd sandbox

创建新分支

git checkout -b my-new-branch

提交规范

在创建 Pull Request 之前，请确保你使用 Conventional Commits 格式。提交信息应采用以下格式：category(scope 或 module): message，其中类别包括：

• feat / feature: 所有引入全新代码或新功能的更改
• fix: 修复 bug 的更改（理想情况下，如果有相关 issue，应一并引用）
• refactor: 不属于修复或特性的任何代码相关更改
• docs: 更改现有文档或创建新文档（如 README、库的使用说明或 CLI 使用说明）
• chore: 所有不属于上述类别的仓库更改

例如：feat(editor): improve tab switching speed

---

技术栈

前端

• Next.js
• TailwindCSS
• Shadcn UI
• Clerk
• Monaco
• Liveblocks

后端

• Cloudflare Workers
  • D1 数据库
  • R2 存储
  • Workers AI
• Express
• Socket.io
• Drizzle ORM
• E2B

Sandbox 快速上手指南

Sandbox 是一个开源的云端代码编辑环境，支持自定义 AI 代码自动补全和实时协作。本指南将帮助你快速在本地搭建开发环境。

1. 环境准备

在开始之前，请确保你的系统已安装以下工具和服务：

• Node.js & npm: 用于运行前端和后端服务。
• Git: 用于克隆代码仓库。
• Docker (可选): 用于容器化部署后端 Socket.io 服务。
• Wrangler CLI: 用于管理 Cloudflare Workers (需安装: npm install -g wrangler)。

必需的外部服务账号与 API Key： 你需要注册以下服务并获取相应的密钥，填入 .env 或 wrangler.toml 文件中：

• Clerk: 用户认证。
• Liveblocks: 实时协作功能。
• E2B: 用于创建安全的 Linux 沙箱终端和实时预览。
• Cloudflare: 用于 D1 数据库、R2 存储和 Workers AI。

注意：配置 .env 文件中的链接时，请勿在末尾添加斜杠 (/)。

2. 安装步骤

第一步：克隆项目

git clone https://github.com/ishaan1013/sandbox.git
cd sandbox

第二步：配置并启动前端 (Frontend)

1. 进入前端目录并安装依赖：

   cd frontend
   npm install
   

   (国内开发者如遇下载慢，可临时使用镜像源：npm install --registry=https://registry.npmmirror.com)

2. 复制环境变量示例文件并填写密钥：

   cp .env.example .env
   

   在 .env 中填入从 Clerk 和 Liveblocks 获取的 API Key。

3. 启动开发服务器：

   npm run dev
   

第三步：配置并启动后端 (Backend)

后端由 Express/Socket.io 主服务和三个 Cloudflare Workers 微服务组成。

A. 启动 Socket.io 服务器

1. 进入后端服务器目录并安装依赖：

   cd ../backend/server
   npm install
   

2. 配置环境变量：

   cp .env.example .env
   

   在 .env 中填入必要的配置（包括 E2B API Key）。项目文件将存储在 projects/<project-id> 目录下。

3. 启动服务：

   npm run dev
   

   注：该目录已 Docker 化，也可选择构建容器部署。

B. 启动 Cloudflare Workers (数据库、存储、AI)

你需要分别配置并启动三个微服务：database (D1), storage (R2), 和 ai (Workers AI)。

1. 安装各模块依赖：

   cd ../database
   npm install
   
   cd ../storage
   npm install
   
   cd ../ai
   npm install
   

2. 配置 Wrangler： 在每个目录 (database, storage, ai) 下，复制示例配置文件：

   cp wrangler.example.toml wrangler.toml
   

   根据提示在 wrangler.toml 中填入对应的 Cloudflare 凭证。

   • 对于 AI Worker，你可以自定义 CF_AI_KEY 的值，并在其他服务的 .env 文件中设置相同的值以授权访问。

3. 本地运行或部署：

   • 本地开发模式 (在每个目录下分别运行):

     npm run dev
     

   • 部署到 Cloudflare:

     npx wrangler deploy
     

3. 基本使用

完成上述所有服务启动后：

1. 访问应用：在浏览器中打开前端运行的地址（通常为 http://localhost:3000）。
2. 登录/注册：使用 Clerk 提供的界面进行账号注册或登录。
3. 创建沙箱：
   • 点击创建新的 Sandbox 项目。
   • 系统将自动在 E2B 上实例化一个安全的 Linux 环境。
4. 编写代码：
   • 使用集成的 Monaco Editor 编写代码。
   • 体验 AI 自动补全 功能（基于 Workers AI）。
   • 邀请协作者进行 实时协同编辑 (基于 Liveblocks)。
5. 运行与预览：
   • 在内置终端中运行命令。
   • 查看实时的代码运行效果预览。

---

项目技术栈概览：Next.js, TailwindCSS, Cloudflare Workers (D1/R2/AI), Express, Socket.io, E2B.