FlashPanel

Appearance

Deploy ứng dụng Next.js ​

Giả sử bạn có một ứng dụng Next.js muốn deploy dưới domain app.domain.com.

Yêu cầu ​

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

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

Đảm bảo NodeJS và PM2 được cài đặt trên máy chủ. Xem hướng dẫn cài đặt ứng dụng tại Quản lý ứng dụng.

WARNING

Nếu bạn sử dụng pnpm hoặc yarn làm package manager, hãy cài đặt ứng dụng tương ứng qua trang Quản lý ứ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ụ: app.domain.com)
  3. Nhập Proxy Port: port mà ứng dụng Next.js của bạn chạy (mặc định là 3000)
  4. Bấm Tạo trang web

Bước 3: Cài đặt mã nguồn ​

Cài đặt mã nguồn cho trang web từ Git hoặc tự tải lên. Để mở trang này, vào trang quản lý trang web và bấm menu Cài đặt Mã nguồn ở thanh bên. Xem hướng dẫn chi tiết tại Cài đặt mã nguồn.

Bước 4: Build ứng dụng ​

Mở terminal máy chủ (qua SSH hoặc tính năng terminal) và di chuyển đến thư mục website để cài đặt dependencies và build ứng dụng:

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

# Cài đặt dependencies
npm install

# Build ứng dụng production
npm run build

TIP

Thay app.domain.com bằng domain thực tế của bạn.

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

Cách A: Sử dụng PM2 Dashboard (Khuyến nghị) ​

Nếu đã cài đặt ứng dụng PM2, bạn có thể dùng trang PM2 trong trang quản lý máy chủ:

  1. Bấm nút Thêm Mới
  2. Ở ô Tên người dùng cách ly trang web, chọn user sở hữu website (mặc định là flashpanel)
  3. Nhập command: npm --name my-nextjs-app --cwd /home/flashpanel/app.domain.com -- start -- -p 3000
  4. Bấm Khởi động

Cách B: Sử dụng SSH ​

Bạn cũng có thể khởi chạy ứng dụng thủ công qua SSH:

bash
cd /home/flashpanel/app.domain.com
pm2 start npm --name my-nextjs-app -- start -- -p 3000

WARNING

Đảm bảo port (3000) khớp với Proxy Port bạn đã cấu hình khi tạo trang web.

Lưu danh sách process PM2 ​

Để ứng dụng tự động khởi động lại sau khi server reboot, đăng nhập SSH bằng user 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 (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) ​

Để tự động hóa các lần deploy sau, bạn có thể cấu hình Deployment Script cho trang web. Một deployment script Next.js điển hình:

bash
cd /home/flashpanel/app.domain.com
git pull origin main
npm install
npm run build
pm2 restart my-nextjs-app

Kiểm tra kết quả ​

  1. Trên trang PM2, process my-nextjs-app có trạng thái online
  2. Truy cập https://app.domain.com và kiểm tra trang hiển thị đúng, kể cả hình ảnh và file tĩnh

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

Khi push code mới, bạn cần rebuild và restart:

  • Nếu đã cấu hình Deployment Script, chỉ cần bấm Triển khai ngay trong menu Triển khai của trang quản lý trang web
  • Nếu dùng trang PM2, rebuild thủ công rồi bấm nút Khởi động lại của process tương ứng
  • Hoặc chạy qua SSH:
bash
cd /home/flashpanel/app.domain.com
git pull origin main
npm install
npm run build
pm2 restart my-nextjs-app

Biến môi trường ​

Next.js sử dụng file .env để cấu hình biến môi trường. Tạo hoặc chỉnh sửa file .env trong thư mục website:

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

Thêm các biến môi trường:

properties
DATABASE_URL=mysql://user:password@localhost:3306/mydb
NEXT_PUBLIC_API_URL=https://api.domain.com
NODE_ENV=production

WARNING

Sau khi thay đổi biến môi trường, bạn cần rebuild (npm run build) và restart ứng dụng để thay đổi có hiệu lực. Các biến có tiền tố NEXT_PUBLIC_ được nhúng vào lúc build.

Xử lý sự cố ​

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

  1. Kiểm tra log PM2: dùng nút Xem Log trên trang PM2, hoặc chạy pm2 logs my-nextjs-app
  2. Xác minh build thành công: npm run build
  3. Kiểm tra port đã bị sử dụng chưa: sudo lsof -i :3000

Lỗi 502 Bad Gateway ​

  1. Xác minh ứng dụng đang chạy: kiểm tra trang PM2 hoặc chạy pm2 status
  2. Đảm bảo port ứng dụng khớp với Proxy Port đã cấu hình cho trang web
  3. Kiểm tra log ứng dụng để xem lỗi khởi động

Hình ảnh không hiển thị ​

Nếu hình ảnh hoặc các tệp tĩnh của Next.js không hiển thị đúng, bạn có thể cần thêm cấu hình Nginx tùy chỉnh (đoạn cấu hình dưới đây chỉ dùng cho Nginx).

  1. Vào trang quản lý trang web
  2. Bấm menu Nginx ở thanh bên
  3. Bấm nút Thêm Cấu Hình, ở mục Vị trí chọn Trong Block Server
  4. Thêm đoạn cấu hình sau (thay app.domain.com bằng domain thực tế của bạn):
nginx
location ^~ /_next/static {
    alias /home/flashpanel/app.domain.com/.next/static;
}
  1. Bấm Lưu, sau đó bấm nút Đồng bộ ở phía trên để áp dụng thay đổi.