使用 ServBay 创建并运行 Koa.js 项目

ServBay 是一个支持 macOS 和 Windows 的本地 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. 创建应用入口文件

   在项目根目录 servbay-koa-app 下创建一个名为 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 文件。为了避免端口冲突或方便 ServBay 配置，我们可以指定一个特定的端口，例如 8585：

   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 可能会提示您需要应用更改，请点击应用。

   配置完成后，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 （指向模拟生产环境 Koa.js 应用监听的端口）
     • 根目录 (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 项目中连接这些数据库非常方便，因为它们都在本地运行，默认配置下可以通过 localhost 访问。

以下是使用 Node.js 驱动连接 ServBay 提供的一些数据库的示例代码片段。请确保您已在 ServBay 的**软件包（Packages）**中安装了相应的数据库，并且它们正在运行。

1. 连接 MongoDB

   首先，在您的 Koa.js 项目目录中安装 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 的 Node.js 驱动：

   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 上，使用 ServBay 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 的日志（通常位于 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. 统一管理: 在 ServBay 中集中管理您的所有本地开发网站，方便快捷。
  4. 端口隐藏: 外部访问者（如果您允许的话）或浏览器访问的是标准的 80/443 端口，内部请求才转发到 Node.js 进程监听的高端口。

• 问：我可以不使用反向代理，直接通过 localhost:PORT 访问吗？

  答： 可以。如果您的 Koa.js 应用直接监听在一个端口（例如 3000 或您指定的其他端口），您理论上可以直接在浏览器中访问 http://localhost:PORT 来进行开发和测试。然而，这样您将无法利用 ServBay 提供的自定义域名、自动 SSL、日志管理等网站层面的便利功能。对于更接近真实部署环境的开发，使用 ServBay 的反向代理是更好的选择。

• 问：ServBay 默认的数据库密码是什么？如何修改？

  答： ServBay 默认的数据库密码可以在 ServBay 应用的数据库界面中找到。点击对应的数据库（如 MariaDB 或 PostgreSQL）旁边的设置图标，通常可以在配置或信息窗口中看到默认的用户和密码。您也可以在该界面修改密码。出于安全考虑，建议您修改默认密码。

总结

通过本文的指导，您应该已经掌握了如何利用 ServBay 在 macOS 上搭建 Koa.js 开发环境。我们创建了一个基本的 Koa.js 应用，并通过 ServBay 的网站功能配置了反向代理，实现了通过自定义域名和 HTTPS 访问本地运行的 Koa.js 开发和模拟生产实例。同时，我们也了解了如何连接 ServBay 提供的多种常用数据库。

ServBay 为 Node.js 开发者提供了一个集成的、易于管理的本地开发环境，让您可以更专注于代码编写，而不是繁琐的环境配置。利用 ServBay 的强大功能，可以显著提升您的开发效率。