使用 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. 创建应用入口文件

   在项目根目录 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 的强大功能，可以显著提升您的开发效率。