IIS部署

概述

ThingsGateway 网关可以部署在 Windows IIS 服务器上，利用 IIS 的强大功能提供稳定、安全的 Web 服务。IIS 部署适用于需要与现有 Windows 基础设施集成的企业环境。

重要注意事项

1、必须启用 IIS WebSocket 协议以支持实时通信功能

2、必须禁用 IIS 应用程序池回收机制以确保网关长期稳定运行

3、确保服务器已安装 .NET 8.0 运行时（或更高版本）

部署模式选择

ThingsGateway 支持两种部署模式：

依赖框架部署（FDD）：需要安装 ASP.NET Core Runtime，发布文件较小
独立部署（SCD）：包含运行时，发布文件较大但无需安装 Runtime

系统要求

操作系统要求

Windows Server 2012 R2 或更高版本
Windows 10/11 专业版或企业版

IIS 要求

IIS 8.0 或更高版本
ASP.NET Core 模块（AspNetCoreModuleV2）
WebSocket 协议支持
URL 重写模块（可选，用于高级路由配置）

.NET 运行时要求

.NET 8.0 Runtime（或更高版本）
下载链接：https://dotnet.microsoft.com/zh-cn/download/dotnet

硬件要求

CPU：双核及以上
内存：4GB 及以上（推荐 8GB）
磁盘空间：至少 2GB 可用空间

部署前准备

安装 .NET 运行时

如果选择依赖框架部署，需要先安装 .NET 运行时：

# 使用 PowerShell 安装 .NET 8.0 Runtime
winget install Microsoft.DotNet.Runtime.8

# 或从官网下载安装包
# https://dotnet.microsoft.com/zh-cn/download/dotnet/8.0

启用 IIS 功能

确保已启用以下 IIS 功能：

# 使用 PowerShell 启用必要的 IIS 功能
Enable-WindowsOptionalFeature -Online -FeatureName IIS-WebServerRole
Enable-WindowsOptionalFeature -Online -FeatureName IIS-WebServer
Enable-WindowsOptionalFeature -Online -FeatureName IIS-CommonHttpFeatures
Enable-WindowsOptionalFeature -Online -FeatureName IIS-HttpErrors
Enable-WindowsOptionalFeature -Online -FeatureName IIS-ApplicationDevelopment
Enable-WindowsOptionalFeature -Online -FeatureName IIS-NetFxExtensibility45
Enable-WindowsOptionalFeature -Online -FeatureName IIS-HealthAndDiagnostics
Enable-WindowsOptionalFeature -Online -FeatureName IIS-HttpLogging
Enable-WindowsOptionalFeature -Online -FeatureName IIS-Security
Enable-WindowsOptionalFeature -Online -FeatureName IIS-RequestFiltering
Enable-WindowsOptionalFeature -Online -FeatureName IIS-Performance
Enable-WindowsOptionalFeature -Online -FeatureName IIS-WebServerManagementTools
Enable-WindowsOptionalFeature -Online -FeatureName IIS-ManagementConsole
Enable-WindowsOptionalFeature -Online -FeatureName IIS-BasicAuthentication
Enable-WindowsOptionalFeature -Online -FeatureName IIS-WindowsAuthentication
Enable-WindowsOptionalFeature -Online -FeatureName IIS-StaticContent
Enable-WindowsOptionalFeature -Online -FeatureName IIS-DefaultDocument
Enable-WindowsOptionalFeature -Online -FeatureName IIS-DirectoryBrowsing
Enable-WindowsOptionalFeature -Online -FeatureName IIS-WebSockets
Enable-WindowsOptionalFeature -Online -FeatureName IIS-ApplicationInit

安装 ASP.NET Core 托管捆绑包

下载并安装 ASP.NET Core 托管捆绑包：

下载链接：https://dotnet.microsoft.com/permalink/dotnetcore-current-windows-runtime-bundle-installer

安装后重启 IIS 服务：

net stop was /y
net start w3svc

发布应用

发布配置

