Посібник з налаштування реверсивного проксі Ngrok у ServBay

Ngrok — це потужний інструмент для створення безпечних тунелів, який базується на технології реверсивного проксі та дозволяє пробивати файрволи й NAT, щоб відображати локально запущені сервіси на публічних доменах. Цей посібник докладно пояснює, як інтегрувати й налаштувати сервіс Ngrok у локальному середовищі ServBay, щоб надати доступ до локальних вебсервісів, API чи інших ресурсів через Інтернет — зручно для віддалених демонстрацій, командної співпраці чи тестування callback-ів від сторонніх сервісів.

Технічний принцип

В основі роботи Ngrok — встановлення зашифрованого тунелю між вашим локальним комп’ютером і сервером Ngrok. Коли зовнішній користувач переходить на виділений Ngrok публічний домен, запит спершу надходить на сервер Ngrok, а звідти через цей безпечний тунель пересилається на відповідний сервіс, що працює у вашій локальній інстанції ServBay. Це дозволяє забезпечити зовнішній доступ до сервісу, навіть якщо у вас немає публічної IP-адреси або ви перебуваєте за файрволом. Для сценаріїв із ServBay це означає, що ви можете ділитися своїм локальним сайтом, backend API чи будь-яким іншим HTTP/HTTPS сервісом із зовнішнім світом у реальному часі для тестування й демонстрацій.

Підготовка середовища

Перш ніж налаштовувати Ngrok, переконайтеся, що виконано наступне:

1. Встановлено та запущено ServBay: Переконайтеся, що додаток ServBay успішно встановлений, а потрібний вебсайт або сервіс, який ви збираєтеся опублікувати через Ngrok, уже додано в сервіс і працює. Переглядайте й керуйте локальними сайтами через панель "Сайти" у ServBay.
2. Встановлений Ngrok-клієнт: Дотримуйтесь таких кроків для інсталяції CLI-інструменту Ngrok:
   1. Перейдіть на офіційну сторінку завантажень Ngrok і скачайте архів для вашої операційної системи.
   2. Розпакуйте архів. Перемістіть або скопіюйте виконуваний файл ngrok у каталог, який входить до системної змінної PATH (наприклад, на macOS це /usr/local/bin), щоб команда ngrok була доступна з будь-якого терміналу.

      # Для macOS ARM64 наприклад
      sudo unzip ~/Downloads/ngrok-v3-stable-darwin-arm64.zip -d /usr/local/bin

   3. Перевірте коректність установки, запустивши команду ngrok version — має з’явитися номер версії:

      ngrok version
      # Приклад виводу: ngrok version 3.5.0

3. Обліковий запис Ngrok (необов’язково, але бажано): Обліковий запис Ngrok (безкоштовний або платний) спрощує керування тунелями та надає доступ до додаткових функцій, наприклад, використання власного домену. Зареєструйтесь на офіційному сайті Ngrok, щоб отримати токен автентифікації (ngrok config add-authtoken <YOUR_AUTH_TOKEN>). Це зніме часові обмеження на підключення тунелів і відкриє більше можливостей.
4. Додано локальний сайт: У ServBay має бути налаштований принаймні один локальний сайт, який ви бажаєте опублікувати через Ngrok — наприклад, з доменом servbay.local або yourproject.servbay.demo.

Практична конфігурація тунелю

Опис основних параметрів

Стандартна структура команди для відображення сервісу виглядає так:

ngrok http --domain=<NGROK_DOMAIN> <LOCAL_ENDPOINT> \
  --request-header-add='host: <VIRTUAL_HOST>'

