启动 Python（FastAPI）项目

原创已于 2025-11-28 11:30:08 修改 · 1k 阅读

11 ·

CC 4.0 BY-SA版权

文章标签：

#python #fastapi #开发语言

于 2025-11-28 11:28:04 首次发布

Python 专栏收录该内容

4 篇文章

订阅专栏

Python 项目启动流程说明，适合 FastAPI / Uvicorn 等常见项目结构。

✅ Python 项目启动步骤说明

1. 创建虚拟环境（推荐，每个项目独立隔离）

在项目目录下执行：

python3 -m venv myenv

2. 激活虚拟环境

macOS / Linux：

source myenv/bin/activate

Windows：

myenv\Scripts\activate

成功后，命令行前面一般会出现：

(myenv) $

3. 安装项目依赖

一般项目都会带 requirements.txt，执行：

pip3 install -r requirements.txt

安装项目运行所需的包（如 FastAPI、Uvicorn、pydantic 等）。

4. 启动 Python（FastAPI）项目

如果你的入口文件是 main.py，且里面有一个 app 对象：

uvicorn main:app --reload --port 8000

参数说明：

main:app → main.py 中的变量 app
–reload → 热更新（开发环境常用）
–port 8000 → 指定端口

启动后浏览器访问：

http://localhost:8000

🔥 如何关闭 Python 服务？

若要关闭运行中的 Uvicorn 服务，有两种方式：

方式 1：直接 Ctrl + C（最常用）

在运行服务的终端按：

Ctrl + C

即可正常停止。

方式 2：通过端口查找进程并 kill

如果因为某些原因服务没退出，可以用端口查 PID，再杀掉进程。

① 查找某端口（如 9000）正在占用的进程：

lsof -i :9000

你会看到类似输出：

uvicorn  PID  ...

② 杀掉进程：

kill -9 PID

🔁 修改端口重新启动

例如要改为 9000 端口：

uvicorn main:app --reload --port 9000

🧩 总结

启动一个 Python 项目的核心步骤就是：

创建虚拟环境
激活环境
安装依赖
用 Uvicorn 启动 FastAPI（或者 flask run 启动 Flask）
需要时关闭或重新启动服务

🚀 下面继续扩展 Python（FastAPI）项目的完整启动与部署指南

包括：

项目结构讲解
main.py 的典型写法
如何写启动脚本（bash）
如何做生产环境部署（systemd 后台运行）
如何做自动重启、日志保存

✅ 一、典型 FastAPI 项目结构

一个常见、规范的 FastAPI 项目结构如下：

project/
│── main.py
│── requirements.txt
│── myenv/（虚拟环境）
│── app/
│     ├── __init__.py
│     ├── routers/
│     ├── models/
│     ├── services/

✅ 二、main.py 通常是什么？

你启动的命令 uvicorn main:app 就是指 main.py 文件里必须有 app 对象。

一个典型 main.py 如下：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"msg": "Hello FastAPI"}

启动命令：

uvicorn main:app --reload --port 8000

访问：

http://localhost:8000

✅ 三、常用启动脚本（建议使用）

你可以创建一个脚本：start.sh

内容：

#!/bin/bash

# 激活虚拟环境
source myenv/bin/activate

# 启动服务
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

让脚本可执行：

chmod +x start.sh

运行：

./start.sh

✅ 四、生产环境部署（推荐使用 systemd）

生产环境不建议使用 --reload，且不希望终端关闭后服务退出。

假设你的项目目录是 /home/ubuntu/project/：

创建 systemd 服务：

sudo nano /etc/systemd/system/myfastapi.service

写入：

[Unit]
Description=FastAPI Service
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/home/ubuntu/project
ExecStart=/home/ubuntu/project/myenv/bin/uvicorn main:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

保存后执行：

sudo systemctl daemon-reload
sudo systemctl start myfastapi
sudo systemctl enable myfastapi

🔍 五、查看服务状态 / 日志

查看运行状态：

