对于 .NET Framework 4.5.2 项目，在 macOS 上需要使用 Mono 来运行。

第一步：安装必需工具

1. 安装 Mono

brew install mono

验证安装：

mono --version

2. 安装 NuGet

brew install nuget

3. 安装 MSBuild (包含在 Mono 中)

验证安装：

msbuild -version

4. 安装 XSP (Mono 的 Web 服务器)

brew install xsp

第二步：安装 VSCode 扩展

在 VSCode 中安装以下扩展（已在 <code>.vscode/extensions.json</code> 中推荐）：

1. C# Dev Kit – 微软官方 C# 支持
2. C# – OmniSharp 语言服务
3. .NET Test Explorer – 测试资源管理器

重启 VSCode 以激活扩展。

第三步：构建项目

方法 1：使用 VSCode 任务（推荐）

1. 按 <code>Cmd+Shift+P</code> 打开命令面板
2. 选择 <code>Tasks: Run Task</code>
3. 选择 <code>构建解决方案 (Debug)</code>

方法 2：使用终端命令

# 恢复 NuGet 包
nuget restore <Solution-Name>.sln

# 构建项目
msbuild <Solution-Name>.sln /p:Configuration=Debug

第四步：运行和调试

运行 WebAPI 项目

方法 1：使用 XSP（Mono Web 服务器）

# 在终端中运行
xsp4 --port=<PORT> --path=<ProjectName>

然后访问：http://localhost:23985/api/message

方法 2：使用 VSCode 任务

1. 按 <code>Cmd+Shift+P</code>
2. 选择 <code>Tasks: Run Task</code>
3. 选择 <code>运行 WebAPI (XSP)</code>

调试代码

1. 在代码中设置断点（点击行号左侧）
2. 按 <code>F5</code> 或点击调试面板的"开始调试"
3. 选择配置：<code>调试 WebAPI (Mono)</code>

运行单元测试

使用 VSCode 任务：

1. 按 <code>Cmd+Shift+P</code>
2. 选择 <code>Tasks: Run Task</code>
3. 选择 <code>运行单元测试</code>

使用命令行：

# 首先需要安装 NUnit Console Runner（如果还没有）
nuget install NUnit.ConsoleRunner -Version 3.15.0 -OutputDirectory packages

# 运行测试
mono packages/NUnit.ConsoleRunner.3.15.0/tools/nunit3-console.exe \
  <TestProjectName>/bin/Debug/<TestProjectName>.dll

常用 VSCode 快捷键

• <code>Cmd+Shift+B</code> – 运行默认构建任务
• <code>F5</code> – 开始调试
• <code>Shift+F5</code> – 停止调试
• <code>F9</code> – 切换断点
• <code>F10</code> – 单步跳过
• <code>F11</code> – 单步进入
• <code>Cmd+K Cmd+D</code> – 格式化文档

常见问题

1. Mono 找不到程序集

确保已运行 <code>nuget restore</code> 来恢复所有依赖包。

2. MSBuild 失败

检查 Mono 版本是否支持 .NET Framework 4.5.2：

mono --version

需要 Mono 5.0 或更高版本。

3. XSP 无法启动

确保端口 23985 未被占用：

lsof -i :23985

4. OmniSharp 无法加载项目

在 VSCode 设置中确保：

• <code>omnisharp.useModernNet</code> 设置为 <code>false</code>
• <code>omnisharp.monoPath</code> 指向正确的 Mono 安装路径

已知限制

1. 调试功能受限：Mono 的调试体验不如 Windows 上的 Visual Studio
2. 性能差异：Mono 运行性能可能低于 Windows .NET Framework
3. 某些 API 不可用：部分 Windows 特定的 API 在 Mono 上不支持

建议

对于生产环境部署，建议：

1. 在 Windows Server 上使用 IIS 托管
2. 或考虑将项目迁移到 .NET 6/8 以获得跨平台支持

迁移到现代 .NET 的好处

如果你计划长期维护此项目，可以考虑迁移到 .NET 8：

• 原生跨平台支持（无需 Mono）
• 更好的性能
• 现代化的工具链
• 长期支持（LTS）

迁移步骤请参考：https://docs.microsoft.com/zh-cn/aspnet/core/migration/

添加 Microsoft 仓库

