Tạo và chạy dự án Koa.js với ServBay

ServBay là một môi trường phát triển web nội bộ dành cho macOS và Windows, tích hợp nhiều gói phần mềm phổ biến như Node.js runtime và các loại cơ sở dữ liệu. Bài viết này sẽ hướng dẫn bạn tận dụng ServBay để nhanh chóng tạo, vận hành và quản lý dự án Koa.js của mình một cách tiện lợi.

Koa.js là gì?

Koa.js là framework web thế hệ tiếp theo trên nền Node.js, được phát triển bởi nhóm tác giả Express.js. Koa.js nổi bật với cú pháp đơn giản, tính biểu cảm cao và bộ tính năng mạnh mẽ, lý tưởng để xây dựng các ứng dụng web và API. Framework tận dụng các tính năng hiện đại của JavaScript, đặc biệt là cú pháp async/await, giúp đơn giản hóa xử lý bất đồng bộ và xây dựng middleware, từ đó khiến mã nguồn rõ ràng, linh hoạt và dễ bảo trì hơn.

Những điểm mạnh của Koa.js

Dựa trên async/await: Thiết kế xoay quanh việc sử dụng async/await giúp kiểm soát luồng bất đồng bộ cực kỳ trực quan.
Nhẹ và tối giản: Thư viện lõi của Koa rất nhỏ gọn, chỉ cung cấp những chức năng cơ bản, còn mở rộng qua hệ thống middleware mô-đun.
Middleware mạnh mẽ: Cơ chế trung gian kiểu chuỗi (cascading) giúp kiểm soát luồng request linh hoạt, rõ ràng.
Tập trung cho Web: Chuyên dành cho ứng dụng web và API, không kèm theo các đặc tính thừa ngoài nhu cầu thiết lập cơ bản.

Nhờ các đặc điểm trên, lập trình viên có thể xây dựng các dịch vụ web hiệu quả, dễ mở rộng và dễ bảo trì với Koa.js.

Thiết lập môi trường phát triển Koa.js với ServBay

ServBay cung cấp cho các lập trình viên Node.js một môi trường "mở hộp là chạy", tích hợp Node.js runtime và nhiều dịch vụ cơ sở dữ liệu thông dụng. Kết hợp với chức năng Website của ServBay, bạn dễ dàng truy cập dự án Koa.js qua tên miền tùy chỉnh và chứng chỉ SSL trong mạng nội bộ.

Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo đã hoàn thành các bước sau:

Cài đặt ServBay: Truy cập trang chủ ServBay để tải và cài đặt phiên bản mới nhất.
Cài đặt gói Node.js: Mở ứng dụng ServBay, vào mục quản lý Packages (Phần mềm) và cài phiên bản Node.js phù hợp với dự án bạn. Nếu chưa có, hãy chọn và cài đặt ngay.
Làm quen với thao tác ServBay: Tìm hiểu cách khởi động/dừng dịch vụ và quản lý các website bên trong ServBay.

Tạo mới dự án Koa.js

Bạn sẽ sử dụng thư mục gốc website ServBay: /Applications/ServBay/www để chứa mã nguồn dự án.

Khởi tạo thư mục dự án
Mở Terminal, chuyển đến thư mục gốc website của ServBay, tạo thư mục dự án mới (ví dụ: servbay-koa-app), sau đó khởi tạo dự án Node.js:
bash
```
cd /Applications/ServBay/www
mkdir servbay-koa-app
cd servbay-koa-app
npm init -y
```
1
2
3
4
Lệnh npm init -y sẽ tạo nhanh file package.json mặc định.
Cài đặt Koa.js
Ngay trong thư mục dự án servbay-koa-app, dùng npm để cài đặt Koa.js cùng với package kiểu TypeScript (nếu cần):
bash
```
npm install koa
# Nếu lập trình TypeScript có thể cài thêm định nghĩa kiểu dữ liệu
# npm install @types/koa --save-dev
```
1
2
3

Tạo file khởi động ứng dụng

Trong servbay-koa-app, tạo file app.js với mã nguồn Koa.js cơ bản:

javascript

const Koa = require('koa');
const app = new Koa();

// Middleware ghi log thông tin yêu cầu
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 xử lý yêu cầu tới root "/"
app.use(async ctx => {
  ctx.body = 'Hello from ServBay Koa.js App!';
});

