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。
关键配置说明：
- 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管理器，创建一个新的应用程序池：
- 在左侧导航栏中右键点击“应用程序池”，选择“添加应用程序池”。
- 输入名称，例如 PythonAppPool。
- .NET CLR 版本 选择“无托管代码”。
- 托管管道模式 选择“集成”。
- 点击“确定”。
- 选中新创建的应用程序池，点击右侧“高级设置”，确保“标识”设置为 ApplicationPoolIdentity（这是默认值，推荐使用）。
3.3 在IIS中添加应用程序
将FastAPI应用添加到IIS网站中：
- 在左侧导航栏中展开“站点” -> “Default Web Site”（或您希望部署的任何网站）。
- 右键点击该网站，选择“添加应用程序”。
- 别名 (Alias): 输入 python。这将是您访问应用的URL路径（例如 http://localhost/python）。
- 应用程序池: 选择您刚刚创建的 PythonAppPool。
- 物理路径: 浏览到您的FastAPI项目目录，即 C:\python-app。
- 点击“确定”。
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应用。
- 访问URL: 打开浏览器，访问 http://localhost/python（如果部署在Default Web Site下，且别名为 python）。
- 预期结果: 如果一切正常，您应该会看到一个JSON响应：{"message": "Hello World from FastAPI on IIS!"}。
- 检查日志: 如果遇到问题，请检查 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应用程序。
