如何在IIS 10上部署FastAPI应用

FastAPI是近年来非常流行的Python异步Web框架，以其高性能和自动生成API文档的特性受到开发者青睐。但在Windows Server的IIS环境下部署FastAPI应用，对许多国内开发者来说可能是一个挑战。本文将从头到尾详细讲解在IIS 10上部署FastAPI的完整流程，涵盖环境准备、依赖安装、IIS配置、站点创建以及常见问题的解决方法。

一、部署前的环境准备

1.1 确认IIS 10已经安装

IIS（Internet Information Services）是Windows Server自带的Web服务器。在开始之前，请确保你的服务器已经安装了IIS 10。可以通过“服务器管理器”中的“添加角色和功能”来检查并安装。如果尚未安装，请先完成IIS的安装，并确保安装了“CGI”功能模块，因为FastCGI依赖于它。

安装完成后，打开IIS管理器，确认左侧连接栏中出现了“应用程序池”和“网站”节点。如果没有看到，说明IIS安装不完整，需要重新添加角色。

1.2 Python环境的安装与版本选择

FastAPI要求Python 3.7及以上版本，推荐使用Python 3.9或3.10，因为它们稳定且兼容性好。从Python官网下载Windows安装包时，务必勾选“Add Python to PATH”，这样可以省去后续手动配置环境变量的麻烦。安装完成后，打开命令提示符，输入python --version验证版本。

此外，建议使用虚拟环境来隔离项目依赖，但为了简化教程，这里直接使用全局Python环境。如果你有多个项目，建议为每个项目创建独立的虚拟环境。

1.3 理解wfastcgi的作用

wfastcgi是一个桥接工具，它让IIS能够通过FastCGI协议与Python WSGI/ASGI应用通信。FastAPI虽然是ASGI框架，但wfastcgi也支持ASGI（通过适配）。简单来说，wfastcgi充当了IIS和Python之间的翻译官，使得IIS可以将HTTP请求转发给Python进程处理，并将处理结果返回给客户端。

二、安装必要的依赖包

2.1 安装FastAPI和uvicorn

在命令提示符中执行以下命令：

pip install fastapi uvicorn

FastAPI是Web框架，uvicorn是ASGI服务器，用于在本地运行FastAPI应用。虽然在IIS部署时不需要直接启动uvicorn，但wfastcgi内部会用到它来处理异步请求，所以必须安装。

2.2 安装wfastcgi并启用

接着安装wfastcgi模块：

pip install wfastcgi

安装完成后，执行启用命令：

wfastcgi-enable

这条命令会输出类似下面的信息：

Config:
    "C:\Python39\python.exe"|"C:\Python39\Lib\site-packages\wfastcgi.py"

请务必记录下这个输出字符串，它包含了Python解释器的路径和wfastcgi.py的路径，中间用竖线分隔。后面配置IIS时需要用到。

三、创建FastAPI测试应用

为了验证部署是否成功，我们先创建一个简单的FastAPI应用。

在服务器上选择一个目录作为项目根目录，例如C:\fastapi_demo。在该目录下新建一个文件main.py，内容如下：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "FastAPI deployed on IIS 10 successfully"}

这个应用只有一个根路由，访问时会返回JSON数据。你也可以根据自己的需求添加更多路由，但测试阶段保持简单即可。

四、配置IIS站点

4.1 添加FastCGI设置

打开IIS管理器，在左侧连接树中点击服务器根节点（通常是计算机名），然后双击中间的“FastCGI设置”图标。

在打开的窗口中，点击右侧操作区的“添加应用程序”。在弹出的对话框中，需要填写两个字段：

• 完整路径：填写Python可执行文件的绝对路径，例如C:\Python39\python.exe。注意，如果你的Python安装在别的位置，请使用实际路径。
• 参数：填写wfastcgi.py的完整路径，例如C:\Python39\Lib\site-packages\wfastcgi.py。

填写完成后点击“确定”。这时你会看到列表中新增了一条记录。这一步相当于告诉IIS：当需要处理Python请求时，请使用这个Python解释器和wfastcgi脚本。

4.2 创建新网站

在IIS管理器的左侧，右键点击“网站”节点，选择“添加网站”。填写以下信息：

• 网站名称：任意命名，例如FastAPIDemo
• 物理路径：选择刚才创建的C:\fastapi_demo文件夹
• 绑定类型：选择http
• IP地址：默认“全部未分配”
• 端口：填写一个未被占用的端口，例如8000。注意不要与其他服务冲突。
• 主机名：留空即可。如果希望用域名访问，可以填写域名，但测试阶段建议留空。

点击“确定”后，新站点就会出现在网站列表中。此时站点处于停止状态，需要手动启动。

4.3 配置处理程序映射

处理程序映射是IIS的核心配置，它定义了什么样的请求应该交给哪个模块处理。我们需要为FastAPI站点添加一个专门的处理程序。

首先，点击刚刚创建的FastAPIDemo站点，在中间区域找到并双击“处理程序映射”。然后点击右侧的“添加模块映射”，填写以下内容：

• 请求路径：输入*，表示所有路径都由这个处理程序处理。
• 模块：选择FastCgiModule。如果下拉列表中没有，说明IIS的CGI功能未安装，需要回去安装。
• 可执行文件：这里需要填写之前在wfastcgi-enable中得到的字符串，格式为C:\Python39\python.exe|C:\Python39\Lib\site-packages\wfastcgi.py。注意中间是竖线符号。
• 名称：自定义，例如FastAPIHandler。