// Định nghĩa cổng, ưu tiên biến môi trường PORT
const port = process.env.PORT || 3000;

// Khởi động HTTP server
app.listen(port, () => {
  console.log(`Koa.js server running on http://localhost:${port}`);
  console.log(`Project path: ${__dirname}`);
});

Đoạn mã trên tạo một ứng dụng Koa cơ bản, với hai middleware: một để ghi lại thời gian và đường dẫn của request, một để trả về thông điệp khi truy cập /. Ứng dụng được lắng nghe tại cổng do biến ENV PORT hoặc mặc định là 3000.

Khởi động chế độ phát triển

Thông thường, bạn sẽ chạy ứng dụng Koa.js ở local bằng tiến trình Node.js, kết hợp truy cập qua website đã cấu hình trong ServBay.

Chạy server Koa.js ở mode phát triển
Mở Terminal, vào thư mục dự án servbay-koa-app và chạy file app.js. Nên chỉ định cổng riêng để tránh xung đột và tiện cấu hình cùng ServBay, ví dụ 8585:
bash
```
cd /Applications/ServBay/www/servbay-koa-app
PORT=8585 node app.js
```
1
2
Terminal sẽ hiện dòng như Koa.js server running on http://localhost:8585, xác nhận server đã chạy và lắng nghe cổng 8585. Cứ để cửa sổ terminal này mở trong suốt quá trình chạy server.
Cấu hình Proxy ngược (Reverse Proxy) Website trong ServBay
Để có thể truy cập ứng dụng Koa.js (đang chạy tại localhost:8585) qua tên miền, bạn cấu hình website dạng proxy ngược trên ServBay như sau:
- Mở ứng dụng ServBay.
- Vào mục Website.
- Nhấn nút + bên dưới để thêm website mới.
- Nhập thông tin:
  - Tên (Name): ServBay Koa.js Dev Site
  - Tên miền (Domain): servbay-koa-dev.servbay.demo (nên dùng đuôi .servbay.demo để ServBay tự tạo chứng chỉ SSL)
  - Kiểu (Type): Chọn Reverse Proxy
  - Địa chỉ IP: 127.0.0.1 (điểm đến Node.js chạy cục bộ)
  - Cổng (Port): 8585 (cổng ứng dụng Koa.js đang nghe)
  - Thư mục gốc (Document Root): Không quan trọng với kiểu proxy, có thể để trống hoặc điền đường dẫn dự án /Applications/ServBay/www/servbay-koa-app.
- Lưu lại.
- Nếu được nhắc áp dụng thay đổi, hãy đồng ý.
Sau khi hoàn tất, ServBay sẽ tự động cập nhật file hosts nội bộ, trỏ tên miền servbay-koa-dev.servbay.demo về 127.0.0.1 và cấu hình proxy ngược bằng Caddy hoặc Nginx để chuyển tiếp các truy vấn về đúng cổng ứng dụng Node.js. Nhờ sử dụng tên miền .servbay.demo, chứng chỉ SSL được tạo và tin cậy tự động bởi ServBay User CA, nên bạn có thể truy cập bằng HTTPS an toàn.
Nếu muốn hướng dẫn chi tiết, tham khảo thêm website phát triển Node.js trong tài liệu ServBay (chọn bản tiếng Anh).
Truy cập website Koa.js trong môi trường phát triển
Mở trình duyệt, truy cập địa chỉ https://servbay-koa-dev.servbay.demo.
Nếu mọi thứ cấu hình đúng, bạn sẽ thấy thông điệp "Hello from ServBay Koa.js App!" hiện trên trang. Điều này xác nhận bạn đã truy cập server Koa.js qua domain và proxy của ServBay. Bất cứ khi nào bạn chỉnh sửa file app.js rồi khởi động lại tiến trình Node.js, chỉ cần refresh trang là sẽ thấy kết quả mới nhất.

Mô phỏng triển khai sản xuất

Khi cần kiểm thử môi trường sản xuất giả lập, bạn có thể sử dụng các cổng, biến môi trường, hoặc script khởi động riêng biệt. Proxy ngược của ServBay hoàn toàn áp dụng được cho các trường hợp này.

