IIS 10部署FastAPI教程详解

1. 引言：IIS与Python FastAPI部署概述

在企业级Windows环境中，IIS（Internet Information Services）是常见的Web服务器。虽然IIS原生对ASP.NET等微软技术栈支持良好，但通过HTTP Platform Handler模块，也能高效地托管Python FastAPI等非.NET应用程序。HTTP Platform Handler充当了IIS与后端进程（如Uvicorn运行的FastAPI应用）之间的桥梁，将HTTP请求转发给后端进程，并将响应返回给客户端。本教程将详细阐述在IIS 10上部署FastAPI应用程序的完整过程。

2. 环境准备与软件安装

在开始部署之前，需要确保服务器环境已配置妥当并安装了必要的软件。

2.1 操作系统与IIS角色

确保您的服务器是Windows Server 2019或更高版本，并且已安装IIS Web服务器角色。

2.2 Python环境安装

建议安装64位的Python版本，并选择“为所有用户安装”以避免权限问题。

1. 下载Python: 访问Python官方网站下载最新稳定版Python 3.x 64位安装包。
2. 安装Python: 运行安装程序，勾选“Add Python to PATH”选项，并选择“为所有用户安装”。默认安装路径通常是 C:\Program Files\PythonXX。

2.3 Microsoft HTTP Platform Handler安装

HTTP Platform Handler是IIS与外部进程通信的关键组件。

1. 下载HTTP Platform Handler: 访问IIS官网下载适用于您服务器架构（通常是x64）的HTTP Platform Handler 1.2版本。
2. 安装Handler: 运行下载的MSI安装包，按照提示完成安装。

2.4 FastAPI与Uvicorn安装

Uvicorn是一个ASGI服务器，用于运行FastAPI应用程序。

1. 打开管理员权限的命令提示符或PowerShell。
2. 安装必要的Python库:

   pip install fastapi uvicorn

3. FastAPI应用程序准备

接下来，我们将创建一个简单的FastAPI应用程序及其所需的文件结构。

3.1 创建应用程序目录结构

在C盘根目录创建一个用于存放FastAPI应用及日志的文件夹。

1. 创建应用主目录: C:\python-app
2. 创建日志子目录: C:\python-app\logs

3.2 编写FastAPI应用程序 (main.py)

在 C:\python-app 目录下创建 main.py 文件，内容如下：

from fastapi import FastAPI

app = FastAPI()

@app.get("/python") # 注意：此路由路径应与IIS中配置的应用程序别名匹配
async def get_root():
    return {"message": "Hello from FastAPI on IIS!"}

重要提示: @app.get("/python") 中的路由路径 /python 必须与您稍后在IIS中为该应用程序设置的别名保持一致。如果IIS别名是 /api，则这里也应是 /api。

4. IIS web.config 文件配置详解

web.config 文件是IIS配置的核心，它告诉IIS如何处理传入的请求并将其转发给Uvicorn。在 C:\python-app 目录下创建 web.config 文件，内容如下：

配置说明:

• : 定义了由 httpPlatformHandler 处理所有传入请求。
• :
  • processPath: 非常关键！ 必须指向您安装Python后 uvicorn.exe 的实际路径。通常在 C:\Program Files\Python312\Scripts\uvicorn.exe (根据您的Python版本调整)。
  • arguments: 传递给Uvicorn的参数。
    • main:app: 指定Uvicorn加载 main.py 文件中的 app 实例。
    • --host 0.0.0.0: 监听所有网络接口。
    • --port %HTTP_PLATFORM_PORT%: Uvicorn将监听IIS通过环境变量 HTTP_PLATFORM_PORT 分配的端口。
    • --log-level info: 设置日志级别。在生产环境中可以改为 error。
  • stdoutLogEnabled="true": 启用标准输出日志。
  • stdoutLogFile=".\logs\uvicorn": 指定日志文件路径。. 表示当前应用程序目录 (C:\python-app)，日志将生成在 C:\python-app\logs\uvicorn_*.log。
  • startupTimeLimit="60": Uvicorn启动的最大等待时间（秒）。
  • processesPerApplication="16": 每个应用程序的最大Uvicorn进程数。
• :
  • PYTHONPATH: 设置Python模块搜索路径，确保Uvicorn能找到 C:\python-app 下的 main.py。
  • HTTP_PLATFORM_PORT: 这是一个内置变量，用于将IIS分配的动态端口传递给后端进程。

5. IIS应用池配置

为了隔离和管理应用程序，我们为FastAPI应用创建一个专用的IIS应用池。

1. 打开IIS管理器。
2. 创建新的应用池:
   • 在“应用程序池”右键选择“添加应用程序池”。
   • 名称: PythonAppPool (或您喜欢的任何名称)。
   • .NET CLR 版本: 选择“无托管代码”。
   • 托管管道模式: 选择“集成”。
   • 点击“确定”。
3. 配置应用池身份:
   • 选中刚创建的 PythonAppPool，点击右侧“高级设置”。
   • 找到“标识”，点击旁边的“...”按钮。
   • 选择“ApplicationPoolIdentity”作为身份。这是推荐的安全实践，因为它使用一个虚拟账户，自动由IIS管理。

