FlashPanel

Deploy ứng dụng Python (Flask) ​

Giả sử bạn có một ứng dụng Flask muốn chạy dưới domain app.domain.com. Ứng dụng được chạy bằng Gunicorn (HTTP server WSGI dùng cho production, xử lý đồng thời tốt hơn server tích hợp sẵn của Flask) ở cổng 8000, Supervisor giữ cho Gunicorn luôn chạy, còn website trên FlashPanel chuyển request từ domain tới cổng 8000.

Yêu cầu ​

  • Máy chủ đã kết nối với FlashPanel
  • DNS của domain đã trỏ về IP máy chủ
  • Mã nguồn có file requirements.txt liệt kê các gói cần cài

INFO

FlashPanel cài sẵn python3 và pip khi kết nối máy chủ, nên trang Ứng dụng không có mục Python riêng.

Bước 1: Cài đặt Python venv ​

Mở Terminal trên trang tổng quan của máy chủ (đăng nhập bằng root) và chạy lệnh sau. Bạn chỉ cần làm một lần cho mỗi máy chủ:

bash
apt install -y python3-venv

Bước 2: Tạo trang web ​

  1. Vào trang quản lý máy chủ, bấm menu Website ở thanh bên, sau đó bấm nút Tạo website
  2. Nhập Tên miền (ví dụ: app.domain.com)
  3. Nhập Proxy Port: 8000 (cổng Gunicorn sẽ lắng nghe)
  4. Bấm Tạo trang web

TIP

Nếu bật Cách ly trang web, website sẽ chạy bằng một người dùng Linux riêng. Khi đó hãy thay flashpanel trong các đường dẫn bên dưới bằng tên người dùng cách ly của website.

Bước 3: Đưa mã nguồn lên máy chủ ​

Chọn một trong hai cách:

  • Từ Git (khuyến nghị): vào trang quản lý website, bấm menu Cài đặt Mã nguồn và cài repository. Xem hướng dẫn tại Cài đặt mã nguồn.
  • Tự tải lên: mở Quản Lý File trên trang tổng quan của website và tải mã nguồn vào thư mục website. Xem Quản lý file.

Mã nguồn nằm trong thư mục /home/flashpanel/app.domain.com.

Bước 4: Tạo môi trường ảo và cài dependencies ​

Mở Terminal trên trang tổng quan của website (terminal đăng nhập bằng người dùng sở hữu website và mở sẵn thư mục website), sau đó chạy:

bash
cd /home/flashpanel/app.domain.com

# Tạo và kích hoạt môi trường ảo
python3 -m venv venv
source venv/bin/activate

# Cài dependencies của ứng dụng và Gunicorn
pip install -r requirements.txt
pip install gunicorn

Chạy thử để chắc chắn ứng dụng hoạt động, sau đó nhấn Ctrl+C để dừng:

bash
gunicorn --bind 127.0.0.1:8000 app:app

Trong app:app, phần trước dấu : là tên file Python chứa ứng dụng (app.py), phần sau là tên biến ứng dụng Flask trong file đó (app = Flask(__name__)). Hãy đổi cho khớp với dự án của bạn. Với Django, dùng dạng ten_du_an.wsgi:application.

TIP

--bind 127.0.0.1:8000 cho Gunicorn chỉ lắng nghe trên máy chủ. Request từ Internet đi qua website (domain), cổng 8000 không bị lộ ra ngoài. Không dùng 0.0.0.0 trừ khi bạn thật sự cần truy cập trực tiếp qua IP và cổng.

Bước 5: Chạy Gunicorn nền bằng Supervisor ​

Dùng Supervisor để Gunicorn chạy nền, tự khởi động lại khi bị dừng và khi máy chủ reboot:

  1. Vào trang quản lý máy chủ, bấm menu Supervisor, sau đó bấm nút Thêm mới
  2. Trong hộp thoại Thêm mới Supervisor, điền:
    • Description (Optional): ví dụ app.domain.com gunicorn
    • Command: /home/flashpanel/app.domain.com/venv/bin/gunicorn --workers 3 --bind 127.0.0.1:8000 app:app
    • User: người dùng sở hữu website (mặc định là flashpanel)
    • Directory (Optional): /home/flashpanel/app.domain.com
    • Giữ nguyên Number Processes là 1 (Gunicorn tự quản lý các worker)
  3. Bấm Lưu

Ghi nhớ giá trị ở cột ID của tiến trình vừa tạo (ví dụ 5), bạn sẽ cần nó khi khởi động lại tiến trình bằng lệnh.

TIP

--workers 3 là số worker process Gunicorn chạy song song. Giá trị thường dùng là 2 × số nhân CPU + 1.

Bước 6: Cài đặt SSL ​

Vào trang quản lý website, bấm menu SSL và cài chứng chỉ cho domain. Xem hướng dẫn tại SSL.

Bước 7: Thiết lập Deployment Script (tùy chọn) ​

Nếu mã nguồn được cài từ Git, vào trang quản lý website, bấm menu Triển khai, sửa phần Kịch bản triển khai rồi bấm Cập nhật. Ví dụ (thay 5 bằng ID của tiến trình Supervisor):

bash
cd /home/flashpanel/app.domain.com
git pull origin main
venv/bin/pip install -r requirements.txt
sudo supervisorctl restart daemon-5:*

WARNING

Lệnh sudo supervisorctl chỉ chạy được khi website dùng người dùng mặc định flashpanel. Với website bật Cách ly trang web, hãy bỏ dòng cuối và khởi động lại tiến trình trên trang Supervisor sau mỗi lần triển khai.

Kiểm tra kết quả ​

  1. Trên trang Supervisor, tiến trình vừa tạo có trạng thái đang chạy
  2. Truy cập https://app.domain.com và kiểm tra ứng dụng phản hồi đúng

Cập nhật ứng dụng ​

  • Nếu đã cấu hình Deployment Script, bấm Triển khai ngay trong menu Triển khai của website
  • Nếu tải mã nguồn thủ công, sau khi tải bản mới lên hãy chạy lại venv/bin/pip install -r requirements.txt (nếu dependencies thay đổi), rồi trên trang Supervisor bấm biểu tượng mũi tên ở cuối dòng của tiến trình và chọn Khởi động lại

Xử lý sự cố ​

Ứng dụng không khởi chạy được ​

  1. Trên trang Supervisor, mở menu thao tác của tiến trình và chọn Xem nhật ký
  2. Kích hoạt môi trường ảo và chạy thử thủ công trong thư mục website để xem lỗi: source venv/bin/activate && gunicorn --bind 127.0.0.1:8000 app:app
  3. Kiểm tra đường dẫn tới venv/bin/gunicorn và phần app:app trong Command có đúng không

Lỗi 502 Bad Gateway ​

  1. Kiểm tra tiến trình Supervisor đang chạy
  2. Đảm bảo cổng trong --bind khớp với Proxy Port của website
  3. Xem thêm Lỗi 502 Bad Gateway

Lỗi ModuleNotFoundError ​

Gói chưa được cài vào môi trường ảo. Chạy venv/bin/pip install -r requirements.txt trong thư mục website rồi khởi động lại tiến trình.