Fast Byte - Thuê VPS Giá Rẻ
Hướng dẫn chung

Cách Cài FastAPI Trên VPS Với Uvicorn & Nginx Trong 8 Bước Dễ Làm

Nắm vững cách cài FastAPI trên VPS giúp bạn thoát khỏi cảnh ứng dụng API chạy chập chờn, dễ sập khi thiếu trình quản lý tiến trình hoặc lộ cổng kết nối kém an toàn. Thay vì chỉ chạy thử nghiệm tạm bợ trên máy cá nhân, bạn có thể triển khai hệ thống chuẩn […]

Ảnh đại diện Thanh Lam NguyễnThanh Lam Nguyễn17 phút đọc

Nắm vững cách cài FastAPI trên VPS giúp bạn thoát khỏi cảnh ứng dụng API chạy chập chờn, dễ sập khi thiếu trình quản lý tiến trình hoặc lộ cổng kết nối kém an toàn. Thay vì chỉ chạy thử nghiệm tạm bợ trên máy cá nhân, bạn có thể triển khai hệ thống chuẩn production trên Ubuntu 24.04 với Uvicorn, systemd và Nginx HTTPS ổn định. Nếu cần hạ tầng riêng, xem ngay tại ThueVPSGiaRe.vn.

FastAPI là gì? So sánh ưu điểm và khi nào nên lựa chọn

FastAPI là một framework web Python hiện đại chuyên dùng để xây dựng các HTTP API và RESTful API trên nền tảng chuẩn ASGI với hiệu suất vượt trội. Công cụ này được phát triển dựa trên các tiêu chuẩn mở như OpenAPI (Swagger) và JSON Schema, giúp lập trình viên rút ngắn đáng kể thời gian phát triển backend khi triển khai ứng dụng Python hoạt động liên tục trên VPS.

FastAPI
FastAPI

Những thế mạnh cốt lõi giúp FastAPI được cộng đồng kỹ thuật ưa chuộng gồm:

  • Hiệu suất xử lý cao: Tốc độ thực thi của FastAPI đạt mức tương đương với NodeJS và Go.
  • Dễ học và dễ viết mã: Hệ thống gợi ý kiểu dữ liệu (type hint) chuẩn xác giúp giảm lỗi logic và hỗ trợ sinh tài liệu API tức thì.
  • Tài liệu API tự động: Tích hợp sẵn giao diện Swagger UI và Redoc chỉ sau vài dòng mã nguồn cấu hình.
  • Hỗ trợ async/await nguyên bản: Tối ưu hóa khả năng xử lý đồng thời cho các tác vụ bất đồng bộ (asynchronous).
  • Tích hợp bảo mật tốt: Hỗ trợ sẵn các cơ chế xác thực phổ biến như OAuth2 hay JWT.

Bảng so sánh FastAPI với Flask và Django

Tiêu chí FastAPI Flask Django
Tốc độ xử lý Rất nhanh Trung bình Trung bình
Hỗ trợ async Có sẵn Không trực tiếp Có nhưng phức tạp
Tự sinh tài liệu API Có Cần cài thêm Cần cài thêm
Dễ học Dễ Rất dễ Trung bình
Quy mô dự án Vừa đến lớn Nhỏ đến vừa Vừa đến lớn
So sánh FastAPI với Flask và Django
So sánh FastAPI với Flask và Django

Khi nào nên và không nên chọn FastAPI?

Bạn nên ưu tiên FastAPI nếu đang xây dựng một dịch vụ API thuần túy để ứng dụng di động hoặc frontend gọi tới, phát triển hệ thống theo kiến trúc microservice (tách thành nhiều vi dịch vụ nhỏ độc lập), hoặc làm backend phải giao tiếp với nhiều dịch vụ bên ngoài, mô hình AI hay cơ sở dữ liệu vector — những kịch bản mà cơ chế bất đồng bộ phát huy hiệu quả rõ rệt.

