> ## 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 中使用。

參考在載入密鑰後解析。循環或損壞的參考會失敗，而不是無聲地回退。