最近更新时间: 2026-09-11 17:43:42

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
}

配置参数

参数	类型	必填	说明
`APIKey`	`string`	是	API 密钥，用于身份认证
`Endpoint`	`string`	否	服务地址，默认 `https://cn-yangzhou-1-sandbox.qiniuapi.com`
`HTTPClient`	`*http.Client`	否	自定义 HTTP 客户端，默认 `http.DefaultClient`

当前支持的沙箱区域如下：

区域	区域标识符	API Endpoint
中国（扬州1）	`cn-yangzhou-1`	`https://cn-yangzhou-1-sandbox.qiniuapi.com`
美国（达拉斯1）	`us-south-1`	`https://us-south-1-sandbox.qiniuapi.com`

快速开始

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("完成！")
}

功能文档

文档	说明
沙箱管理	创建、连接、列出、生命周期管理、暂停/恢复、指标和日志
命令执行	同步/异步命令执行、流式输出、后台进程管理
文件管理	文件读写、批量操作、目录管理、文件监听
PTY 终端	伪终端创建、输入发送、终端调整
模板管理	模板 CRUD、构建管理、标签管理

轮询选项

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

选项	说明
`WithPollInterval(time.Duration)`	设置轮询间隔
`WithBackoff(multiplier, maxInterval)`	启用指数退避
`WithOnPoll(func(attempt int))`	注册轮询回调

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)
	}),
)

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
}

配置参数

参数	类型	必填	说明
`APIKey`	`string`	是	API 密钥，用于身份认证
`Endpoint`	`string`	否	服务地址，默认 `https://cn-yangzhou-1-sandbox.qiniuapi.com`
`HTTPClient`	`*http.Client`	否	自定义 HTTP 客户端，默认 `http.DefaultClient`

当前支持的沙箱区域如下：

区域	区域标识符	API Endpoint
中国（扬州1）	`cn-yangzhou-1`	`https://cn-yangzhou-1-sandbox.qiniuapi.com`
美国（达拉斯1）	`us-south-1`	`https://us-south-1-sandbox.qiniuapi.com`

快速开始

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("完成！")
}

功能文档

文档	说明
沙箱管理	创建、连接、列出、生命周期管理、暂停/恢复、指标和日志
命令执行	同步/异步命令执行、流式输出、后台进程管理
文件管理	文件读写、批量操作、目录管理、文件监听
PTY 终端	伪终端创建、输入发送、终端调整
模板管理	模板 CRUD、构建管理、标签管理

轮询选项

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

选项	说明
`WithPollInterval(time.Duration)`	设置轮询间隔
`WithBackoff(multiplier, maxInterval)`	启用指数退避
`WithOnPoll(func(attempt int))`	注册轮询回调

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)
	}),
)

Go SDK 概览

Go SDK

安装

认证配置

初始化客户端

配置参数

快速开始

功能文档

轮询选项

更多资源

本页内容

Go SDK 概览

Go SDK

安装

认证配置

初始化客户端

配置参数

快速开始

功能文档

轮询选项

更多资源

本页内容