编辑项目的 .csproj 文件，进行基本的发布配置：

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <!-- 只包含英语资源文件，减少发布体积 -->
  <SatelliteResourceLanguages>en-US</SatelliteResourceLanguages>
  <!-- 不生成调试符号文件 -->
  <DebugType>none</DebugType>
  <DebugSymbols>false</DebugSymbols>
</PropertyGroup>

发布命令

# 依赖框架部署（需要安装 Runtime）
dotnet publish -c Release -o ./publish

# 独立部署（包含 Runtime，无需安装）
dotnet publish -c Release -o ./publish --self-contained true -r win-x64

发布选项说明

-c Release：发布配置为 Release 版本
-o ./publish：指定输出目录
--self-contained true：独立部署模式
-r win-x64：目标运行时为 Windows x64

重要注意事项

ThingsGateway 不支持以下发布选项：

PublishTrimmed：程序集裁剪功能
PublishSingleFile：单文件部署功能

请不要在发布配置中使用这些选项，以免导致部署失败。

IIS 部署步骤

步骤 1：创建网站目录

在服务器上创建网站目录并复制发布文件：

# 创建网站目录
New-Item -ItemType Directory -Path "C:\inetpub\ThingsGateway" -Force

# 复制发布文件到网站目录
Copy-Item -Path ".\publish\*" -Destination "C:\inetpub\ThingsGateway" -Recurse -Force

步骤 2：配置 IIS 网站

打开 IIS 管理器
右键点击"网站"，选择"添加网站"
配置网站信息：
- 网站名称：ThingsGateway
- 物理路径：C:\inetpub\ThingsGateway
- 绑定类型：http
- 端口：80（或其他可用端口）
- IP 地址：全部未分配（或指定 IP）

步骤 3：配置应用程序池

在 IIS 管理器中，点击左侧的"应用程序池"
找到刚创建的应用程序池（通常与网站名称相同）
右键点击，选择"高级设置"
配置以下参数：
- .NET CLR 版本：无托管代码
- 托管管道模式：集成
- 启用 32 位应用程序：False（如果是 64 位应用）
- 空闲超时（分钟）：0（禁用回收）
- 最大工作进程数：1（或根据需求调整）

步骤 4：配置环境变量

设置 ASP.NET Core 环境为 Production：

set ASPNETCORE_ENVIRONMENT=Production

或在 IIS 应用程序池的高级设置中添加环境变量：

打开应用程序池的高级设置
在"进程模型"部分，点击"环境变量"后面的"..."按钮
添加环境变量：
- 名称：ASPNETCORE_ENVIRONMENT
- 值：Production

步骤 5：配置 web.config

确保 web.config 文件正确配置：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet" 
                  arguments=".\ThingsGateway.Server.dll" 
                  stdoutLogEnabled="false" 
                  stdoutLogFile=".\logs\stdout" 
                  hostingModel="inprocess">
        <handlerSettings>
          <handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
          <handlerSetting name="debugLevel" value="Information" />
        </handlerSettings>
      </aspNetCore>
    </system.webServer>
  </location>
</configuration>

托管模型选择

ASP.NET Core 支持两种托管模型：

InProcess（进程内）：性能更好，但与 IIS 进程耦合
OutOfProcess（进程外）：隔离性更好，但性能略低

推荐使用 inprocess 模式以获得最佳性能。

步骤 6：测试网站

在 IIS 管理器中，右键点击网站，选择"浏览"
或在浏览器中访问：http://localhost（或配置的端口）
验证网站是否正常运行

高级配置

禁用 IIS 回收

IIS 默认会定期回收应用程序池，这对于长期运行的网关应用是不合适的。配置以下设置以禁用回收：

方法 1：通过配置编辑器

打开 IIS 管理器
点击左侧树根节点（计算机名称）
双击右侧的"配置编辑器"
在"节"下拉列表中选择 system.applicationHost/applicationPools
设置 startMode 为 AlwaysRunning
点击"应用"保存

iis7

方法 2：通过应用程序池设置