6. 文件系统权限配置

IIS工作进程（由应用池身份运行）需要对Python安装目录和FastAPI应用程序目录拥有足够的权限才能执行文件和写入日志。

1. 打开管理员权限的命令提示符或PowerShell。

2. 授予权限: 运行以下 icacls 命令：

   # 授予IIS匿名用户和IIS工作进程组对Python安装目录的读取和执行权限
   icacls "C:\Program Files\Python312" /grant "NT AUTHORITY\IUSR:(OI)(CI)(RX)"
   icacls "C:\Program Files\Python312" /grant "Builtin\IIS_IUSRS:(OI)(CI)(RX)"
   
   # 授予IIS匿名用户和IIS工作进程组对FastAPI应用目录的读取、写入和执行权限
   icacls "C:\python-app" /grant "NT AUTHORITY\IUSR:(OI)(CI)(RX)"
   icacls "C:\python-app" /grant "Builtin\IIS_IUSRS:(OI)(CI)(RX)"

   注意: C:\Program Files\Python312 应替换为您的实际Python安装路径。C:\python-app 是您的FastAPI应用目录。

   • NT AUTHORITY\IUSR: IIS的匿名用户账户。
   • Builtin\IIS_IUSRS: IIS工作进程组。
   • (OI)(CI)(RX): 对象继承、容器继承、读取和执行权限。
   • (OI)(CI)(RX): 对于 C:\python-app 目录，还需要写入权限来生成日志，所以通常会授予 (OI)(CI)(RX,W)，或者直接 (OI)(CI)(F) (完全控制) 以简化，但更推荐精细权限。上述命令已经包含了必要的读取和执行，对于日志写入，web.config 中 stdoutLogFile=".\logs\uvicorn" 会在 C:\python-app\logs 目录下创建文件，所以 C:\python-app 目录及其子目录 logs 需要写入权限。如果 icacls 命令不包含写入权限，日志可能会失败。通常 IUSR 和 IIS_IUSRS 默认对 C:\inetpub\wwwroot 有写入权限，但自定义目录需要明确授予。

7. 在IIS中添加应用程序

最后一步是将FastAPI应用程序添加到IIS网站。

1. 打开IIS管理器。
2. 导航到您的网站: 通常是“Default Web Site”。
3. 添加应用程序:
   • 右键点击“Default Web Site”，选择“添加应用程序”。
   • 别名: python (这应与 main.py 中的路由路径和您希望访问的URL路径一致，例如 http://localhost/python)。
   • 应用程序池: 选择之前创建的 PythonAppPool。
   • 物理路径: C:\python-app。
   • 点击“确定”。

8. 测试与验证

现在，您的FastAPI应用程序应该已在IIS上运行。

1. 打开浏览器。
2. 访问URL: http://localhost/python (如果您的IIS站点是默认站点且别名为 python)。
3. 您应该会看到浏览器显示 {"message": "Hello from FastAPI on IIS!"}。

9. 常见问题与故障排除

• HTTP Error 500.19 - Internal Server Error (Error Code 0x80070003 - Cannot read configuration file):
  • 原因: 这通常表示IIS无法读取 web.config 文件或其所在的目录。
  • 解决方案: 检查 C:\python-app\web.config 文件是否存在，并确保 NT AUTHORITY\IUSR 和 Builtin\IIS_IUSRS 对 C:\python-app 目录及其所有子文件和文件夹具有读取权限。重新运行权限设置命令并确认。
• HTTP 500 错误（无详细信息）:
  • 检查Uvicorn日志: 查看 C:\python-app\logs 目录下生成的 uvicorn_*.log 文件。它会记录Uvicorn启动时的错误或FastAPI应用内部的异常。
  • processPath 错误: 确保 web.config 中 processPath 指向的 uvicorn.exe 路径是正确的，并且Python版本与安装路径匹配。
  • arguments 错误: 检查 arguments 中的 main:app 是否正确，--host 和 --port 参数是否正确传递。
  • Python环境问题: 尝试在命令行直接运行 uvicorn main:app --host 0.0.0.0 --port 8000 来测试FastAPI应用是否能独立运行。
• FastAPI路由不匹配:
  • 确保 main.py 中 @app.get("/python") 的路径与IIS应用程序的别名 (/python) 一致。如果IIS别名是 /my-app，则FastAPI路由也应是 /my-app。
• 端口冲突:
  • 虽然HTTP Platform Handler会自动处理端口分配，但确保没有其他服务占用了IIS监听的端口。

10. 总结

通过本教程，您已成功学会在Windows Server 2019的IIS 10环境中，利用HTTP Platform Handler部署Python FastAPI应用程序。关键步骤包括正确安装Python和HTTP Platform Handler，配置 web.config 文件以指导IIS如何启动和管理Uvicorn进程，创建并配置IIS应用池，以及设置适当的文件系统权限。遵循这些步骤，可以确保您的FastAPI应用在IIS上稳定、高效地运行。在生产环境中，请务必将 log-level 设置为 error 或更高，并定期监控日志以确保应用程序的健康运行。