使用 ServBay 建立並運行 Koa.js 專案

ServBay 是專為 macOS 打造的本機 Web 開發環境，整合了多種開發者常用套件，包括 Node.js 執行環境及數款資料庫。本文將引導你如何善用 ServBay 所提供的便利環境，快速建立、運作與管理你的 Koa.js 專案。

什麼是 Koa.js？

Koa.js 是由 Express.js 團隊開發的新世代 Node.js Web 框架。它以簡潔、表現力強大且功能齊全聞名，是開發 Web 應用與 API 的理想選擇。Koa.js 充分應用現代 JavaScript 特性，特別是 async/await 語法，極大地簡化了非同步操作和中介軟體撰寫，使程式碼更加清晰並易於維護。

Koa.js 主要特色

• 基於 async/await： 核心設計結合 async/await，讓非同步流程更直觀。
• 輕量核心： Koa 的核心程式庫非常精簡，僅提供基礎功能，更多需求可藉由中介軟體擴充。
• 強大的中介軟體： 採用級聯式（cascading）中介軟體機制，請求流程彈性且明確。
• 專注 Web 應用： 專注於 Web 應用與 API 開發，不含多餘或非必要的功能。

透過 Koa.js，開發者可更高效建構高性能、易維護的 Web 服務。

使用 ServBay 建置 Koa.js 開發環境

ServBay 為 Node.js 開發者打造出開箱即用的整合環境，內建 Node.js 執行環境與主流資料庫服務。配合 ServBay 的**網站（Website）**功能，你可輕鬆透過自訂網域以及 SSL 憑證來存取你的本機 Koa.js 專案。

前置條件

開始之前，請完成以下準備：

1. 安裝 ServBay： 前往 ServBay 官方網站 下載並安裝最新版 ServBay。
2. 安裝 Node.js 套件包： 開啟 ServBay 應用程式，進入**套件（Packages）**管理頁面，確認已安裝所需的 Node.js 版本。若未安裝，請勾選後點選安裝。
3. 熟悉 ServBay 操作： 了解如何在 ServBay 啟動/停止服務與管理網站（Website）。

建立 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 使用 npm 安裝 Koa.js 及型態定義檔（若使用 TypeScript）：

   npm install koa
   # 若使用 TypeScript 可安裝型別定義
   # npm install @types/koa --save-dev

3. 建立應用程式入口檔

   於專案目錄下建立 app.js，加入簡單的 Koa.js 應用程式碼：

   const Koa = require('koa');
   const app = new Koa();
   
   // 中介軟體：紀錄請求資訊
   app.use(async (ctx, next) => {
     const start = Date.now();
     await next();
     const ms = Date.now() - start;
     console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
   });
   
   // 中介軟體：處理根路徑請求
   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 應用，包含兩個中介軟體：一個負責請求時間與路徑紀錄，另一個則回應根路徑 / 要求，返回 "Hello from ServBay Koa.js App!"。應用將在 PORT 環境變數指定的埠號或預設的 3000 上監聽。

進入開發模式

開發時，通常會啟動本機 Node.js 行程運行 Koa.js，再透過 ServBay 的**網站（Website）**功能瀏覽本地專案。

1. 啟動 Koa.js 開發伺服器

   於終端機進入 servbay-koa-app 目錄，使用 node 執行 app.js。可指定特定埠號（例如 8585）避免衝突或便於 ServBay 配置：

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

   終端會顯示如 Koa.js server running on http://localhost:8585，代表伺服器成功運行於 8585 埠號。請保持此終端視窗開啟，使伺服器持續運作。

2. 設定 ServBay 網站（Website）反向代理

   若要以自訂網域方式瀏覽運行於 localhost:8585 的 Koa.js，你須在 ServBay 新增一個**網站（Website）**並採用反向代理：

   • 開啟 ServBay 應用。
   • 進入**網站（Website）**頁面。
   • 點擊左下角「+」新增網站。
   • 填寫網站設定：
     • 名稱 (Name)： ServBay Koa.js Dev Site
     • 網域 (Domain)： servbay-koa-dev.servbay.demo （建議使用 .servbay.demo 結尾，ServBay 會自動生成 SSL 憑證）
     • 類型 (Type)： 選擇 反向代理 (Reverse Proxy)
     • IP 位址 (IP Address)： 127.0.0.1（指向本機 Node.js 行程）
     • 埠號 (Port)： 8585（指向 Koa.js 監聽埠號）
     • 根目錄 (Document Root)： 反向代理型態此欄無影響，可留空或填 /Applications/ServBay/www/servbay-koa-app。
   • 儲存後按下「應用變更」。

   完成後，ServBay 會自動更新本機 hosts 檔，將 servbay-koa-dev.servbay.demo 指向 127.0.0.1，並透過內建 Caddy 或 Nginx 將該域名請求反向代理至 localhost:8585。而由於使用 .servbay.demo，ServBay User CA 亦會為該網域自動簽發並信任 SSL 憑證，可安全透過 HTTPS 存取。

   若需更詳細說明，請參考 ServBay 文件之新增 Node.js 開發網站章節（可選中文或英文文檔）。

