Налаштування CORS (крос-доменного доступу) для сайтів у ServBay

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

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

Що таке CORS?

CORS (Cross-Origin Resource Sharing, крос-доменний обмін ресурсами) — це механізм на основі HTTP-заголовків, який дає змогу серверу визначити, які саме джерела (домен, протокол або порт) можуть завантажувати його ресурси. Коли сторінка намагається зробити запит до ресурсу з джерела, відмінного від свого власного, браузер розцінює це як "крос-доменний HTTP-запит". Згідно політики одного джерела браузер блокує такі запити за замовчуванням. CORS забезпечує канал для "узгодження" між сервером і браузером — чи можна дозволити такий міждоменний запит.

Чому розробникам необхідно налаштовувати CORS?

Якщо ви створюєте додаток із розділенням на фронтенд і бекенд (наприклад, фронтенд на app.servbay.demo, бекенд API на api.servbay.demo), або ваш фронтенд звертається до сторонніх API, браузер заблокує ці запити через політику одного джерела. Налаштовуючи CORS, ви даєте браузеру знати, що сервер дозволяє запити з джерела вашого фронтенду, вирішуючи проблему через блокування "чужих" запитів.

Основні HTTP-заголовки, які використовуються для CORS

Коли сервер відповідає на крос-доменний запит, він повертає кілька спеціальних HTTP-заголовків Access-Control-*. Браузер на їх основі вирішує, дозволити чи відхилити запит. Ось ключові параметри CORS, які можна налаштувати в ServBay (це саме ці HTTP-заголовки):

1. Access-Control-Allow-Origin

   • Призначення: Головний CORS-заголовок, який визначає, які саме джерела (домен/доменів) можуть отримувати доступ до ресурсу.
   • Значення:
     • *: дозволити доступ із будь-яких джерел.
       Важливо: хоча це зручно, не рекомендується використовувати в продуктивному середовищі через можливі ризики безпеки — ресурс відкривається для будь-кого.
     • https://servbay.demo: тільки цей конкретний джерело має доступ.
     • https://servbay.demo https://api.servbay.demo: перелік кількох джерел, розділених пробілом.
   • Зверніть увагу: якщо крос-доменний запит має містити Cookie або HTTP-аутентифікацію (тобто ви включаєте Access-Control-Allow-Credentials: true), значення Access-Control-Allow-Origin не може бути * — його треба вказати явно.

2. Access-Control-Allow-Methods

   • Призначення: Перелік HTTP-методів, які дозволено використовувати для крос-доменних запитів (GET, POST, PUT, DELETE, OPTIONS тощо).
   • Значення: Наприклад: GET, POST, PUT, DELETE, OPTIONS (розділяються комою).
   • Зверніть увагу: Для "непростих" запитів (наприклад, з методом PUT або DELETE, або з нестандартними заголовками) браузер спочатку надсилає "preflight-запит" з методом OPTIONS. Сервер обов'язково має відповідати на нього з потрібними заголовками, зокрема Access-Control-Allow-Methods. Тому бажано завжди додавати OPTIONS.

3. Access-Control-Allow-Headers

   • Призначення: Які саме додаткові (нестандартні) заголовки може містити крос-доменний запит.
   • Значення: Наприклад: Content-Type, Authorization, X-Requested-With (розділяються комою).
   • Зверніть увагу: Якщо ваш фронтенд надсилає нестандартні заголовки (будь-які, відмінні від типової трійки: Accept, Accept-Language, Content-Language, Content-Type із певними значеннями), браузер знову ж таки надішле preflight-запит, і потрібно явно вказати ці заголовки тут.

4. Access-Control-Allow-Credentials

   • Призначення: Дозвіл (або заборона) на передачу у крос-доменному запиті облікових даних користувача — cookies, клієнтських SSL-сертифікатів, HTTP-аутентифікації тощо.
   • Значення: true або false.
   • Зверніть увагу: Якщо вказано true, як уже згадувалося, Access-Control-Allow-Origin неможна встановлювати як *, а тільки як конкретне джерело. Також клієнт (JavaScript у браузері) має явно вказати, що слід надсилати облікові дані (xhr.withCredentials = true або fetch(url, { credentials: 'include' })).

