跳转到主要内容

​
密钥

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

​
概念

集合将相关密钥分组在一起（例如 stripe-keys、database-credentials）。每个集合都有一个slug（小写、用连字符分隔），你可以在配置文件和 CLI 命令中引用它。 环境是集合内的可选作用域（例如 production、staging）。密钥可以限定到特定环境，也可以保留在集合级别作为默认值。 **解析顺序：**当为给定的集合 + 环境解析密钥时，特定于环境的密钥会覆盖同名的集合级密钥。这样你可以在环境间共享大多数密钥，同时按环境覆盖特定值。

​
管理密钥

​
在应用中

打开设置 > 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 是 slug，不是显示名称。使用 env.include 仅注入集合密钥的子集： 
env: {
  collection: 'stripe-keys',
  environment: 'production',
  include: ['STRIPE_SECRET_KEY']
}

​
密钥如何变成环境变量

当为组件解析密钥时：
  1. 在你的空间内按 slug 查找集合
  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>} — 整个密钥主体。仅在工具明确要求整个原始密钥时使用；不要在应用环境/配置中使用。
引用在加载密钥后解析。循环或损坏的引用会失败，而不是静默回退。