密钥
Kazzle 内置加密保险库,用于存储 API 密钥、数据库凭证、令牌和应用所需的其他敏感值。密钥使用 AES-256-GCM 加密存储,采用 KMS 包装的数据加密密钥——明文值永远不会接触数据库。概念
集合将相关密钥分组(例如stripe-keys、database-credentials)。每个集合都有一个标识符(小写、用连字符分隔),你可以在配置文件和 CLI 命令中引用它。
环境是集合内的可选作用域(例如 production、staging)。密钥可以限定到特定环境,也可以保留在集合级别作为默认值。
**解析顺序:**解析给定集合和环境的密钥时,环境特定的密钥会覆盖同名的集合级密钥。这样你可以在环境间共享大多数密钥,同时按环境覆盖特定值。
管理密钥
在应用中
打开 Settings > Vault 通过 UI 创建集合、环境和密钥。使用 AI
AI 可以为你创建集合、创建环境、存储密钥、在作用域间移动密钥以及删除密钥。 AI 可以看到密钥名称和元数据,但看不到加密值。使用 CLI
从应用中引用密钥
在kazzle.config.ts 中将组件的 env 指向密钥集合和环境。该作用域内的每个密钥都会作为进程环境变量注入,其名称与密钥名称匹配:
env.collection 和 env.environment 是标识符,不是显示名称。使用 env.include 仅注入集合密钥的子集:
密钥如何变成环境变量
为组件解析密钥时:- 在你的 Space 内按标识符查找集合
- 加载限定到指定环境的密钥
- 集合级密钥(无环境)作为默认值包含
- 环境特定的密钥覆盖同名的集合级密钥
- 解析值内的密钥引用
- 密钥名称转换为环境变量格式:大写,非字母数字字符变为下划线
Stripe Secret Key 的密钥变成 STRIPE_SECRET_KEY。
每个密钥都有一个主体模式,决定它的注入方式:
string密钥(API 密钥、令牌、URI)作为纯标量字符串注入json密钥(结构化配置)作为 JSON 字符串注入fields密钥(登录凭证、类型化字段包)作为 JSON 字符串注入
密钥何时注入
模板引用
密钥值可以使用 Kazzle 在其他地方使用的相同语法引用其他密钥字段:${secret.<uuid>.<field>}——密钥值或工具参数内的特定字段或 JSON 路径,其中启用了保险库引用。${secret.<uuid>}——整个密钥主体。仅在工具明确要求整个原始密钥时使用;不要在应用 env/config 中使用。