Посібник із вирішення проблем веб-серверів у ServBay

ServBay підтримує використання Caddy, NGINX та Apache як стандартних веб-серверів, надаючи гнучке локальне середовище розробки. Під час роботи у вас можуть виникати проблеми, як-от недоступність сайту, повільне завантаження або помилки (наприклад, 500 Internal Server Error). Цей посібник допоможе вам діагностувати й розв'язувати типові проблеми з веб-серверами в середовищі ServBay.

Використання вбудованого інструменту діагностики ServBay

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

Відкрийте застосунок ServBay і натисніть "Діагностика" у лівому навігаційному меню, щоб перейти до вбудованої діагностичної панелі.

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

Перевірка конфігураційних файлів веб-серверів

Конфігураційні помилки найчастіше спричиняють недоступність сайту. Для кожного веб-сервера ServBay має окремий інструмент перевірки синтаксису.

Перевірка Caddyfile

Використайте вбудовану команду Caddy validate, щоб перевірити коректність вашого файлу Caddyfile.

/Applications/ServBay/bin/caddy validate -c /Applications/ServBay/etc/caddy/Caddyfile

Якщо синтаксис правильний, команда поверне Valid configuration. У разі помилок ви отримаєте підказки залежно від типу помилки.

Увага: Команда caddy validate може виводити багато повідомлень INFO чи WARN, які зазвичай відображають процес внутрішнього завантаження Caddy і не завжди вказують на реальну помилку в конфігурації. Основним критерієм є повідомлення Valid configuration наприкінці перевірки.

Поширені помилки у Caddyfile:

• Помилка: відсутній файл сертифіката:

  2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  ... (інші INFO/WARN повідомлення) ...
  Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open /Applications/ServBay/ssl/private/tls-certs/mail.servbay.host/mail.servbay.host.1crt: no such file or directory

  Якщо бачите повідомлення на кшталт loading certificates: open xxxxx: no such file or directory, це означає, що шлях до файлу SSL-сертифіката, вказаного у Caddyfile, неправильний або файл відсутній. Перевірте коректність вказаних у конфігурації адрес сертифікатів (.crt/.cer/.pem) та приватних ключів (.key), і переконайтеся в їхній наявності. ServBay дозволяє вручну імпортувати чи автоматично отримувати сертифікати за допомогою ACME — перевірте відповідні налаштування SSL у ServBay.

• Помилка в шляху до кореневої теки сайту (наявність пробілу):

  2024/12/09 17:26:37.371 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  Error: adapting config using caddyfile: parsing caddyfile tokens for 'root': too many arguments; should only be a matcher and a path, at /Applications/ServBay/etc/caddy/Caddyfile:1388

  Помилка parsing caddyfile tokens for 'root': too many arguments зазвичай виникає, якщо у шляху кореневої теки сайту є пробіли. Наприклад, root * /Applications/ServBay/www/public web — частина public web сприймається як два аргументи. Правильний спосіб — обгорнути шлях із пробілом у лапки: root * "/Applications/ServBay/www/public web".

  Рекомендація: Щоб уникнути подібних проблем, радимо не використовувати пробіли чи спеціальні символи у назвах файлів і тек. Для відокремлення слів добре підходять дефіс - чи підкреслення _, наприклад, public-folder або public_dir.

• Помилки у правилах Rewrite:

  Невірний синтаксис Rewrite у Caddyfile — наприклад, якщо без змін копіювати правила з NGINX — також призведе до невдачі валідації. Ознайомтеся з документацією Rewrite модуля Caddy або інструкцією щодо міграції сайту з NGINX у ServBay, щоб переконатися у правильності правил.

Перевірка конфігурації NGINX

Скористайтеся параметром -t для перевірки конфігурації NGINX:

/Applications/ServBay/bin/nginx -t

Якщо налаштування вірні, команда виведе:

nginx: the configuration file /Applications/ServBay/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /Applications/ServBay/etc/nginx/nginx.conf test is successful