Як увімкнути та налаштувати CORS у ServBay

ServBay має зручний інтерфейс, який дозволяє налаштовувати CORS для кожного сайту окремо. Ось детальна покрокова інструкція:

1. Відкрийте ServBay і перейдіть до списку сайтів: Запустіть додаток ServBay. Зліва у навігаційному меню оберіть пункт "Сайти". Ви побачите перелік усіх локальних сайтів, налаштованих у ServBay.

2. Оберіть сайт для CORS-налаштування: У списку знайдіть саме той сайт, для якого потрібно ввімкнути та налаштувати CORS. Клацніть на його назву для переходу у сторінку налаштувань.

3. Знайдіть і активуйте секцію налаштувань CORS: На сторінці налаштувань сайту прокрутіть вниз і знайдіть секцію "CORS". За замовчуванням CORS вимкнено. Перейдіть поруч із заголовком секції за допомогою повзунка з "Вимкнено" на "Увімкнено". Після активації з'являться доступні для редагування поля налаштувань.

4. Налаштуйте Access-Control-Allow-Origin: У полі "Access-Control-Allow-Origin" введіть одне або кілька джерел, яким ви дозволяєте доступати до ресурсу цього сайту. Для декількох джерел розділяйте їх пробілом. Наприклад: https://frontend.servbay.demo https://anotherapp.servbay.demo. Не використовуйте * у продуктивному середовищі.

5. Налаштуйте Access-Control-Allow-Methods: У полі "Access-Control-Allow-Methods" задайте перелік дозволених HTTP-методів, розділених комами. Наприклад: GET, POST, PUT, DELETE, OPTIONS. Переконайтеся, що всі необхідні для вашого додатку методи, зокрема OPTIONS, зазначені.

6. Налаштуйте Access-Control-Allow-Headers: У полі "Access-Control-Allow-Headers" перелічіть додаткові HTTP-заголовки, які можна передавати у крос-доменному запиті (через кому). Наприклад: Content-Type, Authorization, X-Custom-Header. Вказуйте тільки реально вживані вашим додатком заголовки.

7. Опціонально: налаштуйте Access-Control-Allow-Credentials: Якщо ви дозволяєте передачу cookies чи HTTP-автентифікацію у крос-доменних запитах, активуйте повзунок "Allow-Credentials".
   Ще раз: При його активації в полі Access-Control-Allow-Origin у пункті 4 неможна вказувати *, а потрібно лише конкретні джерела!

8. Збережіть налаштування: Після зміни CORS-параметрів обов'язково натисніть кнопку "Зберегти" (внизу праворуч), щоб застосувати зміни. ServBay автоматично оновить конфігурацію веб-сервера (наприклад Caddy чи Nginx), і не потрібно додаткового ручного перезапуску.

Приклад конфігурації

Нижче наведений скріншот ілюструє приклад CORS-налаштування для сайту "ServBay Demo Website" у ServBay:

У цій конфігурації обрано такі параметри:

• Access-Control-Allow-Origin: https://frontend.servbay.demo https://api.servbay.demo
• Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization
• Allow-Credentials: активовано (true)

Це означає, що тільки запити з джерел https://frontend.servbay.demo та https://api.servbay.demo можуть отримати доступ до ресурсу "ServBay Demo Website". Для цього дозволено використовувати методи GET, POST, PUT, DELETE, OPTIONS; запити можуть містити заголовки Content-Type та Authorization та дозволяється передача cookies та інших облікових даних.

Рекомендації та найкращі практики

