---
title: "Развёртывание"
description: "Обзор развёртывания Ring Platform — production, preview и self-hosted окружения."
locale: "ru"
---
# Руководство по развёртыванию

Ring Platform поддерживает три целевых окружения развёртывания: **k3s-кластер** (production), **Vercel** (preview) и **Docker** (self-hosted). Платформа использует унифицированную конфигурацию окружения; только `DB_BACKEND_MODE` и `RING_DEPLOY_TARGET` изменяются в зависимости от целевого окружения.

> **Info**
> Эта страница представляет обзор стратегии развёртывания. Пошаговые инструкции смотрите на соответствующих страницах: [Vercel](/docs/deployment/vercel.md), [Docker](/docs/deployment/docker.md), [Self-hosted](/docs/deployment/self-hosted.md) и [Конфигурация окружения](/docs/deployment/environment.md).

### For founders

## Выбор целевого окружения развёртывания

### k3s-кластер (production — рекомендуется)

Основное production-окружение — Kubernetes-кластер (`5.161.246.54`). Все клоны империи Ringdom работают на этом кластере.

- Полноценный PostgreSQL с нативным WSS Tunnel (`TUNNEL_HUB_MODE=k8s-postgres`)
- Все функции реального времени (обмен сообщениями, совместная работа, живые уведомления)
- WayForPay платёжные вебхуки
- Cron-задачи для очистки имён пользователей, майнинга рефкодов

### Vercel (preview)

Vercel подходит для preview-развёртываний и быстрого прототипирования. Бессерверные обработчики маршрутов работают на Vercel Edge — собственный сервер (`server.ts`) не используется, поэтому нативный WebSocket Tunnel недоступен. Tunnel переключается на SSE + длинный опрос.

- Установите `RING_DEPLOY_TARGET=vercel` и `NEXT_PUBLIC_RING_DEPLOY_TARGET=vercel`
- Используйте `DB_BACKEND_MODE=firebase-full` (Firestore) или `k8s-postgres-fcm` (требуется доступный PostgreSQL хост)
- WayForPay вебхуки требуют публичной конечной точки — функции Vercel обрабатывают это нативно

### Docker (self-hosted)

Развёртывание Docker задокументировано для самостоятельного размещения сообществом (OSS-репозиторий). `Dockerfile` создаёт production-образ с собственным сервером (`server.ts`) и поддержкой нативного WSS Tunnel. PostgreSQL работает как сопутствующий контейнер или внешний сервис.

- Полная паритетность функций с k3s-развёртыванием
- PostgreSQL обязателен (`DB_BACKEND_MODE=k8s-postgres-fcm`)
- Смотрите [Развёртывание Docker](/docs/deployment/docker.md) и [Самостоятельное размещение](/docs/deployment/self-hosted.md)

## Стратегия переменных окружения

Единственным источником истины для всех переменных окружения является `env.local.template` в корне репозитория. Ключевые решения:

| Переменная | Назначение |
|------------|------------|
| `DB_BACKEND_MODE` | Адаптер базы данных: `k8s-postgres-fcm` (рекомендуется), `firebase-full` или `supabase-fcm` |
| `RING_DEPLOY_TARGET` | Режим Tunnel и среды выполнения: `k8s`, `vercel` или `self-hosted` |
| `AUTH_SECRET` | Шифрование сессий Auth.js (сгенерировать с помощью `openssl rand -base64 32`) |
| `AUTH_GOOGLE_ID` / `AUTH_GOOGLE_SECRET` | Учётные данные Google OAuth |

Полный справочник переменных смотрите в [Конфигурация окружения](/docs/deployment/environment.md).

> **Warning**
> Никогда не коммитьте реальные секреты в Git. Скопируйте `env.local.template` в `.env.local` (входит в gitignore) и заполните production-значения. На k3s инжектируйте секреты через Kubernetes secrets; на Vercel используйте переменные окружения панели управления Vercel.