Chạy server Koa.js ở mode sản xuất giả lập
Ở một Terminal khác, dừng server phát triển (nếu còn chạy), sau đó khởi động ở môi trường sản xuất, ví dụ dùng cổng 8586 và biến môi trường NODE_ENV:
bash
```
cd /Applications/ServBay/www/servbay-koa-app
PORT=8586 NODE_ENV=production node app.js
```
1
2
Server Koa.js sẽ lắng nghe trên cổng 8586, mô phỏng trạng thái prod.
Cấu hình website Proxy ngược cho môi trường sản xuất
Tương tự môi trường dev:
- Mở ServBay, vào Website.
- Nhấn + tạo website mới.
- Nhập thông tin:
  - Tên (Name): ServBay Koa.js Prod Site
  - Tên miền (Domain): servbay-koa-prod.servbay.demo (nếu có domain riêng, có thể đăng ký SSL miễn phí bằng ACME/Let's Encrypt)
  - Kiểu (Type): Chọn Reverse Proxy
  - Địa chỉ IP: 127.0.0.1
  - Cổng: 8586
  - Thư mục gốc: Để trống hoặc điền tùy ý.
- Lưu và áp dụng.
Tên miền .servbay.demo sẽ dùng User CA, còn domain thật, ServBay hỗ trợ lấy và quản lý chứng chỉ SSL/TLS qua ACME (Let's Encrypt). Xem thêm hướng dẫn bảo mật SSL.
Truy cập website Koa.js Sản xuất (giả lập)
Trên trình duyệt, mở https://servbay-koa-prod.servbay.demo.
Bạn sẽ thấy nội dung giống phát triển, nhưng lần này request đi qua proxy ngược tới tiến trình Node.js ở cổng 8586.

Kết nối cơ sở dữ liệu

ServBay tích hợp các hệ cơ sở dữ liệu phổ biến như MongoDB, Redis, MariaDB (tương thích MySQL) và PostgreSQL. Ứng dụng Koa.js dễ dàng kết nối với những database này qua localhost vì đều được cài và chạy trên máy nội bộ.

Dưới đây là một số ví dụ kết nối với các hệ cơ sở dữ liệu ServBay cung cấp. Hãy đảm bảo đã cài đặt database tương ứng trong mục Packages của ServBay và đã khởi động nó.

Kết nối MongoDB

Đầu tiên, cài đặt driver MongoDB (mongoose hoặc mongodb) trong thư mục dự án:

bash

cd /Applications/ServBay/www/servbay-koa-app
npm install mongoose # hoặc npm install mongodb

Thêm đoạn mã kết nối vào file app.js hoặc module khác:

javascript

// Kết nối MongoDB bằng Mongoose
const mongoose = require('mongoose');

// MongoDB mặc định của ServBay không cần xác thực, đặt tên database tùy ý
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));

// Lưu ý: Trong ứng dụng thực tế, nên đặt phần kết nối ở đoạn khởi động
// Chỉ lắng nghe cổng khi connect thành công.

MongoDB mặc định của ServBay chạy ở cổng 27017, thường không yêu cầu username/password. Cứ đặt tên database theo ý bạn, nếu chưa có sẽ được tự động tạo.

Kết nối Redis

Cài đặt thư viện client Redis:

bash

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

Đoạn mã kết nối Redis:

javascript

// Kết nối Redis bằng thư viện redis
const redis = require('redis');

// Khởi tạo client, mặc định kết nối localhost:6379
const client = redis.createClient({
  url: 'redis://localhost:6379' // Redis ServBay mặc định cổng 6379
});

client.on('connect', () => {
  console.log('Connected to Redis');
});

client.on('error', (err) => {
  console.error('Redis connection error:', err);
});

// Kết nối với Redis
client.connect();

// Lưu ý: Trong thực tế, nên đợi kết nối thành công rồi mới thao tác với Redis
// Có thể kết hợp async/await với connect()

Redis mặc định của ServBay chạy ở cổng 6379 và không yêu cầu password.

Kết nối MariaDB (hoặc MySQL)

MariaDB là bản fork từ MySQL và API gần như hoàn toàn tương thích. ServBay cung cấp MariaDB như một gói database với cấu hình tương tự MySQL.

Cài đặt driver MariaDB:

bash

cd /Applications/ServBay/www/servbay-koa-app
npm install mariadb # hoặc npm install mysql2 (khuyên dùng, tương thích tốt)

