Docker Sandboxes
说明创建或更新自定义密钥
用法sbx secret set-custom [flags]

实验性

此命令为实验性功能。

实验性功能仅用于测试和反馈，其功能或设计可能在不同版本之间无预警地发生变化，也可能在未来的版本中被完全移除。

描述 ​

为 sbx 未内置的服务创建或更新自定义密钥。

自定义密钥通过占位符工作：沙箱看到的是占位符值，而不是真实密钥。当沙箱向 目标主机发起出站请求时，代理会在请求头中把占位符替换为真实密钥——密钥本身 从不直接进入沙箱。

--host 接受精确主机名、IP 地址或通配符模式。重复 --host 可以用一个密钥覆盖多个无关域名。"" 匹配单个标签，"**" 匹配任意数量的标签。 例如 ".example.com" 用一条记录即可覆盖 "cli.example.com" 和 "ide.example.com"。

自定义密钥默认全局生效。使用 --sandbox 可把某个密钥限定到 特定沙箱。

命令式密钥在主机上的全新临时目录中运行，以进行 验证和刷新。该宿主机临时目录必须是绝对路径，并且必须 位于可写沙箱挂载之外。诸如 ./helper 或 cat token 这样的相对引用 不再相对于项目目录或守护进程工作目录解析。请使用共享工作区之外的 绝对 helper 路径。sbx 不会复制 helper、检查其 依赖，也不会限制其执行。helper 及其加载的任何代码或配置 都必须位于可写沙箱挂载之外。显式指向共享工作区的路径，以及暴露宿主机配置或 宿主机临时目录的大范围挂载，仍然是不安全的，包括之后才添加到运行中沙箱上的挂载。

使用 --cloud 时，--host 只接受精确的 DNS 名称（不能是 IP 地址或通配符）， 并且代理会在发往这些主机的请求上设置 --header，而不是替换占位符。

选项 ​

选项默认值说明
--command使用命令的标准输出作为密钥值
--env在沙箱中将该环境变量设置为占位值
--format该值填充请求头的方式，其中包含一个 %s；省略 --header 时默认为 "Bearer %s"（使用 --cloud 时）
--header代理在为 --host 发出请求时用于设置密钥的 HTTP 请求头；默认为 Authorization（使用 --cloud 时）
--host主机、IP 或通配符模式（例如 *.example.com）；可重复指定；使用 --cloud 时仅接受精确的 DNS 名称
--name密钥名称；默认根据第一个 --host 推导（使用 --cloud 时）
--no-verify存储时跳过对 --ref 或 --command 来源的检查
--placeholder占位值；使用 {rand} 表示随机后缀（例如 sk-{rand}）
--ref使用 1Password 的 op:// 引用或 AWS Secrets Manager ARN 作为密钥来源
--refresh密钥刷新策略：按需刷新（默认）或在指定时长后刷新
--sandbox将密钥限定到单个沙箱（默认：所有沙箱）
--show-error如果初始检查失败，显示解析器的标准错误（可能包含密钥）
-t, --token密钥值（安全性较低：会出现在 shell 历史记录中）
--value密钥值（安全性较低：会出现在 shell 历史记录中）
--value-stdin从 stdin 读取密钥值

全局选项 ​

选项默认值说明
--cloud改为调用 Docker Cloud Sandboxes API，而不是本地 sandboxd（支持的动词正在逐步增加，运行 sbx --cloud --help 查看当前列表）
-D, --debug启用调试日志
--no-input从不提示；需要应答的命令会直接失败，并给出应当运行的命令

示例 ​

console
# 创建一个全局自定义密钥。会自动生成一个唯一的占位符。
# 沙箱环境变量 API_KEY 会被设置为该占位符值；发往目标主机的出站请求
# 中，占位符会被替换为真实密钥。
sbx secret set-custom --host api.example.com --env API_KEY --value secret123

# 使用通配符主机名，以覆盖共用同一密钥的多个子域名
sbx secret set-custom --host '*.coderabbit.ai' --env CODERABBIT_API_KEY --value secret123

# 使用多个 --host flag，以覆盖共用同一密钥的无关域名
sbx secret set-custom --host api.example.com --host api.other.io --env API_KEY --value secret123

# 限定到特定沙箱，而不是全局生效
sbx secret set-custom --sandbox my-sandbox --host api.example.com --env API_KEY --value secret123

# 使用带 {rand} 后缀的自定义占位符；CLI 会打印生成的值
sbx secret set-custom --host api.example.com --placeholder sk-{rand} --value secret123

# 从 stdin 读取值，避免它出现在 shell 历史和进程列表中
printf '%s' "$API_KEY" | sbx secret set-custom --host api.example.com --env API_KEY --value-stdin

参见 ​