# HttpPlatformHandler：不用 FastCGI 也能在 IIS 后跑 Node 或 Python

> 用 IIS HttpPlatformHandler 启动 Node/Python 进程，传动态端口，收集 stdout，并避免“每请求一进程”的误解。

**测试环境**

- 版本号: 26100.33650
- 版本: Standard / Datacenter
- 架构: x64
- 证据: E1
- 核验日期: 2026-10-29

## 一句话结论

**HttpPlatformHandler（HPH）** 是 IIS 扩展，启动并监管一个长期运行的进程（Node、Python、Go 等），把请求转发给它。它不是 FastCGI，也不是每请求一进程的 CGI。

适用：

- 应用是监听端口的普通 HTTP 服务器；
- 想让 IIS 管 TLS/绑定/日志；
- 应用能从 `%HTTP_PLATFORM_PORT%` 读动态端口。

PHP 用 FastCGI。.NET 用 ASP.NET Core Module（ANCM），不用 HPH。

## web.config

```xml
<configuration>
  <system.webServer>
    <httpPlatform processPath="C:\Program Files\nodejs\node.exe"
                  arguments="server.js"
                  startupTimeLimit="60"
                  stdoutLogEnabled="true"
                  stdoutLogFile=".\logs\node">
      <environmentVariables>
        <environmentVariable name="PORT" value="%HTTP_PLATFORM_PORT%" />
        <environmentVariable name="NODE_ENV" value="production" />
      </environmentVariables>
    </httpPlatform>
  </system.webServer>
</configuration>
```

应用必须监听 `%HTTP_PLATFORM_PORT%`，不能硬编码 3000。HPH 按应用池/进程分配端口并反代。

Python（Waitress）示例：

```xml
<httpPlatform processPath="C:\Python311\python.exe"
              arguments="-m waitress --listen=127.0.0.1:%HTTP_PLATFORM_PORT% app:app"
              stdoutLogEnabled="true"
              stdoutLogFile=".\logs\python">
</httpPlatform>
```

参数语法取决于应用服务器；不要把 Gunicorn 命令抄到 Windows。

## 进程生命周期

- HPH 在应用池启动时拉起进程，退出时重启。
- `startupTimeLimit` 控制 IIS 等第一次监听多久。
- `rapidFailsPerMinute`（可用时）防止崩溃循环无限转。
- 进程以**应用池身份**运行，文件/日志权限跟着它。

不要同一端口既跑 Windows 服务又跑 HPH。选一个监管者。

## 验证

```powershell
Get-WebGlobalModule -Name HttpPlatformHandler
Invoke-WebRequest http://localhost:8080/ -UseBasicParsing | Select-Object StatusCode
Get-Content .\logs\node\*.log -Tail 50
```

IIS 返回 502/503：

- 进程没起来（路径/权限/运行时）；
- 起来了但没监听 `%HTTP_PLATFORM_PORT%`；
- 起来后崩了；读 stdout 日志；
- 应用池身份读不了应用目录。

> **警告: 不要暴露 stdout 日志**
>
> HPH stdout 日志可能含 token、连接串和请求数据。放 Web 根之外，限制 ACL，轮转。

## 什么时候不用 HPH

- PHP：FastCGI。
- ASP.NET Core：ANCM/Hosting Bundle。
- 静态文件：IIS 静态内容。
- 必须被多个站点共享的进程：跑一个服务，用 ARR 反代，而不是每站点一个 HPH。

## 实验室边界

E1。实验室装了 IIS 和 PHP FastCGI，没装 HPH 或 Node/Python。标 E2 前在 Server 2025 上验证进程路径、端口和身份。

## 来源

- [Microsoft Learn — HttpPlatformHandler 配置](https://learn.microsoft.com/zh-cn/iis/extensions/httpplatformhandler/httpplatformhandler-configuration-reference)
- [Microsoft Learn — ASP.NET Core Module](https://learn.microsoft.com/zh-cn/aspnet/core/host-and-deploy/aspnet-core-module)

---

来源页面: https://winbook.fyi/zh/server/web/iis-node-python/