sudo rpm -Uvh https://packages.microsoft.com/config/centos/8/packages-microsoft-prod.rpm

安装运行时

sudo dnf install -y aspnetcore-runtime-8.0

验证

dotnet –list-runtimes

如果上面的源不可用，可以用脚本安装：

下载安装脚本

curl -sSL https://dot.net/v1/dotnet-install.sh -o dotnet-install.sh
chmod +x dotnet-install.sh

安装到 /usr/share/dotnet（全局）

sudo ./dotnet-install.sh –channel 8.0 –runtime aspnetcore –install-dir /usr/share/dotnet

创建软链接

sudo ln -sf /usr/share/dotnet/dotnet /usr/bin/dotnet

验证

dotnet –list-runtimes

本文是一次完整的 线上问题排查 + 架构修复 + 压力测试验证 的工程级总结，可作为 事故复盘、容量评估报告、运维 Runbook 使用。

一、问题背景与现象

初始问题

• Nginx 错误日志频繁出现：

  upstream timed out (110: Connection timed out) while connecting to upstream

• 请求多为：

  OPTIONS /api/Ads/resolve HTTP/2.0

• 上游地址：<code>127.0.0.1:5085</code>（.NET Kestrel）

同时观测到的内核异常

• <code>listen queue overflow</code>
• <code>SYNs to LISTEN sockets dropped</code>
• <code>SYN cookies sent</code>
• <code>TCPTimeWaitOverflow</code>

直接影响

• Nginx 无法连接本机上游
• API 出现大量失败
• 高并发下服务不可用

二、根因分析（结论级）

1⃣ Nginx → Kestrel 连接模型错误（核心根因）

在 <code>location /</code> 中错误地配置了：

proxy_set_header Connection "upgrade";

导致：

• 所有普通 HTTP 请求被迫使用 <code>Connection: upgrade</code>
• Keepalive 失效
• 每个请求都建立/断开 TCP 连接

直接引发短连接风暴

2⃣ OPTIONS 预检请求被放大

• 外站（如豆瓣）触发大量跨域请求
• 每个请求都会先发 <code>OPTIONS</code>
• <code>OPTIONS</code> 被转发到上游应用

在短连接模型下形成 连接洪峰。

3⃣ 内核层连锁反应

• SYN backlog 被打满
• accept queue 溢出
• 内核开始丢 SYN / 启用 SYN cookies
• Nginx 连接上游直接超时（110）

三、关键修复措施（工程级）

1⃣ 引入 upstream keepalive（最关键修复）

在 <code>http {}</code> 作用域中新增：

upstream eaglex_upstream {
    server 127.0.0.1:5085;
    keepalive 256;
}

统一使用：

proxy_pass http://eaglex_upstream;
proxy_http_version 1.1;
proxy_set_header Connection "";

2⃣ 修正 Connection 头使用方式（非常关键）

• 禁止在普通 HTTP 路径中使用：

  Connection: upgrade

• 只在 WebSocket 专用 location 中使用 upgrade

3⃣ 在 Nginx 层直接短路 OPTIONS 预检

location = /api/Ads/resolve {
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin $http_origin always;
        add_header Access-Control-Allow-Methods "GET,POST,OPTIONS" always;
        add_header Access-Control-Allow-Headers "Content-Type,Authorization" always;
        add_header Access-Control-Max-Age 86400 always;
        return 204;
    }
    proxy_pass http://eaglex_upstream;
}

彻底消除预检请求对上游的压力放大

4⃣ 缩短 proxy_connect_timeout（防止雪崩）

proxy_connect_timeout 2s;

避免 Nginx worker 在连接失败时长时间阻塞。

四、压测阶段的验证结论

压测过程中观测到的健康状态

• <code>.NET</code> CPU：≈ 260%–300%（4C 机器，尚有余量）
• Nginx CPU：≈ 10%–20%
• <code>ksoftirqd</code>：极低

• TCP 状态：

  estab ≈ 3000
  timewait ≈ 30
  orphan = 0

• 内核累计计数在压测前后 完全无增长：

  • listen queue overflow
  • SYN dropped
  • TCPTimeWaitOverflow

明确结论

连接层 / Nginx / 内核 TCP 已完全稳定，系统瓶颈成功转移至 .NET 应用 CPU 层。

