Создание и запуск проекта 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-сертификат.

Необходимые условия

Перед началом убедитесь, что:

1. Установлен ServBay: Скачайте и установите последнюю версию с официального сайта ServBay.
2. Установлен пакет Node.js: Откройте приложение ServBay, перейдите во вкладку Пакеты и убедитесь, что нужная версия Node.js установлена. Если нет — выберите и установите.
3. Вы знакомы с базовыми операциями ServBay: Понимаете, как запускать/останавливать сервисы и управлять сайтами.

Создание проекта Koa.js

Для хранения проекта используем рекомендуемую ServBay директорию — /Applications/ServBay/www.

1. Инициализация папки проекта

   Откройте приложение Terminal и перейдите в корневую папку сайта ServBay. Создайте новый каталог для проекта (например, servbay-koa-app), затем инициализируйте новый Node.js-проект:

   cd /Applications/ServBay/www
   mkdir servbay-koa-app
   cd servbay-koa-app
   npm init -y

   Команда npm init -y быстро создаёт файл package.json со стандартными настройками.

2. Установка Koa.js

   В каталоге проекта servbay-koa-app установите Koa.js и при необходимости (если вы планируете использовать TypeScript) его типы:

   npm install koa
   # Если нужен TypeScript, установите типы
   # npm install @types/koa --save-dev

3. Создание стартового файла приложения

   В папке servbay-koa-app создайте файл app.js и добавьте базовый пример кода Koa.js:

   const 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}`);
   });

   Этот код формирует минимальное Koa-приложение: одно middleware для логирования маршрутов и времени, второе — для обработки корня (/) и возврата строки "Hello from ServBay Koa.js App!". Сервер слушает порт, указанный в переменной окружения PORT, либо по умолчанию — 3000.

Режим разработки

В процессе разработки мы обычно запускаем локальный Node.js-процесс и получаем доступ к Koa.js-приложению через функцию Сайты в ServBay.

1. Запуск dev-сервера Koa.js

   Откройте терминал, перейдите в каталог servbay-koa-app и запустите app.js через Node.js. Для удобства или во избежание конфликтов портов рекомендуем явно указать порт, например 8585:

   cd /Applications/ServBay/www/servbay-koa-app
   PORT=8585 node app.js

   В терминале появится сообщение вроде Koa.js server running on http://localhost:8585, подтверждающее запуск. Оставьте этот терминал открытым — сервер должен работать постоянно.

2. Настройка обратного прокси-сайта в 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 (выберите английскую версию!).

3. Доступ к сайту Koa.js через браузер

   Перейдите по адресу https://servbay-koa-dev.servbay.demo в браузере.

   При правильной настройке вы увидите страницу с текстом "Hello from ServBay Koa.js App!". Это означает, что ваш Koa.js сервер работает локально и доступен через ServBay. После внесения изменений в app.js и перезапуска сервера — обновите страницу для просмотра обновлений.

Развёртывание (имитация продакшена)

Чтобы протестировать приложение в условиях, максимально приближённых к production, можно использовать другой порт и переменные окружения. СервBay позволяет аналогично проксировать такие “боевые” инстансы.

1. Имитация запуска Koa.js в production-режиме

   В новом окне терминала остановите dev-сервер и запустите приложение с новым портом (8586) и переменной окружения NODE_ENV:

   cd /Applications/ServBay/www/servbay-koa-app
   PORT=8586 NODE_ENV=production node app.js

   Такой запуск имитирует продакшн-инсталляцию на порту 8586.

2. Настройка сайта 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 для защиты сайта в официальной документации.

3. Просмотр 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.

1. MongoDB

   Сначала установите драйвер MongoDB (например, mongoose или mongodb):

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mongoose # или npm install mongodb

   Затем добавьте подключение в app.js или нужный модуль:

   // Соединение с 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));
   
   // Примечание: На практике подключение к базе обычно производится при инициализации приложения,
   // а сервер стартует только после успешного соединения.

   В стандартной установке MongoDB от ServBay слушает порт 27017, без пароля. Имя БД выбираете сами — она создаётся автоматически при первом обращении.

2. Redis

   Установите Redis-клиент:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install redis

   Подключение к серверу Redis:

   // Подключение к 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.

   ServBay Redis слушает на 6379 и не требует пароля по умолчанию.

3. MariaDB (или MySQL)

   MariaDB — форк MySQL с полной совместимостью API. ServBay включает пакет MariaDB, который можно использовать так же, как и MySQL.

   Установка драйвера MariaDB:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install mariadb # или npm install mysql2 (обычно более совместим, рекомендовано)

   Подключение через драйвер mariadb:

   // Подключение к 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);
     });
   
   // Примечание: соединения из пула выдаются асинхронно через промисы

   Подключение через mysql2 (рекомендуется):

   // Используем 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 не храните пароли в коде, используйте переменные окружения.

   MariaDB по умолчанию слушает порт 3306. Пароль root и другие детали найдёте в настройках ServBay. Базу данных (servbay_koa_app) необходимо создать вручную через ServBay или с помощью внешних инструментов (например, TablePlus, DBeaver).

4. PostgreSQL

   Установите накладку драйвера для PostgreSQL:

   cd /Applications/ServBay/www/servbay-koa-app
   npm install pg

   Подключение к серверу PostgreSQL:

   // Коннект с помощью клиента 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.
   // Не оставляйте пароли в открытом коде!

   PostgreSQL от 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?

  О:

  1. Имитирует production: Пользовательский домен (например, .servbay.demo) выглядит как реальный сайт.
  2. SSL "из коробки": ServBay автоматически выдаёт и устанавливает сертификаты для вашего сайта, позволяя сразу тестировать работу по HTTPS.
  3. Централизованное управление: Все сайты ведутся через общий интерфейс сервиса.
  4. Скрытие портов: Внешний трафик идёт через стандартные порты 80/443, внутренний — перенаправляется на нужный порт Node.js.

• В: Могу ли я работать без прокси, просто открывая localhost:PORT?

  О: Да, можно прямо открыть, например, http://localhost:3000 в браузере. Но так вы не получите преимущества пользовательских доменов, автоматического SSL, просмотра логов и прочих функций сайта от ServBay. Для реалистичной имитации production лучше использовать проксирование ServBay.

• В: Какие пароли для баз данных используются по умолчанию и где их изменить?

  О: Стандартные пароли указаны в разделе Базы данных аппликейшна ServBay. Кликните на настройки нужной БД — там они отображаются и редактируются. В целях безопасности рекомендуется сменить их после установки.

Выводы

Следуя этому руководству, вы научились разрабатывать проекты на Koa.js в macOS с использованием ServBay. Вы создали минимальное приложение Koa.js, настроили обратный прокси для доступа по пользовательскому домену и через HTTPS, а также научились подключать интегрированные базы данных.

ServBay предоставляет Node.js-разработчикам интегрированную и удобную экосистему, позволяя сфокусироваться на коде, а не рутинной настройке среды. Воспользуйтесь потенциалом ServBay, чтобы повысить скорость и качество вашей разработки!