FastGPT/projects/sandbox_server/QUICKSTART.md

快速开始指南

✅ 项目已完成

所有功能已实现并通过测试。

📁 项目结构

sandbox_server/
├── src/
│   ├── index.ts                 # 应用入口
│   ├── env.ts                   # 环境变量配置
│   ├── schemas/                 # Zod Schema 定义（类型导出）
│   │   ├── common.schema.ts     # 公共 schema
│   │   ├── container.schema.ts  # 容器 schema
│   │   └── sandbox.schema.ts    # 沙盒 schema
│   ├── middleware/              # 中间件
│   │   ├── auth.ts              # Bearer token 鉴权
│   │   └── error.ts             # 统一错误处理
│   ├── clients/                 # 客户端（axios 实例）
│   │   ├── sealos.ts            # Sealos API 客户端
│   │   └── sandbox.ts           # Sandbox 客户端
│   ├── routes/                  # 路由（OpenAPI 定义）
│   │   ├── container.route.ts   # 容器生命周期路由
│   │   └── sandbox.route.ts     # 沙盒操作路由
│   └── sdk/                     # SDK 模块
│       ├── container.ts         # sdk.container.*
│       └── sandbox.ts           # sdk.sandbox.*
├── test/                        # 测试
│   ├── setup.ts                 # 测试配置
│   ├── .env.test.template       # 测试环境变量模板
│   └── app.test.ts              # 基础测试
├── Dockerfile                   # Docker 构建
├── .env.template                # 环境变量模板
└── package.json

🚀 启动步骤

1. 安装依赖

cd FastGPT/projects/sandbox_server
bun install

2. 配置环境变量

复制 .env.template 为 .env.local 并填写配置：

cp .env.template .env.local

编辑 .env.local：

PORT=3000
TOKEN=your-secret-token
SEALOS_BASE_URL=https://your-sealos-api-url.com
SEALOS_KC=your-kubeconfig-token

3. 启动开发服务器

bun run dev

4. 访问 API 文档

• Scalar UI: http://localhost:3000/openapi/ui
• OpenAPI JSON: http://localhost:3000/openapi
• 健康检查: http://localhost:3000/health

📝 API 端点

容器生命周期 (/v1/containers)

方法	路径	描述	鉴权
POST	/v1/containers	创建容器	✅
GET	/v1/containers/:name	获取容器信息	✅
POST	/v1/containers/:name/pause	暂停容器	✅
POST	/v1/containers/:name/start	启动容器	✅
DELETE	/v1/containers/:name	删除容器	✅

沙盒操作 (/v1/sandbox)

方法	路径	描述	鉴权
POST	/v1/sandbox/:name/exec	执行命令	✅
GET	/v1/sandbox/:name/health	健康检查	✅

💡 SDK 使用示例

import { createSDK } from './sdk';

const sdk = createSDK('http://localhost:3000', 'your-token');

// 创建容器
await sdk.container.create({
  name: 'my-sandbox',
  image: 'node:18-alpine',
  resource: { cpu: 1, memory: 1024 }
});

// 获取容器信息
const info = await sdk.container.get('my-sandbox');

// 暂停容器
await sdk.container.pause('my-sandbox');

// 启动容器
await sdk.container.start('my-sandbox');

// 执行命令
const result = await sdk.sandbox.exec('my-sandbox', {
  command: 'ls -la',
  cwd: '/app'
});
console.log(result.stdout);

// 健康检查
const healthy = await sdk.sandbox.health('my-sandbox');

// 删除容器
await sdk.container.delete('my-sandbox');

🧪 测试

单元测试

# 运行所有测试
bun run test

# 运行单次测试
bun run test:run

# 类型检查
bun run typecheck

集成测试

集成测试需要真实的 Sealos 环境。

1. 配置测试环境变量：

cp test/.env.test.template test/.env.test.local
# 编辑 test/.env.test.local，填写真实配置

2. 运行集成测试：

RUN_INTEGRATION_TESTS=true bun run test

详细说明请查看 test/README.md

🐳 Docker 部署

# 构建镜像
docker build -t sandbox-server .

# 运行容器
docker run -p 3000:3000 --env-file .env.local sandbox-server

✨ 特性

• ✅ Bun 运行时: 快速的包管理和执行
• ✅ Hono 框架: 轻量级高性能 HTTP 框架
• ✅ Zod 类型验证: 所有入参出参均使用 zod parse
• ✅ OpenAPI 文档: 自动生成 API 文档（使用 @hono/zod-openapi）
• ✅ Scalar UI: 现代化 API 文档界面
• ✅ 类型安全 SDK: 提供完整的 TypeScript 类型支持
• ✅ Bearer Token 鉴权: 统一的认证中间件
• ✅ 统一错误处理: 避免 API 报错时未响应
• ✅ 工厂模式: 优雅的控制器设计
• ✅ Axios 客户端: 为不同场景定制的 axios 实例
• ✅ Vitest 测试: 单元测试和集成测试支持

📦 核心依赖

• hono - HTTP 框架
• @hono/zod-openapi - OpenAPI 集成
• @scalar/hono-api-reference - API 文档 UI
• @t3-oss/env-core - 环境变量管理
• axios - HTTP 客户端
• zod - Schema 验证
• vitest - 测试框架

🔧 环境变量

变量	必填	描述	默认值
PORT	❌	服务器端口	3000
TOKEN	✅	API 认证 token	-
SEALOS_BASE_URL	✅	Sealos API 地址	-
SEALOS_KC	✅	Sealos Kubeconfig	-

📞 问题排查

1. 依赖安装失败

rm -rf node_modules bun.lockb
bun install

2. 类型错误

bun run typecheck

3. 测试失败

确保测试环境变量已正确设置（见 test/setup.ts）

---

🎉 项目已完成！所有功能均已实现并通过测试。