Ngược lại, hãy cân nhắc lại lựa chọn này nếu dự án cần một website hoàn chỉnh có giao diện render phía máy chủ (server-side), trang quản trị và hệ thống quản lý người dùng tích hợp sẵn vì Django sẽ gọn gàng hơn nhiều. Ngoài ra, nếu đội ngũ phát triển chưa quen với lập trình bất đồng bộ, việc đặt async sai ngữ cảnh có thể khiến tốc độ chậm hơn cả xử lý đồng bộ thông thường.

Kiến trúc vận hành FastAPI trên VPS và điều kiện chuẩn bị

Vì FastAPI là một ASGI framework, nó chỉ đảm nhận phần định tuyến (routes), còn thành phần trực tiếp mở cổng mạng và giao tiếp HTTP là máy chủ ASGI Uvicorn. Trong môi trường production, Gunicorn thường tham gia làm trình quản lý tiến trình để khởi chạy nhiều worker Uvicorn tận dụng toàn bộ vCPU và tự thay thế các worker bị treo, kết hợp với Nginx đứng ngoài cùng để xử lý TLS và chuyển tiếp yêu cầu.

Thành phần Vai trò trong hệ thống Cổng / Địa chỉ lắng nghe
Nginx Tiếp nhận lưu lượng, kết thúc kết nối HTTPS và chuyển tiếp tới API Cổng công khai 80 và 443
Gunicorn Quản lý tiến trình, luân chuyển và khởi động lại các worker 127.0.0.1:8000
Uvicorn workers Vận hành ứng dụng FastAPI ở chế độ bất đồng bộ Chạy bên trong Gunicorn
systemd Tự khởi động cùng máy chủ, bật lại khi sập và lưu trữ nhật ký Không mở cổng mạng
PostgreSQL Hệ quản trị cơ sở dữ liệu (nếu API có nhu cầu lưu trữ) Chỉ cổng 5432 trên 127.0.0.1

Nguyên tắc bảo mật cốt lõi là chỉ duy nhất Nginx tiếp xúc với Internet. Cổng 8000 tuyệt đối không được mở trên tường lửa, đồng thời tiến trình Python phải chạy dưới một tài khoản người dùng không có đặc quyền và không thể tự ý chỉnh sửa mã nguồn của chính nó.

Kiến trúc và chuẩn bị cài FastAPI trên VPS
Kiến trúc và chuẩn bị cài FastAPI trên VPS

Trước khi bắt tay vào cấu hình cách web server Nginx xử lý lưu lượng truy cập cùng FastAPI, bạn cần chuẩn bị đầy đủ các điều kiện sau:

  • Một máy chủ ảo (VPS) cài hệ điều hành Ubuntu 24.04 LTS có tối thiểu 1 GB RAM.
  • Một tài khoản non-root được cấp quyền sudo.
  • Một tên miền đã trỏ bản ghi A của tên miền về địa chỉ IP máy chủ công khai của VPS (bài viết dùng api.your_domain làm tên miền ví dụ; hãy thay bằng hostname thực tế của bạn).
  • Hai cổng mạng 80 và 443 có thể truy cập bình thường từ Internet.

Thuê VPS giá rẻ

CPU Intel Gold, SSD NVMe U.2, giá từ 50K/tháng

Hạ tầng riêng giúp triển khai FastAPI và Uvicorn mượt mà

Triển khai backend Python với nhiều worker bất đồng bộ đòi hỏi tài nguyên RAM và ổ cứng tốc độ cao để tránh nghẽn phản hồi API. VPS tại Fast Byte trang bị CPU Intel Xeon Gold, ổ cứng SSD NVMe U.2 cùng IPv4 tĩnh riêng và toàn quyền quản trị root trên Ubuntu 24.04, giúp bạn chủ động cài đặt môi trường ảo, Nginx và chứng chỉ SSL với mức chi phí dễ tiếp cận.

Tham khảo VPS giá rẻ

Hướng dẫn cách cài FastAPI trên VPS Ubuntu 24.04 với Nginx từng bước

