FlashPanel

Deploy ứng dụng ASP.NET ​

Giả sử bạn có một ứng dụng ASP.NET Core muốn chạy dưới domain domain.com. Ứng dụng chạy bằng Kestrel ở cổng 3000, được quản lý bởi một Systemd Service, còn website trên FlashPanel chuyển request từ domain tới cổng 3000.

Yêu cầu ​

  • Máy chủ đã kết nối với FlashPanel
  • DNS của domain đã trỏ về IP máy chủ

Bước 1: Cài đặt .NET SDK ​

Vào trang quản lý máy chủ, bấm menu Ứng dụng, chọn tab Chưa cài đặt, tìm ASP.NET Core rồi bấm Cài đặt. Chọn Phiên bản trùng với phiên bản .NET của dự án (ví dụ dự án nhắm net8.0 thì chọn 8.0). Xem chi tiết tại Ứng dụng.

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ụ: domain.com)
  3. Nhập Proxy Port: cổng ứng dụng sẽ lắng nghe, ví dụ 3000
  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/domain.com.

Bước 4: Build và publish ​

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/domain.com

# Cập nhật database (chỉ khi dùng Entity Framework Core migration)
dotnet ef database update

# Build và publish bản Release vào thư mục publish
dotnet publish -c Release -o publish

Sau lệnh trên, file chạy chính nằm tại publish/<TênDựÁn>.dll, ví dụ publish/domain_com.dll.

TIP

Lệnh dotnet ef database update chỉ cần khi ứng dụng dùng Entity Framework Core và đã cài công cụ dotnet-ef (dotnet tool install --global dotnet-ef). Bỏ qua lệnh này nếu ứng dụng không dùng database migration.

Bước 5: Tạo Service cho ứng dụng ​

Dùng tính năng quản lý Systemd Service để ứng dụng chạy nền và tự khởi động lại:

  1. Vào trang quản lý máy chủ, bấm menu Service, sau đó bấm Tạo Service
  2. Nhập Tên, ví dụ domain_com (ngắn gọn, không chứa ký tự đặc biệt)
  3. Thay nội dung trong trình soạn thảo bằng nội dung sau:
ini
[Unit]
Description=ASP.NET - domain.com

[Service]
WorkingDirectory=/home/flashpanel/domain.com/publish
ExecStart=/usr/bin/dotnet /home/flashpanel/domain.com/publish/domain_com.dll --urls "http://127.0.0.1:3000"
Restart=always
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=domain_com
User=flashpanel
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false
StandardOutput=append:/var/log/services/domain_com.log
StandardError=append:/var/log/services/domain_com-error.log

[Install]
WantedBy=multi-user.target
  1. Giữ chọn Khởi động cùng với hệ thống để service tự chạy khi máy chủ reboot
  2. Bấm Tạo Service. Service được tạo và khởi động ngay

WARNING

  • Thay 3000 bằng Proxy Port của website. 127.0.0.1 giúp ứng dụng chỉ nhận request qua website, không lộ cổng ra Internet
  • Thay domain.com bằng tên miền của website và domain_com.dll bằng tên file dll của dự án
  • User là người dùng sở hữu website (không dùng root)
  • Linux phân biệt chữ hoa chữ thường trong tên file. Với ASPNETCORE_ENVIRONMENT=Production, ứng dụng đọc file appsettings.Production.json, không phải appsettings.production.json
  • Tên biến môi trường không hỗ trợ dấu hai chấm (:). Dùng hai dấu gạch dưới (__) thay thế, ví dụ khóa ConnectionStrings:DefaultConnection được khai báo là:
    ini
    Environment=ConnectionStrings__DefaultConnection={Connection String}

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.

Kiểm tra kết quả ​

  1. Trên trang Service, service domain_com có trạng thái đang hoạt động
  2. Truy cập https://domain.com và kiểm tra ứng dụng phản hồi đúng

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

  1. Cập nhật mã nguồn (bấm Triển khai ngay trong menu Triển khai nếu cài từ Git, hoặc tải bản mới lên bằng Quản Lý File)
  2. Mở Terminal của website và chạy lại dotnet publish -c Release -o publish
  3. Trên trang Service, bấm nút Khởi động lại của service domain_com

TIP

Nếu cài mã nguồn từ Git, bạn có thể thêm dotnet publish -c Release -o publish vào Deployment Script để không phải chạy tay ở bước 2. Deployment Script chạy bằng người dùng sở hữu website nên không khởi động lại được Systemd Service; bạn vẫn cần bấm Khởi động lại trên trang Service.

Xử lý sự cố ​

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

  1. Trên trang Service, bấm Xem Log lỗi của service domain_com
  2. Chạy thử thủ công trong thư mục website để xem lỗi: dotnet publish/domain_com.dll --urls "http://127.0.0.1:3000"
  3. Kiểm tra đường dẫn file dll trong ExecStart có đúng không

Lỗi 502 Bad Gateway ​

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

Lỗi You must install or update .NET to run this application ​

Phiên bản .NET đã cài không khớp với phiên bản mà dự án nhắm tới. Chạy dotnet --list-runtimes để xem các phiên bản đang có, sau đó cài đúng phiên bản trên trang Ứng dụng.