FlashPanel

Deploy ứng dụng Node.js ​

Giả sử bạn có một ứng dụng Node.js (Express, Fastify, NestJS…) muốn chạy dưới domain api.domain.com, ứng dụng lắng nghe ở cổng 3000. Website trên FlashPanel đóng vai trò reverse proxy: nhận request từ domain rồi chuyển tới cổng 3000 của ứng dụng, còn PM2 giữ cho ứng dụng luôn chạy.

Yêu cầu ​

  • Máy chủ đã kết nối với FlashPanel
  • DNS của domain đã trỏ về IP máy chủ
  • Ứng dụng đọc cổng lắng nghe từ cấu hình (ví dụ biến môi trường PORT) hoặc lắng nghe cố định ở một cổng bạn biết trước

Bước 1: Cài đặt ứng dụng cần thiết ​

Vào trang quản lý máy chủ, bấm menu Ứng dụng, chọn tab Chưa cài đặt rồi cài NodeJS (chọn phiên bản Node.js phù hợp với ứng dụng) và PM2. Xem chi tiết tại Ứng dụng.

TIP

Nếu dự án dùng pnpm hoặc yarn, hãy cài thêm ứng dụng tương ứng trên trang Ứ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ụ: api.domain.com)
  3. Nhập Proxy Port: cổng mà ứng dụng Node.js 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 và lệnh 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. Cách này cho phép triển khai lại bằng một cú bấm ở trang Triển khai.
  • 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/api.domain.com.

Bước 4: Cài đặt 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/api.domain.com

# Cài dependencies cho môi trường production
npm install --omit=dev

# Nếu dự án viết bằng TypeScript hoặc cần build, cài đủ dependencies rồi build
# npm install
# npm run build

Nếu ứng dụng dùng file .env, tạo hoặc chỉnh sửa file này trong thư mục website (bằng Quản Lý File hoặc nano .env) và khai báo cổng khớp với Proxy Port:

properties
PORT=3000
NODE_ENV=production

Bước 5: Khởi chạy ứng dụng bằng PM2 ​

Cách A: Dùng trang PM2 (khuyến nghị) ​

  1. Vào trang quản lý máy chủ, bấm menu PM2, sau đó bấm nút Thêm Mới
  2. Ở ô Tên người dùng cách ly trang web, chọn người dùng sở hữu website (mặc định là flashpanel)
  3. Ở ô command (đã có sẵn tiền tố pm2 start), nhập đường dẫn đầy đủ tới file khởi chạy, tên process và thư mục làm việc, ví dụ: /home/flashpanel/api.domain.com/index.js --name my-api --cwd /home/flashpanel/api.domain.com
  4. Bấm Khởi động

Nếu ứng dụng khởi chạy bằng npm start, nhập command dạng: npm --name my-api --cwd /home/flashpanel/api.domain.com -- start

Cách B: Dùng SSH ​

Đăng nhập SSH bằng người dùng sở hữu website (hoặc dùng Terminal của website) và chạy:

bash
cd /home/flashpanel/api.domain.com
pm2 start index.js --name my-api

WARNING

Cổng ứng dụng lắng nghe phải khớp với Proxy Port của website. Nên cho ứng dụng lắng nghe trên 127.0.0.1 (hoặc localhost) thay vì 0.0.0.0 để ứng dụng chỉ nhận request qua website, không lộ trực tiếp ra Internet.

Lưu danh sách process PM2 ​

Để ứng dụng tự khởi động lại sau khi máy chủ reboot, đăng nhập SSH bằng người dùng sở hữu website và chạy:

bash
pm2 startup

Lệnh trên in ra một lệnh bắt đầu bằng sudo env PATH=.... Chạy lệnh đó với quyền root (ví dụ trong Terminal trên trang tổng quan của máy chủ; chỉ cần làm một lần), sau đó lưu danh sách process:

bash
pm2 save

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, bạn có thể tự động hóa các lần cập nhật bằng Deployment Script. 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ụ:

bash
cd /home/flashpanel/api.domain.com
git pull origin main
npm install --omit=dev
pm2 restart my-api

Kiểm tra kết quả ​

  1. Trên trang PM2, process my-api có trạng thái online
  2. Truy cập https://api.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 cài lại dependencies (nếu có thay đổi), rồi bấm nút Khởi động lại của process trên trang PM2, hoặc chạy pm2 restart my-api

Xử lý sự cố ​

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

  1. Bấm nút Xem Log của process trên trang PM2, hoặc chạy pm2 logs my-api
  2. Chạy thử trực tiếp trong thư mục website để xem lỗi: node index.js
  3. Kiểm tra cổng đã bị chương trình khác chiếm chưa: ss -tln | grep 3000

Lỗi 502 Bad Gateway ​

  1. Kiểm tra process đang chạy trên trang PM2 hoặc bằng lệnh pm2 status
  2. Đảm bảo cổng ứng dụng lắng nghe khớp với Proxy Port của website
  3. Xem thêm Lỗi 502 Bad Gateway

Ứng dụng không tự chạy lại sau khi máy chủ khởi động lại ​

Thực hiện lại phần Lưu danh sách process PM2 bằng đúng người dùng sở hữu website.