Зберігання файлів і керування вмістом

Ваш застосунок має окрему файлову систему вмісту для зберігання файлів, які завантажують користувачі, — зображень, документів, PDF і відео. Вона відокремлена від коду застосунку та призначена для динамічного вмісту, який користувачі створюють або завантажують під час роботи з вашим застосунком.

Обмеження та важливі зауваження

  • Розмір окремого файлу може сягати 500 МБ
  • Видалення файлу є остаточним — кошика немає
  • Використаний обсяг сховища враховується в квоті вашого облікового запису

Що дає файлова система вмісту

Файлова система вмісту надає вашому застосунку потужні можливості керування файлами:

  • Зберігати аватари користувачів, фото профілю та галереї зображень
  • Приймати завантаження документів, як-от резюме, договорів чи PDF
  • Створювати функції обміну файлами між користувачами вашого застосунку
  • Створювати застосунки з великою кількістю зображень з автоматичною оптимізацією
  • Давати користувачам змогу завантажувати файли, які вони відправили або які їм належать
  • Створювати адміністративні інструменти, за допомогою яких ви керуєте файлами від імені користувачів

Як це працює

Коли ви описуєте ШІ функцію, якій потрібне сховище файлів, він автоматично виконує всю реалізацію:

Налаштовує інтерфейс завантаження — створює форми або зони перетягування, де користувачі можуть вибирати файли зі свого пристрою

Налаштовує контроль доступу — визначає, хто може переглядати, завантажувати чи видаляти файли, залежно від того, що ви створюєте

Реалізує оптимізацію зображень — автоматично змінює розмір і ефективно віддає зображення, щоб ваш застосунок швидко завантажувався

Створює структуру сховища — упорядковує файли в логічні папки, як-от /content/uploads/ або /content/avatars/

Бере на себе серверну частину — самостійно виконує зберігання, пошук і доставку файлів, так що вам не потрібно про це думати

Файли зберігаються за шляхами на кшталт /content/uploads/photo.jpg, і на них можна посилатися безпосередньо у вашому застосунку. Система відстежує, хто завантажив кожен файл і коли його створено, та забезпечує дотримання ваших правил доступу.

Контроль доступу до файлів

Як і для таблиць бази даних та edge-функцій, для файлів діють політики безпеки, що визначають, хто може отримати до них доступ. Файли за замовчуванням приватні — ніхто не матиме до них доступу, доки ви не налаштуєте дозволи. ШІ налаштовує їх залежно від того, що ви створюєте:

Публічні файли

Будь-хто може їх переглядати, навіть без входу в систему. Завантажувати можуть користувачі, які ввійшли в систему, а видалити файл може лише той, хто його завантажив. Ідеально підходить для фотогалерей, публічного обміну зображеннями або сайтів із вмістом, створеним користувачами.

Приватні файли

Лише користувач, який завантажив файл, може його переглядати чи видаляти. Використовується для конфіденційних документів, приватних фото, медичних записів і всього, що користувачі не хотіли б показувати іншим.

Файли, спільні в межах організації

Користувачі з однієї організації можуть переглядати файли, завантажені будь-ким із їхньої організації. Окремі користувачі можуть видаляти лише ті файли, які завантажили самі. Чудово підходить для обміну документами в команді, ресурсів компанії або спільних робочих просторів.

Доступ лише для власника

Лише ви (творець застосунку) маєте доступ до цих файлів, а ваші кінцеві користувачі — ні. Корисно для зберігання системних файлів, шаблонів чи адміністративних ресурсів, що забезпечують роботу вашого застосунку, але не мають бути доступними користувачам.

Розширений контроль доступу

ШІ може створювати складні правила доступу на основі метаданих файлів. Наприклад:

  • Опубліковані статті є публічними, а чернетки бачить лише автор
  • Файли з позначкою відділу бачать лише користувачі цього відділу
  • Преміальний вміст вимагає позначки підписки в обліковому записі користувача
  • Спільні файли видно співавторам, указаним у метаданих файлу

Оптимізація зображень

Зображення, завантажені у файлову систему вмісту, автоматично оптимізуються для швидкого завантаження. Коли ви показуєте зображення, можна вказати потрібну ширину, а решту система зробить сама:

<!-- Thumbnail (200px wide) -->
<img src="/content/gallery/photo.jpg?w=200" />

<!-- Standard display (800px wide) -->
<img src="/content/gallery/photo.jpg?w=800" />

<!-- Hero image (1920px wide) -->
<img src="/content/gallery/photo.jpg?w=1920" />

<!-- Original, full-size image -->
<img src="/content/gallery/photo.jpg" />

Як працює оптимізація

Поступове завантаження — коли хтось уперше запитує оптимізований розмір, система віддає найближчу з наявних версій, а точний розмір створює у фоновому режимі. Усі наступні запити отримують зображення ідеального розміру, оптимізоване. Оригінальний файл завжди зберігається.

Доставка в сучасних форматах — система автоматично віддає сучасні формати зображень (AVIF або WebP) браузерам, які їх підтримують, а для старіших браузерів автоматично повертається до JPEG або PNG. Це відбувається непомітно: ви лише вказуєте ширину, а користувачі отримують найшвидшу версію, яку може опрацювати їхній браузер.

Оптимізація продуктивності — використовуйте меншу ширину, щоб підвищити продуктивність. Мініатюра шириною 200 пікселів завантажується набагато швидше за оригінал шириною 4000 пікселів і використовує менше трафіку. Виберіть ширину, що відповідає тому, як ви показуєте зображення.