Компонент параметра	Опис
http	Створює тунель для HTTP-протоколу. Ngrok обробляє вхідні HTTP/HTTPS запити.
--domain <NGROK_DOMAIN>	Задання виділеного домену від Ngrok (замініть на фактичний домен із вашої адмінпанелі Ngrok). У безкоштовному тарифі параметр не обов’язковий — Ngrok сам призначає випадковий піддомен.
<LOCAL_ENDPOINT>	Адреса локального сервісу ServBay. Для віртуальних хостів ServBay зазвичай це їхній локальний домен (наприклад, https://servbay.local), але також може бути http://localhost:<порт>.
--request-header-add='host: <VIRTUAL_HOST>'	[Важливо] Перезаписує Host-заголовок запиту. ServBay визначає локальні сайти (віртуальні хости) за значенням заголовка Host, тож цим параметром ми підставляємо локальний домен (наприклад, servbay.local), щоб тунель правильно скеровував запит до потрібного сайту.

Приклад налаштування

Припустімо, у ServBay ви задали локальний сайт із доменом servbay.local і бажаєте відкрити його через Ngrok. Якщо ви використовуєте безкоштовний тарифний план Ngrok, можна відразу відобразити локальний домен:

# Відображення локального сайту servbay.local ServBay на випадковий домен, призначений Ngrok
ngrok http https://servbay.local --request-header-add='host: servbay.local'

Якщо у вас уже налаштований фіксований домен у Ngrok Dashboard, наприклад, your-servbay-demo.ngrok-free.app, чи ви маєте власний домен для платного аккаунта, використовуйте параметр --domain:

# Відображення локального сайту servbay.local ServBay на заданий домен Ngrok
ngrok http --domain=your-servbay-demo.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'

Після виконання цієї команди у терміналі з’явиться статус тунелю: публічна URL-адреса для доступу з Інтернету (щось на кшталт https://xxxx.ngrok-free.app або вашого впровадженого домену), а також локальна адреса для моніторингу трафіку (зазвичай http://127.0.0.1:4040).

Перевірка роботи сервісу

Після завершення налаштувань і успішного запуску тунелю Ngrok дотримуйтеся наступних кроків для перевірки доступності ресурсу з Інтернету:

1. Отримайте публічну адресу: У вікні терміналу Ngrok знайдіть рядок Forwarding і скопіюйте публічний URL, що починається з https://.
2. Перейдіть у браузер: Введіть отриманий Ngrok-адрес у браузері на будь-якому пристрої з доступом до Інтернету (наприклад, https://cunning-lacewing-fresh.ngrok-free.app або ваш власний домен).
3. Перевірте результат:
   • Сайт із ServBay має коректно відкриватися у браузері.
   • В адресному рядку з’явиться значок захищеного з’єднання HTTPS (Ngrok автоматично надає дійсний SSL-сертифікат для тунелю).
   • Логи запитів і статистику трафіку можна переглянути у терміналі Ngrok або у вебінтерфейсі (зазвичай http://127.0.0.1:4040), щоб переконатися, що запити успішно доходять до ServBay і обробляються.

Ілюстрація: успішний доступ до тунелю Ngrok через веббраузер

Розширені поради та зауваження

1. Управління доменами:
   • У безкоштовному плані Ngrok призначає випадковий піддомен .ngrok-free.app, тривалість сесії тунелю обмежена.
   • Зареєструйте обліковий запис Ngrok і керуйте власними доменами через Ngrok Dashboard, щоб кожен раз не міняти публічну адресу.
   • Платний тариф Ngrok дозволяє прив’язати свій власний домен, отримати більше трафіку, підвищену пропускну здатність і ширшу функціональність.
2. Мапінг декількох сервісів: Якщо треба відкрити у публічний доступ одразу декілька локальних сайтів або портів ServBay, можна запускати кілька процесів Ngrok з окремими тунелями, або визначати тунелі в конфіг-файлі Ngrok (зазвичай ~/.config/ngrok/ngrok.yml). Наприклад, для локального сайту ServBay і Node.js API:

   # Тунель для servbay.local (через HTTPS 443 і Host-заголовок)
   ngrok http --domain=servbay-website.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'
   
   # В іншому терміналі або через конфіг-файл — тунель для Node.js на 3000 порту
   ngrok http --domain=nodejs-api.ngrok-free.app http://localhost:3000

   Зауважте: для сервісів на віртуальних хостах ServBay рекомендується відображати адреси через https://[локальний_домен] та використання --request-header-add, а не напряму проброс портів (80/443), оскільки ServBay маршрутизує хости саме по заголовку Host.
3. Діагностичні команди:
   • ngrok config check: перевірка коректності YAML-конфігу Ngrok (зазвичай у ~/.config/ngrok/ngrok.yml).
   • ngrok logs: у реальному часі відображає детальні логи в терміналі — корисно для діагностики проблем підключення чи маршрутизації.
4. Безпека: Відкриття локальних сервісів у мережу несе потенційні ризики. Переконайтесь у безпечності відкритого ресурсу та запускайте тунелі Ngrok лише за необхідності. У платних тарифах доступні IP-білінги, обмеження доступу та додаткові опції для підвищення безпеки.

Усунення неполадок

Симптом	Рішення
Тайм-аут або сторінка не відкривається	Перевірте, чи цільовий сайт у ServBay запущено й доступний через локальний домен (наприклад, у браузері https://servbay.local). Переконайтеся, що вебсервер ServBay (Caddy або Nginx) працює. Також перевірте, чи не блокує трафік локальний файрвол.
Помилка HTTPS-сертифіката (попередження браузера)	Ngrok завжди видає дійсний SSL для публічного домену тунелю. Якщо браузер попереджає про помилку при доступі до NGrok-адреси, імовірно, проблема у налаштуванні тунелю або мережі (не у ServBay). Завжди використовуйте https://-URL Ngrok. Якщо помилка виникає локально, перевірте SSL-налаштування ServBay.
Періодичні обриви сесії або низька швидкість	Перевірте стабільність вашого інтернет-з’єднання — мережеві збої можуть обривати тунель. По можливості використовуйте дротове підключення. Для критично важливих задач краще оформити платний тариф Ngrok із більшими гарантіями та пропускною здатністю.
Відкривається дефолтний сайт ServBay, а не потрібний	Перевірте правильність локальної адреси <LOCAL_ENDPOINT> у команді ngrok http і переконайтеся, що <VIRTUAL_HOST> у --request-header-add точно відповідає домену вашого локального сайту в ServBay. Це критично для правильного роутінгу!

Поширені питання (FAQ)

• Q: Чи можна пробросити базу даних ServBay через Ngrok?

  A: Ngrok призначений передусім для HTTP/HTTPS-тунелів. Він підтримує також TCP-трафік, але це виходить за рамки даного посібника, до того ж не рекомендується відкривати базу даних у мережу напряму — це дуже небезпечно. Краще використовуйте SSH-тунелі або інші безпечні методи для віддаленого доступу до БД.

• Q: Чи змінюється домен Ngrok після кожного запуску?

  A: Так, у безкоштовному тарифі видається випадковий піддомен .ngrok-free.app. Щоб отримати фіксований публічний домен, зареєструйте обліковий запис у Ngrok Dashboard або перейдіть на платний тариф.

• Q: Чи впливає Ngrok на продуктивність мого локального сервісу ServBay?

  A: Через Ngrok додається затримка (усі запити йдуть через сервери Ngrok), але для розробки, тестування й демонстрацій це цілком прийнятно. Продуктивність самого сайту у ServBay визначається ресурсами комп’ютера та якістю коду.

Висновок

Завдяки інтеграції Ngrok користувачі ServBay можуть легко і безпечно ділитися результатами локальної розробки у світі — без складного налаштування мережі. Це идеальний вибір для віддаленої співпраці, демонстрацій замовнику, тестування із мобільних і сторонніх сервісів. Ngrok надає зручний моніторинг трафіку та потужний інструментарій безпеки (для частини функцій потрібен платний акаунт). Для важливих або комерційних проектів із потребою у постійному домені краще вибрати платний тариф Ngrok для стабільності та розширених можливостей.