Ubuntu 22.04与FastAPI开发环境搭建指南-代码聚汇网

Ubuntu 22.04与FastAPI开发环境搭建指南

神经小黑·2026-08-02·阅读 31 GEO检测（免费）

Ubuntu 22.04FastAPIPython 3.10

|难度：普通|阅读约 18 分钟

1. 为什么选择Ubuntu 22.04和FastAPI组合

在Linux发行版中，Ubuntu 22.04 LTS（Jammy Jellyfish）因其长期支持特性和稳定的软件仓库成为开发者的首选。我选择这个版本作为基础环境，主要考虑三个因素：首先是其官方维护周期长达5年（2022-2027），其次是APT仓库中Python 3.10的默认集成，最后是广泛的社区支持——任何你遇到的问题几乎都能在Ask Ubuntu或Stack Overflow找到解决方案。

FastAPI作为现代Python Web框架，其优势在Ubuntu环境下能得到充分发挥。这个由Sebastián Ramírez创建的框架，底层基于Starlette和Pydantic，支持异步请求处理（ASGI）和自动API文档生成。实测在相同硬件条件下，FastAPI的请求处理速度比传统Django快3-5倍，特别适合需要高并发的微服务场景。

注意：虽然Ubuntu 22.04默认Python版本是3.10，但FastAPI完全兼容3.7+版本。如果项目需要特定Python版本，建议使用pyenv管理多版本环境。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 系统环境准备与依赖安装

2.1 基础系统配置

首先更新系统软件源并升级现有包，这是避免后续依赖冲突的关键步骤：

bash复制sudo apt update && sudo apt upgrade -y

安装编译工具链和基础依赖（这些是Python包编译的必备组件）：

bash复制sudo apt install -y build-essential python3-dev python3-pip python3-venv libssl-dev zlib1g-dev libffi-dev

2.2 Python虚拟环境配置

为避免系统Python环境被污染，强烈建议使用venv创建隔离环境：

bash复制python3 -m venv ~/fastapi_env
source ~/fastapi_env/bin/activate

激活虚拟环境后，提示符前会出现(fastapi_env)标记。这个环境的所有pip安装包都会存放在~/fastapi_env/lib/python3.10/site-packages/目录下。

2.3 网络优化配置

国内用户建议先配置pip镜像源加速下载：

bash复制mkdir -p ~/.pip
cat > ~/.pip/pip.conf << EOF
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
EOF

3. FastAPI核心组件安装与验证

3.1 基础包安装

执行以下命令安装FastAPI及其依赖：

bash复制pip install fastapi uvicorn[standard]

这里特别说明几个关键依赖：

uvicorn[standard]：包含C扩展的ASGI服务器，性能比纯Python版本提升40%
pydantic：提供数据验证和设置管理
starlette：轻量级ASGI框架工具包

3.2 最小化应用测试

创建测试文件main.py：

python复制from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

启动开发服务器：

bash复制uvicorn main:app --reload

访问http://127.0.0.1:8000应看到JSON响应，http://127.0.0.1:8000/docs会自动生成Swagger UI文档。

4. 常见问题排查手册

4.1 端口冲突问题

当遇到Address already in use错误时，可通过以下步骤解决：

查找占用端口的进程：
```
bash复制sudo lsof -i :8000
```
终止对应进程：
```
bash复制sudo kill -9 <PID>
```
或者直接指定其他端口：
```
bash复制uvicorn main:app --port 8001
```

4.2 依赖版本冲突

典型报错如ImportError: cannot import name...，解决方法：

生成依赖清单：

bash复制pip freeze > requirements.txt

创建干净虚拟环境重新安装：

bash复制pip install -r requirements.txt --force-reinstall

4.3 ASGI服务器性能调优

生产环境建议使用以下启动参数：

bash复制uvicorn main:app --host 0.0.0.0 --port 80 --workers 4 \
--limit-concurrency 1000 --timeout-keep-alive 30

各参数含义：

--workers：根据CPU核心数设置（建议核数×2+1）
--limit-concurrency：防止DDoS攻击
--timeout-keep-alive：优化长连接资源占用

5. 生产环境部署方案

5.1 使用Systemd托管服务

创建服务文件/etc/systemd/system/fastapi.service：

