---
title: "Ring CDN (edge RingFileBase)"
description: "CDN edge на NGINX для клонів Ring — публічні шляхи /files (оригінали та похідні {fileId}_v_*), зіставлення host-to-bucket, доставка в кількох зонах"
locale: "uk"
---
# Ring CDN (edge RingFileBase)

> **Info**
> Використовуйте вкладки **Founder** / **Developer** на бічній панелі документації, щоб відфільтрувати цю сторінку. Завантаження описано в [RingFileBase](/docs/integrations/ring-filebase.md); ця сторінка охоплює **публічну доставку**. Публічні галереї [Ring File Cabinet](/docs/features/file-cabinet.md) (`/{username}/img`) віддають елементи з `visibility=public` через стабільні CDN URL `/files/{uuid}`.

**Ring CDN** — це шлях читання для об’єктів, які зберігає RingFileBase: edge на NGINX (`ring-filebase-cdn`), що проксує `GET /files/` до MinIO (або RGW) із заголовками кешування. Браузерам і crawler-ам не потрібні облікові дані MinIO. Ключі містять оригінали (`/files/{uuid}`) і похідні (`/files/{uuid}_v_thumb.webp`, `/files/{uuid}_v_video_frame_0_480.webp`, …) — та сама схема `{fileId}_v_*`, що й у [RingFileBase](/docs/integrations/ring-filebase.md).

| Шар | Компонент | Namespace (типовий) |
|-------|-----------|---------------------|
| Edge | `ring-filebase-cdn` Deployment + Ingress | `ring-filebase` |
| Origin | `minio-service` | `ring-filebase-minio` |
| Writer | `ring-filebase-api` | `ring-filebase` |

Публічні хости мають формат `cdn.` (приклади в empire: `cdn.ring-platform.org`, `cdn.greenfood.live`, `cdn.vikka.ua`).

### For founders

## Чому це важливо для вашого клону

Користувачі та пошукові системи завантажують фото продуктів, аватари й згенеровані медіа зі **стабільного CDN-хоста**, а не з pod-ів вашого застосунку. Це звільняє Next.js від великих статичних payload-ів, дає змогу агресивно кешувати дані й розміщувати edge ближче до учасників (US / EU / UA) без змін у коді застосунку.

### Типові сценарії

  
- **[White-label CDN бренду](/docs/examples/white-label.md)** — Зіставте `cdn.yourdomain` → ваш bucket MinIO через Ingress + NGINX `map $host $target_bucket`.

  
- **[Медіа маркетплейсу](/docs/features/store.md)** — Збережіть зображення продуктів один раз через RingFileBase; віддавайте їх безстроково з CDN URL, збережених у Postgres.

  
- **[File Cabinet /img](/docs/features/file-cabinet.md)** — Відібрані елементи публічної галереї вбудовують CDN `/files/{uuid}` (+ похідні `_v_*`) — у поточному адаптері немає підписаних URL із HMAC/TTL.

  
- **[Генеративні медіа](/docs/development/generative-images.md)** — Результати ImageConductor / VideoConductor мають потрапляти до RingFileBase, щоб OG і ресурси newsroom використовували CDN URL.

  
- **[Резервне копіювання ops](/docs/deployment/backup.md)** — CDN — це кеш: створюйте резервну копію **bucket MinIO/RGW**, а не лише NGINX PVC.

  1. DNS `cdn.` → IP-адреса(и) cluster ingress.  
  2. Сертифікат TLS на CDN Ingress.  
  3. App `RINGBASE_PUBLIC_URL=https://cdn.`.  
  4. Переконайтеся, що відома URL `/files/...` повертає **200** у браузері.

### For developers

## Шлях запиту

```mermaid
sequenceDiagram
  participant Browser as Браузер
  participant Ingress as nginx Ingress
  participant CDN as ring-filebase-cdn
  participant MinIO as minio-service:9000
  Browser->>Ingress: GET https://cdn.host/files/key
  Ingress->>CDN: HTTP :80
  CDN->>CDN: map host → bucket
  CDN->>MinIO: GET /bucket/key
  MinIO-->>CDN: object bytes
  CDN-->>Browser: 200 + Cache-Control
```

### Перевірені поверхні конфігурації

