在 macOS 上使用 ServBay 进行 ASP.NET Framework 4.x 开发

ServBay 通过内置强大的 Mono 环境，使得在 macOS 上进行 ASP.NET Framework 1.1/2.0/3.x/4.x (最高支持到 4.7.x) 的开发和测试变得简单可行。

自 ServBay v1.12.0 版本起，我们集成了 Mono 6.14.0，并自带了 XSP 开发服务器和 fastcgi-mono-server 工具，为您提供两种主要的运行 ASP.NET Framework 4.x 应用程序的方式：

使用 XSP 进行快速开发和测试: XSP 是一个轻量级的、专为 Mono 设计的 ASP.NET Web 服务器，非常适合开发和快速测试阶段。
使用 Nginx + FastCGI 部署: 这种方式更稳定、性能更好，更接近生产环境的应用，通过 ServBay 管理的 Nginx 将请求转发给 Mono 后端进程处理。

本文档将指导您如何在 ServBay 环境下配置和运行您的 ASP.NET Framework 4.x 项目。

关于 .NET Framework 和 .NET

请注意，本文档讨论的是基于 Mono 的 ASP.NET Framework 4.x 开发，这是一个较旧的 .NET 技术栈。

ServBay 也完全支持最新的 .NET (包括 .NET Core, .NET 5/6/7/8+) 的开发和部署。如果您正在开发新的 .NET 项目，或者希望迁移到更现代的 .NET 版本，我们推荐您使用 ServBay 提供的官方 Microsoft .NET SDK/运行时支持，而非本文档介绍的基于 Mono 的 ASP.NET Framework 方法。

前提条件

安装 ServBay: 确保您已在 macOS 上安装了 ServBay v1.12.0 或更高版本。
安装 Mono:
- 打开 ServBay 应用程序。
- 在左侧导航栏中，选择「软件包」。
- 在软件包列表中，找到「.NET」分类，点击展开。
- 找到「Mono 6」 (版本应为 6.14.0 或更高)，点击右侧的「安装」按钮，并等待安装完成。

准备您的 ASP.NET 项目

项目文件: 确保您有一个 ASP.NET Framework 4.x 的 Web Application 或 Web Site 项目，包含 web.config 文件。
推荐存放位置: 我们强烈建议将您的网站项目放置在 ServBay 统一管理的 www 目录下，即 /Applications/ServBay/www/。为每个项目创建一个单独的子目录。
- 示例: 如果您的项目名为 MyWebApp，则推荐的网站根路径为 /Applications/ServBay/www/MyWebApp。
- 在后续的步骤中，我们将使用 /Applications/ServBay/www/MyWebApp 作为示例路径。请务必将其替换为您项目的实际路径。

方法一：使用 XSP (内置开发服务器)

XSP 是 Mono 项目自带的轻量级 Web 服务器，非常适合本地开发和快速测试 ASP.NET Framework 应用程序。ServBay 安装的 Mono 6 包已包含 XSP4 (对应 ASP.NET 4.x)。

提示

如果您要运行 ASP.NET 1.1 的项目，请使用 xsp 命令。
如果您要运行 ASP.NET 2.0/3.x 的项目，请使用 xsp2 命令。
如果您要运行 ASP.NET 4.x 的项目，请使用 xsp4 命令。

步骤：

打开终端: 打开 macOS 的终端应用程序 (Terminal)。
导航到项目目录: 使用 cd 命令进入到您 ASP.NET 项目的根目录（即包含 web.config 文件的目录）。
bash
```
# 示例：进入名为 MyWebApp 的项目目录
cd /Applications/ServBay/www/MyWebApp
```
1
2
启动 XSP 服务器: 在项目根目录下，运行以下命令来启动 XSP4 服务器。您可以指定一个未被占用的端口号（例如 8080 或 9000），避免与 ServBay 中其他服务冲突。
bash
```
# 在 9000 端口启动当前目录下的项目
xsp4 --port 9000
```
1
2
- xsp4: 调用适用于 .NET Framework 4.x 的 XSP 服务器。
- --port 9000: 指定服务器监听的 TCP 端口号。
访问应用程序: 打开您的 Web 浏览器，访问 http://localhost:9000 或 http://127.0.0.1:9000。您应该能看到您的 ASP.NET 应用程序正在运行。
停止服务器: 当您完成开发或测试后，返回到启动 XSP 的终端窗口，按下 Ctrl + C 或者 回车键 来停止 XSP 服务器。

优点:

配置简单，启动快速。
非常适合本地开发和调试。

缺点:

性能不如 Nginx 等生产级 Web 服务器。
功能相对基础，不完全模拟生产环境。
需要保持终端窗口开启。

方法二：使用 Nginx + FastCGI

这种方式使用 ServBay 管理的 Nginx 作为前端 Web 服务器，负责接收客户端请求并处理静态文件，同时通过 FastCGI 协议将动态请求（如 .aspx, .ashx 等）转发给 Mono 后端进程 (fastcgi-mono-server4) 处理。这种方式更接近生产环境部署，性能也更好，并且可以利用 Nginx 的高级功能（如 SSL、缓存、压缩等）。