### For developers

## Предварительные требования для всех целевых окружений

- Node.js 20+ (рекомендуется 22)
- npm или pnpm
- Экземпляр PostgreSQL (для режимов `k8s-postgres-fcm` и `supabase-fcm`)
- Firebase-проект (необязательно — только если нужны FCM push-уведомления)

## Целевые окружения развёртывания

### 1. k3s-кластер (production)

Production k3s-кластер использует Kubernetes-манифесты (не включены в публичный OSS-репозиторий). Развёртывание управляется через Ring CLI и CI/CD-конвейер.

Необходимые переменные окружения для production:

```bash
# База данных
DB_BACKEND_MODE=k8s-postgres-fcm
DB_HOST=postgres.ring-platform-org.svc.cluster.local
DB_PORT=5432
DB_NAME=ring_platform
DB_USER=ring_user
DB_PASSWORD=
DB_SSL=true
DB_POOL_SIZE=20
DB_TIMEOUT=30000

# Auth.js
AUTH_SECRET=
AUTH_GOOGLE_ID=
AUTH_GOOGLE_SECRET=

# Tunnel
RING_DEPLOY_TARGET=k8s
NEXT_PUBLIC_RING_DEPLOY_TARGET=k8s
TUNNEL_HUB_MODE=k8s-postgres

# Firebase Admin (FCM только — необязательно)
AUTH_FIREBASE_PROJECT_ID=
AUTH_FIREBASE_CLIENT_EMAIL=
AUTH_FIREBASE_PRIVATE_KEY=""

# Платежи
WAYFORPAY_MERCHANT_ACCOUNT=
WAYFORPAY_SECRET_KEY=
```

В production чувствительные значения инжектируются через Kubernetes secrets во время выполнения, а не встраиваются в Docker-образ.

### 2. Vercel

Развёртывание Vercel использует бессерверные обработчики маршрутов. Собственный сервер (`server.ts`) не используется — Tunnel работает в режиме SSE + длинный опрос.

**vercel.json** (платформа поставляется с этим файлом):

```json
{
  "crons": [
    {
      "path": "/api/cron/cleanup-usernames",
      "schedule": "*/5 * * * *"
    }
  ]
}
```

> **Tip**
> Установите `RING_DEPLOY_TARGET=vercel` и `NEXT_PUBLIC_RING_DEPLOY_TARGET=vercel` в панели управления Vercel. Без этого Tunnel может пытаться инициализировать нативный WebSocket, недоступный в бессерверном окружении.

Шаги:

1. Запушьте репозиторий на GitHub
2. Импортируйте проект в Vercel
3. Установите переменные окружения в панели управления Vercel (все `DB_*`, `AUTH_*`, `NEXT_PUBLIC_*`, `WAYFORPAY_*` и т.д.)
4. Разверните основную ветку

Подробности смотрите в [Развёртывание Vercel](/docs/deployment/vercel.md).

### 3. Docker (self-hosted)

`Dockerfile` создаёт многостадийный production-образ с собственным сервером и нативным WSS Tunnel. Он использует `dumb-init` как точку входа и выполняет проверку состояния на `/api/health`.

Сборка:

```bash
docker build \
  --platform linux/amd64 \
  --build-arg AUTH_SECRET="your-auth-secret" \
  --build-arg DB_BACKEND_MODE=k8s-postgres-fcm \
  --build-arg DB_HOST=postgres.example.com \
  --build-arg DB_PORT=5432 \
  --build-arg DB_NAME=ring_platform \
  --build-arg DB_USER=ring_user \
  --build-arg NEXT_PUBLIC_APP_URL=https://your-domain.com \
  --build-arg NEXT_PUBLIC_API_URL=https://your-domain.com \
  -t ring-platform .
```

