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

# 密钥

> 用于存储 API 密钥、凭证和敏感配置的加密保险库。

# 密钥

Kazzle 内置加密保险库，用于存储 API 密钥、数据库凭证、令牌和应用所需的其他敏感值。密钥使用 AES-256-GCM 加密存储，采用 KMS 包装的数据加密密钥——明文值永远不会接触数据库。

## 概念

**集合**将相关密钥分组（例如 `stripe-keys`、`database-credentials`）。每个集合都有一个**标识符**（小写、用连字符分隔），你可以在配置文件和 CLI 命令中引用它。

**环境**是集合内的可选作用域（例如 `production`、`staging`）。密钥可以限定到特定环境，也可以保留在集合级别作为默认值。

\*\*解析顺序：\*\*解析给定集合和环境的密钥时，环境特定的密钥会覆盖同名的集合级密钥。这样你可以在环境间共享大多数密钥，同时按环境覆盖特定值。

## 管理密钥

### 在应用中

打开 **Settings > Vault** 通过 UI 创建集合、环境和密钥。

### 使用 AI

AI 可以为你创建集合、创建环境、存储密钥、在作用域间移动密钥以及删除密钥。

AI 可以看到密钥名称和元数据，但看不到加密值。

### 使用 CLI

```bash theme={"theme":"material-theme-darker"}
# 将密钥导出为 KEY=value 行
kazzle secrets.export --collection=stripe-keys --env=production
```

## 从应用中引用密钥

在 `kazzle.config.ts` 中将组件的 `env` 指向密钥集合和环境。该作用域内的每个密钥都会作为进程环境变量注入，其名称与密钥名称匹配：

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

export default defineConfig({
  components: [
    {
      name: 'API Server',
      type: 'process',
      path: './server',
      env: {
        collection: 'stripe-keys',
        environment: 'production'
      }
    }
  ]
});
```

`env.collection` 和 `env.environment` 是**标识符**，不是显示名称。使用 `env.include` 仅注入集合密钥的子集：

```typescript theme={"theme":"material-theme-darker"}
env: {
  collection: 'stripe-keys',
  environment: 'production',
  include: ['STRIPE_SECRET_KEY']
}
```

## 密钥如何变成环境变量

为组件解析密钥时：

1. 在你的 Space 内按标识符查找集合
2. 加载限定到指定环境的密钥
3. 集合级密钥（无环境）作为默认值包含
4. 环境特定的密钥覆盖同名的集合级密钥
5. 解析值内的密钥引用
6. 密钥名称转换为环境变量格式：大写，非字母数字字符变为下划线

名为 `Stripe Secret Key` 的密钥变成 `STRIPE_SECRET_KEY`。

每个密钥都有一个**主体模式**，决定它的注入方式：

* **`string`** 密钥（API 密钥、令牌、URI）作为纯标量字符串注入
* **`json`** 密钥（结构化配置）作为 JSON 字符串注入
* **`fields`** 密钥（登录凭证、类型化字段包）作为 JSON 字符串注入

## 密钥何时注入

| 上下文                       | 已注入？ | 详情                                    |
| ------------------------- | ---- | ------------------------------------- |
| **Deploy**（进程组件）          | 是    | 在生产环境中作为运行时环境变量添加                     |
| **Deploy**（UI 组件）         | 部分   | 仅 `VITE_*` 前缀的密钥在构建时传递                |
| **CLI**（`kazzle run`）     | 是    | 注入到命令的环境中                             |
| **CLI**（`secrets.export`） | 是    | 导出为 `KEY=value` 行                     |
| **Dev preview**           | 暂不支持 | 预览启动器尚未解析组件 `env`——目前请使用 `kazzle run` |

## 模板引用

密钥值可以使用 Kazzle 在其他地方使用的相同语法引用其他密钥字段：

```
postgresql://${secret.123e4567-e89b-12d3-a456-426614174000.username}:${secret.123e4567-e89b-12d3-a456-426614174000.password}@db.example.com:5432/mydb
```

支持的格式：

* `${secret.<uuid>.<field>}` ——密钥值或工具参数内的特定字段或 JSON 路径，其中启用了保险库引用。
* `${secret.<uuid>}` ——整个密钥主体。仅在工具明确要求整个原始密钥时使用；不要在应用 env/config 中使用。

引用在加载密钥后解析。循环或损坏的引用会失败，而不是静默回退。