---
title: "Конфигурация Окружения"
description: "Обязательные и опциональные переменные окружения для Ring Platform — бэкенд базы данных, Firebase Admin SDK, FCM, платежи, локали, Tunnel."
locale: "ru"
---
# Конфигурация Окружения

> **Info**
> Эта страница является **каноническим справочником** для каждой переменной окружения, используемой Ring Platform.
>   Источником правды является `env.local.template` в корне репозитория — когда сомневаетесь, обращайтесь к этому файлу.
>   Используйте вкладки **Основатель** / **Разработчик** в боковой панели для фильтрации по аудитории.

## `DB_BACKEND_MODE` (обязательно)

Ring Platform требует `DB_BACKEND_MODE` во время выполнения. Он определяет, какой адаптер базы данных активен и как настроены FCM push уведомления.

| Значение | База данных приложения | Firebase Admin для Firestore? | Push |
|----------|----------------------|-------------------------------|------|
| `k8s-postgres-fcm` | PostgreSQL (ваш кластер) | Нет — mock Firestore | FCM через Firebase Admin messaging |
| `firebase-full` | Firestore | Да | FCM как часть полного стека Firebase |
| `supabase-fcm` | Supabase PostgreSQL | Нет — mock Firestore | FCM через Firebase Admin messaging |

См. [Режимы бэкенда и базы данных](/docs/architecture/backend-modes-and-databases.md) для глубокого сравнения.

### For founders

## Firebase: когда это нужно?

Ваш Ring клон **может** потребовать учетные данные Firebase в двух контекстах:

1. **Push уведомления (FCM)** — требуется во всех трех значениях `DB_BACKEND_MODE`, если вы хотите доставку push. Firebase используется как транспорт FCM; ваши данные приложения остаются в PostgreSQL.
2. **Полный Firestore бэкенд** — только когда `DB_BACKEND_MODE=firebase-full`. В этом режиме Firebase Admin SDK служит основной базой данных.

**Если вам не нужны push уведомления**, вы можете пропустить все переменные окружения Firebase. Платформа работает на PostgreSQL самостоятельно.

Firebase Admin SDK v14 использует **Application Default Credentials (ADC)** в `FirebaseAdapter` (уровень абстракции базы данных). Для пути FCM/auth (`firebase-admin.server.ts`) явные учетные данные сервисного аккаунта через `AUTH_FIREBASE_CLIENT_EMAIL` + `AUTH_FIREBASE_PRIVATE_KEY` все еще требуются, когда ADC не настроен.

В продакшене (Cloud Run, Cloud Functions, GKE) ADC автоматически определяет учетные данные из окружения. Вам нужен только `AUTH_FIREBASE_PROJECT_ID`. В локальной разработке или CI предоставьте полный набор ключей сервисного аккаунта.

### For developers

## Бэкенд базы данных

```bash
# Обязательно — выбирает адаптер базы данных + FCM подключение
DB_BACKEND_MODE=k8s-postgres-fcm

# PostgreSQL подключение (обязательно для k8s-postgres-fcm и supabase-fcm)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ring_platform
DB_USER=ring_user
DB_PASSWORD=ring_password_2024
DB_POOL_SIZE=20
DB_TIMEOUT=30000
DB_RETRIES=3
DB_SSL=false
```

Каноническая dev настройка использует `ring-postgres-dev` (postgres:16-alpine). См. `docker-compose.dev.yml`.

## Firebase Admin SDK (серверная часть)

```bash
# Минимум для FCM-только использования:
AUTH_FIREBASE_PROJECT_ID=your_firebase_project_id

# Требуется когда ADC не настроен (локальная разработка / CI):
AUTH_FIREBASE_CLIENT_EMAIL=your_firebase_client_email
AUTH_FIREBASE_PRIVATE_KEY="your_firebase_private_key"

# Опционально
FIREBASE_DATABASE_URL=https://your-project-default-rtdb.firebaseio.com
FIREBASE_PRIVATE_KEY_ID=your_firebase_private_key_id
FIREBASE_CLIENT_ID="your_firebase_client_id"
FIREBASE_FIRESTORE_DEBUG=true
```

- **`lib/firebase-admin.server.ts`** (FCM + Auth путь): всегда требует `AUTH_FIREBASE_PROJECT_ID`. Когда `AUTH_FIREBASE_CLIENT_EMAIL` и `AUTH_FIREBASE_PRIVATE_KEY` присутствуют, использует явный `cert()`. Откатывается к ADC если они отсутствуют.
- **`lib/database/adapters/FirebaseAdapter.ts`** (абстракция базы данных): использует ADC сначала. Если `credentials.clientEmail` и `credentials.privateKey` есть в конфигурации бэкенда, откатывается к явному `cert()`. Этот путь активен только в режиме `firebase-full`.