五、错误日志的两类问题区分（重要）

A. <code>110 Connection timed out</code>

while connecting to upstream

• 含义：连接队列 / accept / backlog 问题
• 根因：连接模型错误
• 已在本次修复中解决

B. <code>111 Connection refused</code>

connect() failed (111: Connection refused)

• 含义：上游端口当时 没有进程在监听

• 可能原因：

  • dotnet 进程崩溃
  • 被 OOM killer 杀死
  • 重启 / 发布

属于 上游进程稳定性问题，与 backlog 无关。

六、压测与日常排障常用监控命令清单

1⃣ TCP 全局状态（必看）

ss -s

关注：<code>estab / timewait / orphan</code>

2⃣ 上游端口连接数（Nginx → Kestrel）

ss -ant | awk '$4=="127.0.0.1:5085"{c++} END{print c}'

3⃣ 上游连接状态分布

ss -ant | awk '$4=="127.0.0.1:5085"{print $1}' | sort | uniq -c | sort -nr

4⃣ 内核是否再次被打爆（差分判断）

netstat -s | egrep -i 'listen queue|SYNs to LISTEN|SYN cookies|TCPTimeWaitOverflow'

必须用 前后对比 判断是否仍在发生。

5⃣ Nginx 错误日志关键字

tail -n 200 /www/wwwlogs/eaglex_ads_api.error.log | egrep -i 'timed out|refused|502|504'

6⃣ 上游进程是否存活 / 是否重启

ps -p <dotnet_pid> -o pid,etimes,%cpu,%mem,cmd
ss -lntp | grep 5085

7⃣ OOM / 内核杀进程检查

dmesg -T | egrep -i 'oom|killed process'
journalctl -k | egrep -i 'oom|killed'

8⃣ .NET 运行时指标（强烈推荐）

dotnet-counters monitor System.Runtime --process-id <pid>

关注：

• CPU Usage
• ThreadPool Queue Length
• % Time in GC

七、最终工程级结论（可直接写入文档）

本次问题的根因是 Nginx → Kestrel 连接模型错误（短连接 + OPTIONS 预检放大），导致 TCP listen queue 溢出与 upstream connect timeout。

通过引入 upstream keepalive、修正 Connection 头、在 Nginx 层短路 CORS 预检，并配合合理的超时配置，连接层问题已完全消除。

压测结果表明：系统当前瓶颈已转移至 .NET 应用 CPU 层，TCP 与代理层稳定可靠，具备可预测的容量上限。

app.UseHttpsRedirection()

作用：HTTP 到 HTTPS 的即时重定向

• 当用户访问 http://example.com 时

• 服务器返回 307/308 重定向响应

• 浏览器自动跳转到 https://example.com

• 每次 HTTP 请求都会重定向

  特点：

• 立即生效，无需浏览器记忆

• 首次请求仍是 HTTP（可能被拦截）

• 每次都需要一次额外的重定向请求

  响应示例：
  HTTP/1.1 308 Permanent Redirect
  Location: https://example.com

  ---

  app.UseHsts()

  作用：HTTP 严格传输安全（HTTP Strict Transport Security）

• 首次访问（HTTPS）后，服务器返回特殊响应头

• 浏览器记住"这个网站只能用 HTTPS"

• 之后浏览器自动将所有 HTTP 请求改为 HTTPS

• 甚至在发送请求前就转换

  特点：

• 浏览器端强制，无需服务器重定向

• 防止中间人攻击（用户无法绕过）

• 首次访问必须是 HTTPS 才能设置

• 设置后很难撤销（有过期时间）

  响应头示例：
  Strict-Transport-Security: max-age=31536000; includeSubDomains

  参数说明：

• max-age=31536000：浏览器记住 1 年

• includeSubDomains：所有子域名也强制 HTTPS

  ---

  对比总结

  特性	UseHttpsRedirection	UseHsts
  工作位置	服务器端重定向	浏览器端强制
  首次访问	HTTP 可访问（重定向）	必须 HTTPS
  后续访问	每次都重定向	浏览器自动转 HTTPS
  性能	多一次请求	无额外请求
  安全性	中等（首次可被劫持）	高（浏览器强制）
  撤销难度	随时可撤销	需等待过期（max-age）