Đoạn mã sử dụng driver mariadb:

javascript

// Kết nối MariaDB bằng driver mariadb
const mariadb = require('mariadb');

// MariaDB của ServBay có tài khoản root mặc định là 'password'
const pool = mariadb.createPool({
  host: 'localhost',
  user: 'root',
  password: 'password',
  database: 'servbay_koa_app', // Đảm bảo đã tạo database này
  connectionLimit: 5
});

pool.getConnection()
  .then(conn => {
    console.log("Connected to MariaDB");
    conn.release(); // Giải phóng kết nối về pool
  })
  .catch(err => {
    console.error("MariaDB connection error:", err);
  });

// Lưu ý: Lấy kết nối từ pool là thao tác bất đồng bộ

Đoạn mã dùng driver mysql2 (khuyên dùng):

javascript

// Kết nối MariaDB/MySQL bằng mysql2 (Promise)
const mysql = require('mysql2/promise');

// MariaDB của ServBay có tài khoản root mặc định là 'password'
const pool = mysql.createPool({
  host: 'localhost',
  user: 'root',
  password: 'password',
  database: 'servbay_koa_app', // Đảm bảo đã tạo database này
  waitForConnections: true,
  connectionLimit: 10,
  queueLimit: 0
});

pool.getConnection()
  .then(conn => {
    console.log("Connected to MariaDB/MySQL using mysql2");
    conn.release(); // Giải phóng kết nối về pool
  })
  .catch(err => {
    console.error("MariaDB/MySQL connection error:", err);
  });

// Lưu ý: Password root có thể xem/chỉnh trong GUI ServBay Database
// Trong dự án thực tế không nên ghi cứng password, hãy dùng biến môi trường

MariaDB trên ServBay mặc định chạy ở cổng 3306. Password của user root bạn xem tại giao diện quản lý database trong ServBay. Có thể dùng TablePlus, DBeaver… để tạo database servbay_koa_app.

Kết nối PostgreSQL

Cài đặt driver PostgreSQL:

bash

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

Đoạn mã kết nối PostgreSQL:

javascript

// Kết nối PostgreSQL bằng thư viện pg
const { Pool } = require('pg');

// PostgreSQL trên ServBay dùng user 'user', password 'password'
const pool = new Pool({
  user: 'user', // User mặc định của ServBay
  host: 'localhost',
  database: 'servbay_koa_app', // Đảm bảo đã tạo database này
  password: 'password', // Password mặc định
  port: 5432, // PostgreSQL mặc định của ServBay
});

pool.connect((err, client, done) => {
  if (err) {
    console.error('PostgreSQL connection error:', err);
    return;
  }
  console.log('Connected to PostgreSQL');
  client.release(); // Giải phóng kết nối về pool
});

// Lưu ý: Password của user mặc định xem/chỉnh trong giao diện ServBay
// Trong dự án thực tế không nên hardcode password

PostgreSQL trên ServBay mặc định lắng nghe cổng 5432, user và password như trên. Bạn cũng cần tự tạo database servbay_koa_app nếu chưa có.

Quản lý database trong ServBay

Bên cạnh truy cập thông qua mã nguồn, bạn có thể dùng các phần mềm quản lý database có giao diện đồ họa để quản lý database của ServBay. Chúng đều chạy trên IP 127.0.0.1 hoặc localhost với cổng, user, password như trong giao diện ServBay chỉ rõ.

Xem/chỉnh password mặc định: Vào ứng dụng ServBay, nhấn vào icon cài đặt của database ghép cần, sẽ thấy hoặc đổi được password của user như root (MariaDB) hay user (PostgreSQL).
Tạo database/user: Dùng TablePlus, DBeaver, pgAdmin, MongoDB Compass… kết nối tới database cục bộ, rồi tạo mới database, user, table bằng SQL hoặc giao diện trực quan.

Lưu ý quan trọng

Xung đột cổng: Chọn cổng chạy ứng dụng Koa.js (8585, 8586…) không bị ứng dụng khác chiếm dụng.
Trạng thái ServBay: Đảm bảo ServBay và các gói phần mềm Node.js, database đều đã khởi động.
File hosts: ServBay tự động quản lý file hosts. Nếu gặp vấn đề domain không resolve, kiểm tra /etc/hosts có đúng record.
Firewall: Hãy chắc chắn tường lửa macOS hoặc phần mềm bảo mật không chặn kết nối mạng của ServBay hay Node.js.
Xem log: Khi lỗi, hãy xem log trong ServBay (tab log trên giao diện ứng dụng) và terminal của Node.js để chẩn đoán chính xác.