При помилках NGINX вкаже файл і рядок, де виникла проблема. Поширені помилки конфігурації:

1. Синтаксична помилка: Пропущена крапка з комою ;, неправильно закриті дужки } тощо.
2. Неправильний шлях до файлів: Через помилки у параметрах include чи інших дерективах не знаходиться потрібний файл чи тека.
3. Конфлікт портів: Вказаний порт уже зайнятий іншою програмою.

Перевірка конфігурації Apache

Щоб перевірити конфігурацію Apache, скористайтеся командою apachectl configtest:

/Applications/ServBay/bin/apachectl configtest

Якщо налаштування правильні, команда поверне Syntax OK. Якщо виявлено помилки, вони будуть детально описані. Типові проблеми:

1. Не вдалося завантажити модуль: Зазначений у LoadModule модуль не існує або має неправильний шлях.
2. Синтаксична помилка у файлі .htaccess: Помилки у .htaccess всередині робочої теки можуть спричинити збій всього Apache або відмову у доступі до окремої теки.
3. Неправильні права на директорії: Директиви Directory, Files та налаштування прав (Require, Allow, Deny) можуть блокувати доступ до файлів сайту.

Усунення помилки 500 Internal Server Error

500 Internal Server Error — загальний код HTTP-помилки, який означає, що сервер зіткнувся з неочікуваною ситуацією під час виконання запиту. Для веб-додатків це здебільшого свідчить про збій виконання скриптів на бекенді (PHP, Python, Node.js тощо).

Загальний порядок діагностики

Після появи помилки 500 дійте за наступним планом:

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

   • Caddy: /Applications/ServBay/var/logs/caddy/error.log
   • NGINX: /Applications/ServBay/var/logs/nginx/error.log
   • Apache: /Applications/ServBay/var/logs/apache/error.log Перегляньте останні записи, шукаючи слова error чи critical.

2. Перевірка роботи бекенд-сервісів (наприклад, PHP-FPM): Якщо сайт використовує PHP, переконайтеся, що сервіс PHP-FPM запущено.

   ps aux | grep php-fpm

   Шукайте рядки з php-fpm: master process чи php-fpm: pool www. За відсутності процесу PHP-FPM не запущено або зупинено через збій. Запустіть його через інтерфейс ServBay або через консольну команду servbayctl.

3. Перевірка журналу помилок бекенд-скриптів (PHP): Коли проблеми пов’язані з FastCGI або помилками виконання скриптів, звертайтеся до логів бекенд-мови.

   • PHP: /Applications/ServBay/var/logs/php/php_error.log Перегляньте повідомлення про Fatal error, Parse error, Warning, Notice, звертаючи особливу увагу на строки, пов’язані з проблемним скриптом. На продакшені параметр display_errors повинен бути вимкнений, так само, як і у php.ini налаштування, але для розробки можна тимчасово увімкнути для зручності.

4. Перевірте права на файли та теки: Веб-сервер працює під певним користувачем (часто _www) і має мати доступ на читання/запис до відповідних тек та файлів:

   ls -la /Applications/ServBay/www/your-site/

   Переконайтеся, що в користувача веб-сервера є права на читання потрібних тек/файлів. Для функціоналу завантаження чи ведення логів також потрібні права на запис. Використовуйте команди chmod і chown з обережністю.

Особливості діагностики помилок 500 для різних серверів

• Caddy:

  1. Налаштування FastCGI: Перевірте, чи директиви php_fastcgi або reverse_proxy у Caddyfile вказують на правильну адресу прослуховування PHP-FPM (зазвичай 127.0.0.1:9000 або unix:/path/to/php-fpm.sock).
  2. Стан PHP-FPM: Переконайтеся, що потрібна версія PHP та PHP-FPM активні у ServBay.
  3. Налаштування реверс-проксі: Якщо використовується reverse_proxy для Node.js чи інших бекендів, перевірте адресу й порт проксі та те, що бекенд працює належним чином.