Quy trình cài đặt dưới đây bao gồm toàn bộ các bước từ chuẩn bị Python, tách biệt quyền user, đóng gói dịch vụ qua systemd cho tới mở khóa HTTPS bằng Let’s Encrypt. Bạn hãy thực hiện tuần tự từng lệnh để đảm bảo mọi thành phần kết nối khớp với nhau.

Hướng dẫn cách cài FastAPI trên VPS Ubuntu 24.04
Hướng dẫn cách cài FastAPI trên VPS Ubuntu 24.04

Bước 1: Cài đặt Python và Nginx trên Ubuntu 24.04

Phiên bản Ubuntu 24.04 mặc định đi kèm Python 3.12, hoàn toàn tương thích với các bản phát hành FastAPI hiện nay. Bạn cần cài thêm module venv để thiết lập môi trường Python với Pip và Venv trên Ubuntu một cách cô lập cùng máy chủ web Nginx:

sudo apt update
sudo apt install -y python3-venv python3-pip nginx

Kiểm tra lại phiên bản Python vừa cài đặt:

python3 --version

Kết quả trả về trên màn hình sẽ có dạng:

Python 3.12.3

Bước 2: Tạo user riêng cho ứng dụng và môi trường ảo Python

Việc chạy API dưới một tài khoản người dùng không có đặc quyền giúp hạn chế tối đa thiệt hại nếu ứng dụng chẳng may bị khai thác lỗ hổng. Hãy khởi tạo một system user tên là fastapi không có shell đăng nhập:

sudo useradd --system --home-dir /opt/myapi --shell /usr/sbin/nologin fastapi

Tiếp theo, tạo thư mục chứa ứng dụng và bàn giao quyền sở hữu cho tài khoản fastapi vừa tạo:

sudo mkdir -p /opt/myapi/app
sudo chown -R fastapi:fastapi /opt/myapi

Khởi tạo môi trường ảo bên trong thư mục đó và cài đặt FastAPI cùng Uvicorn. Tùy chọn bổ sung standard sẽ cài kèm uvloop và httptools giúp Uvicorn đạt tốc độ xử lý nhanh hơn rõ rệt:

sudo -u fastapi python3 -m venv /opt/myapi/venv
sudo -u fastapi /opt/myapi/venv/bin/pip install fastapi "uvicorn[standard]"

Xác nhận cả hai gói thư viện đã được cài đặt thành công:

sudo -u fastapi /opt/myapi/venv/bin/pip list | grep -iE '^(fastapi|uvicorn) '
fastapi           0.118.0
uvicorn           0.37.0

Số phiên bản thực tế của bạn có thể mới hơn ví dụ trên. Khi đưa dự án thật vào vận hành, bạn nên cài đặt các thư viện phụ thuộc từ tệp requirements.txt đã cố định phiên bản bằng lệnh sudo -u fastapi /opt/myapi/venv/bin/pip install -r /opt/myapi/app/requirements.txt.

Bước 3: Tạo mã nguồn ứng dụng FastAPI mẫu và chạy thử

Nếu đã có sẵn mã nguồn FastAPI, bạn hãy sao chép vào đường dẫn /opt/myapi/app (chẳng hạn qua git clone hoặc rsync) và đảm bảo toàn bộ thư mục thuộc quyền sở hữu của user fastapi. Nếu muốn thử nghiệm ngay, hãy tạo một tệp ứng dụng mẫu nhỏ:

sudo -u fastapi nano /opt/myapi/app/main.py

Dán đoạn mã Python sau vào trình soạn thảo rồi lưu lại:

import os

from fastapi import FastAPI

# Hide the interactive docs in production unless explicitly enabled
show_docs = os.getenv("ENABLE_DOCS", "false").lower() == "true"

app = FastAPI(
    title="My API",
    docs_url="/docs" if show_docs else None,
    redoc_url=None,
    openapi_url="/openapi.json" if show_docs else None,
)

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

@app.get("/health")
async def health():
    return {"status": "ok"}

Kiểm tra khả năng khởi chạy của ứng dụng và chỉ gắn kết (bind) vào giao diện mạng loopback nội bộ:

