使用 qshell 管理密钥注入

密钥注入用于在沙箱内访问外部服务时自动注入真实密钥,避免把 API Key 明文写入沙箱环境、代码或镜像中。qshell sandbox injection-rule 可以创建、查看、更新、删除注入规则,也可以在创建沙箱时引用规则或传入内联注入配置。以下示例基于 qshell v2.19.9+，该版本支持 GitHub 凭证注入和请求匹配条件。

命令概览

qshell sandbox injection-rule <子命令>
qshell sbx ir <子命令>

常用子命令:

命令	说明
injection-rule list	列出注入规则
injection-rule get	查看注入规则详情
injection-rule create	创建注入规则
injection-rule update	更新注入规则
injection-rule delete	删除注入规则

支持的注入类型

类型	常用参数	说明
openai	--api-key, --base-url	OpenAI API 请求注入
anthropic	--api-key, --base-url	Anthropic API 请求注入
gemini	--api-key, --base-url	Gemini API 请求注入
qiniu	--api-key, --base-url	七牛 AI API 请求注入
github	--api-key, --base-url	GitHub 凭证注入，--api-key 传入 GitHub Token
http	--base-url, --headers	自定义 HTTP 服务请求头注入

所有类型都可以通过 --if-headers 和 --if-queries 设置匹配条件。只有请求中已经存在这些 Header 或 query 参数且值精确匹配时，平台才会注入密钥。条件只用于缩小匹配范围，不是授权边界。

创建注入规则

创建 OpenAI 注入规则:

qshell sandbox injection-rule create \
  --name openai-default \
  --type openai \
  --api-key sk-xxx

创建带代理地址的 OpenAI 注入规则:

qshell sandbox injection-rule create \
  --name openai-proxy \
  --type openai \
  --api-key sk-xxx \
  --base-url https://openai-proxy.example.com

创建 Anthropic 注入规则:

qshell sandbox injection-rule create \
  --name anthropic-default \
  --type anthropic \
  --api-key sk-ant-xxx

创建 Gemini 注入规则:

qshell sandbox injection-rule create \
  --name gemini-default \
  --type gemini \
  --api-key sk-gemini-xxx

创建七牛 AI API 注入规则:

qshell sandbox injection-rule create \
  --name qiniu-ai \
  --type qiniu \
  --api-key sk-qiniu-xxx

创建 GitHub 凭证注入规则:

qshell sandbox injection-rule create \
  --name github-default \
  --type github \
  --api-key ghp-xxx

创建仅匹配 GitHub API 仓库路径的 GitHub 凭证注入规则:

qshell sandbox injection-rule create \
  --name github-api \
  --type github \
  --api-key ghp-xxx \
  --base-url https://api.github.com/repos/qiniu/*

创建自定义 HTTP 注入规则:

qshell sandbox injection-rule create \
  --name api-auth \
  --type http \
  --base-url https://api.example.com \
  --headers "Authorization=Bearer token,X-Env=dev"

创建带匹配条件的自定义 HTTP 注入规则:

qshell sandbox injection-rule create \
  --name api-auth-scoped \
  --type http \
  --base-url https://api.example.com \
  --headers "Authorization=Bearer token" \
  --if-headers "X-Scope=prod" \
  --if-queries "inject=true"

--headers、--if-headers 和 --if-queries 使用逗号分隔多个 key=value。如果 value 本身包含 shell 特殊字符,建议用引号包裹整个参数。

查看注入规则

列出规则:

qshell sandbox injection-rule list

JSON 输出:

qshell sandbox injection-rule list --format json

查看单条规则:

qshell sandbox injection-rule get <rule-id>

创建沙箱时引用规则

创建沙箱时通过 --injection-rule 引用已有规则:

qshell sandbox create <template-id> --injection-rule <rule-id>

引用多个规则:

qshell sandbox create <template-id> \
  --injection-rule <openai-rule-id> \
  --injection-rule <http-rule-id>

后台创建:

qshell sandbox create <template-id> \
  --detach \
  --timeout 300 \
  --injection-rule <rule-id>

内联注入

如果不希望提前创建规则,可以在创建沙箱时直接使用 --inline-injection:

qshell sandbox create <template-id> \
  --inline-injection 'type=openai,api-key=sk-xxx'

内联 Anthropic:

qshell sandbox create <template-id> \
  --inline-injection 'type=anthropic,api-key=sk-ant-xxx,base-url=https://anthropic-proxy.example.com'

内联自定义 HTTP:

qshell sandbox create <template-id> \
  --inline-injection 'type=http,base-url=https://api.example.com,headers=Authorization=Bearer token;X-Env=dev'

内联带条件匹配的 HTTP 注入:

qshell sandbox create <template-id> \
  --inline-injection 'type=http,base-url=https://api.example.com,headers=Authorization=Bearer token,if-headers=X-Scope=prod,if-queries=inject=true'

内联 GitHub 凭证注入:

qshell sandbox create <template-id> \
  --inline-injection 'type=github,api-key=ghp-xxx,base-url=https://api.github.com/repos/qiniu/*'

同时传入多个内联注入:

qshell sandbox create <template-id> \
  --inline-injection 'type=openai,api-key=sk-xxx' \
  --inline-injection 'type=http,base-url=https://api.example.com,headers=Authorization=Bearer token'

内联注入适合临时调试。生产或多人协作场景建议使用持久注入规则,便于审计和复用。

更新注入规则

更新规则名称:

qshell sandbox injection-rule update <rule-id> --name openai-prod

更新 OpenAI 密钥:

qshell sandbox injection-rule update <rule-id> \
  --type openai \
  --api-key sk-new

更新 GitHub 凭证注入:

qshell sandbox injection-rule update <rule-id> \
  --type github \
  --api-key ghp-new \
  --base-url https://api.github.com/repos/qiniu/*

更新自定义 HTTP header:

qshell sandbox injection-rule update <rule-id> \
  --type http \
  --base-url https://api.example.com \
  --headers "Authorization=Bearer new-token"

更新自定义 HTTP 匹配条件:

qshell sandbox injection-rule update <rule-id> \
  --type http \
  --base-url https://api.example.com \
  --headers "Authorization=Bearer new-token" \
  --if-headers "X-Scope=prod" \
  --if-queries "inject=true"

更新注入配置时需要同时指定 --type,以明确更新哪种类型的注入规则。

删除注入规则

删除单条规则:

qshell sandbox injection-rule delete <rule-id>

跳过确认:

qshell sandbox injection-rule delete <rule-id> -y

删除多条规则:

qshell sandbox injection-rule delete rule-aaa rule-bbb -y

交互式选择删除:

qshell sandbox injection-rule delete --select

使用建议

• 不要把真实 API Key 写入模板镜像、Dockerfile 或仓库。
• 长期使用的密钥配置建议创建持久注入规则。
• 临时验证可以使用 --inline-injection。
• 自定义 HTTP 注入的 headers 建议只放认证相关 header。
• GitHub 注入的 --base-url 只能使用 github.com 或 api.github.com；如已通过 --resource type=github_repository 挂载仓库资源，不要再额外传入 type=github 注入。
• 删除规则前确认没有自动化流程仍在引用该规则。