• Безпека — пріоритет: Для розробки і тестування можна налаштовувати Access-Control-Allow-Origin: *, але у продуктиві завжди варто обмежувати конкретними доменами, із якими ваша система реально взаємодіє.
• Preflight-запити: Розуміння принципів роботи preflight-запитів (метод OPTIONS) важливе для налагодження CORS. Переконайтеся, що сервер (зокрема через налаштування у ServBay) правильно відповідає на такі запити.
• Кешування браузера: CORS-стратегію браузер може кешувати. Якщо після зміни налаштувань у ServBay проблема не зникла, очистіть кеш браузера або протестуйте в режимі інкогніто.
• CORS на рівні застосунку: Деякі фреймворки чи бібліотеки (Laravel, Express.js, Spring Boot тощо) дозволяють налаштовувати CORS і у коді застосунку. CORS через ServBay діє на рівні веб-сервера (Caddy/Nginx) та, зазвичай, має пріоритет. У складних випадках слід враховувати налаштування й сервера, і коду.
• Засоби для налагодження: Користуйтеся інструментами веб-розробника у браузері (F12), а саме вкладкою "Мережа" (Network) для перегляду HTTP-запитів та заголовків — це допоможе встановити, чи відправляються і застосовуються потрібні CORS-заголовки, та де саме виникають помилки.

Часті запитання (FAQ)

Q: Я налаштував CORS за інструкцією, але все одно виникає помилка при крос-доменному запиті. Чому?

A: Перевірте такі моменти:

1. Браузерна консоль й вкладка "Мережа": Браузер детально повідомляє про CORS-помилки у консолі і виводить всі заголовки у вкладці Network. Перевірте, чи повертається правильне значення у Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers, а також чи співпадають ці значення із вашим запитом.
2. Джерело запиту: Порівняйте значення Access-Control-Allow-Origin із реальним джерелом запиту (протокол, домен, порт) — вони повинні повністю співпадати.
3. Методи та заголовки: Упевніться, що у Access-Control-Allow-Methods є всі потрібні HTTP-методи, а у Access-Control-Allow-Headers — перелік всіх кастомних заголовків, які пересилає ваш фронтенд.
4. Використання облікових даних: Якщо потрібна передача cookies чи іншої ідентифікації, переконайтеся, що у ServBay ввімкнено Allow-Credentials і у полі Access-Control-Allow-Origin НЕ стоїть *. Також перевірте, що клієнтський код теж просить надсилати облікові дані (наприклад, з withCredentials = true).
5. Preflight-запити: Для "непростих" запитів, проконтролюйте, що браузер надсилає preflight-запит із методом OPTIONS, а сервер відповідає із усіма необхідними заголовками CORS.
6. Збереження у ServBay: Перевірте, що після зміни параметрів у ServBay ви натиснули “Зберегти”.

Q: Чи можна задати глобальну CORS-стратегію одразу для всіх сайтів у ServBay?

A: CORS у ServBay налаштовується окремо для кожного сайту — це гнучко й безпечно. Глобального CORS-налаштування в ServBay поки що немає. Якщо треба однорідна стратегія для кількох сайтів, налаштуйте це вручну для кожного.

Q: Як реалізується CORS у ServBay?

A: У якості веб-сервера ServBay використовує Caddy або Nginx. Налаштовуючи CORS через UI, ви фактично змінюєте відповідні директиви у файлах конфігурації Caddyfile або Nginx. Оновлення і перезавантаження сервера відбувається автоматично — жодних ручних дій не потрібно.

Висновок

Завдяки інтуїтивному інтерфейсу ServBay ви легко можете ввімкнути і налаштувати CORS для сайтів локального середовища розробки й таким чином уникнути проблем із крос-доменним доступом. Глибоке розуміння та правильне налаштування основних заголовків — Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers, Access-Control-Allow-Credentials — гарантує безпечну та стабільну роботу ваших крос-доменних запитів. Дотримання рекомендацій із цього посібника допоможе зробити вашу локальну веб-розробку ще ефективнішою й безпечнішою.