3. 訪問 Koa.js 開發網站

   開啟瀏覽器，前往 https://servbay-koa-dev.servbay.demo。

   若一切順利，將可見 "Hello from ServBay Koa.js App!" 字樣，表示你已順利透過 ServBay 網站功能存取本地 Koa.js 開發伺服器。未來只需修改 app.js 並重啟 Node.js 行程，重新整理頁面即可預覽變更。

部署生產環境（模擬）

模擬生產環境時，通常會採用不同埠號、環境變數或啟動方式。ServBay 的反向代理同樣適用。

1. 啟動 Koa.js 生產伺服器（模擬）

   新開終端機，停止舊的開發伺服器（如仍在運行），並以模擬生產模式啟動，例如指定埠號 8586、加入 NODE_ENV：

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

   這將於 8586 埠號啟動 Koa.js 以模擬生產環境。

2. 配置 ServBay 網站（Website）反向代理（生產模擬）

   同上，在 ServBay 新增一組網站作為仿真生產入口：

   • 開啟 ServBay 並至**網站（Website）**頁面。
   • 點選「+」新增網站。
   • 輸入設定：
     • 名稱 (Name)： ServBay Koa.js Prod Site
     • 網域 (Domain)： servbay-koa-prod.servbay.demo （或你自己的網域，並可用 ServBay ACME/Let's Encrypt 申請免費 SSL 憑證）
     • 類型 (Type)： 選擇 反向代理 (Reverse Proxy)
     • IP 位址 (IP Address)： 127.0.0.1
     • 埠號 (Port)： 8586
     • 根目錄 (Document Root)： 留空或填專案路徑。
   • 儲存並套用變更。

   使用 .servbay.demo 仍採用 ServBay User CA 憑證。若自備公開網域，ServBay 支援經由 ACME（例如 Let's Encrypt）自動申請管理免費 SSL/TLS 憑證，完整模擬真實上線情境。更多詳情請見 ServBay 文件網站 SSL 加密連線說明。

3. 訪問 Koa.js 生產網站（模擬）

   開啟瀏覽器，前往 https://servbay-koa-prod.servbay.demo。

   頁面輸出內容將與開發環境相同，但本次請求經 ServBay 反向代理至 8586 埠上的 Node.js 行程處理。

資料庫連線

ServBay 整合多款主流資料庫系統（MongoDB、Redis、MariaDB（MySQL相容）、PostgreSQL）。你的 Koa.js 專案可直接使用 Node.js 驅動程式連接，默認皆可於本機 localhost 存取。

以下說明如何與 ServBay 內建資料庫連線。請先確認已於 ServBay 套件（Packages） 安裝並啟動所需資料庫。

1. 連接 MongoDB

   於專案目錄安裝 MongoDB Node.js 驅動（例如 mongoose 或 mongodb）：

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

   於 app.js 或其他模組添加連線程式：

   // 使用 Mongoose 連接 MongoDB
   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));
   
   // 注意：實務上，建議於服務啟動時建立連線
   // 並於連接成功後才開始監聽埠號。

   ServBay 預設安裝之 MongoDB 監聽 27017 埠，預設無需帳號密碼。只要自訂資料庫名稱即可（若不存在會自動建立）。

2. 連接 Redis

   安裝 Redis Node.js 客戶端：

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

   建立 Redis 連線：

   // 以 redis 套件連接 Redis
   const redis = require('redis');
   
   // 建立 Redis 客戶端，預設為 localhost:6379
   const client = redis.createClient({
     url: 'redis://localhost:6379' // ServBay 預設 Redis 埠號為 6379
   });
   
   client.on('connect', () => {
     console.log('Connected to Redis');
   });
   
   client.on('error', (err) => {
     console.error('Redis connection error:', err);
   });
   
   // 連接 Redis 伺服器
   client.connect();
   
   // 注意：實務應於連線成功後再執行 Redis 操作
   // 例如 async/await 配合 client.connect() 使用

   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');
   
   // ServBay 預設 MariaDB root 密碼為 '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 客戶端連接 MariaDB/MySQL
   const mysql = require('mysql2/promise'); // 請使用 promise 版本
   
   // ServBay 預設 MariaDB root 密碼為 '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 預設 root 密碼可於 ServBay GUI 資料庫設定頁查詢/修改。
   // 生產專案建議用環境變數管理密碼，避免硬編碼。

   ServBay 的 MariaDB 監聽 3306 埠。預設的 root 密碼可於 ServBay 管理介面查詢。你必須先於 ServBay 或用 TablePlus、DBeaver 等工具建立 servbay_koa_app 資料庫。