Giải đáp thắc mắc thường gặp (FAQ)

Hỏi: Vì sao nên dùng proxy ngược (Reverse Proxy) của ServBay cho dự án Koa.js?
Đáp: Có nhiều lợi ích khi sử dụng proxy ngược qua chức năng Website của ServBay:
1. Mô phỏng môi trường sản xuất: Truy cập qua domain tùy chỉnh (.servbay.demo hoặc domain riêng) sẽ sát thực tế deployment hơn so với localhost:PORT.
2. Hỗ trợ SSL: ServBay tự động cấp chứng chỉ SSL cho website (User CA hoặc Let's Encrypt), giúp bạn phát triển và kiểm thử với HTTPS ngay ở local.
3. Quản lý tập trung: Quản lý mọi website nội bộ tại ServBay rất tiện lợi và nhanh chóng.
4. Ẩn cổng: Truy cập từ ngoài (nếu bạn cấp phép) hoặc qua trình duyệt dùng các cổng tiêu chuẩn 80/443, còn request nội bộ mới chuyển sang port của tiến trình Node.js.
Hỏi: Có thể không dùng proxy ngược, chỉ truy cập localhost:PORT được không?
Đáp: Hoàn toàn được. Nếu ứng dụng Koa.js nghe trên cổng riêng (3000 hoặc bất kỳ), bạn có thể mở trực tiếp bằng http://localhost:PORT trên trình duyệt để phát triển và kiểm thử. Tuy nhiên, như thế bạn sẽ không tận dụng được tên miền tùy chỉnh, SSL tự động, quản lý log… của ServBay. Để sát với môi trường deployment thật và khai thác các tiện ích của ServBay, proxy ngược là lựa chọn tối ưu.
Hỏi: Password mặc định cho database ServBay là gì? Có thay đổi được không?
Đáp: Password mặc định xem tại tab Database của ứng dụng ServBay. Nhấn vào biểu tượng cài đặt của database (như MariaDB, PostgreSQL) sẽ hiển thị user và password mặc định. Bạn có thể chỉnh sửa ngay tại đây. Vì lý do bảo mật, nhớ đổi password mặc định.

Tổng kết

Qua bài viết, bạn đã nắm được cách thiết lập môi trường phát triển Koa.js trên macOS với ServBay. Bạn tạo ứng dụng Koa.js cơ bản, cấu hình website proxy ngược để truy cập bằng tên miền tùy chỉnh và HTTPS, mô phỏng cả chế độ phát triển và sản xuất, đồng thời tìm hiểu cách kết nối với các database phổ biến do ServBay tích hợp.

ServBay mang đến môi trường local phục vụ lập trình Node.js hiện đại, quản lý tất cả trong một, giúp bạn tập trung hơn vào xây dựng tính năng thay vì mất thời gian thiết lập môi trường. Hãy khai thác hiệu quả các chức năng của ServBay để tăng tốc quá trình phát triển dự án của bạn!

Tạo và chạy dự án Koa.js với ServBay ​

Koa.js là gì? ​

Những điểm mạnh của Koa.js ​

Thiết lập môi trường phát triển Koa.js với ServBay ​

Điều kiện tiên quyết ​

Tạo mới dự án Koa.js ​

Khởi động chế độ phát triển ​

Mô phỏng triển khai sản xuất ​

Kết nối cơ sở dữ liệu ​

Quản lý database trong ServBay ​

Lưu ý quan trọng ​

Giải đáp thắc mắc thường gặp (FAQ) ​

Tổng kết ​

Tạo và chạy dự án Koa.js với ServBay

Koa.js là gì?

Những điểm mạnh của Koa.js

Thiết lập môi trường phát triển Koa.js với ServBay

Điều kiện tiên quyết

Tạo mới dự án Koa.js

Khởi động chế độ phát triển

Mô phỏng triển khai sản xuất

Kết nối cơ sở dữ liệu

Quản lý database trong ServBay

Lưu ý quan trọng

Giải đáp thắc mắc thường gặp (FAQ)

Tổng kết