Skip to main content

密钥

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

概念

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

管理密钥

在应用中

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

使用 AI

AI 可以为你创建集合、创建环境、存储密钥、在作用域间移动密钥以及删除密钥。 AI 可以看到密钥名称和元数据,但看不到加密值。

使用 CLI

从应用中引用密钥

kazzle.config.ts 中将组件的 env 指向密钥集合和环境。该作用域内的每个密钥都会作为进程环境变量注入,其名称与密钥名称匹配:
env.collectionenv.environment标识符,不是显示名称。使用 env.include 仅注入集合密钥的子集:

密钥如何变成环境变量

为组件解析密钥时:
  1. 在你的 Space 内按标识符查找集合
  2. 加载限定到指定环境的密钥
  3. 集合级密钥(无环境)作为默认值包含
  4. 环境特定的密钥覆盖同名的集合级密钥
  5. 解析值内的密钥引用
  6. 密钥名称转换为环境变量格式:大写,非字母数字字符变为下划线
名为 Stripe Secret Key 的密钥变成 STRIPE_SECRET_KEY 每个密钥都有一个主体模式,决定它的注入方式:
  • string 密钥(API 密钥、令牌、URI)作为纯标量字符串注入
  • json 密钥(结构化配置)作为 JSON 字符串注入
  • fields 密钥(登录凭证、类型化字段包)作为 JSON 字符串注入

密钥何时注入

模板引用

密钥值可以使用 Kazzle 在其他地方使用的相同语法引用其他密钥字段:
支持的格式:
  • ${secret.<uuid>.<field>} ——密钥值或工具参数内的特定字段或 JSON 路径,其中启用了保险库引用。
  • ${secret.<uuid>} ——整个密钥主体。仅在工具明确要求整个原始密钥时使用;不要在应用 env/config 中使用。
引用在加载密钥后解析。循环或损坏的引用会失败,而不是静默回退。