FastAPI 部署核心概念从 HTTPS、进程复制到资源利用率的实战决策指南【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi部署一个FastAPI应用事实上任何类型的 Web API 都是如此时真正决定成败的往往不是框架 API 本身而是一组贯穿始终的部署概念——HTTPS 安全、开机自启、崩溃重启、进程复制Replication、内存占用、启动前步骤以及资源利用率。本文将基于本仓库 docs/pt/docs/deployment/concepts.md对应英文原稿 docs/en/docs/deployment/concepts.md展开并结合 fastapi/cli.py 等源码实现与系列部署文档帮助你建立足够的直觉去评估与设计你自己的 FastAPI API 在各种环境甚至是未来还不存在的环境中的最佳部署方案。读完本文你将掌握七个关键概念各自的为什么与怎么办知道 HTTPS 该由谁提供、进程与程序的本质区别、为什么 API 必须开机自启和自动重启、为何需要多 Worker 却只能有一个进程监听端口、内存为什么按进程翻倍、启动前的迁移步骤为什么只能执行一次以及如何把服务器资源利用率调到尽可能高又不崩溃的合理区间。部署的本质目标在开始讨论概念之前先明确终极目标安全地服务 API 客户端、避免中断disruptions并尽可能高效地利用计算资源例如远程服务器、虚拟机。这三个目标可以拆解为下面几个可操作的概念维度安全 —— HTTPS在开机时运行Running on startup重启Restarts复制Replication即运行进程的数量内存Memory启动前的预备步骤Previous steps before starting在 部署总览 中部署被定义为执行必要步骤让应用对用户可用——通常意味着把应用放到远程机器上配合性能与稳定性良好的服务器程序运行。而本仓库的 部署章节 下还有 手动运行服务器、HTTPS、容器化Docker、云服务、服务器与 Worker 等更具体的菜谱。本文的任务是先帮你在这些具体菜谱之前把概念地基打牢。说明以下概念不仅适用于 FastAPI也适用于任何其他类型的 Web API。安全HTTPS 由外部组件提供第一个概念是安全。HTTPS 加密由应用服务器外部的组件提供这个组件就是TLS 终止代理TLS Termination Proxy。从 关于 HTTPS 的文档 可以知道TLS 负责的加密发生在 TCP 层、HTTP 之下证书有生命周期会过期因此系统中还必须有东西负责续期 HTTPS 证书——它可以是 TLS 终止代理本身也可以是另一个独立组件。可用的 HTTPS 工具示例可作为 TLS 终止代理的工具及证书续期方式如下表工具证书续期方式Traefik自动处理证书续期 ✨Caddy自动处理证书续期 ✨Nginx配合外部组件如 Certbot完成续期HAProxy配合外部组件如 Certbot完成续期Kubernetes Ingress Controller如 Nginx配合外部组件如 cert-manager完成续期云服务商托管作为其服务的一部分由云厂商内部处理另一种做法是直接使用承担更多工作的云服务包含配置 HTTPS这种方式可能有某些限制或收费更高但好处是你不需要自己搭建 TLS 终止代理。从协议原理看为什么必须有这么一层因为 TCP 只认识 IP 地址、不认识域名而 HTTPS 证书证明的是特定域名。默认情况下一个 IP 地址只能有一个 HTTPS 证书借助 TLS 的SNIServer Name Indication扩展单个服务器单个公网 IP才能同时持有多个证书、服务多个 HTTPS 域名——这要求唯一一个监听公网 IP 的组件持有服务器上的全部证书。因此常见的做法是让一个程序/服务器统一负责 HTTPS 的接收、解密、转发与再加密这个服务器就是 TLS 终止代理。具体示例将在后续章节如 Docker中给出。程序Program与进程Process先把术语说清楚接下来的所有概念都围绕运行你 API 的程序例如 Uvicorn展开而文档中会大量使用进程这个词因此必须先厘清它与程序的区别。什么是程序程序一词通常被用来描述多种东西含义较宽泛你编写的代码即Python 文件操作系统可以执行的二进制文件例如python、python.exe或uvicorn操作系统中的一个程序正在运行时的状态——占用 CPU、在内存中存储数据。这种状态其实也叫进程。什么是进程进程一词的用法更精确仅指正在操作系统中运行的那个东西它是被执行且被操作系统管理的实例不指磁盘上的文件也不指代码本身任何程序、任何代码只有处于进程在运行状态时才能真正做事进程可以被你或操作系统终止kill一旦终止便停止运行、不能再做任何事你电脑上运行的每个应用背后都有一个进程操作系统开着时通常同时运行着大量进程同一个程序可以同时有多个进程在运行。打开操作系统的任务管理器或系统监视器就能看到大量进程。例如你会发现同一个浏览器程序Firefox、Chrome、Edge 等通常有多个进程——一般每个标签页一个进程外加若干辅助进程。把程序/进程区分清楚后就可以继续讨论部署相关的话题了。开机自启Running on Startup让 API 永远在线绝大多数情况下你希望 Web API持续不间断地运行让客户端随时可以访问——除非你有特殊理由希望它只在特定场景运行。在远程服务器上手动运行的问题在远程服务器云服务器、虚拟机等上最简单的方式是像本地开发那样手动执行fastapi run它内部使用 Uvicorn或类似命令。这在开发阶段没问题但存在两个致命隐患如果到服务器的连接断开正在运行的进程很可能随之消亡如果服务器重启例如云厂商更新或迁移后你可能根本不会注意到于是连需要手动重启进程这件事都不知道——你的 API 就那样一直死着。开机自动运行与独立守护程序因此通常你需要让服务器程序例如 Uvicorn在服务器启动时自动运行无需任何人工干预始终保持一个运行着你 FastAPI 应用的进程。达成这一点往往需要一个独立的程序来负责——它保证你的应用在开机时被拉起很多时候还顺带负责拉起数据库等其他组件。可用的开机自启工具常见的选择包括DockerKubernetesDocker ComposeDocker Swarm 模式Docker in Swarm ModeSystemdSupervisor云服务商托管作为其服务的一部分其他……Docker、Kubernetes 等具体示例会在后续章节给出。值得一提的是仓库中fastapi命令的入口定义在 fastapi/cli.py它从fastapi_cli包导入cli_main若未安装则提示需要先安装fastapi[standard]。也就是说当文档提到使用fastapi run底层是 Uvicorn时指的就是这个命令——它只有在安装了fastapi[standard]附带uvicorn[standard]时才可用。这在 手动运行服务器的英文文档 中也有印证。重启Restarts崩溃之后如何恢复与确保开机自启类似你还希望应用在出错崩溃之后能被自动重启。小错误由 FastAPI 自动兜住我们在写代码时几乎总会埋下 bug但用 FastAPI 构建 Web API 时代码中的错误通常会被限制在触发该错误的那一次请求内该请求的客户端会收到一个500 Internal Server Error而应用整体不会崩溃后续请求依然正常工作。这一点是 FastAPI 异常处理机制带来的天然健壮性。大错误整个进程崩溃但仍有少数情况代码会让整个应用崩溃连 Uvicorn 和 Python 一起挂掉。此时你依然不希望 API 因为某一处错误而长期离线——至少要让没坏的那些路径操作继续服务。崩溃后由外部组件负责重启真正让 Python/Uvicorn 进程崩溃的严重错误发生时你需要一个外部组件负责重启该进程至少尝试重启几次。注意外部这个措辞很关键到这一步同一个应用含 Uvicorn 与 Python自己已经崩溃了应用自身的任何代码都无能为力所以重启责任必须交给应用之外的组件。需要说明的边界如果应用一启动就立刻崩溃无限重启没有意义——不过这类情况通常在开发阶段或部署后不久就会被发现。本文聚焦的典型场景是应用在运行一段时间后未来某个特定场景下可能整体崩溃此时自动重启依然合理。可用的自动重启工具多数情况下负责开机自启的工具同时也负责崩溃自动重启例如DockerKubernetesDocker ComposeDocker Swarm 模式SystemdSupervisor云服务商托管其他……复制Replication进程、Worker 与内存的权衡用fastapi命令运行 Uvicorn这样的服务器程序来跑 FastAPI 应用时单个进程本身就能并发服务大量客户端。但很多场景下你会希望同时运行多个 Worker 进程。为什么需要多个进程Worker如果客户端数量超过了单进程能处理的上限例如虚拟机配置不够大而服务器的 CPU 又有多个核心那么可以同时运行多个承载同一应用的进程把请求分发到它们之间。这种同一 API 程序的多个进程通常被称为Worker。Worker 进程与端口只能有一个监听者还记得 HTTPS 文档 中提到的约束吗一个服务器上一个IP 地址 端口组合只能被一个进程监听。这条规则依然成立。因此想要同时运行多个进程必须存在一个监听端口的唯一进程它再把通信转发给各个 Worker 进程。每个进程的独立内存当程序把东西加载进内存——例如把一个机器学习模型放进变量、把一个超大文件内容读进变量——这些都会消耗服务器的内存RAM。而多个进程之间通常不共享任何内存每个运行中的进程都拥有自己独立的变量与内存。如果你的代码消耗大量内存那么每一个进程都会消耗等量内存。内存核算示例假设代码加载了一个1 GB的机器学习模型运行 1 个进程至少消耗1 GB RAM运行4 个进程4 个 Worker每个消耗 1 GB合计4 GB RAM。如果你的远程服务器/虚拟机只有 3 GB RAM却试图加载超过 4 GB 的内容就会出问题。一个多进程架构示例下面示意的是一个管理进程Manager Process启动并控制两个Worker 进程的模型管理进程通常在 IP 上监听端口把通信转发给 WorkerWorker 才是真正运行你应用、负责收请求、算逻辑、回响应的进程也是把内容加载进 RAM 的进程。当然同一台机器上除了你的应用还会运行其他进程。一个值得注意的细节是每个进程的CPU 占用百分比随时间波动可能很大而内存RAM占用通常相对稳定如果你的 API 每次计算量相当且客户端很多那么CPU 利用率往往也会趋于稳定而不是忽上忽下。复制的工具与策略组合实现多进程复制可以有多种路径具体策略会在 Docker/容器章节展开。核心约束始终是公网 IP 上的端口只能由唯一一个组件处理然后它必须有能力把通信分发给被复制的进程/Worker。可行的组合包括Uvicorn 加--workers一个 Uvicorn进程管理器监听 IP 和端口并启动多个 Uvicorn Worker 进程Kubernetes 及其他分布式容器系统由 Kubernetes 这一层监听 IP 与端口复制方式是运行多个容器每个容器内跑一个 Uvicorn 进程云服务商托管云服务替你处理复制通常让你定义要运行的一个进程或要使用的容器镜像多半是单个 Uvicorn 进程由云服务负责复制它。如果对容器、Docker、Kubernetes 这些名词还不太理解不必担心——后续章节 FastAPI 容器化Docker 会详细讲解容器镜像、Docker、Kubernetes 等概念。启动前的预备步骤Previous Steps Before Starting只执行一次很多场景下你希望在启动应用之前执行一些预备步骤典型例子是数据库迁移。这些步骤在多数情况下只需要执行一次。因此你需要用单个进程在应用启动前完成这些预备工作并且要确保即使之后为应用本身启动了多个进程多个 Worker预备步骤依然只由一个进程执行。为什么这点很重要如果预备步骤被多个进程同时并行执行就会重复劳动而当步骤是数据库迁移这类精细活时并行执行可能彼此产生冲突。当然也存在例外有些预备步骤重复执行无害那种情况下处理起来会容易得多。另外请记住视你的配置而定有些场景可能根本不需要任何启动前步骤——那就不必为这些问题操心。预备步骤的策略示例具体怎么做高度依赖你的部署方式通常与如何启动程序、如何处理重启绑定在一起。可选思路包括Kubernetes 中的Init Container在应用容器启动前运行一个bash 脚本先执行预备步骤再启动应用——但此时你仍需要一个机制去启动/重启这个bash 脚本、检测其错误等。更具体的容器化做法会在后续 Docker 章节 中给出。资源利用率Resource Utilization尽可能高但别撞墙你的服务器本质上是资源——CPU 上的计算时间、可用的 RAM 内存都可以被你用程序消耗/利用。问题来了你希望消耗多少系统资源也许直觉上会觉得少用点好但现实是你大概率希望在不崩溃的前提下尽可能多用。如果你付费买了 3 台服务器却只用了一点点 RAM 和 CPU那你多半在浪费钱也在浪费服务器的电力。这种情况下不如只保留 2 台服务器、提高单台资源CPU、内存、磁盘、网络带宽等的利用率。反过来如果 2 台服务器已经跑到CPU 和 RAM 的 100%那么某个时刻某个进程请求更多内存时服务器只能把磁盘当内存用速度可能慢成千上万倍甚至直接崩溃或者某个进程需要计算时只能干等 CPU 空闲。这种时候不如再加一台服务器把一部分进程迁移过去让每台都拥有充足的 RAM 与 CPU 时间。还有一个现实因素你的 API 可能出现使用尖峰——比如突然爆火或者被其他服务/爬虫盯上。为了在这些情况下保持安全预留一些额外资源是明智的。实践中你可以设定一个目标区间例如让资源利用率保持在50%90%之间。这类指标正是部署调优时最需要测量和参考的东西。工具方面htop这样的简单工具就能查看服务器整体的 CPU/RAM 用量或每个进程的占用也可以使用更复杂的、可跨服务器分布式部署的监控工具。概念回顾Recap部署决策的检查清单把上述关键概念串起来就是你在决定如何部署应用时需要时刻放在心上的检查清单安全 —— HTTPS由外部的 TLS 终止代理提供并要有证书续期机制开机自启让服务器程序随系统启动无需人工干预重启崩溃后由外部组件自动拉起而不是让 API 一直离线复制视流量与 CPU 核数决定运行多少个进程Worker内存多进程不共享内存按单进程占用 × Worker 数估算总需求启动前的预备步骤数据库迁移等一次性工作务必只由一个进程执行。理解这些概念并知道如何应用它们足以让你在配置与调优部署时做出合理的决策。后续的部署章节如 手动运行服务器、HTTPS、服务器与 Worker、容器化、云服务 与 版本管理会给出各种可以直接照做的具体策略。在你评估下一套部署方案无论是 1 个 Uvicorn 进程、--workers 4还是一组 Kubernetes 副本时不妨先对着这份清单过一遍HTTPS 谁来终结、谁来守护启动、崩溃谁来拉起、Worker 数与内存预算是否匹配、迁移只跑一次、以及资源利用率是否落在 50%90% 的舒适区。把这些问题想清楚任何部署环境的变化都只是套用同一套直觉而已。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考