概述

资源挂载是七牛沙箱额外提供的开发者能力，适合在 AI Agent、代码审查、自动化构建和代码迁移等场景中安全地使用外部资源。

创建沙箱时可以通过 resources 参数声明需要挂载的外部资源：

当前 resources 支持 GitHub 仓库资源。访问外部资源需要的凭证尽量由平台侧持有，不直接暴露给沙箱内进程。

支持的资源类型

GitHub 仓库资源

GitHub 仓库资源用于在沙箱启动前预拉取仓库快照，并挂载到沙箱内指定路径。适合代码审查、自动化构建、AI Agent 改代码等场景。

如果创建沙箱时传入 github_repository 资源，平台会使用资源中的 authorization_token 预拉取仓库，并自动派生运行时 GitHub 密钥注入。沙箱内进程不需要、也无法直接读取真实 Token。

工作原理

沙箱启动前:
外部资源 ── 平台使用凭证准备资源 ── 挂载到沙箱内 mount_path

核心行为：

• 资源在沙箱启动前准备完成，启动后可直接访问 mount_path
• 凭证由平台侧持有，不以环境变量、文件或命令参数形式进入沙箱
• GitHub 仓库资源会自动派生运行时 GitHub 注入，后续 git pull、git push 等操作可继续鉴权

当 resources 中包含 github_repository 时，不要再显式传入 type: github 的 injections。服务端会根据 authorization_token 自动派生 GitHub 注入；如果同时显式传入，会返回 400 github_repository resources do not support explicit github injections。

使用 Go SDK 挂载 GitHub 仓库

以下示例基于 七牛 Go SDK v7.26.12+。

package main

import (
    "context"
    "log"
    "os"

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

func stringPtr(s string) *string { return &s }

func main() {
    ctx := context.Background()

    apiKey := requiredEnv("QINIU_API_KEY")
    githubToken := requiredEnv("GITHUB_TOKEN")

    client, err := sandbox.NewClient(&sandbox.Config{
        APIKey:   apiKey,
        Endpoint: os.Getenv("QINIU_SANDBOX_API_URL"),
    })
    if err != nil {
        log.Fatal(err)
    }

    sb, _, err := client.CreateAndWait(ctx, sandbox.CreateParams{
        TemplateID: "base",
        Resources: &[]sandbox.SandboxResourceSpec{
            {
                GitRepository: &sandbox.GitRepositoryResource{
                    Type:               sandbox.GitRepositoryTypeGithub,
                    URL:                "https://github.com/owner/private-repo.git",
                    MountPath:          "/workspace/repo",
                    AuthorizationToken: stringPtr(githubToken),
                },
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    defer sb.Kill(ctx)

    result, err := sb.Commands().Run(ctx, "cd /workspace/repo && git status --short")
    if err != nil {
        log.Fatal(err)
    }

    log.Println(result.Stdout)
}

func requiredEnv(name string) string {
    value := os.Getenv(name)
    if value == "" {
        log.Fatalf("%s is required", name)
    }
    return value
}

这个例子中：

• /workspace/repo 在沙箱启动后已经包含仓库内容
• GITHUB_TOKEN 不会出现在沙箱环境变量或文件系统中
• 后续在 /workspace/repo 执行 git pull、git push 时，会复用平台自动派生的 GitHub 注入

REST API 示例

创建沙箱并挂载 GitHub 仓库资源：

curl -X POST "$QINIU_SANDBOX_API_URL/sandboxes" \
  -H "X-API-Key: $QINIU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateID": "base",
    "resources": [
      {
        "type": "github_repository",
        "url": "https://github.com/owner/private-repo.git",
        "mount_path": "/workspace/repo",
        "authorization_token": "'"$GITHUB_TOKEN"'"
      }
    ]
  }'

常见工作流

启动即拥有代码

适合代码审查、构建测试、仓库内容分析：

1. 创建沙箱时传入 github_repository 资源
2. 平台预拉取仓库并挂载到 mount_path
3. Agent 直接在挂载目录内运行测试、分析或修改代码

修改后推送回仓库

适合自动修复、批量迁移、文档更新：

1. 创建沙箱时传入 github_repository 资源
2. Agent 在挂载目录中修改代码
3. Agent 配置 Git 作者信息并提交
4. Agent 直接执行 git push

示例：

cd /workspace/repo
git checkout -b feature/auto-fix
git config user.name "AI Bot"
git config user.email "bot@example.com"
git add .
git commit -m "fix: update generated files"
git push -u origin feature/auto-fix

限制与注意事项

• resources 最多 20 项
• 所有 mount_path 必须是绝对路径，不能重复，不能包含路径穿越
• github_repository.authorization_token 当前必填，即使目标仓库是公开仓库
• 同一个沙箱内多个 GitHub 仓库资源必须使用同一个 authorization_token
• 使用 github_repository 资源时，不要额外显式传入 GitHub 注入
• GitHub 仓库资源使用缓存快照，不保证每次创建沙箱都拉取最新 HEAD；如果任务依赖最新代码，请在挂载目录内执行 git pull
• 如果需要最小化权限，GitHub 建议使用 Fine-grained PAT，并只授予目标仓库需要的读写权限

相关文档

• 密钥注入
• Git 集成