Go SDK

七牛云沙箱服务提供官方 Go SDK（github.com/qiniu/go-sdk/v7/sandbox），用于管理安全隔离的云端沙箱环境。

安装

go get github.com/qiniu/go-sdk/v7

要求 Go 1.22 或更高版本。

认证配置

SDK 使用 API Key 进行身份认证，通过 X-API-Key HTTP 请求头传递。从七牛云 API 密钥管理获取你的 API Key。

推荐通过环境变量配置：

export QINIU_API_KEY="your-api-key"
export QINIU_SANDBOX_API_URL="https://cn-yangzhou-1-sandbox.qiniuapi.com"  # 可选，有默认值

初始化客户端

package main

import (
	"log"
	"os"

	"github.com/qiniu/go-sdk/v7/sandbox"
)

func main() {
	c, err := sandbox.NewClient(&sandbox.Config{
		APIKey:   os.Getenv("QINIU_API_KEY"),
		Endpoint: os.Getenv("QINIU_SANDBOX_API_URL"), // 可选，默认值: https://cn-yangzhou-1-sandbox.qiniuapi.com
	})
	if err != nil {
		log.Fatalf("创建客户端失败: %v", err)
	}
	_ = c
}

配置参数

当前支持的区域：cn-yangzhou-1

快速开始

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/qiniu/go-sdk/v7/sandbox"
)

func main() {
	// 1. 初始化客户端
	c, err := sandbox.NewClient(&sandbox.Config{
		APIKey:   os.Getenv("QINIU_API_KEY"),
		Endpoint: os.Getenv("QINIU_SANDBOX_API_URL"),
	})
	if err != nil {
		log.Fatalf("创建客户端失败: %v", err)
	}

	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
	defer cancel()

	// 2. 创建沙箱并等待就绪
	timeout := int32(120)
	sb, info, err := c.CreateAndWait(ctx, sandbox.CreateParams{
		TemplateID: "base",
		Timeout:    &timeout,
	}, sandbox.WithPollInterval(2*time.Second))
	if err != nil {
		log.Fatalf("创建沙箱失败: %v", err)
	}
	defer sb.Kill(ctx)

	fmt.Printf("沙箱已就绪: %s (CPU: %d, 内存: %d MB)\n", sb.ID(), info.CPUCount, info.MemoryMB)

	// 3. 执行命令
	result, err := sb.Commands().Run(ctx, "echo hello world")
	if err != nil {
		log.Fatalf("执行命令失败: %v", err)
	}
	fmt.Printf("命令输出: %s", result.Stdout)

	// 4. 文件操作
	sb.Files().Write(ctx, "/tmp/test.txt", []byte("Hello from Go SDK!"))
	content, _ := sb.Files().Read(ctx, "/tmp/test.txt")
	fmt.Printf("文件内容: %s\n", string(content))

	// 5. 列出目录
	entries, _ := sb.Files().List(ctx, "/tmp")
	fmt.Printf("/tmp 目录: %d 个文件\n", len(entries))

	fmt.Println("完成！")
}

功能文档

轮询选项

CreateAndWait、WaitForReady 和 WaitForBuild 支持自定义轮询行为：

sb, info, err := c.CreateAndWait(ctx, params,
	sandbox.WithPollInterval(2*time.Second),
	sandbox.WithBackoff(1.5, 10*time.Second),
	sandbox.WithOnPoll(func(attempt int) {
		fmt.Printf("轮询第 %d 次...\n", attempt)
	}),
)

更多资源

• API 文档：pkg.go.dev/github.com/qiniu/go-sdk/v7/sandbox
• 示例代码：examples