提示

如果您要运行 ASP.NET 1.1 的项目，请使用 fastcgi-mono-server 命令。
如果您要运行 ASP.NET 2.0/3.x 的项目，请使用 fastcgi-mono-server2 命令。
如果您要运行 ASP.NET 4.x 的项目，请使用 fastcgi-mono-server4 命令。

步骤：

确保 Mono 和 Nginx 已安装并运行:
- 通过 ServBay 的「软件包」安装 Mono 6 和 Nginx。
- 在 ServBay 的「服务」部分，确保 Nginx 服务已启动。
准备 ASP.NET 项目: 确保您的项目位于推荐路径下，例如 /Applications/ServBay/www/MyWebApp。
启动 FastCGI Mono Server:
- 打开一个新的终端窗口。
- 运行 fastcgi-mono-server4 进程。这个进程负责监听来自 Nginx 的 FastCGI 请求，解析 ASP.NET 页面和处理业务逻辑。
  bash
```
# 示例：为 MyWebApp 项目启动 FastCGI 服务
fastcgi-mono-server4 --applications=/:/Applications/ServBay/www/MyWebApp \
                     --socket=tcp:127.0.0.1:9001 \
                     --loglevels=Standard \
                     --printlog
```
  1
  2
  3
  4
  5
  - fastcgi-mono-server4: 启动适用于 .NET Framework 4.x 的 FastCGI 服务器。
  - --applications=/:/Applications/ServBay/www/MyWebApp: 此参数定义了 URL 路径到物理文件路径的映射。/: 表示网站的根 URL (/)，/Applications/ServBay/www/MyWebApp 是您项目的实际物理路径。当 Nginx 转发 /some/page.aspx 的请求时，Mono 会在 /Applications/ServBay/www/MyWebApp/some/page.aspx 查找并执行。请务必将 /Applications/ServBay/www/MyWebApp 替换为您项目的实际路径。
  - --socket=tcp:127.0.0.1:9001: 指定 FastCGI 服务器监听的 TCP 地址和端口。127.0.0.1 表示仅监听本地连接，9001 是端口号。请确保此端口（例如 9001）未被 ServBay 中其他服务或您系统中其他应用程序占用，并且与下面 Nginx 配置中的 fastcgi_pass 指令使用的端口一致。
  - --loglevels=Standard --printlog: （可选）在终端打印标准级别的日志，方便调试和查看 Mono 进程的输出。
- 注意: 启动 fastcgi-mono-server4 的终端窗口需要保持打开状态，否则服务会停止。对于长期运行，您可能需要使用 nohup、screen 或 tmux 等工具让它在后台运行。

配置 Nginx 站点:

在 ServBay 中，转到「站点」部分。
点击「添加站点」或选择一个现有站点进行编辑。
设置域名: 例如，使用品牌相关的域名 mywebapp.servbay.demo。ServBay 会自动为您将此域名添加到 macOS 的 Hosts 文件，使其指向 127.0.0.1。
设置网站根目录: 非常重要！ 将此设置为您 ASP.NET 项目的实际路径，例如 /Applications/ServBay/www/MyWebApp。这会正确设置 Nginx 配置中的 root 指令，用于 Nginx 处理静态文件。

启用并编辑自定义配置: 勾选站点设置右上角的「自定义配置」选择框。ServBay 会根据您设置的域名和网站根目录生成基础的 Nginx 配置文件。您需要在此基础上添加或修改配置，以将 ASP.NET 动态请求转发到 FastCGI Mono Server。

一个基于 ServBay 自动生成的配置，需要检查、添加或修改的部分示例如下：

nginx

server {
    listen 80; # 监听 HTTP 端口
    listen 443 ssl http2; # 监听 HTTPS 端口，启用 SSL 和 HTTP/2

    # ServBay 自动管理的 SSL 证书配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';
    ssl_prefer_server_ciphers on;
    ssl_session_timeout 1d;
    ssl_session_cache shared:ServBay:10m;
    ssl_session_tickets off;

    # 证书文件路径，ServBay 会自动生成并管理
    ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.crt; # 确保证书与实际域名路径一致
    ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.key; # 确保证书与实际域名路径一致

    server_name mywebapp.servbay.demo; # 应与您在 ServBay 中设置的域名一致
    root /Applications/ServBay/www/MyWebApp; # **确保**这与您设置的网站根目录一致

    # 添加 ASP.NET 默认文档，Nginx 找不到 index.html/htm 时会尝试这些
    index index.html index.htm default.aspx Default.aspx;

    # 主要的请求处理逻辑
    location / {
        # 尝试按顺序查找文件 ($uri) 或目录 ($uri/)
        # 如果找不到静态文件，则将请求交给 @mono 处理
        try_files $uri $uri/ @mono;
    }

    # （可选，但推荐）Nginx 直接高效地处理常见静态文件
    # 可以通过设置 expires 来利用浏览器缓存
    location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
        expires max; # 浏览器缓存到期时间最大化
        log_not_found off; # 不记录找不到静态文件的错误日志
        access_log off; # 不记录静态文件的访问日志，减少日志量
    }

    # 定义 @mono 命名 location 块，用于处理动态请求
    location @mono {
        # 将请求通过 FastCGI 协议传递给 Mono Server
        # **端口必须**与 fastcgi-mono-server4 启动时 --socket 参数指定的端口一致
        fastcgi_pass 127.0.0.1:9001;

        # 包含标准的 FastCGI 参数集
        include fastcgi_params;
        # 关键参数：设置脚本文件名，Mono Server 会根据这个路径找到要执行的 ASP.NET 文件
        # $document_root 是 Nginx 的 root 指令设置的路径
        # $fastcgi_script_name 是经过 Nginx 处理后的请求路径，通常是相对于 root 的文件路径
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        # PATH_INFO 通常不需要，这里设置为空
        fastcgi_param PATH_INFO "";

        # （可选）设置其他的 FastCGI 参数，例如 HOST 等，根据需要添加
        # fastcgi_param HOST $host;
    }

    # ServBay 可能还会包含其他默认配置，如日志路径等
    # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
    # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
}

