FastAPI 生产部署核心概念：HTTPS、进程与 Worker、自动重启与资源利用率

FastAPI 生产部署核心概念HTTPS、进程与 Worker、自动重启与资源利用率【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi部署一个 FastAPI 应用事实上任何 Web API 都是如此时真正决定架构成败的往往不是框架本身而是围绕它的六个核心概念安全HTTPS、开机自启、故障重启、进程复制Worker 数量、内存、以及启动前的准备步骤。理解这些概念后你就能针对任意环境——包括尚不存在的未来环境——评估并设计出最适合自己的部署方案。本文基于 FastAPI 官方文档中的部署概念章节docs/en/docs/deployment/concepts.md结合仓库源码与配套文档系统梳理这些概念的含义、约束条件与落地工具选型。六大部署概念总览官方文档把部署决策归纳为以下六个必须考量的维度安全 - HTTPS如何为 API 提供加密传输Running on startup开机自启如何保证应用进程在服务器启动后自动运行Restarts重启进程崩溃后如何自动拉起Replication复制/进程数同时运行多少个进程来处理请求Memory内存每个进程的内存占用如何叠加到整机上Previous steps before starting启动前步骤如何以单进程方式先执行数据库迁移等一次性任务。最终目标是以安全的方式服务 API 客户端避免服务中断并尽可能高效地利用计算资源例如远程服务器/虚拟机。官方文档强调这些概念适用于任何类型的 Web API掌握它们是为了获得“直觉”——即在不同环境中做出正确部署决策的判断力。安全HTTPS 与 TLS 终结代理TLS 终结加密由谁负责如官方 HTTPS 指南 所述HTTPS 为 API 提供传输加密而通常情况下HTTPS 是由一个位于应用服务器外部的组件提供的即TLS 终结代理TLS Termination Proxy。此外还必须有一个组件负责HTTPS 证书的续期——它可以是同一个组件也可以是另外的组件。常见的 TLS 终结工具组合文档给出的可选工具清单如下证书续期方式各异选型时重点关注工具证书续期方式Traefik自动处理证书续期Caddy自动处理证书续期Nginx需要外部组件如 CertbotHAProxy需要外部组件如 CertbotKubernetes Ingress Controller如 Nginx需要外部组件如 cert-manager云服务商内部托管云服务作为其服务的一部分内部处理可能有限制或额外费用但无需自己搭建 TLS 终结代理选择云服务方案时它可能有一些限制或更高的费用但省去了自行配置 TLS 终结代理的工作。具体的部署示例在后续章节如 手动部署、Docker 部署中给出。程序Program与进程Process的区别部署语境下会频繁提到“运行中的进程process”因此必须先厘清它与“程序program”的区别。“程序”一词的多重含义Program一词常被用来指代很多不同的东西你编写的代码即那些Python 文件操作系统可以执行的文件例如python、python.exe或uvicorn某个正在操作系统上运行的特定程序实例它占用 CPU、在内存中存储数据——这个东西也被称为进程process。“进程”的确切定义Process的用法更具体只指操作系统中正在运行的那个东西它不指文件不指代码而是特指正在被执行、由操作系统管理的那个实体任何程序、任何代码只有正在被执行即有进程在运行时才能“做事”进程可以被你或操作系统终止kill终止后它停止运行也就不再能做任何事你电脑上运行的每个应用背后都有若干进程每个窗口、每个运行中的程序都对应进程一台开机运行的电脑通常同时有大量进程同一程序的多个进程可以同时运行。打开操作系统的“任务管理器”或“系统监视器”类工具就能看到这一点。例如通常能观察到多个进程正在运行同一个浏览器程序Firefox、Chrome、Edge 等——浏览器通常为每个标签页启动一个进程外加若干辅助进程理解了程序与进程的区别下面讨论的所有部署策略才有了共同的语义基础。开机自启让应用常驻大多数情况下Web API 需要持续运行、不中断让客户端随时可访问除非你有特定理由只想让它在某些情况下运行。在远程服务器上手动启动的问题在远程服务器云服务器、虚拟机等上最简单的方式是手动运行fastapi run它使用 Uvicorn或类似命令就像本地开发时那样。这在开发阶段没问题但有两个致命风险如果到服务器的连接中断运行中的进程很可能随之死亡如果服务器被重启例如系统更新、云厂商迁移后你很可能根本察觉不到也就不会去手动重启进程API 会一直死着。自动启动与“独立程序”因此通常需要让服务器程序如 Uvicorn在服务器启动时自动启动无需任何人工干预保证始终有一个进程在运行你的 API。实现方式是引入一个独立的程序separate program它负责保证你的应用开机即运行在很多场景下它还负责启动其他组件例如数据库。文档列出的候选工具DockerKubernetesDocker ComposeDocker in Swarm ModeSystemdSupervisor云服务商作为其服务的一部分内部托管其他方案仓库视角fastapi run从哪里来从源码结构看fastapi命令行入口本身只是一个薄封装fastapi/cli.py 尝试从fastapi_cli包导入真正的 CLI 实现若未安装则抛出提示To use the fastapi command, please install fastapi[standard]的RuntimeError。对应的入口注册与依赖声明见 pyproject.toml 中的[project.scripts]fastapi fastapi.cli:main以及standard可选依赖包含uvicorn[standard]。这一行为由测试 tests/test_fastapi_cli.py 验证未安装fastapi_cli时调用fastapi.cli.main()会抛出带安装提示的异常。换言之部署文档中说的“fastapi run使用 Uvicorn”在实现上依赖于fastapi[standard]提供的uvicorn[standard]这是生产部署前应确认的前置条件。故障重启从局部 500 到进程级崩溃与开机自启类似你还需要确保应用在故障后被重启。人的错误与小错误的自动兜底人类会不断犯错软件几乎总有一些隐藏的 bug开发者在修复旧 bug、开发新功能的过程中也在持续引入新变化。值得庆幸的是用 FastAPI 构建 Web API 时如果代码中出现错误FastAPI 通常会把错误限制在触发它的那单个请求内客户端收到该请求的500 Internal Server Error而应用继续为后续请求正常工作不会整体崩溃。进程级崩溃与自动重启但确实存在会让整个应用崩溃的代码使 Uvicorn 和 Python 进程直接挂掉。即便如此你通常也不希望应用因为一处的错误就“死掉”而是希望它至少为那些没坏的 path operation继续服务。对于这类导致运行中进程崩溃的严重错误你需要一个外部组件负责重启该进程——因为进程已经死了应用自身的代码此时已无能为力。文档特别提醒如果应用是一启动就立刻崩溃那无限重启就没有意义了——这种情况你通常会在开发期或刚部署后就发现。我们应聚焦的主体场景是应用未来在某些特定情况下可能完全崩溃此时重启是有价值的。在大多数情况下负责开机自启的同一个工具也负责自动重启例如Docker、Kubernetes、Docker Compose、Docker in Swarm Mode、Systemd、Supervisor、云服务商内部托管等。复制Worker 进程、端口约束与内存使用fastapi命令运行 Uvicorn时一个进程就能并发服务多个客户端。但很多场景下你需要同时运行多个worker 进程。多进程与单端口约束如果客户端数量超过单进程的处理能力比如虚拟机不大而服务器 CPU 有多个核心就可以让多个进程运行同一应用把请求分发到它们之间。运行同一 API 程序的多个进程通常被称为workers。这里有一个硬约束同一 IP 与端口的组合只能有一个进程监听这一点在 HTTPS 指南 中也有说明。因此要同时存在多个进程就必须有一个进程监听端口再以某种方式把通信转发给各个 worker 进程。每个进程独立的内存占用程序在内存中加载的东西——例如把一个机器学习模型赋给变量、把大文件内容读进变量——都会消耗服务器的 RAM。而多个进程之间通常不共享任何内存每个运行中的进程拥有自己的变量与内存。如果你的代码占用大量内存每个进程都会占用一份等量的内存。具体算一笔账假设你的代码加载了一个1 GB 的机器学习模型运行 1 个进程时至少消耗 1 GB RAM启动4 个 worker时每个消耗 1 GBAPI 总共消耗4 GB RAM。如果服务器只有 3 GB RAM加载超过 4 GB 就会出问题。Manager 进程与 Worker 进程的结构官方文档用一张图说明典型结构一个Manager Process管理器进程启动并控制多个Worker Process。管理器进程负责在 IP 的某个端口上监听并把所有通信转发给 worker 进程worker 进程则真正运行你的应用——接收请求、返回响应、执行主要计算并把代码中赋给变量的任何东西加载进 RAM。同一台机器上通常还运行着其他进程。该图见 process-ram.drawio.svg。一个值得注意的观察各进程占用的CPU 百分比可能随时间大幅波动而**内存RAM**通常相对稳定。如果你的 API 每次请求的计算量相近且客户端很多CPU 利用率大概率也会趋于稳定而不是快速上下抖动。常见复制策略与工具主要约束始终不变必须有单一组件处理公网 IP 上的端口然后它需要有某种方式把通信转发给被复制的进程/worker。文档给出的策略组合Uvicorn --workers一个 Uvicorn管理器进程监听 IP 和端口并启动多个 Uvicorn worker 进程Kubernetes 等其他分布式容器系统Kubernetes 层的某个组件监听 IP 和端口复制方式是多个容器每个容器内运行一个 Uvicorn 进程代劳的云服务云服务通常替你处理复制——你可能只需定义要运行的进程或容器镜像而大概率是单个 Uvicorn 进程由云服务负责复制。关于第一条策略仓库中配套的 Uvicorn Workers 文档 给出了可复制的实证执行fastapi run --workers 4 main.py后日志会依次输出Started parent process [27365]与 4 条Started server process [...]直观印证了上文“一个管理器进程 N 个 worker 进程”的结构。文档同时提示若使用 Docker/Kubernetes在 Kubernetes 上通常不希望在单个容器里用 workers而是每个容器跑单个 Uvicorn 进程交由容器层做复制详见 Docker 部署指南。启动前的准备步骤Previous Steps很多场景下你需要在启动应用之前执行某些步骤最典型的例子是运行数据库迁移。但多数情况下这些步骤只需要执行一次因此需要一个单一进程来执行这些前置步骤然后再启动应用必须确保即使之后应用本身以多进程多 worker方式运行前置步骤也只由单进程执行。如果这些步骤被多个进程并行执行就会重复劳动如果步骤是数据库迁移这类敏感操作并行执行还可能互相冲突当然也存在某些前置步骤可以安全地重复执行的情况那样处理就简单得多。另外取决于你的架构有些情况下根本不需要任何前置步骤那就完全不用考虑这一节。文档给出的可选策略Kubernetes 中的 Init Container在你的应用容器之前运行bash 脚本先执行前置步骤再启动应用——注意你仍然需要一种方式来启动/重启这个 bash 脚本本身、检测错误等。更具体的容器化示例官方文档指向了 Docker 部署章节。资源利用率把付费资源用满但别撑爆你的服务器是资源你的程序消耗其中的 CPU 计算时间和 RAM。你希望占用多少资源直觉上可能觉得“别太多”但现实中你大概率希望在不崩溃的前提下占用尽可能多如果你付了 3 台服务器的钱却只用了很少的 RAM 和 CPU那基本是浪费钱、也浪费电力。这时可能用 2 台服务器并把资源利用率CPU、内存、磁盘、网络带宽等提得更高更划算反过来如果 2 台服务器的CPU 和 RAM 都用到 100%某个进程迟早会请求更多内存服务器将被迫把磁盘当作内存使用可能慢数千倍甚至崩溃或者某个进程需要计算却只能等 CPU 空闲。此时应该多加一台服务器把部分进程放上去让所有进程都有足够的 RAM 和 CPU 时间还要考虑流量尖峰应用可能突然走红或有其他服务、机器人开始使用它你需要冗余资源来应对这种情况。实践建议可以设定一个目标利用率区间例如 50%90%。关键是这些指标CPU 与内存利用率就是你调优部署时最主要需要度量的对象。度量工具可以从简单的htop查看整机或单进程的 CPU/RAM 占用开始也可以升级到更复杂的、跨服务器分布的监控工具。小结六个概念的清单回顾本章建立的核心概念清单它们是你决定如何部署应用时应该持续放在心上的概念关键问题典型工具/手段安全 - HTTPS谁终结 TLS谁续期证书Traefik / Caddy自动续期Nginx / HAProxy CertbotK8s Ingress cert-manager云服务托管开机自启服务器重启后进程如何自动回来Docker、Kubernetes、Docker Compose、Swarm、Systemd、Supervisor、云托管自动重启进程崩溃后谁来拉起通常与自启为同一外部组件复制进程数单端口只能一个进程如何多进程Uvicorn--workers管理器进程、K8s 多容器、云服务复制内存每个 worker 各占一份内存总量如何规划以模型/大对象大小 × worker 数估算启动前步骤数据库迁移等一次性任务如何只跑一次K8s Init Container、bash 脚本资源利用率用多少资源合适htop或分布式监控目标区间 50%90%掌握这些概念并知道如何应用是你在配置和调优部署时做出任何决策所需的直觉基础。在这份概念清单之上官方文档的后续章节HTTPS、Server Workers、Docker 容器部署、手动部署会给出各策略的具体落地配方。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考