IIS部署FastAPI应用出现无效主机名/错误请求问题排查

已执行操作步骤 #

1. 搭建FastAPI应用，位于C:\test-fastapi，通过命令python -m uvicorn main:app --host 0.0.0.0 --port 8800测试正常，可通过局域网IP访问
2. 安装HttpPlatformHandler后，在IIS 10中创建test-fastapi应用池，设置为无托管代码、集成托管管道模式
3. 添加IIS站点，主机名设为test，端口9000，绑定本地IP，物理路径指向C:\test-fastapi
4. 在C:\test-fastapi中添加web.config配置文件（原配置见下方）
5. 为Python安装目录及C:\test-fastapi目录赋予IIS_IUSRS完全权限

遇到的错误 #

• 访问http://test:9000时，提示DNS_PROBE_FINISHED_NXDOMAIN
• 访问<本地IP>:9000时，提示Bad Request - Invalid Hostname, HTTP Error 400
• 切换为用户特定安装的Python后，出现C:\Users\<PCName>\AppData\Local\Programs\Python\Python312\python.exe: No module named uvicorn错误，但本地PowerShell可正常启动服务

针对性解决方案 #

1. 解决DNS_PROBE_FINISHED_NXDOMAIN错误 #

本地DNS无法解析test主机名，需手动配置hosts文件：

• 打开C:\Windows\System32\drivers\etc\hosts（需管理员权限）
• 添加一行：<你的本地IP地址> test，例如192.168.1.100 test
• 保存后执行命令ipconfig /flushdns刷新DNS缓存

2. 解决Bad Request - Invalid Hostname错误 #

核心问题是web.config中uvicorn启动参数缺失应用入口：

• 修改web.config的httpPlatform节点的arguments，补充main:app（指定FastAPI应用的入口文件和实例），正确参数应为：

  -m uvicorn main:app --port %HTTP_PLATFORM_PORT% --host 0.0.0.0
  

• 同时确认IIS站点绑定的IP地址与访问时使用的IP完全一致，避免IP不匹配导致的主机名验证失败

3. 解决No module named uvicorn错误 #

IIS应用池默认身份无法访问用户级Python包，可通过以下方式解决：

方案一：使用全局Python环境

• 以管理员身份打开PowerShell，执行pip install uvicorn fastapi，确保全局Python环境（C:\Program Files\Python312）中安装了依赖包
• 确认web.config的processPath指向全局Python路径

方案二：调整应用池权限

• 将IIS应用池test-fastapi的运行身份改为当前登录用户（需进入IIS管理器→应用池→高级设置→进程模型→标识）
• 或手动为用户Python包目录（C:\Users\<PCName>\AppData\Local\Programs\Python\Python312\Lib\site-packages）赋予IIS_IUSRS和IIS AppPool\test-fastapi读取权限

方案三：使用虚拟环境（推荐）

• 在C:\test-fastapi目录下创建虚拟环境：

  python -m venv venv
  

• 激活虚拟环境并安装依赖：

  .\venv\Scripts\activate
  pip install uvicorn fastapi
  

• 修改web.config的processPath为虚拟环境的Python路径：

  processPath="C:\test-fastapi\venv\Scripts\python.exe"
  

修正后的web.config示例 #

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="PythonHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified"/>
    </handlers>
    <httpPlatform processPath="C:\Program Files\Python312\python.exe"
                  arguments="-m uvicorn main:app --port %HTTP_PLATFORM_PORT% --host 0.0.0.0"
                  stdoutLogEnabled="true"
                  stdoutLogFile="C:\inetpub\logs\python.log" <!-- 建议使用IIS默认日志目录，确保权限 -->
                  startupTimeLimit="60"
                  processesPerApplication="16">
      <environmentVariables>
        <!-- 可按需添加环境变量，如PYTHONPATH -->
      </environmentVariables>
    </httpPlatform>
  </system.webServer>
</configuration>

内容的提问来源于stack exchange，提问作者5.9 protons