在 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启动 XSP 服务器: 在项目根目录下，运行以下命令来启动 XSP4 服务器。您可以指定一个未被占用的端口号（例如 8080 或 9000），避免与 ServBay 中其他服务冲突。
bash# 在 9000 端口启动当前目录下的项目 xsp4 --port 9000xsp4: 调用适用于 .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 \ --printlogfastcgi-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 自动生成的配置，需要检查、添加或修改的部分示例如下：
nginxserver { 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 应用变得更加规范和便捷。希望本文档能帮助您顺利地开始您的开发工作！