> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Секреты

> Зашифрованное хранилище для API-ключей, учетных данных и конфиденциальной конфигурации.

# Секреты

Kazzle имеет встроенное зашифрованное хранилище для сохранения API-ключей, учетных данных базы данных, токенов и других конфиденциальных значений, необходимых вашему приложению. Секреты зашифрованы в покое с помощью AES-256-GCM с использованием ключей шифрования данных, обернутых KMS — открытые значения никогда не попадают в базу данных.

## Концепции

**Коллекции** группируют связанные секреты вместе (например, `stripe-keys`, `database-credentials`). Каждая коллекция имеет **slug** (строчные буквы, через дефис), на который вы ссылаетесь в файлах конфигурации и командах CLI.

**Окружения** — это необязательные области видимости в коллекции (например, `production`, `staging`). Секреты могут быть привязаны к конкретному окружению или оставлены на уровне коллекции как значения по умолчанию.

**Порядок разрешения:** при разрешении секретов для данной коллекции + окружения секреты, специфичные для окружения, переопределяют секреты уровня коллекции с тем же именем. Это позволяет вам делиться большинством секретов между окружениями, переопределяя конкретные значения для каждого окружения.

## Управление секретами

### В приложении

Откройте **Settings > Vault** для создания коллекций, окружений и секретов через интерфейс.

### С помощью ИИ

ИИ может создавать коллекции, создавать окружения, сохранять секреты, перемещать их между областями видимости и удалять их для вас.

ИИ видит имена секретов и метаданные, но не зашифрованные значения.

### С помощью CLI

```bash theme={"theme":"material-theme-darker"}
# Экспортировать секреты как строки KEY=value
kazzle secrets.export --collection=stripe-keys --env=production
```

## Ссылки на секреты из вашего приложения

Укажите `env` компонента на коллекцию секретов и окружение в `kazzle.config.ts`. Каждый секрет в этой области видимости внедряется как переменная окружения процесса, имя которой совпадает с именем секрета:

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

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

`env.collection` и `env.environment` — это **slugs**, а не отображаемые имена. Используйте `env.include` для внедрения только подмножества секретов коллекции:

```typescript theme={"theme":"material-theme-darker"}
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-строки

## Когда внедряются секреты

| Контекст                        | Внедряется? | Детали                                                                                 |
| ------------------------------- | ----------- | -------------------------------------------------------------------------------------- |
| **Deploy** (компонент процесса) | Да          | Добавляется как переменные окружения выполнения в production                           |
| **Deploy** (компонент UI)       | Частично    | Только секреты с префиксом `VITE_*` передаются во время сборки                         |
| **CLI** (`kazzle run`)          | Да          | Внедряется в окружение команды                                                         |
| **CLI** (`secrets.export`)      | Да          | Экспортируется как строки `KEY=value`                                                  |
| **Dev preview**                 | Еще нет     | Стартер предпросмотра еще не разрешает компонент `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>}` — все тело секрета. Используйте только когда инструмент явно запрашивает весь необработанный секрет; не используйте это в конфигурации/окружении приложения.

Ссылки разрешаются после загрузки секретов. Циклические или неработающие ссылки приводят к ошибке вместо молчаливого отката.