填写完毕后，点击“请求限制”按钮，在弹出的窗口中取消勾选“仅当请求映射以下内容时才调用处理程序”，然后一路点击“确定”保存。

4.4 添加web.config配置文件

虽然处理程序映射已经通过IIS管理器配置好了，但为了确保配置持久化和便于迁移，建议在项目根目录下创建web.config文件。这个文件是IIS的XML配置文件，可以直接覆盖或补充管理器的设置。

在C:\fastapi_demo目录下新建一个文本文件，命名为web.config，内容如下：

<configuration>
  <system.webServer>
    <handlers>
      <add name="FastAPIHandler" path="*" verb="*" modules="FastCgiModule" 
           scriptProcessor="C:\Python39\python.exe|C:\Python39\Lib\site-packages\wfastcgi.py" 
           resourceType="Unspecified" />
    </handlers>
  </system.webServer>
  <appSettings>
    <add key="WSGI_HANDLER" value="main.app" />
    <add key="PYTHONPATH" value="C:\fastapi_demo" />
  </appSettings>
</configuration>

注意以下几点：

• scriptProcessor的值必须与之前wfastcgi-enable输出的字符串完全一致，包括路径和竖线。
• WSGI_HANDLER的值main.app表示main.py文件中的app实例。如果你的应用文件名或变量名不同，请相应修改。
• PYTHONPATH指定了应用所在目录，这样Python才能正确导入main模块。

保存文件后，IIS会自动读取这个配置。如果之前已经通过管理器配置过处理程序映射，两者可能会重复，但不会冲突。

五、测试部署效果

现在可以测试了。在浏览器中输入http://localhost:8000（如果绑定了其他端口，请使用对应端口）。如果一切正常，页面会显示：

{"message": "FastAPI deployed on IIS 10 successfully"}

这表明FastAPI应用已经在IIS上成功运行。你也可以尝试访问其他自定义的路由，比如http://localhost:8000/docs，看看Swagger文档是否能正常加载。

如果遇到问题，不要着急，下面列出常见的故障及其解决办法。

六、常见问题与解决方案

6.1 访问出现500内部服务器错误

500错误通常意味着服务器端发生了异常。首先，检查IIS的“失败请求跟踪”功能，它可以记录详细的错误日志。启用方法：在站点主页双击“失败请求跟踪”，点击右侧“添加”，设置跟踪条件（例如状态代码500），然后再次访问站点，日志文件会生成在%SystemDrive%\inetpub\logs\FailedReqLogFiles目录下。

常见原因包括：

• Python路径错误：确认web.config中的scriptProcessor路径与实际Python安装路径一致，注意Python版本和位数（32位/64位）也要与IIS应用程序池匹配。
• 依赖未安装：确保FastAPI和uvicorn已经安装，并且是在同一个Python环境中。
• wfastcgi未正确启用：重新执行wfastcgi-enable，确认输出路径无误。

6.2 提示“模块 FastCgiModule 未安装”

这个错误说明IIS缺少FastCGI模块。在服务器管理器中，进入“添加角色和功能”，在“Web服务器(IIS)”→“应用程序开发”中，勾选“CGI”和“FastCGI”。安装完成后重启IIS管理器。

6.3 访问时返回空白页面或404

检查站点的物理路径是否正确，以及web.config文件是否放置在根目录。另外，确认IIS应用程序池的.NET CLR版本设置为“无托管代码”，因为我们的应用是Python，不需要.NET支持。可以在应用程序池的高级设置中修改。

6.4 异步接口无法正常工作

FastAPI本身基于异步，但wfastcgi在IIS下运行时会自动处理异步请求，无需额外配置。只要uvicorn已经安装，wfastcgi会调用uvicorn的异步循环。如果遇到异步接口卡死，可以尝试更新wfastcgi到最新版本。

七、进阶优化与注意事项

7.1 使用虚拟环境

在生产环境中，强烈建议使用Python虚拟环境，以避免全局包冲突。创建虚拟环境后，需要在web.config的PYTHONPATH中指定虚拟环境的site-packages路径，或者直接使用虚拟环境中的Python解释器路径。

7.2 配置HTTPS

如果站点需要通过HTTPS访问，可以在IIS中为站点绑定SSL证书，并修改绑定类型为https。注意，wfastcgi本身不处理加密，加密由IIS负责，所以配置方式与普通IIS站点相同。

7.3 日志记录

为了方便排查问题，可以在FastAPI应用中添加日志输出，或者启用IIS的日志记录。IIS默认会记录所有请求，可以在站点主页的“日志”中查看。

7.4 性能调优

IIS的FastCGI设置中可以调整进程池的最大请求数、空闲超时等参数，以适应高并发场景。可以根据实际负载进行调整。

结语

通过以上步骤，你应该能够在IIS 10上成功部署FastAPI应用。整个过程虽然涉及多个环节，但只要仔细核对每一步的路径和配置，就能顺利完成。如果在部署过程中遇到任何问题，欢迎查阅官方文档或社区讨论。希望这篇文章对你有所帮助！

FastAPIIIS_10uvicornweb部署wsgi修改时间：2026-08-23 02:17:24