概述

密钥注入是沙箱平台提供的密钥安全保护能力。用户可以预先配置注入规则，在创建沙箱时引用这些规则；沙箱内 AI Agent 发起的匹配 HTTPS 请求在离开沙箱时会自动注入真实密钥。沙箱内部代码无法获取真实密钥，从而确保密钥安全。

工作原理

Sandbox (AI Agent) ─── HTTPS ──> 沙箱平台 ─── HTTPS ──> 上游服务
  (无真实密钥)                  (注入真实密钥)

核心流程：

1. 创建沙箱时通过 injections 字段传入注入规则
2. 沙箱内代码发起 HTTPS 请求时，平台自动拦截匹配的出站流量
3. 根据规则注入或替换认证信息
4. 将携带真实密钥的请求转发到上游服务

安全保障：

• 密钥在平台侧管理，沙箱内代码无法直接读取
• 仅对匹配的出站 HTTPS 请求生效
• 仅拦截命中的目标域名，请求不命中时直接透传
• 注入规则可以独立管理、复用和审计

初始化客户端

以下示例基于 七牛 Go SDK v7.26.14+。v7.26.14 起，Go SDK 支持 GitHub 凭证注入和 if_headers / if_queries 条件匹配。

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

client, err := sandbox.NewClient(&sandbox.Config{
    APIKey:   "<API_KEY>",
    Endpoint: "https://cn-yangzhou-1-sandbox.qiniuapi.com",
})

注入规则格式

injections 是一个数组，每条规则通过 type 字段区分类型，支持以下七种：

在 OpenAPI 中，这些规则通过带 type 判别字段的联合体表示；在最新 Go SDK 中，对应为互斥结构体：

• 管理注入规则时使用 sandbox.InjectionSpec
• 创建沙箱时使用 sandbox.SandboxInjectionSpec

同一个结构体一次只能设置一种注入类型。

在沙箱中使用注入规则

以下示例均使用七牛 Go SDK 创建沙箱。

id 类型：引用已保存规则

ruleID := "rule-id-xxx"

sb, err := client.Create(ctx, sandbox.CreateParams{
    TemplateID: templateID,
    Injections: &[]sandbox.SandboxInjectionSpec{
        {ByID: &ruleID},
    },
})

引用已保存规则需要七牛认证。适用于规则需要复用、集中管理的场景。

http 类型：自定义 HTTP 注入

base_url 用于匹配目标域名，headers 为要注入或覆盖的 HTTP 请求头。if_headers 和 if_queries 可选，用于限制只有请求中已存在指定 Header 或 query 参数且值精确匹配时才注入。

ifHeaders := map[string]string{"X-Scope": "demo"}
ifQueries := map[string]string{"inject": "true"}

sb, err := client.Create(ctx, sandbox.CreateParams{
    TemplateID: templateID,
    Injections: &[]sandbox.SandboxInjectionSpec{
        {
            HTTP: &sandbox.HTTPInjection{
                BaseURL: "https://api.example.com",
                Headers: &map[string]string{
                    "Authorization":   "Bearer secret-token",
                    "X-Custom-Header": "value",
                },
                IfHeaders: &ifHeaders,
                IfQueries: &ifQueries,
            },
        },
    },
})

适用于：Azure OpenAI、自定义服务、任何需要手动指定 Header 的场景。

openai 类型：OpenAI 兼容协议

sb, err := client.Create(ctx, sandbox.CreateParams{
    TemplateID: templateID,
    Injections: &[]sandbox.SandboxInjectionSpec{
        {
            OpenAI: &sandbox.OpenAIInjection{
                APIKey: stringPtr("sk-real-openai-key"),
            },
        },
    },
})

不指定 base_url 时默认匹配 api.openai.com。如需使用 OpenAI 兼容协议的第三方服务，指定 base_url：

sb, err := client.Create(ctx, sandbox.CreateParams{
    TemplateID: templateID,
    Injections: &[]sandbox.SandboxInjectionSpec{
        {
            OpenAI: &sandbox.OpenAIInjection{
                BaseURL: stringPtr("https://api.deepseek.com"),
                APIKey:  stringPtr("sk-deepseek-xxx"),
            },
        },
    },
})

anthropic 类型：Anthropic 协议

sb, err := client.Create(ctx, sandbox.CreateParams{
    TemplateID: templateID,
    Injections: &[]sandbox.SandboxInjectionSpec{
        {
            Anthropic: &sandbox.AnthropicInjection{
                APIKey: stringPtr("sk-ant-real-key"),
            },
        },
    },
})

不指定 base_url 时默认匹配 api.anthropic.com。

qiniu 类型：七牛 AI 协议

七牛 AI 网关（api.qnaigc.com）同时兼容 OpenAI 和 Anthropic 协议，api_key 会根据实际请求携带的认证头（Authorization 或 x-api-key）自动注入，无需区分协议类型。

