메인 콘텐츠로 건너뛰기

​
시크릿

Kazzle은 API 키, 데이터베이스 자격증명, 토큰 및 앱에 필요한 기타 민감한 값을 저장하기 위한 내장 암호화 저장소를 제공합니다. 시크릿은 KMS로 래핑된 데이터 암호화 키를 사용하여 AES-256-GCM으로 저장 시 암호화되며, 평문 값은 데이터베이스에 저장되지 않습니다.

​
개념

컬렉션은 관련 시크릿을 함께 그룹화합니다(예: stripe-keys, database-credentials). 모든 컬렉션에는 설정 파일과 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는 슬러그이며, 표시 이름이 아닙니다. 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>} — 전체 시크릿 본문. 도구가 전체 원본 시크릿을 명시적으로 요청할 때만 사용하며, 앱 환경/설정에서는 사용하지 마세요.
참조는 시크릿이 로드된 후 해석됩니다. 순환 또는 손상된 참조는 자동으로 폴백되지 않고 실패합니다.