> **Tip**
> На Cloud Run / Cloud Functions / GKE: установите только `AUTH_FIREBASE_PROJECT_ID`. SDK автоматически определяет учетные данные через ADC.
>   В локальной разработке: установите `AUTH_FIREBASE_CLIENT_EMAIL` и `AUTH_FIREBASE_PRIVATE_KEY` из вашего JSON ключа сервисного аккаунта.

## Firebase Client SDK (браузерная часть)

Требуется когда ваш Ring клон использует Firebase для **клиентских функций** (регистрация FCM push токенов, FirebaseUI auth):

```bash
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_firebase_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-YCZKPV315E
NEXT_PUBLIC_FIREBASE_VAPID_KEY=your_vapid_key
```

Получите их из **Firebase Console → Project Settings → General → Web apps**.

## Провайдеры аутентификации

```bash
# Auth.js core
AUTH_SECRET=your_auth_secret
AUTH_TRUST_HOST=true

# Google OAuth (обязательно для входа через Google)
AUTH_GOOGLE_ID=your_google_client_id
AUTH_GOOGLE_SECRET=your_google_client_secret

# Apple Sign-In (обязательно для входа через Apple)
AUTH_APPLE_ID=your_apple_client_id
AUTH_APPLE_SECRET=your_apple_private_key

# Magic links (опционально — использует Resend)
# Ring Mailer: EMAIL_MODE=ethereal or SMTP_HOST / SMTP_USER / SMTP_PASSWORD
# OTP_HMAC_SECRET=
```

Auth.js v5 читает переменные с префиксом `AUTH_*` автоматически для каждого провайдера. См. [Архитектура аутентификации](/docs/architecture/authentication.md).

## Платежи (PaymentConductor)

```bash
# Процессор по умолчанию
PAYMENT_DEFAULT_PROCESSOR=wayforpay

# Переопределения по назначению (опционально)
PAYMENT_STORE_PROCESSOR=wayforpay
PAYMENT_MEMBERSHIP_PROCESSOR=wayforpay
PAYMENT_NEWS_PROCESSOR=wayforpay

# WayForPay
WAYFORPAY_MERCHANT_ACCOUNT=your_merchant
WAYFORPAY_SECRET_KEY=your_secret

# Stripe (альтернатива)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
PAYMENT_FIAT_CURRENCY=UAH
```

Примените `data/migrations/004_payment_transactions.sql` перед продакшн платежами.

## Локали

```bash
NEXT_PUBLIC_SUPPORTED_LOCALES=en,uk,ru
NEXT_PUBLIC_DEFAULT_LOCALE=en
```

См. `lib/locale-config.ts`. Поддерживаемые локали: `en`, `uk`, `ru`.

## Генеративные кондукторы (xAI Grok)

```bash
XAI_API_KEY=your_xai_key
XAI_API_BASE_URL=https://api.x.ai/v1
```

Префиксы по назначению:
- `IMAGE_GEN_*` / `XAI_IMAGE_*` — ImageConductor
- `TEXT_GEN_*` / `XAI_TEXT_*` — TextConductor (цитируемые статьи)
- `TTS_*` / `XAI_TTS_*` — AudioConductor (озвучка)
- `NEWS_AUTOGEN_*` — стандартные настройки новостной редакции

Требует `FILE_BACKEND=ringbase` с `RINGBASE_API_URL` и `RINGBASE_API_TOKEN` для CDN загрузок.

## Ring Tunnel (реальное время)

```bash
# vercel | k8s | self-hosted
RING_DEPLOY_TARGET=self-hosted
NEXT_PUBLIC_RING_DEPLOY_TARGET=self-hosted

# Опциональная явная WS URL (по умолчанию: тот же хост /api/tunnel/ws)
# NEXT_PUBLIC_TUNNEL_WS_URL=wss://ring-platform.org/api/tunnel/ws
```

## Функциональные флаги

```bash
FEATURE_DOCUMENTATION=true
FEATURE_NETWORKING=true
FEATURE_MESSAGING=true
FEATURE_WALLET=true
FEATURE_AI_MATCHER=true
FEATURE_WEB3_INTEGRATION=true
```

## Платформа

```bash
NEXT_PUBLIC_BASE_URL=https://ring-platform.org
NODE_ENV=development
```

## Опционально — Email AI-CRM, CRON, резервное копирование

См. `env.local.template` для полного комментированного справочника. Ключевые опциональные блоки:

```bash
# Email CRM (IMAP опрос + админ интерфейс)
# IMAP_HOST=mail.example.com
# IMAP_PORT=993
# ...

# CRON защита
# CRON_SECRET=generate-a-long-random-string

# Резервное копирование и соответствие
# BACKUP_ENABLED=true
# BACKUP_SCHEDULE=0 2 * * *
```

> **Warning**
> **Никогда не коммитьте реальные секреты в Git.** Файл `env.local.template` использует значения-заполнители. Скопируйте его в `.env.local` (gitignored) и заполните своими продакшн значениями. Используйте K8s секреты или хранилище секретов вашей системы развертывания для продакшна.

## Связанная документация