4. 連接 PostgreSQL

   安裝 PostgreSQL Node.js 驅動：

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

   連接 PostgreSQL 伺服器：

   // 以 pg 套件連接 PostgreSQL
   const { Pool } = require('pg');
   
   // ServBay 預設 PostgreSQL 使用者為 'user'，密碼 'password'
   const pool = new Pool({
     user: 'user', // ServBay 預設使用者
     host: 'localhost',
     database: 'servbay_koa_app', // 請確認資料庫已建立
     password: 'password', // ServBay 預設密碼
     port: 5432, // ServBay 預設 PostgreSQL 埠號
   });
   
   pool.connect((err, client, done) => {
     if (err) {
       console.error('PostgreSQL connection error:', err);
       return;
     }
     console.log('Connected to PostgreSQL');
     client.release(); // 釋放連線回連線池
   });
   
   // 注意：ServBay 預設 'user' 密碼可於 ServBay GUI 的資料庫設定查詢/修改
   // 生產專案建議勿硬編碼密碼

   ServBay 內建 PostgreSQL 監聽 5432 埠號，預設用戶與密碼可於 ServBay 管理界面查詢。你同樣需自建 servbay_koa_app 資料庫。

管理 ServBay 內資料庫

除了程式連線外，也可用圖形化工具管理 ServBay 提供的資料庫。ServBay 預設將所有資料庫服務監聽於 127.0.0.1 或 localhost，直接以 GUI 顯示之埠號、帳密連接即可。

• 查詢/變更預設密碼： 於 ServBay 應用，找到該資料庫套件，點擊設定圖示，即可查詢與修改預設 root (MariaDB) 或 user (PostgreSQL) 密碼。
• 建立資料庫/使用者： 可用 TablePlus、DBeaver、pgAdmin、MongoDB Compass 等工具，連上 ServBay 資料庫，並透過 SQL 命令或圖形化介面建立新資料庫、用戶與資料表等。

注意事項

• 埠號衝突： 請確認 Koa.js 應用所選埠號（如 8585、8586）未被其他程式佔用。
• ServBay 狀態： 確保 ServBay 及所需 Node.js 套件與資料庫服務均已啟動。
• hosts 檔案： ServBay 會自動管理 hosts 檔案，如碰到域名解析問題，可檢查 /etc/hosts 是否有相關記錄。
• 防火牆設置： 請確認 macOS 防火牆或第三方防火牆未擋下 ServBay 或 Node.js 行程網路連線。
• 日誌檢查： 若遇問題，檢查 ServBay 日誌（位於應用的日誌頁），以及 Node.js 行程於終端的輸出，有助問題排查。

常見問答 (FAQ)

• 問：為什麼要用 ServBay 反向代理存取我的 Koa.js 專案？

  答： 反向代理（經由 ServBay 網站功能）有下列好處：

  1. 仿真生產環境： 用自訂網域（如 .servbay.demo 或自域）而非 localhost:PORT 更貼近真實上線型態。
  2. SSL 支援： ServBay 可自動為你本地網站配置 SSL 憑證（ServBay User CA 或 Let's Encrypt），讓你於開發階段也能測試 HTTPS。
  3. 統一管理： 集中管理所有本機開發網站，維運更便捷。
  4. 埠號藏匿： 供外部存取時（如你允許）或瀏覽器用標準 80/443 埠，內部再轉發至 Node.js 監聽的高埠位。

• 問：能不能不用反向代理，直接 localhost:PORT 存取？

  答： 絕對可以。如果 Koa.js 監聽某個埠（如 3000 或其他），你可直接於瀏覽器輸入 http://localhost:PORT 測試。不過，這將不能享用 ServBay 的自訂網域、SSL、網站層級日誌管理等便利。若想仿真真實部署，還是推薦用 ServBay 反向代理。

• 問：ServBay 預設資料庫密碼是什麼？要怎麼改？

  答： 預設密碼可於 ServBay 應用 資料庫 介面查詢。在 MariaDB、PostgreSQL 等資料庫旁按設定圖示，於設定或資訊頁面會顯示預設帳號密碼，也可直接修改。出於安全建議，請務必修改預設密碼。

總結

依據本教學，你已學會如何利用 ServBay 在 macOS 上組建 Koa.js 開發環境：我們建立了一個基本 Koa.js 專案，並以 ServBay 的網站功能設置反向代理，達成以自訂網域和 HTTPS 存取本地 Koa.js 開發與生產（模擬）實例，同時說明如何串接 ServBay 提供的多款主流資料庫。

ServBay 為 Node.js 開發者提供了整合且易於管理的本機開發環境，讓你能更專注於撰寫程式，而不用花時間處理繁瑣環境配置。活用 ServBay 強大功能，可大幅提升你的開發效率。