在IIS 10上部署FastAPI应用的完整教程

花韻仙語

发布时间：2025-09-30 16:30:21

943人浏览过

来源于php中文网

原创

在IIS 10上部署FastAPI应用的完整教程

本教程详细指导如何在Windows Server 2019的IIS 10环境中，利用HTTP Platform Handler部署Python FastAPI应用程序。内容涵盖Python、HTTP Platform Handler的安装，FastAPI应用及Uvicorn配置，IIS应用池创建与权限设置，以及关键的web.config文件配置，确保FastAPI应用在IIS上稳定运行。

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版本，并选择“为所有用户安装”以避免权限问题。

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

2.3 Microsoft HTTP Platform Handler安装

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

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

2.4 FastAPI与Uvicorn安装

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

打开管理员权限的命令提示符或PowerShell。
安装必要的Python库:
```
pip install fastapi uvicorn
```

3. FastAPI应用程序准备

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

3.1 创建应用程序目录结构

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

创建应用主目录: C:\python-app
创建日志子目录: 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 文件，内容如下：

php中级教程之ajax技术

AJAX即“Asynchronous Javascript And XML”（异步JavaScript和XML），是指一种创建交互式网页应用的网页开发技术。它不是新的编程语言，而是一种使用现有标准的新方法，最大的优点是在不重新加载整个页面的情况下，可以与服务器交换数据并更新部分网页内容，不需要任何浏览器插件，但需要用户允许JavaScript在浏览器上执行。《php中级教程之ajax技术》带你快速

下载

配置说明:

: 定义了由 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应用池。

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

6. 文件系统权限配置

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

打开管理员权限的命令提示符或PowerShell。
授予权限: 运行以下 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网站。

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

8. 测试与验证

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

打开浏览器。
访问URL: http://localhost/python (如果您的IIS站点是默认站点且别名为 python)。
您应该会看到浏览器显示 {"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 或更高，并定期监控日志以确保应用程序的健康运行。

Python HTTP 客户端 requests 的实现原理

Python 包结构设计的最佳实践

Python 虚拟环境 venv 的工作原理

Python 信号处理机制解析

Python 垃圾回收机制是如何工作的