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 […]
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.

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 |

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ó.

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_domainlà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.
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.

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ệnhnproc).--proxy-headersvà--forwarded-allow-ips 127.0.0.1: Cho phép Uvicorn tin cậy hai headerX-Forwarded-ForvàX-Forwarded-Protodo 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ứchttps.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 quasudo ss -tlnp | grep 8000, đồng thời xem chi tiết lỗi trong tệp/var/log/nginx/error.loghoặ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:appphụ thuộc vàoWorkingDirectory, nên tệp/opt/myapi/app/main.pybắt buộc phải tồn tại và có khai báo biếnapp. Mọi gói thư viện cũng phải được cài đúng vào/opt/myapi/venvthay 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ápKEY=value(không viết thêm từ khóaexport). Sau khi sửa file unit hoặc file biến môi trường, bắt buộc phải chạy lạisudo systemctl daemon-reloadvà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.1và khối cấu hình Nginx đã thiết lậpX-Forwarded-Protohay 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_timeouttrong 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.
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.



