使用 qshell 管理密钥注入

密钥注入用于在沙箱内访问外部服务时自动注入真实密钥,避免把 API Key 明文写入沙箱环境、代码或镜像中。qshell sandbox injection-rule 可以创建、查看、更新、删除注入规则,也可以在创建沙箱时引用规则或传入内联注入配置。

命令概览

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 请求注入
http	--base-url, --headers	自定义 HTTP 服务请求头注入

创建注入规则

创建 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

创建自定义 HTTP 注入规则:

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

--headers 使用逗号分隔多个 key=value。如果 header 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'

同时传入多个内联注入:

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

更新自定义 HTTP header:

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

更新注入配置时需要同时指定 --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。
• 删除规则前确认没有自动化流程仍在引用该规则。