Node.js App
HƯỚNG DẪN NODE.JS APP TRÊN VPANEL
Trang Node.js App giúp bạn triển khai và quản lý các tiến trình Node.js dài hạn (Express API, Next.js server, Fastify…) ngay trên account hosting. vPanel gắn mỗi app với một domain, giám sát tiến trình (auto-restart khi crash), và expose ra ngoài qua OpenLiteSpeed dưới dạng reverse proxy.
1. Truy cập Node.js App
Đăng nhập User Panel cổng :2083. Ở thanh bên, chọn Node.js App trong nhóm Software.
Các cột trong bảng
| Cột | Mô tả |
|---|---|
| Name | Tên hiển thị bạn đặt cho app. |
| Domain | Domain (hoặc prefix path) hứng traffic. |
| Node Version | Runtime Node đã pin cho app. |
| Port | Cổng nội bộ app lắng nghe. |
| Status | Running, Stopped, Errored. |
| Actions | Start / Stop / Restart, Edit, Delete, Logs. |
2. Tạo App
Nhấn Create App.
Trường cần nhập
| Trường | Mô tả |
|---|---|
| App Name | Nhãn thân thiện, VD: api-prod. Dùng cho log và tên service. |
| Domain | Domain phía ngoài. https://api.example.com/… sẽ được forward vào app. |
| Path Prefix | (Tuỳ chọn) Gắn dưới subpath (/api) khi share domain với site PHP. |
| Node Version | Chọn từ các phiên bản đã cài (18.x, 20.x, 22.x…). |
| Application Root | Đường dẫn tuyệt đối tới thư mục code, phải nằm trong home dir. |
| Entry Point | Script khởi chạy — server.js, dist/main.js… |
| Port | Cổng nội bộ. vPanel gợi ý cổng còn trống. |
| Start Command | (Tuỳ chọn) Ghi đè node <entry> — VD npm start hoặc node --enable-source-maps dist/main.js. |
Nhấn Create. vPanel tạo systemd user service, khởi tạo .env và chạy app. App hiện lên bảng khi tiến trình đã confirm listen.
3. Chỉnh sửa App
Nhấn Edit trên dòng cần sửa.
Mọi trường trong form Create đều sửa được. Một số thay đổi (Node version, entry point) sẽ auto restart khi bạn nhấn Save.
4. Biến môi trường
Kéo tới mục Environment Variables trong form chỉnh sửa.
Biến môi trường là nơi an toàn nhất để lưu secret (mật khẩu DB, API key) — không lộ ra code và chỉ tiến trình app đọc được.
| Cột | Mô tả |
|---|---|
| Key | Tên viết hoa (VD: DATABASE_URL, JWT_SECRET). |
| Value | Giá trị. Nhấn biểu tượng mắt để hiện/ẩn. |
| Actions | Delete để xoá. |
Nhấn Add Variable để thêm dòng mới, rồi Save. vPanel cập nhật Environment= trong systemd unit và restart service để load giá trị mới.
Mẹo:
NODE_ENV=productionlà mặc định thông minh — nhiều framework bật cache và tắt dev tooling dựa trên biến này.
5. Start / Stop / Restart
Dùng các hành động trên dòng để điều khiển tiến trình:
- Start — chạy app đang stop.
- Stop — gửi SIGTERM (graceful), SIGKILL sau 30 giây.
- Restart — stop + start liền mạch. Dùng sau khi deploy code mới.
Thao tác chạy nền dưới dạng background task; dòng hiển thị spinner cho tới khi trạng thái ổn định.
6. Xem log
Nhấn Logs để mở live-tail viewer, xem cả stdout và stderr. Dùng để debug crash, xem log request, hoặc kiểm tra app boot đúng env.
7. Xử lý sự cố
Status kẹt ở Errored
- Nguyên nhân: Script entry thoát ngay (thiếu dependency, syntax error).
- Cách xử lý: Mở Logs, đọc vài dòng cuối, sửa code, nhấn Restart.
Domain trả 502 Bad Gateway
- Nguyên nhân: App crash hoặc port không khớp với port OLS proxy tới.
- Cách xử lý: Kiểm tra app Running, so cổng trong app details với
listen()thực tế.
Đổi env var không hiệu lực
- Nguyên nhân: Đã save nhưng chưa restart, hoặc code đọc file
.envchứ không đọcprocess.env. - Cách xử lý: Nhấn Restart. Nếu app đọc
.env, sửa file đó trong app root và restart.
"Port already in use" khi create
- Nguyên nhân: Có app khác đang listen cổng đó.
- Cách xử lý: Chọn cổng khác — gợi ý của vPanel luôn là cổng trống.
Chúc bạn quản trị Server an toàn và hiệu quả!