跳轉到主要內容

​
密鑰

Kazzle 內建加密保管庫，用於儲存 API 金鑰、資料庫認證、權杖和應用程式所需的其他敏感值。密鑰使用 AES-256-GCM 加密（採用 KMS 包裝的資料加密金鑰）進行靜態加密 — 純文字值永遠不會接觸資料庫。

​
概念

集合將相關密鑰分組在一起（例如 stripe-keys、database-credentials）。每個集合都有一個識別碼（小寫、用連字號分隔），您可在設定檔和 CLI 命令中參考。 環境是集合內的選用範圍（例如 production、staging）。密鑰可限定於特定環境，或保留在集合層級作為預設值。 **解析順序：**解析給定集合 + 環境的密鑰時，環境特定密鑰會覆寫同名的集合層級密鑰。這讓您可在環境間共用大多數密鑰，同時按環境覆寫特定值。

​
管理密鑰

​
在應用程式中

開啟 Settings > Vault 以透過 UI 建立集合、環境和密鑰。

​
使用 AI

AI 可為您建立集合、建立環境、儲存密鑰、在範圍間移動密鑰，以及刪除密鑰。 AI 可看到密鑰名稱和中繼資料，但看不到加密值。

​
使用 CLI

# 執行命令並將密鑰注入為環境變數
kazzle run --collection=stripe-keys --env=production -- bun run server.ts

# 將密鑰匯出為 KEY=value 行
kazzle secrets.export --collection=stripe-keys --env=production

​
從應用程式參考密鑰

在 kazzle.config.ts 中將元件的 env 指向密鑰集合和環境。該範圍內的每個密鑰都會注入為程序環境變數，其名稱與密鑰名稱相符： 
import { defineConfig } from './kazzle.types';

export default defineConfig({
  components: [
    {
      name: 'API Server',
      type: 'process',
      path: './server',
      env: {
        collection: 'stripe-keys',
        environment: 'production'
      }
    }
  ]
});
env.collection 和 env.environment 是識別碼，不是顯示名稱。使用 env.include 只注入集合密鑰的子集： 
env: {
  collection: 'stripe-keys',
  environment: 'production',
  include: ['STRIPE_SECRET_KEY']
}

​
密鑰如何成為環境變數

解析元件的密鑰時：
  1. 在您的空間內按識別碼找到集合
  2. 載入限定於指定環境的密鑰
  3. 集合層級密鑰（無環境）作為預設值包含
  4. 環境特定密鑰覆寫同名的集合層級密鑰
  5. 解析值內的密鑰參考
  6. 密鑰名稱轉換為環境變數格式：大寫，非英數字元變為底線
名為 Stripe Secret Key 的密鑰變為 STRIPE_SECRET_KEY。 每個密鑰都有主體模式，決定其注入方式：
  • string 密鑰（API 金鑰、權杖、URI）注入為純量字串
  • json 密鑰（結構化設定）注入為 JSON 字串
  • fields 密鑰（登入認證、型別欄位包）注入為 JSON 字串

​
何時注入密鑰

內容已注入？詳細資訊
部署（程序元件）是在生產環境中新增為執行時環境變數
部署（UI 元件）部分只有 VITE_* 前置密鑰在建置時傳遞
CLI（kazzle run）是注入到命令的環境
CLI（secrets.export）是匯出為 KEY=value 行
開發預覽尚未預覽啟動器尚未解析元件 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>} — 整個密鑰主體。僅在工具明確要求整個原始密鑰時使用；不要在應用程式環境/設定中使用。
參考在載入密鑰後解析。循環或損壞的參考會失敗，而不是無聲地回退。