sudo systemctl status myfastapi

查看日志：

journalctl -u myfastapi -f

停止服务：

sudo systemctl stop myfastapi

重启服务：

sudo systemctl restart myfastapi

📝 六、为生产环境加入日志文件（可选）

如果想保存日志到文件，可以使用 gunicorn + uvicorn workers：

ExecStart=/home/ubuntu/project/myenv/bin/gunicorn -k uvicorn.workers.UvicornWorker main:app --bind 0.0.0.0:8000 --access-logfile /var/log/myapi/access.log

🎉 你现在已经掌握了：

虚拟环境的创建和使用
FastAPI 项目的结构
如何启动（开发 / 生产）
如何关闭服务（Ctrl+C / kill / 端口方式）
如何写脚本启动
如何 systemd 后台运行

🔹 解释 Uvicorn、Gunicorn、FastAPI 之间的关系

下面用最简单、最直观的方式解释 FastAPI、Uvicorn、Gunicorn 之间的关系，你一看就懂。

🧩 三者关系一句话总结

FastAPI 是 Web 框架
Uvicorn 是 Web 服务器（ASGI Server）
Gunicorn 是进程管理器（多进程运行 FastAPI 的大管家）

在生产环境中常见组合是：

Gunicorn 管多个 Uvicorn Worker 运行 FastAPI

图示关系如下：

            ┌───────────────┐
            │   Gunicorn    │  ← 负责多进程、管理 worker
            └───────┬───────┘
     ┌──────────────┴──────────────┐
     │                              │
┌──────────┐                 ┌──────────┐
│ Uvicorn  │                 │ Uvicorn  │  ← 真正运行你的 FastAPI 程序
└─────┬────┘                 └─────┬────┘
      │                            │
 ┌────▼──────┐                 ┌────▼──────┐
 │  FastAPI  │                 │  FastAPI  │  ← 你的应用逻辑
 └───────────┘                 └───────────┘

⭐ 各自详细职责解析

1️⃣ FastAPI（框架）

FastAPI 是：

一个 Web 框架
帮你写接口、路由、参数校验
提供 Swagger 文档
和业务逻辑最相关

你写的代码比如：

from fastapi import FastAPI

app = FastAPI()

@app.get("/hello")
def hello():
    return {"msg": "hi"}

FastAPI 本身不能提供网络服务
它需要运行在一个 ASGI Server 上。

2️⃣ Uvicorn（ASGI Server）——真正运行 FastAPI 的服务

Uvicorn:

是一个 ASGI Server
负责处理 HTTP 请求、WebSocket
速度非常快（基于 uvloop）
开发环境中常用命令：

uvicorn main:app --reload --port 8000

Uvicorn 就像 Node.js 中的 node，负责启动你的服务。

3️⃣ Gunicorn（进程管理器）——生产环境大管家

Gunicorn 本身只支持 WSGI，但可以通过：

gunicorn -k uvicorn.workers.UvicornWorker

来使用 Uvicorn Worker，以便运行 ASGI 应用。

Gunicorn 负责：

多进程管理（可同时开多个 worker）
自动重启
崩溃恢复
生产环境的健壮性

它像一个“老板”，负责管理多个 Uvicorn 工人。

🧨 为什么生产环境不用单独的 Uvicorn？

因为：

特性	Uvicorn	Gunicorn + Uvicorn
多进程	❌ 不支持	✅ 支持（可开多个 worker）
自动重启	❌	✅
崩溃恢复	❌	✅
生产环境稳定性	较弱	非常强
性能	单进程性能高	多核利用更好

因此生产推荐使用：

gunicorn -k uvicorn.workers.UvicornWorker main:app

📌 生产环境推荐架构

Nginx 反向代理
      │
      ▼
Gunicorn（多进程）
      │
      ├── Uvicorn Worker 1
      ├── Uvicorn Worker 2
      └── Uvicorn Worker 3
            │
            ▼
         FastAPI 应用