本文详解如何通过 iis 的 httpplatformhandler 模块托管 go web 应用，涵盖模块安装、web.config 配置、路径与环境变量设置，并指出常见误区（如误用 asp.net core module）。
本文详解如何通过 iis 的 httpplatformhandler 模块托管 go web 应用，涵盖模块安装、web.config 配置、路径与环境变量设置，并指出常见误区（如误用 asp.net core module）。
在 Windows 开发环境中，将 Go 编写的 Web 服务（如基于 net/http 或 Gin/Echo 的应用）部署到 IIS 是可行的，但不能直接像 ASP.NET 应用那样原生托管。关键前提：必须安装并启用 HttpPlatformHandler——这是微软专为 IIS 8+ 设计的反向代理模块，用于将 HTTP 请求转发给外部进程（如 Go 可执行文件），取代了已废弃的 FastCGI 或自建反向代理方案。
✅ 正确配置步骤
安装 HttpPlatformHandler
下载并安装 HttpPlatformHandler（最新版推荐 v2.0+），安装后需重启 IIS（iisreset）或服务器。验证是否启用：在 IIS 管理器 → “模块”中应可见 httpPlatformHandler。-
编译 Go 应用（推荐）
不建议在生产/开发环境中使用 go run（如 Azure 示例中的写法），因其启动慢、调试困难且依赖源码和 GOROOT。应预先编译为独立可执行文件：GOOS=windows GOARCH=amd64 go build -o server.exe server.go
将 server.exe 放置于站点物理路径下（如 C:\inetpub\wwwroot\mygoapp\server.exe）。
-
配置 web.config（核心）
在站点根目录放置 web.config，内容如下（适配本地开发环境）：<?xml version="1.0" encoding="UTF-8"?> <configuration> <system.webServer> <handlers> <add name="httpPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" /> </handlers> <httpPlatform processPath=".\server.exe" arguments="" startupTimeLimit="60" startupRetryCount="3" stdoutLogEnabled="true" stdoutLogFile=".\logs\stdout.log"> <environmentVariables> <!-- 如需指定 GOPATH/GOROOT（通常无需） --> <!-- <environmentVariable name="GOROOT" value="C:\Go" /> --> <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" /> </environmentVariables> </httpPlatform> </system.webServer> </configuration>⚠️ 注意事项：
- processPath 必须是相对路径（以站点物理路径为基准） 或绝对路径；避免硬编码 d:\home\...（Azure 专用路径）。
- stdoutLogEnabled="true" + stdoutLogFile 对排查启动失败至关重要（日志会记录 panic、端口占用等错误）。
- Go 应用代码中必须监听 http://localhost:PORT（非 0.0.0.0），且端口由 IIS 动态分配（通过环境变量 HTTP_PLATFORM_PORT 传入）——你的 Go 代码应读取该变量：
port := os.Getenv("HTTP_PLATFORM_PORT") if port == "" { port = "5000" // fallback } log.Fatal(http.ListenAndServe(":"+port, handler))
❌ 常见误区与替代方案
- 不要使用 ASP.NET Core Module：该模块专为 .NET Core Runtime 设计，无法启动 Go 进程。HttpPlatformHandler 是 Go 场景的官方推荐方案（历史原因详见 The Rough History of IIS HttpPlatformHandler）。
- 避免 go run 生产化：Azure 示例中的 go run 仅适用于快速演示，开发机上因路径、GOROOT、模块缓存等问题极易失败；始终优先使用预编译二进制。
- 权限问题：确保 IIS_IUSRS 或应用池标识对 server.exe 及其所在目录有读取+执行权限。
✅ 验证与调试
- 启动后检查 stdout.log 是否输出 Listening on :xxxx；
- 若出现 502.5 - Process Failure，90% 原因为：可执行文件路径错误、缺少依赖 DLL、端口被占或 Go 程序 panic；
- 使用 netstat -ano | findstr :PORT 确认进程是否真实监听。
通过 HttpPlatformHandler，Go 应用可无缝集成 IIS 的 HTTPS 终止、URL 重写、身份认证等企业级功能，是 Windows 服务器环境下稳健可靠的托管方案。