点击左侧的"应用程序池"
点击右侧的"设置应用程序池默认设置..."
设置以下参数：
- 常规 > 启动模式：AlwaysRunning
- 进程模型 > 空闲超时（分钟）：0
- 回收 > 固定时间间隔（分钟）：0
- 回收 > 虚拟内存限制（KB）：0
- 回收 > 专用内存限制（KB）：0
- 回收 > 请求限制：0

iis9

方法 3：通过 applicationHost.config

直接编辑 C:\Windows\System32\inetsrv\config\applicationHost.config 文件：

<applicationPools>
  <add name="ThingsGateway" startMode="AlwaysRunning">
    <processModel idleTimeout="00:00:00" />
    <recycling>
      <periodicRestart time="00:00:00" />
      <periodicRestart memory="0" />
      <periodicRestart privateMemory="0" />
      <periodicRestart requests="0" />
    </recycling>
  </add>
</applicationPools>

配置 HTTPS

为了安全起见，建议配置 HTTPS：

获取 SSL 证书（自签名证书或购买商业证书）
在 IIS 中绑定证书：
- 右键点击网站，选择"编辑绑定"
- 点击"添加"
- 类型：https
- 端口：443
- SSL 证书：选择已安装的证书
强制 HTTPS 重定向：

<system.webServer>
  <rewrite>
    <rules>
      <rule name="HTTP to HTTPS redirect" stopProcessing="true">
        <match url="(.*)" />
        <conditions>
          <add input="{HTTPS}" pattern="off" ignoreCase="true" />
        </conditions>
        <action type="Redirect" url="https://{HTTP_HOST}/{R:1}" redirectType="Permanent" />
      </rule>
    </rules>
  </rewrite>
</system.webServer>

配置 WebSocket

确保 WebSocket 协议已启用：

打开"控制面板" > "程序" > "启用或关闭 Windows 功能"
展开"Internet Information Services" > "万维网服务" > "应用程序开发功能"
勾选"WebSocket 协议"
点击"确定"并重启 IIS

或在 PowerShell 中执行：

Enable-WindowsOptionalFeature -Online -FeatureName IIS-WebSockets

配置日志

配置应用程序日志和 IIS 日志：

ASP.NET Core 日志

在 appsettings.json 中配置日志级别：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

IIS 日志

在 IIS 管理器中配置日志：

点击网站，双击"日志"
配置日志格式和位置
建议使用 W3C 日志格式

配置性能优化

启用压缩

在 web.config 中启用静态和动态内容压缩：

<system.webServer>
  <urlCompression doStaticCompression="true" doDynamicCompression="true" />
  <httpCompression>
    <dynamicTypes>
      <add mimeType="application/json" enabled="true" />
      <add mimeType="application/javascript" enabled="true" />
      <add mimeType="text/css" enabled="true" />
    </dynamicTypes>
    <staticTypes>
      <add mimeType="text/css" enabled="true" />
      <add mimeType="application/javascript" enabled="true" />
    </staticTypes>
  </httpCompression>
</system.webServer>

配置缓存

<system.webServer>
  <staticContent>
    <clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="30.00:00:00" />
  </staticContent>
</system.webServer>

配置卷影复制（热更新）

启用卷影复制可以在不停止网站的情况下更新文件：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <remove name="aspNetCore"/>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified"/>
    </handlers>
    <aspNetCore processPath="dotnet" 
                arguments=".\ThingsGateway.Server.dll" 
                stdoutLogEnabled="false" 
                stdoutLogFile=".\logs\stdout">
      <handlerSettings>
        <handlerSetting name="experimentalEnableShadowCopy" value="true" />
        <handlerSetting name="shadowCopyDirectory" value="..\ShadowCopyDirectory\" />
      </handlerSettings>
    </aspNetCore>
  </system.webServer>
</configuration>

卷影复制注意事项

卷影复制是实验性功能，建议在测试环境验证后再在生产环境使用
确保卷影复制目录有足够的权限和磁盘空间
更新后可能需要手动重启应用程序池以加载新文件

常见问题与解决方案

405 错误：不支持 PUT、DELETE 请求

