概述

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

工作原理

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

核心流程：

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

安全保障：

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

初始化客户端

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

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 字段区分类型，支持以下五种：

type	说明
id	引用已保存的注入规则
http	自定义 HTTP 注入（base_url + headers）
openai	OpenAI 协议（自动注入 Authorization: Bearer <key>）
anthropic	Anthropic 协议（自动注入 x-api-key: <key>）
gemini	Google Gemini 协议（自动注入 x-goog-api-key: <key>）

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

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

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

在沙箱中使用注入规则

以下示例均使用七牛 Go SDK 创建沙箱，完整可运行示例与 stringPtr 辅助函数见 docs/developer/example/test-injection-rules.go。

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 请求头。

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

适用于：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。

gemini 类型：Google Gemini 协议

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

不指定 base_url 时默认匹配 generativelanguage.googleapis.com。

组合使用多条规则

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

管理注入规则（按 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 联合体

type	必填字段	可选字段	说明
id	id	—	引用已保存规则的 ID
http	base_url	headers	自定义 HTTP 注入
openai	api_key	base_url	OpenAI 兼容协议，默认 host: api.openai.com
anthropic	api_key	base_url	Anthropic 协议，默认 host: api.anthropic.com
gemini	api_key	base_url	Google Gemini，默认 host: generativelanguage.googleapis.com

base_url

• 可省略 scheme，默认使用 https
• 域名部分用于 host 匹配
• 不支持通配符：*、?、+
• 不支持显式端口号（仅允许默认 HTTPS 端口）
• 不支持路径

Go SDK 类型映射

API type	管理规则时的 SDK 类型	创建沙箱时的 SDK 类型
id	不支持	sandbox.SandboxInjectionSpec{ByID: &ruleID}
http	sandbox.InjectionSpec{HTTP: &sandbox.HTTPInjection{...}}	sandbox.SandboxInjectionSpec{HTTP: &sandbox.HTTPInjection{...}}
openai	sandbox.InjectionSpec{OpenAI: &sandbox.OpenAIInjection{...}}	sandbox.SandboxInjectionSpec{OpenAI: &sandbox.OpenAIInjection{...}}
anthropic	sandbox.InjectionSpec{Anthropic: &sandbox.AnthropicInjection{...}}	sandbox.SandboxInjectionSpec{Anthropic: &sandbox.AnthropicInjection{...}}
gemini	sandbox.InjectionSpec{Gemini: &sandbox.GeminiInjection{...}}	sandbox.SandboxInjectionSpec{Gemini: &sandbox.GeminiInjection{...}}

headers（http 类型）

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

限制

限制项	上限
每次沙箱最多注入规则数	20
http 类型 headers 数量	20
注入规则名称长度	64 字符
http 类型 header key/value 长度	1000 字节
api_key / base_url 长度	1000 字节