> **Warning**
> Только безопасные для времени сборки переменные (`NEXT_PUBLIC_*`, `DB_BACKEND_MODE`) должны передаваться как build args. Чувствительные секреты (`AUTH_GOOGLE_SECRET`, `DB_PASSWORD`, `WAYFORPAY_SECRET_KEY`) инжектируются во время выполнения через переменные окружения или менеджеры секретов.

Запуск:

```bash
docker run -d \
  -p 3000:3000 \
  -e AUTH_SECRET= \
  -e AUTH_GOOGLE_ID= \
  -e AUTH_GOOGLE_SECRET= \
  -e DB_BACKEND_MODE=k8s-postgres-fcm \
  -e DB_HOST=postgres.example.com \
  -e DB_PORT=5432 \
  -e DB_NAME=ring_platform \
  -e DB_USER=ring_user \
  -e DB_PASSWORD= \
  -e DB_SSL=true \
  -e RING_DEPLOY_TARGET=self-hosted \
  -e NEXT_PUBLIC_RING_DEPLOY_TARGET=self-hosted \
  ring-platform
```

Смотрите [Развёртывание Docker](/docs/deployment/docker.md) для конфигурации docker-compose и настройки PostGIS, а также [Самостоятельное размещение](/docs/deployment/self-hosted.md) для OSS-настройки сообщества с помощью `install.sh`.

## Настройка базы данных для разных целевых окружений

Платформа использует единый уровень абстракции базы данных через `getDatabaseService()` (см. `lib/database/DatabaseService.ts`). Активный адаптер выбирается с помощью `DB_BACKEND_MODE`:

- **`k8s-postgres-fcm`** — PostgreSQL для всех CRUD, Firebase Admin SDK только для FCM push. Рекомендуется для production и локальной разработки.
- **`firebase-full`** — Firestore (Firebase) для всех CRUD. Самая быстрая настройка для прототипирования и Vercel.
- **`supabase-fcm`** — Supabase PostgreSQL для базы данных, Firebase Admin SDK только для FCM push.

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

```bash
# Проверка соединения с базой данных (любой режим)
# Использует getDatabaseService() — НЕ Firebase client SDK
# lib/firebase.ts не существует в этой кодовой базе
```

> **Info**
> Firestore client SDK (`db.collection(...).doc(...).get()`) не используется в этой платформе. Весь доступ к базе данных осуществляется через `getDatabaseService()` с методами `findById(collection, id)`, `create(collection, data)`, `update(collection, id, data)`, `delete(collection, id)` и `query({ collection, filters?, orderBy?, pagination? })`.

## Устранение неполадок

### Сбой сборки с ошибками TypeScript

Очистите кеш и повторите попытку:

```bash
rm -rf .next node_modules
npm install
npm run type-check
npm run build
```

### Сессия Auth.js не работает

Убедитесь, что `AUTH_SECRET` установлен и одинаков во всех развёртываниях. Auth.js v5 использует `AUTH_SECRET` (не `NEXTAUTH_SECRET`). Переменные Google OAuth: `AUTH_GOOGLE_ID` и `AUTH_GOOGLE_SECRET` (не `GOOGLE_CLIENT_ID`).

### Отказано в соединении с базой данных

Проверьте, доступен ли PostgreSQL из целевого окружения развёртывания:

```bash
# Из k3s pod
kubectl exec deploy/ring-platform -- wget -qO- http://postgres:5432

# Из Docker
docker exec ring-platform nc -zv postgres.example.com 5432
```

Убедитесь, что `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER` и `DB_PASSWORD` соответствуют вашей конфигурации PostgreSQL.

### Tunnel / WebSocket не подключается

Убедитесь, что `RING_DEPLOY_TARGET` и `NEXT_PUBLIC_RING_DEPLOY_TARGET` установлены. На Vercel нативный WebSocket недоступен — Tunnel автоматически переключается на SSE + длинный опрос. На k3s или Docker убедитесь, что `TUNNEL_HUB_MODE=k8s-postgres` установлен.

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