Використання файлів у вашому застосунку

ШІ автоматично інтегрує файлову систему вмісту у ваш застосунок на React. Коли ви просите про можливості, пов’язані з файлами, він створює компоненти інтерфейсу, підключає логіку завантаження на сервер і з сервера та обробляє помилки.

Типові сценарії, які реалізує ШІ

Завантаження аватара — інтерфейс завантаження фото профілю, який перевіряє типи зображень, показує хід завантаження, відображає попередній перегляд і зберігає шлях у профілі користувача.

Галерея документів — файловий оглядач, який показує список завантажених документів, мініатюри зображень, посилання для завантаження та дає змогу фільтрувати чи шукати.

Завантаження перетягуванням — інтуїтивна зона завантаження, де користувачі можуть перетягувати файли зі свого робочого столу, бачити хід завантаження, скасовувати завантаження, що триває, і отримувати повідомлення про помилки для недійсних файлів.

Вибір файлу — модальне вікно чи бічна панель, що показує файли, які користувач завантажував раніше, дає змогу вибрати один для повторного використання та відображає мініатюри й назви файлів.

Інтеграція з edge-функціями

Edge-функції (ваш серверний код) можуть отримувати доступ до файлової системи вмісту, щоб обробляти файли, створювати їх програмно або реалізовувати власну логіку роботи з файлами.

Що edge-функції можуть робити з файлами

  • Створювати звіти у форматі PDF і зберігати їх, щоб користувачі могли завантажити
  • Обробляти завантажені зображення (накладати водяні знаки, створювати мініатюри, видобувати метадані)
  • Перевіряти завантажені документи на наявність конфіденційних даних, перш ніж їх приймати
  • Реалізовувати власну логіку резервного копіювання чи архівування
  • Аналізувати вміст файлів і видобувати структуровані дані
  • Запускати робочі процеси, коли завантажуються певні файли

Попередження: важлива примітка щодо безпеки

Edge-функції оминають звичайний контроль доступу. Коли ваша функція звертається до файлів, її не обмежують правила «публічний» чи «власник», які діють для користувачів. Це означає, що в коді функції ви маєте реалізувати власні перевірки авторизації, щоб користувачі могли отримати доступ лише до тих файлів, які їм дозволено бачити.

Наприклад, якщо користувач викликає вашу функцію й запитує файл, перед поверненням вмісту потрібно перевірити, що він є власником цього файлу або має дозвіл на доступ до нього. ШІ враховує це під час створення ваших функцій, але важливо розуміти, що код функції виконується з підвищеними привілеями.

Організація сховища

ШІ упорядковує файли в логічні папки залежно від того, що ви створюєте. Вам не потрібно вручну створювати структуру папок — просто опишіть, що вам потрібно, і ШІ налаштує відповідні шляхи.

Типові схеми організації

  • /content/uploads/ — загальні завантаження користувачів
  • /content/avatars/ — фото профілю користувачів
  • /content/documents/ — PDF і документи
  • /content/gallery/ — зображення фотогалереї
  • /content/private/ — приватні файли користувачів
  • /content/public/ — публічно доступні файли
  • /content/temp/ — тимчасові файли, які можна видалити

ШІ може створювати вкладені папки, як-от /content/uploads/2024/ або /content/users/[username]/, коли це доречно для вашого випадку. Файли відстежуються за повним шляхом, тому переміщення чи перейменування файлів автоматично оновлює всі посилання.

Моніторинг і налагодження

Усі операції з файлами записуються в журнал — завантаження на сервер, завантаження з сервера, відмови в доступі та помилки. Ви можете переглядати ці журнали в інтерфейсі адміністратора, щоб зрозуміти, як використовується ваше сховище файлів:

  • Дивіться, які файли завантажують найчастіше
  • З’ясовуйте, які завантаження не вдалися і чому
  • Відстежуйте закономірності завантажень і популярні файли
  • Стежте за використанням сховища та його зростанням у часі
  • Усувайте проблеми з контролем доступу, коли користувачі не бачать файлів, які мали б бачити

Система також відстежує показники сховища — загальну кількість файлів, загальний розмір, темпи зростання та найбільші файли. Це допомагає зрозуміти обсяг сховища вашого застосунку й спланувати масштабування.

Ліміти й обмеження

За замовчуванням розмір окремого файлу може сягати 500 МБ. Це можна налаштувати — ШІ може змінити ліміт залежно від того, що ви створюєте. Для більшості застосунків (завантаження зображень, обмін документами, PDF) стандартного ліміту більш ніж достатньо.

Для надійності файли зберігаються з надлишковістю. Якщо ви видаляєте файл, його остаточно вилучено із системи — кошика немає, тож видалення є негайним і незворотним.

Робота з ШІ

Описуючи функції, яким потрібне сховище файлів, уточніть:

  • Хто має доступ до файлів — публічний, приватний, спільний в організації чи власні правила
  • Які типи файлів — лише зображення, PDF, будь-який тип файлів, обмеження розміру
  • Як упорядковано файли — папки, правила іменування, чи можуть користувачі створювати підпапки
  • Що відбувається після завантаження — показ у галереї, прикріплення до запису, обробка функцією

ШІ використовує цю інформацію, щоб правильно налаштувати сховище, створити політики доступу та інтерфейс, що відповідає вашим потребам.


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