密钥注入

最近更新时间: 2026-06-30 15:56:37

概述

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

工作原理

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

核心流程：

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

安全保障：

密钥在平台侧管理，沙箱内代码无法直接读取
仅对匹配的出站 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 字段区分类型，支持以下七种：

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>`）
`qiniu`	七牛 AI 协议（自动注入密钥到 OpenAI 或 Anthropic 认证头）
`github`	GitHub 凭证注入（自动为 `github.com` / `api.github.com` 请求鉴权）

在 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。

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。

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

如果创建沙箱时已经通过 resources 挂载 github_repository，不要再显式传入 github 注入。服务端会根据资源中的 authorization_token 自动派生运行时 GitHub 注入，同时显式传入会被拒绝。

组合使用多条规则

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 联合体

type	必填字段	可选字段	说明
`id`	`id`	—	引用已保存规则的 ID
`http`	`base_url`	`headers`、`if_headers`、`if_queries`	自定义 HTTP 注入
`openai`	`api_key`	`base_url`、`if_headers`、`if_queries`	OpenAI 兼容协议，默认 host: `api.openai.com`
`anthropic`	`api_key`	`base_url`、`if_headers`、`if_queries`	Anthropic 协议，默认 host: `api.anthropic.com`
`gemini`	`api_key`	`base_url`、`if_headers`、`if_queries`	Google Gemini，默认 host: `generativelanguage.googleapis.com`
`qiniu`	`api_key`	`base_url`、`if_headers`、`if_queries`	七牛 AI 协议，默认 host: `api.qnaigc.com`
`github`	`token`	`base_url`、`if_headers`、`if_queries`	GitHub HTTPS 请求注入，默认 host: `github.com` / `api.github.com`

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 类型映射

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{...}}`
`qiniu`	`sandbox.InjectionSpec{Qiniu: &sandbox.QiniuInjection{...}}`	`sandbox.SandboxInjectionSpec{Qiniu: &sandbox.QiniuInjection{...}}`
`github`	`sandbox.InjectionSpec{Github: &sandbox.GithubInjection{...}}`	`sandbox.SandboxInjectionSpec{Github: &sandbox.GithubInjection{...}}`

headers（http 类型）

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

if_headers / if_queries

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

限制

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

以上内容是否对您有帮助？

全栈应用服务器