Создание и запуск проекта Koa.js с помощью ServBay
ServBay — это локальная среда веб-разработки, специально созданная для macOS. Она включает множество необходимых разработчику пакетов: среду выполнения Node.js и популярные базы данных. В этом руководстве вы узнаете, как быстро создавать, запускать и управлять своим проектом Koa.js с использованием возможностей ServBay.
Что такое Koa.js?
Koa.js — это веб-фреймворк нового поколения на базе Node.js, разработанный командой Express.js. Он известен своей лаконичностью, выразительным синтаксисом и широкими возможностями, что делает его отличным выбором для создания веб-приложений и API. Koa.js в полной мере использует современные возможности JavaScript — особенно синтаксис async/await
, который упрощает асинхронное программирование и создание middleware, делая код более чистым и удобным для сопровождения.
Основные особенности Koa.js
- Использование async/await: Архитектура построена вокруг синтаксиса
async/await
, что делает работу с асинхронностью интуитивно понятной. - Легковесное ядро: Основная библиотека Koa минималистична и содержит только базовые функции. Всё остальное добавляется через модули-middleware.
- Мощная система middleware: Используется каскадная (cascading) модель middleware, благодаря чему цепочки обработки запроса выглядят прозрачно и гибко.
- Фокус на веб: Koa ориентирован только на веб-приложения и API, не навязывая лишних функций.
Используя Koa.js, разработчики могут эффективно строить производительные и сопровождаемые веб-сервисы.
Развёртывание среды разработки Koa.js с помощью ServBay
ServBay предоставляет готовую к работе инфраструктуру для Node.js-разработчиков, интегрируя runtime Node.js и популярные СУБД. Благодаря функции Сайты вы с лёгкостью настроите доступ к своему Koa.js-проекту через пользовательский домен и SSL-сертификат.
Необходимые условия
Перед началом убедитесь, что:
- Установлен ServBay: Скачайте и установите последнюю версию с официального сайта ServBay.
- Установлен пакет Node.js: Откройте приложение ServBay, перейдите во вкладку Пакеты и убедитесь, что нужная версия Node.js установлена. Если нет — выберите и установите.
- Вы знакомы с базовыми операциями ServBay: Понимаете, как запускать/останавливать сервисы и управлять сайтами.
Создание проекта Koa.js
Для хранения проекта используем рекомендуемую ServBay директорию — /Applications/ServBay/www
.
Инициализация папки проекта
Откройте приложение Terminal и перейдите в корневую папку сайта ServBay. Создайте новый каталог для проекта (например,
servbay-koa-app
), затем инициализируйте новый Node.js-проект:bashcd /Applications/ServBay/www mkdir servbay-koa-app cd servbay-koa-app npm init -y
1
2
3
4Команда
npm init -y
быстро создаёт файлpackage.json
со стандартными настройками.Установка Koa.js
В каталоге проекта
servbay-koa-app
установите Koa.js и при необходимости (если вы планируете использовать TypeScript) его типы:bashnpm install koa # Если нужен TypeScript, установите типы # npm install @types/koa --save-dev
1
2
3Создание стартового файла приложения
В папке
servbay-koa-app
создайте файлapp.js
и добавьте базовый пример кода Koa.js:javascriptconst Koa = require('koa'); const app = new Koa(); // Middleware: логирование запросов app.use(async (ctx, next) => { const start = Date.now(); await next(); const ms = Date.now() - start; console.log(`${ctx.method} ${ctx.url} - ${ms}ms`); }); // Middleware: обработка корневого маршрута app.use(async ctx => { ctx.body = 'Hello from ServBay Koa.js App!'; }); // Задание порта, приоритет — переменная окружения PORT const port = process.env.PORT || 3000; // Запуск HTTP-сервера app.listen(port, () => { console.log(`Koa.js server running on http://localhost:${port}`); console.log(`Project path: ${__dirname}`); });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24Этот код формирует минимальное Koa-приложение: одно middleware для логирования маршрутов и времени, второе — для обработки корня (
/
) и возврата строки "Hello from ServBay Koa.js App!". Сервер слушает порт, указанный в переменной окруженияPORT
, либо по умолчанию —3000
.
Режим разработки
В процессе разработки мы обычно запускаем локальный Node.js-процесс и получаем доступ к Koa.js-приложению через функцию Сайты в ServBay.
Запуск dev-сервера Koa.js
Откройте терминал, перейдите в каталог
servbay-koa-app
и запуститеapp.js
через Node.js. Для удобства или во избежание конфликтов портов рекомендуем явно указать порт, например8585
:bashcd /Applications/ServBay/www/servbay-koa-app PORT=8585 node app.js
1
2В терминале появится сообщение вроде
Koa.js server running on http://localhost:8585
, подтверждающее запуск. Оставьте этот терминал открытым — сервер должен работать постоянно.Настройка обратного прокси-сайта в ServBay
Чтобы открыть свой Koa.js-проект по пользовательскому доменному имени через ServBay, настройте новый Сайт с обратным проксированием:
- Откройте приложение ServBay.
- Перейдите на вкладку Сайты.
- В нижнем левом углу нажмите на
+
для добавления нового сайта. - Заполните параметры:
- Имя:
ServBay Koa.js Dev Site
- Домен:
servbay-koa-dev.servbay.demo
(рекомендуется использовать домены на.servbay.demo
, ServBay автоматически выдаёт для них SSL-сертификат) - Тип: выберите
Обратный прокси (Reverse Proxy)
- IP-адрес:
127.0.0.1
(указывает на локальный Node.js) - Порт:
8585
(порт, на котором работает Koa.js) - Корневая директория: для обратного прокси этот параметр неважен — оставьте пустым или укажите проект:
/Applications/ServBay/www/servbay-koa-app
.
- Имя:
- Сохраните изменения.
- Если ServBay попросит, примените настройки.
После настройки ServBay автоматически обновит файл hosts, направив
servbay-koa-dev.servbay.demo
на127.0.0.1
. Все запросы к этому домену через внутренний сервер Caddy или Nginx будут проксироваться на порт8585
. За счёт использования зоны.servbay.demo
ServBay User CA бесплатно выдаст и установит доверенный SSL-сертификат, что позволит безопасно работать по HTTPS.Для более подробных инструкций обратитесь к разделу Adding Node.js Development Website в документации ServBay (выберите английскую версию!).
Доступ к сайту Koa.js через браузер
Перейдите по адресу
https://servbay-koa-dev.servbay.demo
в браузере.При правильной настройке вы увидите страницу с текстом "Hello from ServBay Koa.js App!". Это означает, что ваш Koa.js сервер работает локально и доступен через ServBay. После внесения изменений в
app.js
и перезапуска сервера — обновите страницу для просмотра обновлений.
Развёртывание (имитация продакшена)
Чтобы протестировать приложение в условиях, максимально приближённых к production, можно использовать другой порт и переменные окружения. СервBay позволяет аналогично проксировать такие “боевые” инстансы.
Имитация запуска Koa.js в production-режиме
В новом окне терминала остановите dev-сервер и запустите приложение с новым портом (
8586
) и переменной окруженияNODE_ENV
:bashcd /Applications/ServBay/www/servbay-koa-app PORT=8586 NODE_ENV=production node app.js
1
2Такой запуск имитирует продакшн-инсталляцию на порту
8586
.Настройка сайта ServBay для production (имитация)
Как и раньше, настройте новый сайт в ServBay для production-версии приложения:
- Откройте приложение ServBay, вкладка Сайты.
- Нажмите
+
для добавления нового сайта. - Заполните:
- Имя:
ServBay Koa.js Prod Site
- Домен:
servbay-koa-prod.servbay.demo
(или свой домен, если хотите — ServBay поддерживает штатный выпуск сертификатов Let's Encrypt/ACME) - Тип:
Обратный прокси (Reverse Proxy)
- IP-адрес:
127.0.0.1
(локальный хост) - Порт:
8586
(тот, что использует ваш production-сервер) - Корневой каталог: можно оставить пустым или указать путь к проекту.
- Имя:
- Сохраните и примените изменения.
Если вы используете домен
.servbay.demo
, ServBay User CA автоматически обеспечит SSL. Для публичных доменов можно оформить бесплатные сертификаты Let's Encrypt/ACME. Подробнее смотрите использование SSL для защиты сайта в официальной документации.Просмотр production-сайта (симуляция)
В браузере откройте
https://servbay-koa-prod.servbay.demo
.Вы увидите тот же результат, что и в dev-среде, только теперь трафик проксируется через ServBay на production экземпляр вашего Koa.js на порту
8586
.
Подключение к базе данных
ServBay включает ряд популярных СУБД: MongoDB, Redis, MariaDB (совместимую с MySQL) и PostgreSQL. Подключаться к ним из вашего Koa.js-проекта очень просто — сервисы работают локально и доступны на стандартных портах через localhost
.
Ниже представлены примеры подключения к различным базам данных с помощью официальных Node.js-драйверов. Перед этим убедитесь, что нужная СУБД установлена и запущена через раздел Пакеты в ServBay.
MongoDB
Сначала установите драйвер MongoDB (например,
mongoose
илиmongodb
):bashcd /Applications/ServBay/www/servbay-koa-app npm install mongoose # или npm install mongodb
1
2Затем добавьте подключение в
app.js
или нужный модуль:javascript// Соединение с MongoDB через Mongoose const mongoose = require('mongoose'); // В ServBay по умолчанию MongoDB не требует аутентификации. Название БД на ваш выбор. mongoose.connect('mongodb://localhost:27017/servbay-koa-app', { useNewUrlParser: true, useUnifiedTopology: true }) .then(() => console.log('Connected to MongoDB')) .catch(err => console.error('MongoDB connection error:', err)); // Примечание: На практике подключение к базе обычно производится при инициализации приложения, // а сервер стартует только после успешного соединения.
1
2
3
4
5
6
7
8
9
10
11
12
13В стандартной установке MongoDB от ServBay слушает порт
27017
, без пароля. Имя БД выбираете сами — она создаётся автоматически при первом обращении.Redis
Установите Redis-клиент:
bashcd /Applications/ServBay/www/servbay-koa-app npm install redis
1
2Подключение к серверу Redis:
javascript// Подключение к Redis через официальный клиент const redis = require('redis'); // Создание клиента (по умолчанию — localhost:6379) const client = redis.createClient({ url: 'redis://localhost:6379' // стандартный порт Redis в ServBay }); client.on('connect', () => { console.log('Connected to Redis'); }); client.on('error', (err) => { console.error('Redis connection error:', err); }); // Установление соединения client.connect(); // Примечание: желательно использовать async/await и удостоверяться в успешном соединении перед работой с Redis.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20ServBay Redis слушает на
6379
и не требует пароля по умолчанию.MariaDB (или MySQL)
MariaDB — форк MySQL с полной совместимостью API. ServBay включает пакет MariaDB, который можно использовать так же, как и MySQL.
Установка драйвера MariaDB:
bashcd /Applications/ServBay/www/servbay-koa-app npm install mariadb # или npm install mysql2 (обычно более совместим, рекомендовано)
1
2Подключение через драйвер
mariadb
:javascript// Подключение к MariaDB через клиент mariadb const mariadb = require('mariadb'); // Указан стандартный пароль root для MariaDB в ServBay — 'password' const pool = mariadb.createPool({ host: 'localhost', user: 'root', password: 'password', database: 'servbay_koa_app', // убедитесь, что база создана, или измените при необходимости connectionLimit: 5 }); pool.getConnection() .then(conn => { console.log("Connected to MariaDB"); conn.release(); // Возврат соединения в пул }) .catch(err => { console.error("MariaDB connection error:", err); }); // Примечание: соединения из пула выдаются асинхронно через промисы
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22Подключение через
mysql2
(рекомендуется):javascript// Используем mysql2/promise — промис-версия клиента для MariaDB/MySQL const mysql = require('mysql2/promise'); // Стандартный пароль root для MariaDB в ServBay — 'password' const pool = mysql.createPool({ host: 'localhost', user: 'root', password: 'password', database: 'servbay_koa_app', // база должна быть создана заранее waitForConnections: true, connectionLimit: 10, queueLimit: 0 }); pool.getConnection() .then(conn => { console.log("Connected to MariaDB/MySQL using mysql2"); conn.release(); // Возврат соединения в пул }) .catch(err => { console.error("MariaDB/MySQL connection error:", err); }); // Примечание: стандартный пароль указан в настройках СУБД в интерфейсе ServBay и может быть изменен. // Для production не храните пароли в коде, используйте переменные окружения.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25MariaDB по умолчанию слушает порт
3306
. Пароль root и другие детали найдёте в настройках ServBay. Базу данных (servbay_koa_app
) необходимо создать вручную через ServBay или с помощью внешних инструментов (например, TablePlus, DBeaver).PostgreSQL
Установите накладку драйвера для PostgreSQL:
bashcd /Applications/ServBay/www/servbay-koa-app npm install pg
1
2Подключение к серверу PostgreSQL:
javascript// Коннект с помощью клиента pg const { Pool } = require('pg'); // В ServBay по умолчанию пользователь 'user', пароль 'password' const pool = new Pool({ user: 'user', // стандартное имя пользователя ServBay host: 'localhost', database: 'servbay_koa_app', // база должна быть создана вручную password: 'password', // стандартный пароль ServBay port: 5432, // стандартный порт PostgreSQL }); pool.connect((err, client, done) => { if (err) { console.error('PostgreSQL connection error:', err); return; } console.log('Connected to PostgreSQL'); client.release(); // Возврат соединения в пул }); // Примечание: стандартные логин/пароль вы всегда найдете и поменяете в интерфейсе ServBay. // Не оставляйте пароли в открытом коде!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23PostgreSQL от ServBay слушает на
5432
. Имя базы данных потребуется создать вручную.
Управление базами данных в ServBay
Помимо кода, управлять базами удобно с помощью графических приложений. Все сервисы в ServBay слушают на 127.0.0.1
и доступ к ним осуществляется по стандартным портам, логинам и паролям из GUI ServBay.
- Просмотр/смена стандартных паролей: Откройте ServBay -> необходимая БД -> значок настроек — там можно посмотреть и поменять пароль пользователя
root
(MariaDB) илиuser
(PostgreSQL). - Создание БД/пользователей: Используйте внешние инструменты (например, TablePlus, DBeaver, pgAdmin, MongoDB Compass), подключайтесь к нужному серверу и осуществляйте администрирование через SQL или UI.
Важные замечания
- Конфликт портов: Убедитесь, что выбранные вами порты для Koa.js (например, 8585, 8586) не заняты другими приложениями.
- Состояние ServBay: Проверьте, что сам ServBay и все нужные пакеты Node.js и СУБД работают.
- Файл hosts: ServBay обычно корректно обновляет
/etc/hosts
, но если появляются проблемы с доменами — проверьте этот файл. - Firewall: Брандмауэр macOS или сторонний firewall не должен блокировать ServBay и процессы Node.js.
- Просмотр логов: При затруднениях изучите логи ServBay (во вкладке в интерфейсе) и вывод терминала Node.js для диагностики.
Часто задаваемые вопросы (FAQ)
В: Почему стоит использовать обратный прокси ServBay для доступа к проекту Koa.js?
О:
- Имитирует production: Пользовательский домен (например,
.servbay.demo
) выглядит как реальный сайт. - SSL "из коробки": ServBay автоматически выдаёт и устанавливает сертификаты для вашего сайта, позволяя сразу тестировать работу по HTTPS.
- Централизованное управление: Все сайты ведутся через общий интерфейс сервиса.
- Скрытие портов: Внешний трафик идёт через стандартные порты 80/443, внутренний — перенаправляется на нужный порт Node.js.
- Имитирует production: Пользовательский домен (например,
В: Могу ли я работать без прокси, просто открывая
localhost:PORT
?О: Да, можно прямо открыть, например,
http://localhost:3000
в браузере. Но так вы не получите преимущества пользовательских доменов, автоматического SSL, просмотра логов и прочих функций сайта от ServBay. Для реалистичной имитации production лучше использовать проксирование ServBay.В: Какие пароли для баз данных используются по умолчанию и где их изменить?
О: Стандартные пароли указаны в разделе Базы данных аппликейшна ServBay. Кликните на настройки нужной БД — там они отображаются и редактируются. В целях безопасности рекомендуется сменить их после установки.
Выводы
Следуя этому руководству, вы научились разрабатывать проекты на Koa.js в macOS с использованием ServBay. Вы создали минимальное приложение Koa.js, настроили обратный прокси для доступа по пользовательскому домену и через HTTPS, а также научились подключать интегрированные базы данных.
ServBay предоставляет Node.js-разработчикам интегрированную и удобную экосистему, позволяя сфокусироваться на коде, а не рутинной настройке среды. Воспользуйтесь потенциалом ServBay, чтобы повысить скорость и качество вашей разработки!