Cách triển khai ứng dụng Node.js trên VPS Ubuntu từ A đến Z

Đưa ứng dụng Node.js lên VPS giúp bạn chủ động hơn trong việc quản lý môi trường, cấu hình và tài nguyên máy chủ. Tuy nhiên, để ứng dụng chạy ổn định và truy cập được bằng tên miền, bạn cần thực hiện nhiều bước ngoài việc cài Node.js. Bài viết này hướng dẫn quy trình triển khai Node.js trên VPS Ubuntu từ khâu chuẩn bị, cấu hình dịch vụ đến kiểm tra và cập nhật ứng dụng.

Các ví dụ bên dưới áp dụng cho ứng dụng Node.js thông thường trên Ubuntu. Tên miền, thư mục dự án, cổng ứng dụng và tên tệp có thể cần điều chỉnh theo dự án thực tế.

1. Chuẩn bị VPS và thông tin cần thiết

Trước khi bắt đầu, bạn cần có một VPS cài Ubuntu, quyền truy cập SSH và mã nguồn ứng dụng Node.js. Nếu muốn người dùng truy cập bằng tên miền, hãy chuẩn bị tên miền và quyền quản lý DNS. Với dự án cần cơ sở dữ liệu, bạn cũng cần thông tin kết nối tương ứng.

Đăng nhập vào VPS bằng SSH:

ssh root@DIA_CHI_IP_VPS

Thay DIA_CHI_IP_VPS bằng địa chỉ IP máy chủ. Sau khi đăng nhập, cập nhật các gói hệ thống:

apt update && apt upgrade -y

Bạn có thể tạo một tài khoản riêng để quản lý ứng dụng thay vì chạy tiến trình bằng root:

adduser deploy
usermod -aG sudo deploy

Đăng nhập bằng tài khoản này ở các bước tiếp theo. Nếu bật tường lửa UFW, hãy cho phép SSH trước khi kích hoạt để tránh tự khóa quyền truy cập:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

Không cần mở cổng ứng dụng Node.js ra Internet nếu Nginx sẽ tiếp nhận kết nối bên ngoài và chuyển tiếp đến ứng dụng qua localhost.

2. Cài Node.js trên Ubuntu VPS

Ubuntu có thể cung cấp phiên bản Node.js khác với phiên bản dự án yêu cầu. Trước khi cài, hãy kiểm tra trường engines trong package.json hoặc tài liệu của ứng dụng, sau đó chọn phiên bản LTS tương thích.

Ví dụ dưới đây cài Node.js 22 từ kho NodeSource. Hãy xác nhận phiên bản này phù hợp với ứng dụng trước khi chạy lệnh:

sudo apt install -y curl ca-certificates
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Kiểm tra phiên bản Node.js và npm:

node -v
npm -v

Nếu dự án dùng Yarn hoặc pnpm, hãy cài và sử dụng đúng trình quản lý gói được chỉ định trong dự án. Khi triển khai, ưu tiên dùng tệp khóa như package-lock.json, yarn.lock hoặc pnpm-lock.yaml để các lần cài phụ thuộc nhất quán hơn.

3. Đưa mã nguồn ứng dụng lên VPS

Tạo thư mục dành cho ứng dụng và cấp quyền cho tài khoản triển khai:

sudo mkdir -p /var/www/myapp
sudo chown -R deploy:deploy /var/www/myapp

Có thể đưa mã nguồn lên máy chủ bằng Git:

cd /var/www/myapp
git clone DIA_CHI_REPOSITORY .

Thay DIA_CHI_REPOSITORY bằng địa chỉ repository của bạn. Nếu repository riêng tư, hãy cấu hình xác thực an toàn; tránh đặt mật khẩu hoặc token trực tiếp trong lịch sử lệnh. Bạn cũng có thể tải tệp lên bằng SFTP.

Kiểm tra cấu trúc dự án và đọc hướng dẫn triển khai của ứng dụng. Thông thường, tệp package.json chứa các lệnh trong mục scripts, chẳng hạn start hoặc build. Cài các gói phụ thuộc từ thư mục dự án:

cd /var/www/myapp
npm ci

Nếu dự án có bước biên dịch, chạy lệnh build được khai báo trong package.json, ví dụ:

npm run build

Không phải ứng dụng nào cũng cần build. Với ứng dụng cần biên dịch, hãy hoàn tất bước này trước khi chuyển sang chế độ cài phụ thuộc production. Nếu build cần các gói phát triển, không nên xóa chúng trước khi build xong.

4. Cấu hình biến môi trường và chạy thử

Thông tin nhạy cảm như khóa API, mật khẩu cơ sở dữ liệu và cấu hình môi trường nên được lưu bên ngoài mã nguồn. Tạo tệp môi trường có quyền truy cập giới hạn:

nano /var/www/myapp/.env

Ví dụ nội dung:

NODE_ENV=production
PORT=3000
DATABASE_URL=thay_bang_chuoi_ket_noi

Định dạng biến môi trường tùy theo ứng dụng. Không đưa tệp .env lên repository công khai; hãy kiểm tra .gitignore và chỉ cấp quyền đọc cần thiết:

chmod 600 /var/www/myapp/.env