sb, err := client.Create(ctx, sandbox.CreateParams{
    TemplateID: templateID,
    Injections: &[]sandbox.SandboxInjectionSpec{
        {
            Qiniu: &sandbox.QiniuInjection{
                APIKey: stringPtr("your-qiniu-ai-api-key"),
            },
        },
    },
})

不指定 base_url 时默认匹配 api.qnaigc.com。

github 类型：GitHub 凭证注入

GitHub 注入用于在沙箱运行期间为匹配的 github.com / api.github.com HTTPS 请求自动注入 GitHub Token。Token 不会以明文暴露给沙箱内进程。

sb, err := client.Create(ctx, sandbox.CreateParams{
    TemplateID: templateID,
    Injections: &[]sandbox.SandboxInjectionSpec{
        {
            Github: &sandbox.GithubInjection{
                Token: stringPtr("ghp-real-token"),
            },
        },
    },
})

不指定 base_url 时默认匹配 github.com 和 api.github.com。如需收窄到 GitHub API 的指定路径，可指定 base_url，host 必须是 github.com 或 api.github.com：

ifHeaders := map[string]string{"X-GitHub-Api-Version": "2022-11-28"}

sb, err := client.Create(ctx, sandbox.CreateParams{
    TemplateID: templateID,
    Injections: &[]sandbox.SandboxInjectionSpec{
        {
            Github: &sandbox.GithubInjection{
                BaseURL:   stringPtr("https://api.github.com/repos/qiniu/*"),
                IfHeaders: &ifHeaders,
                Token:     stringPtr("ghp-real-token"),
            },
        },
    },
})

用户可同时使用 github_repository resource 和显式 github 注入：用户注入优先级高于自动派生（同 host+path 范围时自动派生被过滤）。如果仅挂载 resource 不提供 github injection，服务端自动派生 git 注入规则。自动派生注入的 token 可通过 PUT /sandboxes/{id}/github-token 更新。

组合使用多条规则

sb, err := client.Create(ctx, sandbox.CreateParams{
    TemplateID: templateID,
    Injections: &[]sandbox.SandboxInjectionSpec{
        {
            OpenAI: &sandbox.OpenAIInjection{
                APIKey: stringPtr("sk-real-openai-key"),
            },
        },
        {
            Anthropic: &sandbox.AnthropicInjection{
                APIKey: stringPtr("sk-ant-real-key"),
            },
        },
        {
            HTTP: &sandbox.HTTPInjection{
                BaseURL: "https://my-resource.openai.azure.com",
                Headers: &map[string]string{
                    "api-key": "your-azure-api-key",
                },
            },
        },
        {
            Github: &sandbox.GithubInjection{
                Token: stringPtr("ghp-real-token"),
            },
        },
    },
})

管理注入规则（按 ID 引用）

用户可以通过 七牛控制台 或 API 管理请求注入规则。

创建注入规则

rule, err := client.CreateInjectionRule(ctx, sandbox.CreateInjectionRuleParams{
    Name: "openai-api-key",
    Injection: sandbox.InjectionSpec{
        OpenAI: &sandbox.OpenAIInjection{
            APIKey: stringPtr("sk-real-openai-key"),
        },
    },
})

fmt.Println(rule.RuleID)

列出注入规则

rules, err := client.ListInjectionRules(ctx)
for _, r := range rules {
    fmt.Printf("%s: %s\n", r.RuleID, r.Name)
}

获取单个注入规则

rule, err := client.GetInjectionRule(ctx, rule.RuleID)

更新注入规则

支持部分更新，未提供的字段保持不变。

newName := "openai-api-key-v2"
rule, err := client.UpdateInjectionRule(ctx, rule.RuleID,
    sandbox.UpdateInjectionRuleParams{
        Name: &newName,
        Injection: &sandbox.InjectionSpec{
            OpenAI: &sandbox.OpenAIInjection{
                APIKey: stringPtr("sk-new-openai-key"),
            },
        },
    },
)

删除注入规则

err := client.DeleteInjectionRule(ctx, rule.RuleID)

字段说明

Injection 联合体

base_url

• 可省略 scheme，默认使用 https
• 域名部分用于 host 精确匹配
• 包含 path 时按规范化后的 path 精确匹配
• path 末尾的 * 表示字符串前缀匹配，例如 https://api.github.com/repos/qiniu/*
• github 类型指定 base_url 时，host 必须是 github.com 或 api.github.com

Go SDK 类型映射

headers（http 类型）

• 最多 20 个
• 无条件设置或覆盖到匹配请求上

if_headers / if_queries

• 支持 http、openai、anthropic、qiniu 和 github 类型
• if_headers 最多 20 项，Header 名大小写不敏感；重复 Header 只比较第一个值
• if_queries 最多 20 项，query 参数名大小写敏感
• 条件只用于缩小请求匹配范围，不是授权边界；沙箱内进程仍可主动设置匹配 Header 或 query

限制