ini复制[Unit]
Description=FastAPI Application
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/home/ubuntu/app
Environment="PATH=/home/ubuntu/fastapi_env/bin"
ExecStart=/home/ubuntu/fastapi_env/bin/uvicorn main:app --host 0.0.0.0 --port 8000

[Install]
WantedBy=multi-user.target

启用并启动服务：

bash复制sudo systemctl enable fastapi
sudo systemctl start fastapi

5.2 Nginx反向代理配置

在/etc/nginx/sites-available/fastapi中添加：

nginx复制server {
    listen 80;
    server_name your_domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

启用配置后测试Nginx语法：

bash复制sudo nginx -t && sudo systemctl reload nginx

6. 进阶配置技巧

6.1 异步任务处理

对于耗时操作，使用BackgroundTasks避免阻塞主线程：

python复制from fastapi import BackgroundTasks

def write_log(message: str):
    with open("log.txt", mode="a") as log:
        log.write(message)

@app.post("/send-notification")
async def send_notification(email: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, f"email to {email}")
    return {"message": "Notification sent"}

6.2 数据库集成示例

以SQLAlchemy异步版为例：

bash复制pip install sqlalchemy asyncpg

数据库连接配置：

python复制from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession

engine = create_async_engine(
    "postgresql+asyncpg://user:pass@localhost/dbname",
    echo=True
)

6.3 监控与日志

添加Prometheus监控：

bash复制pip install prometheus-fastapi-instrumentator

在应用中启用：

python复制from prometheus_fastapi_instrumentator import Instrumentator

Instrumentator().instrument(app).expose(app)

访问/metrics端点即可获取监控指标。

7. 开发工具链推荐

7.1 VS Code配置

安装以下扩展提升开发效率：

Python (Microsoft)
Pylance
FastAPI Snippets

.vscode/settings.json推荐配置：

json复制{
    "python.linting.pylintEnabled": true,
    "python.formatting.provider": "black",
    "python.analysis.typeCheckingMode": "basic"
}

7.2 测试方案

使用pytest编写API测试：

python复制from fastapi.testclient import TestClient

def test_read_main():
    client = TestClient(app)
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello World"}

运行测试：

bash复制pip install pytest
pytest -v

8. 性能优化实战

8.1 响应缓存策略

使用fastapi-cache2实现Redis缓存：

bash复制pip install fastapi-cache2 redis

示例配置：

python复制from fastapi_cache import FastAPICache
from fastapi_cache.backends.redis import RedisBackend

@app.on_event("startup")
async def startup():
    FastAPICache.init(RedisBackend("redis://localhost"))

8.2 Gzip压缩启用

修改Uvicorn启动参数：

bash复制uvicorn main:app --compress --compress-min-bytes 1000

或在Nginx层配置：

nginx复制gzip on;
gzip_types application/json;

8.3 连接池优化

数据库连接池推荐配置：

python复制engine = create_async_engine(
    "postgresql+asyncpg://user:pass@localhost/dbname",
    pool_size=20,
    max_overflow=10,
    pool_timeout=30,
    pool_recycle=3600
)

9. 安全加固措施

9.1 CORS配置

精确控制跨域访问：

python复制from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://yourdomain.com"],
    allow_methods=["GET", "POST"],
    allow_headers=["*"],
)

9.2 速率限制

使用slowapi防止暴力请求：

bash复制pip install slowapi

实现示例：

python复制from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter

@app.get("/")
@limiter.limit("5/minute")
async def root(request: Request):
    return {"message": "Hello World"}

9.3 HTTPS强制跳转

在Nginx配置中添加：

nginx复制server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$host$request_uri;
}

10. 容器化部署方案

10.1 Dockerfile示例

dockerfile复制FROM python:3.10-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"]

构建并运行：

bash复制docker build -t fastapi-app .
docker run -d -p 8000:80 --name myapp fastapi-app

10.2 Docker Compose配置

docker-compose.yml示例：

yaml复制version: '3'

services:
  app:
    build: .
    ports:
      - "8000:80"
    environment:
      - ENV=production
    depends_on:
      - redis

  redis:
    image: redis:alpine
    volumes:
      - redis_data:/data

volumes:
  redis_data:

启动集群：

bash复制docker-compose up -d