保存配置并重载/重启 Nginx: 在 ServBay 中保存 Nginx 配置文件。ServBay 会尝试自动重载 Nginx 配置使其生效。如果配置有语法错误，ServBay 会弹出提示。如果需要，可以在 ServBay 的「服务」页面手动重启 Nginx 服务。

访问应用程序: 打开浏览器，访问您在 Nginx 中配置的域名（例如 https://mywebapp.servbay.demo）。由于 Nginx 配置了 443 端口的 SSL，建议使用 HTTPS 访问。Nginx 会将静态文件直接返回，将动态请求转发给 fastcgi-mono-server4，由 Mono 执行您的 ASP.NET 代码。

优点:

性能更好，更稳定，适合更接近生产环境的测试。
可以利用 Nginx 的强大功能（静态文件服务、SSL、负载均衡等）。
与 ServBay 的站点管理、域名和 Hosts 管理集成度更高。

缺点:

配置相对 XSP 复杂一些。
需要手动管理 fastcgi-mono-server4 进程（除非使用后台工具）。

如何选择合适的方法

对于快速开发、调试和简单功能测试，使用 XSP 是最便捷、启动最快的方式。只需一个命令即可运行。
对于需要更高性能、更接近生产环境的测试或内部部署，或者希望利用 Nginx 的高级特性（如 HTTPS、自定义域名、静态文件优化）和 ServBay 的站点管理功能时，选择 Nginx + FastCGI 模式是更好的选择。

注意事项与故障排查

文件权限: 确保运行 Nginx 的用户进程（通常由 ServBay 管理）和运行 fastcgi-mono-server4 的 macOS 用户对您的项目文件（位于 /Applications/ServBay/www/YourProjectName）拥有足够的读取权限。有时可能需要使用 chmod 或 chown 命令调整目录和文件的权限。
路径一致性: 仔细检查 Nginx 配置 (root 指令) 和 fastcgi-mono-server4 命令 (--applications 参数) 中的项目路径是否完全正确，并且都指向包含 web.config 文件的项目根目录。
端口冲突: 确保 XSP 或 fastcgi-mono-server4 使用的端口（示例中为 9000 或 9001）没有被 ServBay 中其他服务或您系统中其他应用程序占用。
日志检查:
- 检查 fastcgi-mono-server4 启动时终端的输出日志。--printlog 参数有助于直接在终端查看 Mono 的运行时日志。
- 检查 Nginx 的错误日志。ServBay 会在站点设置中显示对应站点的日志路径，通常位于 /Applications/ServBay/logs/nginx/your-domain.error.log。错误日志是排查 Nginx 配置问题或与 FastCGI Mono Server 通信问题的关键。
Mono 版本兼容性: ServBay 内置的 Mono 6.14.0 大致兼容 .NET Framework 1.1 到 4.7.2 的特性。如果您使用了更高版本 .NET Framework 的特性，或者遇到了兼容性问题，请考虑使用 ServBay 安装微软官方的 .NET SDK/运行时来运行现代 .NET 应用程序，或者尝试降级您的项目到 Mono 支持的 Framework 版本。
FastCGI 进程管理: 如果选择 Nginx + FastCGI 方式，请记住 fastcgi-mono-server4 进程需要持续运行。在开发过程中保持终端开启即可，但在更正式的环境中，您可能需要将其配置为后台服务或使用进程管理器。

通过 ServBay 内置的 Mono 6 环境和推荐的项目结构，在 macOS 上开发和运行传统的 ASP.NET Framework 4.x 应用变得更加规范和便捷。希望本文档能帮助您顺利地开始您的开发工作！

在 macOS 上使用 ServBay 进行 ASP.NET Framework 4.x 开发 ​

前提条件 ​

准备您的 ASP.NET 项目 ​

方法一：使用 XSP (内置开发服务器) ​

方法二：使用 Nginx + FastCGI ​

如何选择合适的方法 ​

注意事项与故障排查 ​