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

1. 环境准备与先决条件

在开始部署FastAPI应用之前，需要确保服务器环境已正确配置。

1.1 安装Python

推荐安装Python 3.x 64位版本，并选择“为所有用户安装”以确保系统级别的可用性。

• 访问Python官方网站下载最新稳定版Python 3.x 64位安装程序。
• 运行安装程序，勾选“Add Python to PATH”选项，并选择“Install Now”。

1.2 安装Microsoft HTTP Platform Handler

HTTP Platform Handler是IIS用于托管非.NET应用程序（如Python、Node.js等）的关键组件。

• 访问IIS.NET下载页面下载Microsoft HTTP Platform Handler 1.2 64位版本。
• 运行安装程序完成安装。

1.3 安装Python库

打开命令提示符（以管理员身份运行），安装FastAPI和Uvicorn。Uvicorn是一个ASGI服务器，用于运行FastAPI应用。

pip install fastapi uvicorn

2. FastAPI应用程序构建

2.1 创建项目目录

在服务器上创建一个用于存放FastAPI应用代码的目录，例如 C:\python-app。同时，为日志文件创建一个子目录 C:\python-app\logs。

2.2 编写 main.py

在 C:\python-app 目录下创建 main.py 文件，并添加以下FastAPI示例代码。请注意，为了与IIS中的应用程序别名匹配，示例中的路由路径包含了 /python。

from fastapi import FastAPI

app = FastAPI()

@app.get("/python") # 路由路径应与IIS中设置的应用程序别名一致
async def get_root():
    return {"message": "Hello World from FastAPI on IIS!"}

3. IIS配置

IIS的配置是部署FastAPI应用的核心环节，主要包括 web.config 文件、应用程序池和IIS应用程序设置。

3.1 创建 web.config 文件

在 C:\python-app 目录下创建 web.config 文件。这个文件告诉IIS如何处理传入的请求，并将它们转发给Uvicorn。

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <!-- 配置httpPlatformHandler来处理所有请求 -->
      <add name="httpPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" />
    </handlers>
    <httpPlatform processPath="C:\Program Files\Python312\Scripts\uvicorn.exe"
                  arguments="main:app --host 0.0.0.0 --port %HTTP_PLATFORM_PORT% --log-level info"
                  stdoutLogEnabled="true"
                  stdoutLogFile=".\logs\uvicorn"
                  startupTimeLimit="60"
                  processesPerApplication="16">
      <environmentVariables>
        <!-- 将项目根目录添加到PYTHONPATH，确保Uvicorn能找到main.py -->
        <environmentVariable name="PYTHONPATH" value="C:\python-app\" />
        <!-- 确保Uvicorn能获取到IIS分配的端口 -->
        <environmentVariable name="HTTP_PLATFORM_PORT" value="%HTTP_PLATFORM_PORT%" />
      </environmentVariables>
    </httpPlatform>
  </system.webServer>
</configuration>

关键配置说明：

码上飞

码上飞（CodeFlying） 是一款AI自动化开发平台，通过自然语言描述即可自动生成完整应用程序。

138

查看详情

• processPath: 必须指向Uvicorn的可执行文件路径。根据您的Python安装路径，这通常位于 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\logs\uvicorn.log 文件。这是诊断启动问题的重要手段。
• environmentVariable name="PYTHONPATH" value="C:\python-app\": 将FastAPI项目的根目录添加到Python的搜索路径中，确保Uvicorn能够找到 main.py。

3.2 创建IIS应用程序池

打开IIS管理器，创建一个新的应用程序池：

1. 在左侧导航栏中右键点击“应用程序池”，选择“添加应用程序池”。
2. 输入名称，例如 PythonAppPool。
3. .NET CLR 版本 选择“无托管代码”。
4. 托管管道模式 选择“集成”。
5. 点击“确定”。
6. 选中新创建的应用程序池，点击右侧“高级设置”，确保“标识”设置为 ApplicationPoolIdentity（这是默认值，推荐使用）。

3.3 在IIS中添加应用程序

将FastAPI应用添加到IIS网站中：

