Hướng dẫn Debug Node.js trong Docker và Kubernetes mà không cần khởi động lại

Node.js là một nền tảng phổ biến cho các ứng dụng web và dịch vụ backend, nhưng việc debug Node.js trong môi trường container hóa như Docker hoặc Kubernetes lại không đơn giản. Bạn không thể SSH vào container hoặc dễ dàng khởi động lại với tùy chọn --inspect. Bài viết này giới thiệu node-loop-detective v1.3.0 — một công cụ hữu ích giúp bạn có thể kết nối từ xa đến trình debug Node.js mà không cần phải restart hoặc deploy lại ứng dụng.

Thách thức của việc debug từ xa trong container

Node.js tích hợp trình debug dựa trên giao thức V8 Inspector và Chrome DevTools Protocol (CDP). Khi chạy Node.js với --inspect, một WebSocket được mở trên 127.0.0.1:9229, chỉ cho phép truy cập từ máy chạy Node.js. Đây là một tính năng bảo mật quan trọng vì giao thức CDP không có cơ chế xác thực — nếu mở cổng ngoài, ai cũng có thể chạy mã tùy ý trong tiến trình Node.js.

Trong môi trường container, "máy chạy Node.js" chính là container đó, còn laptop hoặc máy của bạn thì bên ngoài, không thể truy cập trực tiếp cổng debug.

Giải pháp 1: Docker với mở cổng Inspector

Cách đơn giản nhất là chạy Node.js với --inspect=0.0.0.0:9229 để mở cổng trên tất cả các giao diện mạng, đồng thời map port trong docker:

docker run -p 9229:9229 my-app node --inspect=0.0.0.0:9229 app.js

Sau đó, từ máy chủ bạn chạy lệnh:

loop-detective --host <docker-host-ip> --port 9229 -d 30

Nếu Docker chạy local, IP có thể là 127.0.0.1 hoặc host.docker.internal.

Docker Compose ví dụ

services:
  api:
    build: .
    command: node --inspect=0.0.0.0:9229 app.js
    ports:
      - "9229:9229"
      - "3000:3000"

Chạy lệnh:

loop-detective --host localhost --port 9229

Nếu container đang chạy không có --inspect

Bạn vẫn có thể kích hoạt inspector runtime bằng cách gửi tín hiệu SIGUSR1 tới tiến trình Node.js:

docker exec my-container pgrep -f "node"
docker exec my-container kill -SIGUSR1 1

Inspector sẽ chỉ mở trên 127.0.0.1 trong container, không thể truy cập bên ngoài. Có hai cách giải quyết:

• Chạy loop-detective trực tiếp trong container:

docker exec -it my-container npx loop-detective 1

• Hoặc dùng socat để chuyển tiếp cổng:

docker exec -d my-container socat TCP-LISTEN:9230,fork TCP:127.0.0.1:9229

Sau đó kết nối từ bên ngoài qua cổng 9230.

Giải pháp 2: Kubernetes

Kubernetes có lớp mạng riêng biệt, các pods thường không thể truy cập trực tiếp từ máy ngoài.

Dùng kubectl port-forward

Cách đơn giản và an toàn nhất:

kubectl port-forward pod/my-app-pod-abc123 9229:9229
loop-detective --port 9229 -d 30

Khi port được forward về localhost, bạn không cần chỉ định --host.

Truy cập trực tiếp pod IP

Nếu mạng của bạn cho phép truy cập IP pod (ví dụ trong VPC hoặc qua VPN):

POD_IP=$(kubectl get pod my-app-pod -o jsonpath='{.status.podIP}')
loop-detective --host $POD_IP --port 9229

Kích hoạt Inspector trên pod đang chạy

Nếu pod chưa chạy với --inspect, bạn vẫn có thể bật inspector với SIGUSR1:

kubectl exec my-app-pod -- pgrep -f "node"
kubectl exec my-app-pod -- kill -SIGUSR1 1
kubectl port-forward my-app-pod 9229:9229 &
loop-detective --port 9229

Đoạn Helm Chart cấu hình inspector

Bạn có thể thêm vào Helm để bật inspector trong môi trường staging/debug:

containers:
- name: api
  command: ["node"]
  args: ["--inspect=0.0.0.0:9229", "app.js"]
  ports:
    - containerPort: 9229
      name: inspector
      protocol: TCP

Lưu ý: Không dùng cấu hình này trong production trừ khi có chính sách mạng hạn chế truy cập vào cổng inspector.

Giải pháp 3: Server truyền thống

Với VM hoặc máy chủ vật lý, SSH tunnel là cách an toàn nhất:

ssh -L 9229:127.0.0.1:9229 user@remote-server
loop-detective --port 9229

Nếu không dùng được SSH tunneling và inspector mở trên IP có thể truy cập:

loop-detective --host remote-server.example.com --port 9229

Nhưng sẽ có cảnh báo an ninh vì giao thức CDP không có xác thực.

Lưu ý về bảo mật

• Tuyệt đối không để inspector mở ra 0.0.0.0 trong môi trường production nếu không có firewall hoặc chính sách mạng bảo vệ.

• Ưu tiên dùng SSH tunnel hoặc kubectl port-forward vì đã có xác thực và mã hóa.

• Đóng inspector ngay sau khi debug xong (nếu bật bằng SIGUSR1 thì phải restart tiến trình để đóng).

• Dùng network policy trong Kubernetes để giới hạn quyền truy cập cổng inspector.

Những gì bạn có được với loop-detective

Khi kết nối thành công, bạn sẽ nhận được báo cáo chẩn đoán đầy đủ:

• Thời gian chạy profiling, số mẫu thu thập, các hàm "hot" dùng CPU nhiều

• Cảnh báo độ trễ event loop

• Thống kê các thao tác I/O chậm (HTTP, TCP,...)

• Vị trí file, dòng code gây tắc nghẽn CPU hoặc I/O chậm

Điều này giúp bạn dễ dàng xác định nhanh nguyên nhân gây chậm trễ mà không cần thay đổi code, restart hoặc deploy lại ứng dụng.

Quy trình debug tiêu chuẩn với loop-detective

1. Xác định pod đang gặp vấn đề

kubectl get pods -l app=my-service

2. Kích hoạt inspector (nếu chưa mở)

kubectl exec my-service-abc123 -- kill -SIGUSR1 1

3. Forward port

kubectl port-forward my-service-abc123 9229:9229 &

4. Chạy profiling

loop-detective --port 9229 -d 60 --io-threshold 500

5. Xuất báo cáo JSON (nếu muốn)

loop-detective --port 9229 -d 30 --json > diagnostic-report.json

Tổng thời gian từ khi phát hiện chậm đến khi biết vị trí lỗi khoảng 2 phút, rất nhanh và tiện lợi.

Thử ngay

Cài đặt node-loop-detective phiên bản mới nhất:

npm install -g [email protected]

Code nguồn mở trên GitHub: https://github.com/iwtxokhtd83/node-loop-detective

---

Chỉ với một flag mới --host, công cụ này cung cấp cách tiếp cận thiết thực cho việc debug Node.js trong các môi trường sản xuất container, nơi bạn không thể thao tác giống như máy local thông thường. Đây là sự nâng cấp đáng giá dành cho các kỹ sư DevOps và phát triển backend quản lý ứng dụng Node.js trong kỷ nguyên cloud và container hóa.