Ứng dụng cần đọc biến PORT và lắng nghe trên 127.0.0.1 để Nginx có thể chuyển tiếp yêu cầu nội bộ. Cách triển khai cụ thể phụ thuộc framework; hãy xác nhận ứng dụng không chỉ chạy trên môi trường phát triển. Khởi chạy thử theo script của dự án, sau đó kiểm tra phản hồi tại máy chủ:

curl http://127.0.0.1:3000

Nếu lệnh trả về nội dung phù hợp, ứng dụng đang nhận yêu cầu trên cổng nội bộ. Dừng tiến trình chạy thử trước khi cấu hình dịch vụ nền.

5. Tạo dịch vụ systemd để ứng dụng tự chạy

Chạy ứng dụng trong phiên SSH không phù hợp cho vận hành lâu dài: tiến trình có thể dừng khi phiên kết thúc. Tạo dịch vụ systemd để khởi động ứng dụng cùng hệ thống và thuận tiện xem trạng thái.

Mở tệp cấu hình:

sudo nano /etc/systemd/system/myapp.service

Thêm nội dung sau, điều chỉnh đường dẫn và lệnh chạy theo dự án:

[Unit]
Description=Node.js application
After=network.target

[Service]
Type=simple
User=deploy
WorkingDirectory=/var/www/myapp
EnvironmentFile=/var/www/myapp/.env
ExecStart=/usr/bin/node /var/www/myapp/server.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Ví dụ trên giả định ứng dụng khởi động từ server.js. Nếu dự án cần chạy bằng một script khác, hãy dùng lệnh khởi chạy phù hợp và kiểm tra đường dẫn Node.js bằng which node. Tải lại cấu hình rồi bật dịch vụ:

sudo systemctl daemon-reload
sudo systemctl enable --now myapp
sudo systemctl status myapp

Để xem nhật ký nếu ứng dụng không khởi động:

sudo journalctl -u myapp -n 100 --no-pager

6. Cài Nginx làm reverse proxy

Nginx nhận kết nối HTTP từ bên ngoài và chuyển tiếp đến ứng dụng Node.js đang chạy trên localhost. Cài Nginx:

sudo apt install -y nginx

Tạo cấu hình cho tên miền, thay example.com bằng tên miền của bạn:

sudo nano /etc/nginx/sites-available/myapp

Dán cấu hình cơ bản:

server {
    listen 80;
    server_name example.com www.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Kích hoạt cấu hình và kiểm tra cú pháp trước khi tải lại Nginx:

sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/myapp
sudo nginx -t
sudo systemctl reload nginx

Trỏ bản ghi DNS của tên miền về IP VPS, sau đó thử truy cập bằng trình duyệt. Nếu ứng dụng dùng WebSocket, bạn có thể cần bổ sung các header nâng cấp kết nối theo hướng dẫn của framework.

7. Bật HTTPS và kiểm tra toàn bộ hệ thống

Sau khi DNS đã trỏ về VPS và tên miền truy cập được qua HTTP, bạn có thể cài Certbot để xin chứng chỉ TLS từ Let's Encrypt:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d www.example.com

Làm theo hướng dẫn trên màn hình để hoàn tất. Kiểm tra ứng dụng qua HTTPS và bảo đảm cả trang chính lẫn các chức năng cần thiết hoạt động bình thường.

8. Cập nhật ứng dụng và xử lý lỗi thường gặp

Khi phát hành phiên bản mới, quy trình cơ bản là lấy mã nguồn, cài lại phụ thuộc, build nếu cần và khởi động lại dịch vụ:

cd /var/www/myapp
git pull
npm ci
npm run build
sudo systemctl restart myapp
sudo systemctl status myapp

Bỏ qua npm run build nếu dự án không có bước này. Nếu dự án yêu cầu chỉ cài các gói production, hãy thực hiện đúng hướng dẫn triển khai sau khi hoàn tất build.

Một số lỗi thường gặp gồm:

• Ứng dụng không khởi động: xem journalctl, kiểm tra đường dẫn ExecStart, quyền thư mục và biến môi trường.
• Tên miền không truy cập được: kiểm tra DNS, trạng thái Nginx và tường lửa; dùng sudo nginx -t để tìm lỗi cú pháp.
• Lỗi kết nối cổng: xác nhận ứng dụng lắng nghe đúng cổng mà Nginx chuyển tiếp, chẳng hạn 3000.
• Chạy được trong SSH nhưng không chạy bằng systemd: kiểm tra người dùng dịch vụ, thư mục làm việc và các biến môi trường; dịch vụ không tự nhận cấu hình của phiên shell.

Kết luận

Để triển khai Node.js trên VPS thành công, bạn cần cài đúng phiên bản Node.js, cấu hình mã nguồn và biến môi trường, rồi dùng systemd quản lý tiến trình. Nginx giúp tiếp nhận kết nối web, còn HTTPS bảo vệ dữ liệu trao đổi với người dùng. Sau khi đưa ứng dụng lên máy chủ, hãy theo dõi nhật ký, cập nhật phần mềm và sao lưu dữ liệu định kỳ.

Nếu đang tìm môi trường để tự triển khai, bạn có thể tham khảo các gói VPS AMD EPYC Gen 3 hoặc VPS Platinum Gen 2 của VibeVPS, có giá từ 81.000đ/tháng. Hãy chọn cấu hình phù hợp với yêu cầu ứng dụng và tài nguyên dự kiến.