1. 在左侧导航栏中展开“站点” -> “Default Web Site”（或您希望部署的任何网站）。
2. 右键点击该网站，选择“添加应用程序”。
3. 别名 (Alias): 输入 python。这将是您访问应用的URL路径（例如 http://localhost/python）。
4. 应用程序池: 选择您刚刚创建的 PythonAppPool。
5. 物理路径: 浏览到您的FastAPI项目目录，即 C:\python-app。
6. 点击“确定”。

4. 文件系统权限设置

不正确的权限是导致HTTP 500.19 错误（无法读取配置文件）或应用程序无法启动的常见原因。IIS应用程序池标识（通常是 IIS APPPOOL\PythonAppPool 或 NT AUTHORITY\IUSR 和 Builtin\IIS_IUSRS）需要对Python安装目录和FastAPI应用目录具有读取和执行权限，对日志目录具有写入权限。

打开命令提示符（以管理员身份运行），执行以下命令来授予必要的权限：

# 授予IIS匿名用户和IIS_IUSRS组对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_IUSRS组对FastAPI应用目录的读取和执行权限
icacls "C:\python-app" /grant "NT AUTHORITY\IUSR:(OI)(CI)(RX)"
icacls "C:\python-app" /grant "Builtin\IIS_IUSRS:(OI)(CI)(RX)"

# 确保Uvicorn能够写入日志文件，对C:\python-app\logs目录授予修改权限
icacls "C:\python-app\logs" /grant "NT AUTHORITY\IUSR:(OI)(CI)(M)"
icacls "C:\python-app\logs" /grant "Builtin\IIS_IUSRS:(OI)(CI)(M)"

注意：

• 请根据您的Python实际安装路径调整 C:\Program Files\Python312。
• NT AUTHORITY\IUSR 是IIS匿名用户的内置账户。
• Builtin\IIS_IUSRS 是IIS工作进程使用的组。
• (OI)(CI) 表示对象继承和容器继承，确保子文件夹和文件也继承这些权限。
• (RX) 表示读取和执行权限。
• (M) 表示修改权限（包括写入），对于日志目录是必需的。

5. 测试与验证

完成所有配置后，即可测试您的FastAPI应用。

1. 访问URL: 打开浏览器，访问 http://localhost/python（如果部署在Default Web Site下，且别名为 python）。
2. 预期结果: 如果一切正常，您应该会看到一个JSON响应：{"message": "Hello World from FastAPI on IIS!"}。
3. 检查日志: 如果遇到问题，请检查 C:\python-app\logs 目录下的 uvicorn.log 文件。这个日志文件会记录Uvicorn的启动信息和运行时错误，是诊断问题的关键。

6. 故障排除与最佳实践

• HTTP Error 500.19 - Internal Server Error (Error Code 0x80070003):
  • 这通常表示IIS无法读取 web.config 文件或其依赖项。最常见的原因是文件权限不足。请仔细检查第4节中的 icacls 命令是否正确执行，确保 NT AUTHORITY\IUSR 和 Builtin\IIS_IUSRS 对 C:\python-app 目录及其子文件具有读取权限。
  • 另一个可能原因是 web.config 文件格式错误。使用XML编辑器检查其语法。
• 应用程序启动失败，浏览器显示空白或通用错误页:
  • 检查 C:\python-app\logs\uvicorn.log 文件。它会显示Uvicorn启动时的详细错误信息，例如模块找不到、Python语法错误、端口冲突等。
  • 确保 web.config 中的 processPath 指向正确的 uvicorn.exe 路径。
  • 确认 PYTHONPATH 环境变量设置正确，指向您的FastAPI项目根目录。
• Python版本和架构: 推荐使用64位Python，并确保HTTP Platform Handler也安装了64位版本，以避免潜在的兼容性问题。
• Uvicorn参数: main:app 中的 main 对应 main.py 文件名（不含.py），app 对应 FastAPI() 实例的变量名。如果您的文件或实例名不同，请相应修改。
• 日志级别: 在生产环境中，将 web.config 中 arguments 参数的 --log-level 设置为 error 或 critical，以减少日志输出量。

通过遵循本教程的步骤，您应该能够在IIS 10上成功部署和运行您的FastAPI应用程序。

以上就是在IIS 10上部署FastAPI应用：完整教程的详细内容，更多请关注php中文网其它相关文章！