问题描述：IIS 默认拒绝 PUT 和 DELETE 请求，返回 405 状态码。

原因：IIS 默认注册了 WebDAVModule 模块。

解决方案：在 web.config 中移除 WebDAVModule：

<configuration>
  <system.webServer>
    <modules runAllManagedModulesForAllRequests="true">
      <remove name="WebDAVModule"/>
    </modules>
    <handlers>
      <remove name="WebDAV"/>
    </handlers>
  </system.webServer>
</configuration>

或在 IIS 管理器中：

点击网站，双击"模块"
找到 WebDAVModule，右键点击"移除"

WebSocket 连接失败

问题描述：WebSocket 或 SignalR 连接失败。

原因：IIS WebSocket 协议未启用。

解决方案：

确认 WebSocket 协议已启用（见上文配置步骤）
检查防火墙设置，确保 WebSocket 端口（通常为 80/443）开放
在 web.config 中启用 WebSocket：

<system.webServer>
  <webSocket enabled="true" />
</system.webServer>

缺失 api-ms-win-*.dll 文件

问题描述：部署后出现缺少 api-ms-win-*.dll 文件的错误。

原因：发布时选择了错误的运行时架构。

解决方案：

重新发布，选择正确的目标运行时：
- 64 位服务器：-r win-x64
- 32 位服务器：-r win-x86
或使用独立部署模式：--self-contained true

应用程序池频繁回收

问题描述：应用程序池自动回收，导致服务中断。

原因：IIS 默认的回收策略。

解决方案：按照上文"禁用 IIS 回收"章节配置应用程序池。

文件占用无法更新

问题描述：更新文件时提示文件被占用。

解决方案：

启用卷影复制（见上文配置）

或临时停止应用程序池：

%windir%\system32\inetsrv\appcmd stop apppool "ThingsGateway"

更新文件后重新启动：

%windir%\system32\inetsrv\appcmd start apppool "ThingsGateway"

500.19 错误：配置文件错误

问题描述：访问网站时返回 500.19 错误。

原因：web.config 文件配置错误或 XML 格式问题。

解决方案：

检查 web.config 文件的 XML 格式是否正确
确认 AspNetCoreModuleV2 已正确安装
查看详细错误信息：
- 在 IIS 管理器中，双击"配置编辑器"
- 在"节"下拉列表中选择 system.webServer/httpErrors
- 设置 errorMode 为 Detailed

权限问题

问题描述：应用程序无法访问文件或目录。

解决方案：

为 IIS 应用程序池标识添加必要的权限：

$path = "C:\inetpub\ThingsGateway"
$acl = Get-Acl $path
$accessRule = New-Object System.Security.AccessControl.FileSystemAccessRule("IIS AppPool\ThingsGateway", "FullControl", "ContainerInherit,ObjectInherit", "None", "Allow")
$acl.SetAccessRule($accessRule)
Set-Acl $path $acl

或为 IIS_IUSRS 组添加权限：

icacls "C:\inetpub\ThingsGateway" /grant "IIS_IUSRS:(OI)(CI)F" /T

性能问题

问题描述：网站响应缓慢或 CPU 使用率高。

解决方案：

启用输出压缩（见上文配置）
优化数据库连接池配置
启用应用程序缓存
增加应用程序池的最大工作进程数（如果服务器资源充足）
使用性能分析工具（如 dotnet-trace）分析性能瓶颈

监控与维护

查看 IIS 日志

IIS 日志默认位置：C:\inetpub\logs\LogFiles\

查看 ASP.NET Core 日志

ASP.NET Core 日志默认位置：C:\inetpub\ThingsGateway\logs\

监控应用程序池

使用以下命令监控应用程序池状态：

# 查看所有应用程序池状态
%windir%\system32\inetsrv\appcmd list apppool

# 查看特定应用程序池状态
%windir%\system32\inetsrv\appcmd list apppool "ThingsGateway" /text:*

# 查看工作进程
%windir%\system32\inetsrv\appcmd list wp

自动化部署脚本

创建自动化部署脚本 deploy-iis.ps1：