cd /opt/myapi
sudo -u fastapi /opt/myapi/venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000
INFO:     Started server process [2415]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Mở một phiên kết nối SSH thứ hai và gửi yêu cầu kiểm tra tới endpoint /health:

curl http://127.0.0.1:8000/health
{"status":"ok"}

Sau khi xác nhận API phản hồi đúng, bạn nhấn tổ hợp phím CTRL+C ở phiên SSH đầu tiên để tắt máy chủ chạy thử.

Bước 4: Lưu cấu hình nhạy cảm trong tệp biến môi trường

Các thông tin bí mật như chuỗi kết nối cơ sở dữ liệu hay khóa API không bao giờ nên lưu cứng trong mã nguồn. Hãy đặt chúng vào một tệp riêng mà chỉ tài khoản root mới đọc được; khi chạy, systemd sẽ đọc tệp này với quyền root rồi truyền giá trị vào tiến trình ứng dụng:

sudo mkdir -p /etc/myapi
sudo nano /etc/myapi/myapi.env

Thêm các biến cấu hình theo mẫu bên dưới:

ENABLE_DOCS=false
DATABASE_URL=postgresql://myapi:your_strong_password@localhost/myapi
SECRET_KEY=replace_with_a_long_random_value

Hãy thay thế các giá trị minh họa bằng thông số thực của bạn (có thể sinh chuỗi khóa ngẫu nhiên bằng lệnh openssl rand -hex 32), sau đó giới hạn quyền đọc tệp:

sudo chmod 600 /etc/myapi/myapi.env

Bên trong ứng dụng, bạn có thể đọc lại các biến môi trường này thông qua os.getenv() hoặc thư viện quản lý cấu hình như pydantic-settings.

Bước 5: Thiết lập FastAPI chạy ngầm như một dịch vụ systemd

Một unit file của systemd giúp API tự động khởi chạy cùng hệ điều hành, tự phục hồi khi gặp sự cố và đẩy toàn bộ log về nhật ký journal. Tạo tệp cấu hình dịch vụ bằng lệnh:

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

Nhập nội dung cấu hình chuẩn sau vào tệp:

[Unit]
Description=My FastAPI application
After=network.target

[Service]
Type=exec
User=fastapi
Group=fastapi
WorkingDirectory=/opt/myapi
EnvironmentFile=/etc/myapi/myapi.env
ExecStart=/opt/myapi/venv/bin/uvicorn app.main:app \
    --host 127.0.0.1 \
    --port 8000 \
    --workers 2 \
    --proxy-headers \
    --forwarded-allow-ips 127.0.0.1
Restart=on-failure
RestartSec=5

# Hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true

[Install]
WantedBy=multi-user.target

Một số tham số quan trọng trong tệp cấu hình trên cần lưu ý:

  • --workers 2: Khởi chạy hai tiến trình worker do Uvicorn quản lý. Điểm khởi đầu hợp lý là một worker trên mỗi nhân CPU (kiểm tra số nhân bằng lệnh nproc).
  • --proxy-headers và --forwarded-allow-ips 127.0.0.1: Cho phép Uvicorn tin cậy hai header X-Forwarded-For và X-Forwarded-Proto do Nginx chuyển tới, nhờ đó ứng dụng nhận diện đúng IP thật của khách truy cập và giao thức https.
  • ProtectSystem=strict: Gắn kết toàn bộ hệ thống tệp ở chế độ chỉ đọc (read-only) đối với dịch vụ. Nếu ứng dụng cần quyền ghi tệp, hãy khai báo thêm đường dẫn với tham số ReadWritePaths=/var/lib/myapi.

Nạp lại cấu hình systemd và kích hoạt dịch vụ ngay lập tức:

sudo systemctl daemon-reload
sudo systemctl enable --now myapi.service

Kiểm tra trạng thái hoạt động của dịch vụ:

sudo systemctl status myapi.service
● myapi.service - My FastAPI application
     Loaded: loaded (/etc/systemd/system/myapi.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-09-25 10:32:04 UTC; 5s ago
   Main PID: 3102 (uvicorn)

Kiểm tra lại phản hồi cục bộ bằng lệnh curl:

curl http://127.0.0.1:8000/
{"message":"Hello from FastAPI"}

Nếu dịch vụ không thể khởi chạy, bạn có thể kiểm tra và theo dõi nhật ký hoạt động qua journalctl bằng lệnh sudo journalctl -u myapi.service -n 50.

Bước 6: Cấu hình Nginx làm Reverse Proxy và mở tường lửa UFW

Nginx sẽ tiếp nhận toàn bộ lưu lượng truy cập công khai tại cổng 80 và 443, sau đó chuyển tiếp nội bộ tới Uvicorn đang lắng nghe ở địa chỉ 127.0.0.1:8000. Tạo tệp server block cho tên miền API của bạn:

sudo nano /etc/nginx/sites-available/myapi

Dán cấu hình Nginx sau vào tệp (nhớ thay api.your_domain thành tên miền thực tế):

server {
    listen 80;
    listen [::]:80;
    server_name api.your_domain;

    client_max_body_size 10m;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 60s;
    }
}

Thông số client_max_body_size quy định kích thước phần thân request tối đa mà Nginx tiếp nhận; hãy nâng mức này nếu API của bạn có tính năng tải tệp lên. Tiếp theo, kích hoạt trang web, kiểm tra lỗi cú pháp và tải lại Nginx:

sudo ln -s /etc/nginx/sites-available/myapi /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Để hoàn thiện bước mạng, hãy cấu hình tường lửa UFW mở cổng đúng chuẩn trên Ubuntu cho phép SSH cùng lưu lượng web, rồi bật tường lửa nếu hệ thống chưa kích hoạt:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

Từ máy tính cá nhân, bạn đã có thể kiểm tra API phản hồi qua giao thức HTTP thông thường:

curl http://api.your_domain/health
{"status":"ok"}

Bước 7: Kích hoạt HTTPS với chứng chỉ Let’s Encrypt

Để mã hóa toàn bộ lưu lượng API, bạn hãy cài đặt chứng chỉ bảo mật SSL Let’s Encrypt bằng Certbot và để công cụ này tự động cập nhật lại cấu hình Nginx:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d api.your_domain

Trong quá trình chạy, Certbot sẽ yêu cầu nhập địa chỉ email để nhận cảnh báo hết hạn chứng chỉ và xác nhận đồng ý điều khoản dịch vụ. Khi hoàn tất, công cụ sẽ tự chèn chứng chỉ vào server block kèm quy tắc chuyển hướng tự động từ HTTP sang HTTPS. Kiểm tra lại kết quả:

curl -I https://api.your_domain/health
HTTP/1.1 200 OK
Server: nginx/1.24.0 (Ubuntu)
Content-Type: application/json

Chứng chỉ SSL sẽ được gia hạn tự động định kỳ nhờ bộ đếm thời gian certbot.timer của systemd. Bạn có thể kiểm tra trước quy trình gia hạn bằng lệnh chạy thử sau:

sudo certbot renew --dry-run

Cách cập nhật mã nguồn và xử lý các lỗi thường gặp

Sau khi hoàn tất bước cài đặt ban đầu, việc bảo trì hệ thống định kỳ bao gồm quy trình kéo mã nguồn phiên bản mới và chẩn đoán nhanh khi dịch vụ gặp trục trặc trong quá trình vận hành.

Triển khai bản cập nhật ứng dụng mới

Mỗi khi phát hành phiên bản mới, bạn chỉ cần cập nhật mã nguồn, cài đặt thêm thư viện mới phát sinh (nếu có) và khởi động lại dịch vụ systemd. Với dự án quản lý bằng Git, các lệnh thực hiện lần lượt như sau:

sudo -u fastapi git -C /opt/myapi/app pull
sudo -u fastapi /opt/myapi/venv/bin/pip install -r /opt/myapi/app/requirements.txt
sudo systemctl restart myapi.service

Quá trình khởi động lại chỉ mất khoảng một đến hai giây. Ngay sau đó, hãy theo dõi trực tiếp nhật ký hệ thống để chắc chắn phiên bản mới chạy ổn định:

sudo journalctl -u myapi.service -f

Khắc phục các sự cố thường gặp khi vận hành

  • Nginx báo lỗi 502 Bad Gateway: Tình trạng này xảy ra khi Nginx không thể kết nối tới Uvicorn. Hãy kiểm tra dịch vụ có đang chạy không bằng sudo systemctl status myapi.service, xác minh tiến trình đang lắng nghe cổng 8000 qua sudo ss -tlnp | grep 8000, đồng thời xem chi tiết lỗi trong tệp /var/log/nginx/error.log hoặc tham khảo cách xử lý sự cố máy chủ phản hồi lỗi 502 Bad Gateway.
  • Dịch vụ thoát với lỗi ModuleNotFoundError: Uvicorn không tìm thấy ứng dụng để import. Tham số app.main:app phụ thuộc vào WorkingDirectory, nên tệp /opt/myapi/app/main.py bắt buộc phải tồn tại và có khai báo biến app. Mọi gói thư viện cũng phải được cài đúng vào /opt/myapi/venv thay vì môi trường Python toàn cục.
  • Biến môi trường bị rỗng bên trong ứng dụng: Hãy rà soát lại đường dẫn ở dòng EnvironmentFile= xem đã chuẩn xác chưa và đảm bảo từng dòng dùng cú pháp KEY=value (không viết thêm từ khóa export). Sau khi sửa file unit hoặc file biến môi trường, bắt buộc phải chạy lại sudo systemctl daemon-reload và sudo systemctl restart myapi.service.
  • Đường dẫn chuyển hướng trỏ về http:// thay vì https://: Nguyên nhân do Uvicorn chưa tin cậy proxy header. Hãy đối chiếu lại tệp unit đã có đủ --proxy-headers --forwarded-allow-ips 127.0.0.1 và khối cấu hình Nginx đã thiết lập X-Forwarded-Proto hay chưa.
  • Yêu cầu bị timeout ở các endpoint xử lý chậm: Bạn có thể tăng giá trị proxy_read_timeout trong cấu hình Nginx. Tuy nhiên, với những tác vụ mất nhiều hơn vài giây xử lý, giải pháp đúng đắn là đưa chúng sang hàng đợi tác vụ nền (background task queue) thay vì giữ kết nối HTTP mở quá lâu.

Khi hoàn tất quy trình trên, bạn đã nắm trọn cách cài FastAPI trên VPS chuẩn chỉnh: ứng dụng vận hành dưới Uvicorn như một dịch vụ systemd được tăng cường bảo mật, tự động khởi chạy lại khi gặp sự cố và phục vụ qua kết nối HTTPS bởi Nginx với chứng chỉ tự gia hạn. Mô hình triển khai này cũng áp dụng linh hoạt cho mọi ứng dụng ASGI khác. Để mở rộng hệ thống bền vững hơn, bạn có thể tích hợp cơ sở dữ liệu PostgreSQL, chuyển tiếp nhật ký journal về máy chủ log tập trung và thiết lập công cụ giám sát endpoint /health nhằm nhận cảnh báo tức thì nếu API ngừng phản hồi.

Cần một VPS giá rẻ để bắt đầu?

Chọn cấu hình vừa đủ nhu cầu, ưu tiên chi phí dễ tiếp cận và khả năng quản trị riêng.

Xem bảng giá VPS

Lưu ý kỹ thuật: Các câu lệnh và thông số cấu hình trong bài viết chỉ mang tính chất tham khảo, có thể thay đổi tùy thuộc vào phiên bản hệ điều hành Ubuntu, bản cập nhật phần mềm Python, Nginx, Certbot cũng như môi trường máy chủ thực tế. Bạn nên sao lưu dữ liệu, kiểm tra kỹ các bước trên môi trường thử nghiệm và đánh giá đầy đủ rủi ro bảo mật trước khi áp dụng cho hệ thống production.

Chia sẻ: Facebook LinkedIn
Quay lại trang blog

Bài viết liên quan