本文介绍通过 iis 的 httpplatformhandler 模块在 windows 本地环境（非 azure）中托管 go web 应用的完整方案，涵盖模块安装、web.config 配置要点、路径与权限注意事项，并提供可直接运行的配置示例。
本文介绍通过 iis 的 httpplatformhandler 模块在 windows 本地环境（非 azure）中托管 go web 应用的完整方案，涵盖模块安装、web.config 配置要点、路径与权限注意事项，并提供可直接运行的配置示例。
在 Windows 开发环境中，将 Go 编写的 Web 服务（如基于 net/http 或 Gin、Echo 等框架的应用）部署到 IIS 并非原生支持，但可通过 HttpPlatformHandler（HTTP 平台处理程序）模块实现——这是微软为 IIS 8+ 设计的通用进程托管机制，专用于代理请求至外部可执行程序（如 Go 二进制），已取代过时的 FastCGI 和反向代理手动配置方式。
✅ 前置条件：安装 HttpPlatformHandler
IIS 默认不包含该模块，需单独下载安装：
- 访问官方发布页：HttpPlatformHandler 下载（推荐最新稳定版，如 HttpPlatformHandler_amd64.msi）；
- 以管理员身份运行安装包；
- 安装完成后，重启 IIS（执行 iisreset 或通过 IIS 管理器重启）；
- 验证：在 IIS 管理器 → 选择服务器 → “模块”中应可见 httpPlatformHandler 条目。
⚠️ 注意：若使用 IIS 10（Windows 10/Server 2016+），请确保启用“WebSocket 协议”和“URL 重写”（非必需但建议），并确认应用程序池 .NET CLR 版本设为 “无托管代码”（No Managed Code）——Go 进程完全独立于 .NET 运行时。
?️ web.config 配置（适配本地开发环境）
Azure 示例中的路径（如 d:\home\site\wwwroot\...）仅适用于 App Service，本地 IIS 必须改为绝对物理路径或使用 IIS 变量。以下为本地部署推荐配置（保存为站点根目录下的 web.config）：
<?xml version="1.0" encoding="UTF-8"?><configuration><system.webserver><handlers><add name="httpPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" resourcetype="Unspecified"></add></handlers><httpplatform processpath="C:\mygoapp\server.exe" arguments="" startuptimelimit="60" startupretrycount="3" stdoutlogenabled="true" stdoutlogfile="C:\mygoapp\logs\stdout.log"><environmentvariables><environmentvariable name="GOMAXPROCS" value="4"></environmentvariable><environmentvariable name="APP_ENV" value="production"></environmentvariable></environmentvariables></httpplatform></system.webserver></configuration>
? 关键说明：
- processPath：必须指向 已编译的 Go 可执行文件（如 go build -o server.exe server.go），不推荐使用 go run（开发便捷但生产环境不稳定、启动慢、依赖源码和 GOPATH）；
- arguments：若应用需命令行参数（如 --port=8080），在此填写；
- stdoutLogEnabled：强烈建议开启，便于排查启动失败问题（日志路径需确保 IIS_IUSRS 用户有写入权限）；
- 环境变量可按需添加，如 GOMAXPROCS 控制并发线程数。
? 常见问题排查
-
502.5 - Process Failure：最常见错误，通常因路径错误、权限不足或进程启动超时导致。检查：
- stdout.log 是否生成？内容是否含 panic 或 listen tcp :8080: bind: permission denied？
- 确认 server.exe 具有 IIS_IUSRS 组的读取+执行权限；
- 若 Go 应用监听 :8080，确保未被其他进程占用；HttpPlatformHandler 默认将请求转发至 Go 进程监听的端口（由 Go 代码指定，如 http.ListenAndServe(":8080", nil)），无需在 IIS 中配置端口映射；
- 404 / Handler Not Found：确认 handlers 节点已注册且 path="*" 匹配所有请求；
- 中文路径/特殊字符乱码：确保 web.config 文件编码为 UTF-8（无 BOM）。
✅ 最佳实践总结
- ✅ 生产环境始终使用 go build 生成静态二进制，而非 go run；
- ✅ 将 Go 应用设计为监听 127.0.0.1:端口（如 :8080），避免暴露到公网接口；
- ✅ 利用 httpPlatformHandler 的健康检查能力（如 requestTimeout 属性）提升稳定性；
- ❌ 不要尝试使用 ASP.NET Core Module 托管 Go 应用——它专为 .NET Core 进程设计，与 Go 二进制不兼容。
通过以上配置，你的 Go Web 应用即可作为 Windows 服务化后端，无缝集成 IIS 的 SSL 终止、URL 重写、IP 限制等企业级功能，真正实现“一次开发，多环境部署”。