| Шлях | Роль |
|------|------|
| `infrastructure/k3s-3/ring-filebase/10-cdn-config.yaml` | NGINX `map $host $target_bucket` + location `/files/` |
| `infrastructure/ring-file-base/k8s/ring-filebase/cdn-*-ingress.yaml` | Ingress для кожного домену + TLS |
| `infrastructure/ring-file-base/k8s/ring-filebase/20-cdn-deployment.yaml` | CDN Deployment |
| App ConfigMap | `RINGBASE_PUBLIC_URL`, необов’язковий `REFMAGIC_CDN_INTERNAL_URL` (CDN у кластері) |

### Host → bucket map (патерн)

Конфігурація CDN зіставляє Host header з назвою bucket MinIO, а потім проксує:

`/files/` → `http://minio_backend//`

Приклад зіставлення, який використовується в конфігураціях empire:

| Host | Bucket |
|------|--------|
| `cdn.ring-platform.org` | `ring-filebase` |
| `cdn.greenfood.live` | `ring-filebase` |
| `cdn.vikka.ua` | `ring-vikka-ua` |

**Ключі** об’єктів — це все, що записав `ring-filebase-api` (деякі розгорнуті образи API досі додають до ключів префікс сегмента проєкту, наприклад `ring-greenfood-live/`). Шлях CDN завжди має вигляд `/files/` + цей ключ.

### Підключення застосунку

| Змінна | Призначення |
|----------|---------|
| `RINGBASE_PUBLIC_URL` | Абсолютний origin, вбудований у відповіді завантаження (`https://cdn.`) |
| `REFMAGIC_CDN_INTERNAL_URL` | Необов’язкове внутрішньокластерне отримання (`http://ring-filebase-cdn.ring-filebase.svc.cluster.local`) |
| `CDN_URL` | Необов’язковий застарілий/закоментований прапорець у `env.local.template` — для RingFileBase надавайте перевагу `RINGBASE_PUBLIC_URL` |

### Edge-зони (довідка empire)

Ringdom працює з CDN edge як з **географічним набором** (описано в AI-CONTEXT `cdn-edge-architecture`): US (k3s-1 / Ashburn), EU (Finland), UA (k8s). У кожній зоні працюють локальні MinIO + CDN proxy; DNS може публікувати кілька A/AAAA-записів для `cdn.*`. Ваш клон може використовувати лише одну зону — все одно дотримуйтеся того самого контракту `/files/`.

### Кроки оператора

### Створіть bucket + публічне читання для CDN

Об’єкти MinIO часто завантажуються з приватним ACL. CDN proxy потребує **анонімного GetObject** (або еквівалентного підписаного fetch) для bucket, інакше браузери побачать **403** XML від MinIO через NGINX.

### Розгорніть CDN + Ingress

Застосуйте ConfigMap-и CDN, Deployment, Service та Ingress `cdn.` із TLS від cert-manager. Переконайтеся, що `server_name` містить ваш хост.

### Спрямуйте застосунок на публічний origin

Задайте `RINGBASE_PUBLIC_URL=https://cdn.`, щоб `RingBaseAdapter` / відповіді API повертали CDN URL. Після змін ConfigMap перезапустіть Ring Deployment.

### Перевірте

{`# From an app pod (no TLS issues)
curl -sS -o /dev/null -w "%{http_code}\n" \
  http://ring-filebase-cdn.ring-filebase.svc.cluster.local/files/

# Public
curl -sS -o /dev/null -w "%{http_code}\n" \
  https://cdn./files/`}

Очікуйте **200**. **403** → політика bucket / ACL. **404** → неправильне зіставлення bucket або префікс ключа.

### Нотатки з безпеки

- CDN є **лише для читання** щодо `/files/` — завантаження проходять через RingFileBase API з Bearer auth.
- Не відкривайте console MinIO або S3 API публічно без потреби; залишайте `minio-service` як ClusterIP.
- Плоскі ключі `/files/` зменшують можливість переліку директорій порівняно з деревами папок за датами (див. нотатки з посилення безпеки RingFileBase в AI-CONTEXT).

## Пов’язана документація

- [integrations/ring-filebase](/docs/integrations/ring-filebase.md) — Передумова: автентифіковані завантаження та file() / RingBaseAdapter перед публічним читанням CDN.

- [features/file-cabinet](/docs/features/file-cabinet.md) — Той самий процес: кураторство галереї учасника → публічний /{username}/img через CDN /files/{uuid}; приватні байти використовують проксі завантаження ACL.

- [deployment/environment](/docs/deployment/environment.md) — Залежність: RINGBASE_PUBLIC_URL і env, пов’язані зі сховищем, для клонів.

- [deployment/performance](/docs/deployment/performance.md) — Див. також: кешування та edge-міркування для клонів.