param(
    [string]$SourcePath = ".\publish",
    [string]$TargetPath = "C:\inetpub\ThingsGateway",
    [string]$AppPoolName = "ThingsGateway"
)

# 停止应用程序池
Write-Host "Stopping application pool..."
%windir%\system32\inetsrv\appcmd stop apppool $AppPoolName

# 备份现有文件
$BackupPath = "$TargetPath\backup_$(Get-Date -Format 'yyyyMMdd_HHmmss')"
Write-Host "Backing up existing files to $BackupPath..."
New-Item -ItemType Directory -Path $BackupPath -Force | Out-Null
Copy-Item -Path "$TargetPath\*" -Destination $BackupPath -Recurse -Force -Exclude "backup_*"

# 复制新文件
Write-Host "Copying new files..."
Copy-Item -Path "$SourcePath\*" -Destination $TargetPath -Recurse -Force

# 启动应用程序池
Write-Host "Starting application pool..."
%windir%\system32\inetsrv\appcmd start apppool $AppPoolName

Write-Host "Deployment completed successfully!"

安全建议

启用 HTTPS：使用 SSL/TLS 加密通信
定期更新：保持 .NET Runtime 和 IIS 更新
限制访问：配置 IP 地址和域名限制
启用日志：记录访问和错误日志以便审计
最小权限原则：为应用程序池分配最小必要权限
定期备份：备份配置文件和重要数据
监控异常：设置警报以监控异常活动

概述​

系统要求​

操作系统要求​

IIS 要求​

.NET 运行时要求​

硬件要求​

部署前准备​

安装 .NET 运行时​

启用 IIS 功能​

安装 ASP.NET Core 托管捆绑包​

发布应用​

发布配置​

发布命令​

IIS 部署步骤​

步骤 1：创建网站目录​

步骤 2：配置 IIS 网站​

步骤 3：配置应用程序池​

步骤 4：配置环境变量​

步骤 5：配置 web.config​

步骤 6：测试网站​

高级配置​

禁用 IIS 回收​

方法 1：通过配置编辑器​

方法 2：通过应用程序池设置​

方法 3：通过 applicationHost.config​

配置 HTTPS​

配置 WebSocket​

配置日志​

ASP.NET Core 日志​

IIS 日志​

配置性能优化​

启用压缩​

配置缓存​

配置卷影复制（热更新）​

常见问题与解决方案​

405 错误：不支持 PUT、DELETE 请求​

WebSocket 连接失败​

缺失 api-ms-win-*.dll 文件​

应用程序池频繁回收​

文件占用无法更新​

500.19 错误：配置文件错误​

权限问题​

性能问题​

监控与维护​

查看 IIS 日志​

查看 ASP.NET Core 日志​

监控应用程序池​

自动化部署脚本​

安全建议​

参考资源​

概述

系统要求

操作系统要求

IIS 要求

.NET 运行时要求

硬件要求

部署前准备

安装 .NET 运行时

启用 IIS 功能

安装 ASP.NET Core 托管捆绑包

发布应用

发布配置

发布命令

IIS 部署步骤

步骤 1：创建网站目录

步骤 2：配置 IIS 网站

步骤 3：配置应用程序池

步骤 4：配置环境变量

步骤 5：配置 web.config

步骤 6：测试网站

高级配置

禁用 IIS 回收

方法 1：通过配置编辑器

方法 2：通过应用程序池设置

方法 3：通过 applicationHost.config

配置 HTTPS

配置 WebSocket

配置日志

ASP.NET Core 日志

IIS 日志

配置性能优化

启用压缩

配置缓存

配置卷影复制（热更新）

常见问题与解决方案

405 错误：不支持 PUT、DELETE 请求

WebSocket 连接失败

缺失 api-ms-win-*.dll 文件

应用程序池频繁回收

文件占用无法更新

500.19 错误：配置文件错误

权限问题

性能问题

监控与维护

查看 IIS 日志

查看 ASP.NET Core 日志

监控应用程序池

自动化部署脚本

安全建议

参考资源