> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 概述

Secret 是在 PPIO Sandbox 中安全存储和使用敏感值（如 API 密钥、令牌和密码）的方式。它让在沙箱中运行的代码无需在源代码、Snapshot 或沙箱环境变量中硬编码凭证，即可向外部服务进行身份验证。

<Note>
  此功能仅支持 v2 [区域](/docs/sandbox/overview#区域)。
</Note>

## 什么是 Secret

Secret 是在当前团队范围内管理的加密凭证。PPIO 会在来自沙箱的符合条件的出站 HTTPS 请求上使用该凭证，但绝不会将真实值注入沙箱本身。

相反，沙箱环境变量中保存的是一个不透明的**占位符**，而不是实际的 API 密钥。只有当目标主机匹配该 Secret 的允许列表时，出站代理才会将占位符替换为真实值。

这使得沙箱可以使用 LLM API 密钥或数据库密码等凭证，同时让真实值不出现在沙箱的环境变量、文件系统和进程参数中。沙箱中运行的代码可以使用 Secret 访问已批准的主机，但无法通过 Secret 环境变量读取真实值。

<Note>
  真实的 Secret 值绝不会被传递进沙箱。沙箱持有的只是一个不透明的占位符；替换为真实值的操作发生在代理层，位于沙箱之外。
</Note>

## 工作原理

在正常的 Secret 注入流程中，沙箱环境变量保存的是占位符，而不是 Secret 的真实值。PPIO 使用外部代理在请求时将符合条件的占位符替换为实际值。

1. 你在当前团队中存储一个 Secret 值。PPIO 会加密并存储它，并分配一个不透明的占位符，例如 `ppio_secret_<random_hex>`，其中 `<random_hex>` 是随机生成的十六进制字符串。
2. 创建沙箱时，你通过 `secret_envs` 将环境变量映射到某个 Secret。PPIO 会将该环境变量设置为占位符，而不是实际值。
3. 当沙箱发起出站 HTTPS 请求时，代理会检查该请求。如果请求头中携带占位符，且目标主机匹配该 Secret 的允许列表，代理会在请求到达目的地之前将占位符替换为真实值。
4. 如果目标主机不在该 Secret 的允许列表中，则不会替换真实值。占位符会按原样通过沙箱的正常出站路径转发，因此目的地收到的是占位符而不是真实的 Secret。

请求替换和响应过滤都发生在代理层，因此真实的 Secret 值绝不会通过 Secret 环境变量注入沙箱。对于匹配某个 Secret 且使用受支持格式的响应，代理还会在将响应返回给沙箱之前，尝试将真实值替换回占位符。

<Note>
  占位符仅在 HTTPS 请求头的值中被替换（例如 `Authorization` 或 `X-Api-Key`）。请求体、URL 路径和查询参数、纯 HTTP 请求以及 WebSocket 消息内容会按原样转发，不会被替换。使用 Secret 时请优先采用基于请求头的身份验证。
</Note>