• NGINX:

  1. Налаштування fastcgi_pass: Переконайтеся, що директива у nginx.conf чи специфічному конфігу сайту вказує на правильний сокет/порт PHP-FPM.
  2. client_max_body_size: Якщо помилка з'являється при завантаженні великих файлів, можливо цей параметр занадто малий.
  3. try_files: Перевірте синтаксис і порядок цієї директиви для коректного оброблення запитів через FastCGI.

• Apache:

  1. Модуль mod_rewrite: Якщо у .htaccess використовуються правила переписування URL, переконайтеся у ввімкненні модуля mod_rewrite.
  2. Вміст .htaccess: Помилки у цьому файлі ведуть до 500 помилок. Уважно перегляньте синтаксис, особливо для RewriteRule.
  3. Налаштування AllowOverride: Директива в конфігурації повинна давати змогу застосовувати .htaccess у відповідній теці (часто значення All або принаймні FileInfo, Limit).

Керування сервісами

Після внесення змін у конфігурацію або виправлення проблем із бекендом зазвичай треба перезапустити веб-сервер чи дотичні служби.

Перезапуск сервісів

Для перезапуску певного веб-сервера скористайтеся командою servbayctl restart:

# Перезапуск сервісу Caddy
servbayctl restart caddy -all

# Перезапуск сервісу NGINX
servbayctl restart nginx -all

# Перезапуск сервісу Apache
servbayctl restart apache -all

Параметр -all додатково спробує перезапустити супутні служби — наприклад, при перезапуску Caddy/NGINX/Apache також буде перезапущено PHP-FPM, якщо потрібно.

Перевірка стану сервісів

Для перегляду поточного стану сервісу скористайтеся командою servbayctl status:

# Перевірити стан Caddy
servbayctl status caddy -all

# Перевірити стан NGINX
servbayctl status nginx -all

# Перевірити стан Apache
servbayctl status apache -all

Вивід покаже, чи сервіс running (активний), stopped (зупинений) або інший стан, що допоможе переконатися в успішному запуску.

Поглиблені кроки з діагностики

Якщо попередні методи не допомогли, спробуйте виконати нижченаведені кроки:

1. Перевірка інструментів розробника браузера: Відкрийте інструменти розробника (клавіша F12), перегляньте вкладки "Console" (консоль) та "Network" (мережа): помилки JavaScript, коди статусу відповідей, заголовки запитів/відповідей, що допоможе знайти причину — у фронтенді чи бекенді.
2. Перевірка через curl -v: У терміналі виконайте curl -v your-website.servbay.demo, щоб побачити деталізований обмін із сервером — заголовки, дані шифрування й статуси. Замініть your-website.servbay.demo на фактичний домен вашого сайту у ServBay.
3. Тимчасове вимкнення фаєрволу: Локальний фаєрвол (наприклад, на macOS) чи сторонні антивіруси можуть блокувати зовнішні підключення. Вимкніть їх на час тесту й, якщо проблема зникла, налаштуйте правила доступу для портів ServBay (80, 443 тощо).
4. Тестування у різних браузерах/пристроях: Перевірте сайт у кількох браузерах і на інших пристроях, щоб виключити кеш браузера чи специфічні налаштування обладнання.
5. Перевірте локальний DNS або файл hosts: Якщо ви використовуєте кастомний домен (не localhost чи IP), відкрийте /etc/hosts або налаштування DNS, щоб переконатися, що домен правильно резольвиться у 127.0.0.1 або ::1.

Висновок

Виникнення проблем із веб-серверами — типова ситуація в локальній розробці. Більшість помилок вирішуються шляхом ретельної перевірки синтаксису конфігураційних файлів, аналізу журналів помилок, контролю стану сервісів і налаштування доступу до файлів. Потужні вбудовані інструменти діагностики ServBay та командний рядок servbayctl значно спрощують це завдання. Якщо труднощі залишилися, звертайтеся до офіційної документації ServBay або звертайтеся до служби підтримки.