简介这份资源面向需要在 Windows 服务器上部署 .NET WebApi 的开发者与运维人员聚焦 IIS 环境搭建与端口开放这一常见落地难题。内容以图文步骤为主线覆盖服务器管理器中添加角色与功能、勾选 Web 服务器IIS、补全 .NET Framework 3.5 与 4.5 组件、安装管理工具以及后续站点、应用程序池与虚拟目录的配置思路并提示端口开放与访问验证中的注意事项。资源包共 1 个 PDF 文件约 536KB篇幅精炼适合作为部署时的对照清单或排错参考。目前已有 341 人学习说明该主题在 Windows 服务发布场景中具有实际需求。读者可据此快速理清 IIS 托管 .NET WebApi 的完整链路减少因组件缺失或配置不当导致的部署失败提升上线效率。1. 从一次 500.19 说起.NET WebApi 挂 IIS 到底卡在哪上周帮一个朋友处理他那个模拟项目X的上线问题.NET WebApi 本地跑得好好的一发布到 Windows 服务器就给你甩脸子——HTTP 500.19配置错误页面连个像样的报错都不给。他折腾了一下午重装了两次运行时最后发现是 IIS 里 .NET Framework 4.5 功能压根没勾全。这种坑我见得太多了.NET WebApi 发布到 Windows 服务器并开放端口这件事说难不难但 IIS 的角色服务勾选、应用程序池的托管管道模式、端口防火墙这三处任意一个没对齐就是玄学 404 或者 500。这篇笔记面向的是第一次把 .NET WebApi 往 Windows Server 上扔的开发者也适合那些装过 IIS 但被“功能勾选不全”坑过的熟手。我会按“装 IIS → 配站点 → 放行端口 → 验证排错”的顺序把每一步的命令、参数和翻车点都摊开讲。你照着走一遍至少能少走我当年那两小时的弯路。2. 装 IIS 与 .NET 功能角色服务勾选清单2.1 添加角色和功能的前置检查在 Windows Server 上装 IIS第一步不是直接点安装而是先确认服务器管理器能正常加载。打开左下角第二个图标进入服务器管理器点击“管理”菜单选择“添加角色和功能”。向导会先让你选安装类型这里必须选“基于角色或功能的安装”不要选“远程桌面服务安装”后者是给 VDI 场景用的选错了后面勾选界面完全不一样。接下来是服务器选择默认选本地服务器。如果你是在一台已经加域的机器上操作注意别手滑选到别的节点。到了“服务器角色”这一步勾选“Web 服务器(IIS)”。这时候大概率会弹出一个确认框提示需要添加 IIS 管理控制台等依赖功能直接点“添加功能”。这个弹窗不是报错是 Windows 在帮你补全管理工具不点的话后面 IIS 管理器都打不开。提示如果服务器管理器打开缓慢或者角色列表刷不出来先检查 Windows Update 服务是否被禁用。我遇到过一台被优化过的镜像WU 服务停了导致角色功能列表加载卡死。2.2 功能勾选.NET 3.5 与 4.5 的取舍进入“功能”节点后你会看到 .NET Framework 3.5 功能和 .NET Framework 4.5 功能两个大项。这里是最容易埋雷的地方。原文说“全部勾选上”我建议你照做但要知道为什么。.NET Framework 3.5 功能里包含 HTTP 激活、非 HTTP 激活、TCP 端口共享这些 WCF 相关组件。如果你的 .NET WebApi 项目里用了 WCF 服务引用或者依赖了 System.ServiceModel 的程序集不勾这个后面运行时会报“未能加载文件或程序集”。.NET Framework 4.5 功能里则是 ASP.NET 4.5、WCF 服务、HTTP 激活等。注意每个可展开的下级选项框都要点开检查默认折叠状态下父项勾选不代表子项全选。# 用 PowerShell 一次性查看当前已安装的 .NET 功能状态 Get-WindowsFeature -Name NET-Framework-Features, NET-Framework-Core, NET-Framework-45-Features | Format-Table Name, DisplayName, InstallState -AutoSize这段命令的作用是列出 .NET Framework 相关功能的安装状态。InstallState列显示Installed才算装好Available表示没装。如果你不想通过图形界面反复点可以用Install-WindowsFeature NET-Framework-45-Features -IncludeAllSubFeature来补装但图形向导在首次安装时更直观能让你看清每个子项。2.3 IIS 角色服务与管理工具继续下一步到“角色服务”选择框。这里列表很长默认只勾了静态内容、默认文档这些基础项。原文说“将最下面的管理工具全部勾上其他项默认即可”这个策略对大多数 .NET WebApi 场景是够用的。但如果你需要跑 HTTPS记得把“安全性”下的“请求筛选”“IP 和域限制”按需勾上如果 API 要处理大文件上传把“性能”下的“动态内容压缩”也勾了。管理工具里的 IIS 管理控制台、IIS 管理脚本和工具、IIS 管理兼容性这几项必须全选。不装管理控制台你后面没法用图形界面建站点不装管理脚本PowerShell 里的WebAdministration模块加载不了自动化部署脚本直接歇菜。勾完点下一步确认安装等进度条走完。安装完成后不需要重启但建议重启一次服务器管理器让 IIS 管理器图标刷新出来。3. 建站点与应用程序池托管管道模式别选错3.1 应用程序池的 .NET 版本与管道模式IIS 装好后打开 IIS 管理器。左侧连接面板里展开服务器节点右键“应用程序池”选择“添加应用程序池”。名称随便起比如ApiPool。.NET CLR 版本这里要选v4.0.30319对应 .NET Framework 4.5 及以上。托管管道模式选“集成”不要选“经典”。为什么强调这个.NET WebApi 的WebApiConfig和RouteConfig依赖System.Web.Routing在集成模式下才能正常走 URL 路由。经典模式是给老 ASP.NET 1.1 兼容用的选错了会出现“无法找到资源”或者路由 404。我见过有人从老项目迁移过来应用程序池默认建成了经典模式调了半天代码最后发现是管道模式的问题。# 创建应用程序池并设置托管管道为集成模式 Import-Module WebAdministration New-WebAppPool -Name ApiPool Set-ItemProperty -Path IIS:\AppPools\ApiPool -Name managedRuntimeVersion -Value v4.0 Set-ItemProperty -Path IIS:\AppPools\ApiPool -Name managedPipelineMode -Value IntegratedNew-WebAppPool创建池子managedRuntimeVersion设为v4.0对应 .NET 4.xmanagedPipelineMode设为Integrated就是集成模式。如果你在图形界面里操作右键应用程序池 → 高级设置也能找到这两个参数。3.2 添加网站与物理路径右键“网站”选择“添加网站”。网站名称填一个能认出来的比如SimulatedApi。物理路径指向你发布出来的文件夹比如D:\publish\SimulatedApi。这个路径的权限要注意IIS 默认用IIS_IUSRS组来读取如果你的发布目录在 C 盘用户目录下权限继承可能有问题建议放在非系统盘根目录下。绑定类型选 HTTPIP 地址选“全部未分配”端口填一个你计划开放的端口比如8080。主机名留空除非你要用域名区分。这里有个细节如果你服务器上已经有站点占了 80 端口新站点用 8080 没问题但后面防火墙要对应放行 8080。!-- 发布目录下的 Web.config 关键节点确认 system.webServer 配置正确 -- system.webServer handlers remove nameExtensionlessUrlHandler-Integrated-4.0 / add nameExtensionlessUrlHandler-Integrated-4.0 path*. verb* typeSystem.Web.Handlers.TransferRequestHandler preConditionintegratedMode,runtimeVersionv4.0 / /handlers modules runAllManagedModulesForAllRequeststrue / /system.webServer这段 Web.config 是 .NET WebApi 在 IIS 上跑起来的关键。ExtensionlessUrlHandler负责把无扩展名的 API 请求转给托管处理器runAllManagedModulesForAllRequests确保所有请求都走托管模块。如果你发布后遇到 404 但路径明明没错先检查 Web.config 里有没有这段。3.3 应用程序池与站点的绑定站点建好后在 IIS 管理器里选中站点右侧操作面板点“基本设置”确认应用程序池选的是刚才建的ApiPool而不是默认的DefaultAppPool。默认池的 .NET 版本可能不对而且多个站点共用一个池一个崩了全崩。物理路径旁边的“连接为”按钮一般保持“应用程序用户(通过身份验证)”即可。如果你的 API 需要访问网络共享或者特定目录才需要改成特定用户。改之前想清楚改错了就是 401 或者 500.24。4. 开放端口防火墙与 URL 保留4.1 Windows 防火墙入站规则站点建好、应用程序池配好本地浏览器访问http://localhost:8080能通不代表外部能访问。Windows 防火墙默认拦截入站连接。打开“高级安全 Windows Defender 防火墙”新建入站规则类型选“端口”协议 TCP特定本地端口填8080操作选“允许连接”配置文件三个都勾上域、专用、公用名称写SimulatedApi-8080。# 用 PowerShell 添加入站规则放行 TCP 8080 New-NetFirewallRule -DisplayName SimulatedApi-8080 -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow -Profile Domain,Private,Public-Direction Inbound表示入站-LocalPort 8080指定端口-Action Allow放行-Profile三个网络位置都生效。如果你只在内网用可以去掉 Public但云服务器通常需要全开。执行完用Get-NetFirewallRule -DisplayName SimulatedApi-8080确认规则状态是 Enabled。4.2 HTTP.sys 与 URL 保留的坑有时候防火墙开了端口也通了但外部访问还是 503 或者连接被拒。这时候要查 HTTP.sys 的 URL 保留。IIS 用 HTTP.sys 内核驱动监听端口如果某个端口被其他进程通过netsh http add urlacl保留了IIS 就绑不上。# 查看当前 HTTP.sys 的 URL 保留和已注册端口 netsh http show urlacl netsh http show servicestateshow urlacl列出所有 URL 保留项show servicestate看当前监听的请求队列。如果发现 8080 被别的应用占了要么换端口要么删掉冲突的保留项。我一般会先netstat -ano | findstr :8080看端口占用确认是 IIS 的System进程PID 4在听而不是其他服务。注意不要随意用netsh http delete urlacl删保留项有些是系统组件注册的。删错了可能导致其他服务异常。先确认冲突来源再动手。4.3 云服务器安全组与网络 ACL如果你的 Windows 服务器是云主机除了系统防火墙还有一层云平台的安全组。安全组规则没放行 8080外面照样连不上。登录云控制台找到对应实例的安全组添加入站规则协议 TCP端口范围 8080/8080源地址按需填0.0.0.0/0或者你的办公网段。这一步和系统防火墙是“与”的关系两边都放行才通。我遇到过有人在系统防火墙里折腾半天最后发现是安全组没开。排查顺序建议先本地localhost通不通 → 再服务器本机127.0.0.1通不通 → 再同内网另一台机器访问 → 最后外网访问。一层层往外推能快速定位是哪层拦了。5. 避坑排查500.19、503 与端口不通5.1 HTTP 500.19 配置错误现象访问站点返回 500.19提示“无法读取配置文件”或“配置节被锁定”。原因通常是 IIS 缺少对应的角色服务或者 Web.config 里用了未安装的模块。比如system.webServer下的rewrite节点需要先装 URL Rewrite 模块否则 IIS 读配置时直接报错。解决先看错误页面里的“配置源”和“配置路径”定位到具体行。如果是rewrite相关去微软官网下载 URL Rewrite 模块装上。如果是handlers里的某个处理器类型找不到回服务器管理器检查 .NET 4.5 功能下的“ASP.NET 4.5”是否勾选。我一般会在装完 IIS 后用Get-WindowsFeature | Where-Object InstallState -eq Available扫一遍看有没有漏装的。5.2 HTTP 503 服务不可用现象站点能打开但返回 503或者应用程序池自动停止。原因多半是应用程序池的身份标识权限不足或者池子崩溃后快速失败保护触发了。先看事件查看器 → Windows 日志 → 应用程序找WAS或IIS-W3SVC-WP来源的错误。解决如果是权限问题给应用程序池身份IIS AppPool\ApiPool授予发布目录的读取和执行权限。如果是快速失败在应用程序池高级设置里把“快速失败保护”的“启用”设为 False先让错误暴露出来。但这不是长久之计根因通常是代码里有未处理异常导致进程反复崩溃。5.3 端口不通但本地能访问现象服务器上localhost:8080正常外部telnet 服务器IP 8080不通。原因按概率排云安全组没放行 Windows 防火墙没放行 HTTP.sys 端口冲突 网络 ACL 限制。解决按第 4 章的排查顺序逐层验证。telnet不通时先在服务器上用Test-NetConnection -ComputerName localhost -Port 8080确认本地监听正常再用Test-NetConnection -ComputerName 服务器内网IP -Port 8080确认内网可达。如果内网通外网不通基本就是安全组或防火墙。5.4 应用程序池自动回收导致首次请求慢现象API 闲置一段时间后第一次请求特别慢要等好几秒。原因是 IIS 应用程序池默认闲置 20 分钟就回收下次请求要重新加载 CLR 和程序集。解决在应用程序池高级设置里把“闲置超时”设为 0不回收或者把“固定时间间隔”设长一点。但完全禁用回收有内存泄漏风险我一般设成 1740 分钟29 小时每天凌晨低峰期回收一次。另外把“启动模式”设为AlwaysRunning配合“预加载”能进一步减少冷启动。5.5 发布后静态文件 404现象API 接口能通但 Swagger UI 或者 wwwroot 下的静态文件 404。原因是 IIS 的静态内容角色服务没装或者 Web.config 里system.webServer的staticContent被覆盖了。解决回服务器管理器确认“Web 服务器(IIS) → 常见 HTTP 功能 → 静态内容”已勾选。如果用了 Swagger确保SwaggerConfig里启用了EnableSwaggerUi并且发布目录下swagger-ui文件夹完整。有时候发布时漏了文件对比本地bin和服务器bin的文件列表能快速发现。6. 验证跑通从 curl 到浏览器全链路检查装完不是终点能稳定跑起来才算数。我习惯按下面这个顺序做一轮验证每一步都有明确的预期结果哪一步断了就停在哪一步排查。第一步服务器本机命令行验证。打开 PowerShell执行# 测试本地 API 端点-UseBasicParsing 避免 IE 引擎依赖 Invoke-WebRequest -Uri http://localhost:8080/api/values -UseBasicParsing | Select-Object StatusCode, Content预期返回StatusCode: 200和 JSON 内容。如果返回 404检查路由配置和RouteConfig里的MapHttpRoute如果返回 500看事件查看器里的详细异常。第二步内网另一台机器验证。用Test-NetConnection测端口再用浏览器或 curl 访问。这一步能排除本机回环地址的特殊性。# 在另一台内网机器上测试端口连通性和 HTTP 响应 Test-NetConnection -ComputerName 192.168.1.100 -Port 8080 curl -v http://192.168.1.100:8080/api/valuesTest-NetConnection的TcpTestSucceeded为 True 表示端口通curl -v能看到完整的请求响应头。如果端口通但 HTTP 返回 503回第 5.2 节查应用程序池。第三步外网验证。用手机热点或者外部网络访问公网 IP 加端口。这一步通了才算真正“开放端口”成功。如果外网不通但内网通回第 4.3 节查安全组。第四步持续可用性观察。别验证一次就完事挂个简单的监控脚本每隔几分钟请求一次观察 24 小时内的可用率。# 简易循环探测每 30 秒请求一次记录失败次数 $url http://localhost:8080/api/values $failCount 0 1..120 | ForEach-Object { try { $resp Invoke-WebRequest -Uri $url -UseBasicParsing -TimeoutSec 5 if ($resp.StatusCode -ne 200) { $failCount } } catch { $failCount } Start-Sleep -Seconds 30 } Write-Host 24 分钟内容失败次数: $failCount这个脚本跑 24 分钟覆盖了应用程序池默认闲置回收的时间窗口。如果失败次数大于 0说明有冷启动或者池子回收问题回第 5.4 节调整。第五步检查 IIS 日志。IIS 默认把访问日志写在C:\inetpub\logs\LogFiles\W3SVC*下用记事本或者 Log Parser 打开看有没有大量 500 或者 503。日志里的sc-status列就是状态码time-taken列能看到响应耗时。如果某个接口耗时突然飙高结合事件查看器里的ASP.NET性能计数器一起看。我自己的习惯是每次新服务器部署完这五步走完才把域名解析切过去。有一次偷懒跳过了第四步的持续观察结果上线第二天早上高峰期应用程序池回收API 集体超时被业务方追着问。从那以后我每次部署完 .NET WebApi 到 IIS都强制走一遍 24 分钟探测确认没有冷启动问题才收工。希望这套流程能帮你少踩几个坑。本文还有配套的精品资源点击获取