Sekrety

Kazzle ma wbudowaną zaszyfrowaną skarbnicę do przechowywania kluczy API, poświadczeń bazy danych, tokenów i innych wrażliwych wartości, których potrzebuje Twoja aplikacja. Sekrety są szyfrowane w spoczynku za pomocą AES-256-GCM przy użyciu kluczy szyfrowania danych zawinięte w KMS — wartości w postaci zwykłego tekstu nigdy nie trafiają do bazy danych.

Koncepcje

Kolekcje grupują powiązane sekrety razem (np. stripe-keys, database-credentials). Każda kolekcja ma slug (małe litery, z myślnikami), do którego odwołujesz się w plikach konfiguracyjnych i poleceniach CLI. Środowiska to opcjonalne zakresy w ramach kolekcji (np. production, staging). Sekrety mogą być ograniczone do określonego środowiska lub pozostawione na poziomie kolekcji jako wartości domyślne. Kolejność rozwiązywania: podczas rozwiązywania sekretów dla danej kolekcji + środowiska, sekrety specyficzne dla środowiska zastępują sekrety na poziomie kolekcji o tej samej nazwie. Pozwala to na udostępnianie większości sekretów między środowiskami przy jednoczesnym zastępowaniu określonych wartości dla każdego środowiska.

Zarządzanie sekretami

W aplikacji

Otwórz Ustawienia > Skarbnica aby tworzyć kolekcje, środowiska i sekrety za pośrednictwem interfejsu użytkownika.

Za pomocą AI

AI może tworzyć kolekcje, tworzyć środowiska, przechowywać sekrety, przenosić je między zakresami i usuwać je dla Ciebie. AI widzi nazwy sekretów i metadane, ale nie zaszyfrowane wartości.

Za pomocą CLI

# Uruchom polecenie z wstrzykniętymi sekretami jako zmienne env
kazzle run --collection=stripe-keys --env=production -- bun run server.ts

# Eksportuj sekrety jako linie KEY=value
kazzle secrets.export --collection=stripe-keys --env=production

Odwoływanie się do sekretów z aplikacji

Wskaż env komponentu na kolekcję sekretów i środowisko w kazzle.config.ts. Każdy sekret w tym zakresie jest wstrzykiwany jako zmienna środowiskowa procesu, której nazwa odpowiada nazwie sekretu:

import { defineConfig } from './kazzle.types';

export default defineConfig({
  components: [
    {
      name: 'API Server',
      type: 'process',
      path: './server',
      env: {
        collection: 'stripe-keys',
        environment: 'production'
      }
    }
  ]
});

env.collection i env.environment to slugi, nie nazwy wyświetlane. Użyj env.include aby wstrzyknąć tylko podzbiór sekretów kolekcji:

env: {
  collection: 'stripe-keys',
  environment: 'production',
  include: ['STRIPE_SECRET_KEY']
}

Jak sekrety stają się zmiennymi env

Gdy sekrety są rozwiązywane dla komponentu:

Kolekcja jest znaleziona po slugu w ramach Twojej przestrzeni
Sekrety ograniczone do określonego środowiska są ładowane
Sekrety na poziomie kolekcji (bez środowiska) są dołączane jako wartości domyślne
Sekrety specyficzne dla środowiska zastępują sekrety na poziomie kolekcji o tej samej nazwie
Odwołania do sekretów wewnątrz wartości są rozwiązywane
Nazwy sekretów są konwertowane na format zmiennej env: wielkie litery, znaki niealfanumeryczne stają się podkreśleniami

Sekret o nazwie Stripe Secret Key staje się STRIPE_SECRET_KEY. Każdy sekret ma tryb treści, który określa sposób jego wstrzyknięcia:

Sekrety string (klucze API, tokeny, URI) są wstrzykiwane jako zwykłe skalarne ciągi znaków
Sekrety json (konfiguracja strukturalna) są wstrzykiwane jako ciągi JSON
Sekrety fields (poświadczenia logowania, worki pól typowanych) są wstrzykiwane jako ciągi JSON

Kiedy sekrety są wstrzykiwane

Kontekst	Wstrzykiwane?	Szczegóły
Wdrażanie (komponent procesu)	Tak	Dodane jako zmienne środowiskowe czasu wykonywania w produkcji
Wdrażanie (komponent UI)	Częściowo	Tylko sekrety z prefiksem `VITE_*` są przekazywane w czasie kompilacji
CLI (`kazzle run`)	Tak	Wstrzykiwane do środowiska polecenia
CLI (`secrets.export`)	Tak	Eksportowane jako linie `KEY=value`
Podgląd deweloperski	Jeszcze nie	Starter podglądu nie rozwiązuje jeszcze `env` komponentu — na razie użyj `kazzle run`

Odwołania do szablonów

Wartości sekretów mogą odwoływać się do innych pól sekretów przy użyciu tej samej składni, którą Kazzle używa w innym miejscu:

postgresql://${secret.123e4567-e89b-12d3-a456-426614174000.username}:${secret.123e4567-e89b-12d3-a456-426614174000.password}@db.example.com:5432/mydb

Obsługiwane formaty:

${secret.<uuid>.<field>} — określone pole lub ścieżka JSON. Użyj tego formatu dla env/konfiguracji aplikacji.
${secret.<uuid>} — całe ciało sekretu. Używaj tylko gdy narzędzie wyraźnie prosi o cały surowy sekret; nie używaj tego w env/konfiguracji aplikacji.

Odwołania są rozwiązywane po załadowaniu sekretów. Odwołania cykliczne lub uszkodzone kończą się niepowodzeniem zamiast dyskretnie wracać do wartości domyślnych.

​Sekrety

​Koncepcje

​Zarządzanie sekretami

​W aplikacji

​Za pomocą AI

​Za pomocą CLI

​Odwoływanie się do sekretów z aplikacji

​Jak sekrety stają się zmiennymi env

​Kiedy sekrety są wstrzykiwane

​Odwołania do szablonów