Cách sửa lỗi 'getaddrinfo ENOTFOUND' trong Node.js: Tại sao ứng dụng không thể kết nối Internet

Bối cảnh

Bạn vừa mới triển khai một microservice Node.js, và các bản log đang báo lỗi dồn dập. Mọi thứ trông có vẻ hoàn hảo trên máy cục bộ của bạn, nhưng trong môi trường production, mọi yêu cầu đến cổng thanh toán bên ngoài đều thất bại ngay lập tức. Thủ phạm là gì? Một lỗi mạng khó hiểu trông như thế này:

Error: getaddrinfo ENOTFOUND api.paymentservice.com

Nói một cách dễ hiểu, ENOTFOUND có nghĩa là trình phân giải DNS của hệ điều hành không thể ánh xạ hostname của bạn sang một địa chỉ IP. Máy chủ không nhất thiết phải đang ngoại tuyến. Đơn giản là ứng dụng của bạn không biết gửi dữ liệu đi đâu. Nó giống như việc cố gắng gửi một bức thư đến một ngôi nhà không có địa chỉ trên bản đồ.

Quy trình Debug

Khi terminal của tôi bắt đầu xuất hiện hàng loạt lỗi đỏ, tôi thường tuân theo một danh sách kiểm tra có hệ thống. Điều này giúp xác định xem lỗi nằm ở mã nguồn, môi trường triển khai hay mạng nội bộ.

1. Kiểm tra các URL bị sai định dạng

Bắt đầu với những điều cơ bản: kiểm tra các chuỗi ký tự của bạn. Một sai lầm phổ biến là truyền một URL đầy đủ trong khi Node.js chỉ yêu cầu một hostname. Nếu bạn sử dụng các module gốc http hoặc https, việc cung cấp https://api.example.com làm tham số hostname sẽ gây ra lỗi trong mọi trường hợp.

// SAI: Bao gồm cả giao thức
const options = {
  hostname: 'https://api.example.com', 
  path: '/v1/data',
  method: 'GET'
};

// ĐÚNG: Chỉ bao gồm tên miền
const options = {
  hostname: 'api.example.com', 
  path: '/v1/data',
  method: 'GET'
};

2. Xác minh kết nối bên ngoài

Máy chủ có thực sự truy cập được internet không? Tôi thường mở terminal và chạy lệnh ping hoặc dig để xem hệ điều hành có nhận diện được host hay không.

ping api.paymentservice.com
# HOẶC
nslookup api.paymentservice.com

Nếu các lệnh này trả về lỗi "Non-existent domain" hoặc hết thời gian chờ sau 5 giây, vấn đề không nằm ở mã nguồn Node.js của bạn. Có khả năng bạn đang gặp sự cố về giao diện mạng hoặc một quy tắc tường lửa đang chặn lưu lượng truy cập đi (outbound) trên cổng 53.

3. Kiểm tra kỹ các biến môi trường

Các tệp cấu hình là nơi dễ phát sinh các lỗi tiềm ẩn. Tệp .env mà bạn sao chép có thể chứa một khoảng trắng thừa hoặc một ký tự ASCII ẩn làm hỏng quá trình tra cứu. Tôi đã từng dành bốn giờ để debug một kết nối chỉ để phát hiện ra một khoảng trắng duy nhất (ASCII 32) ở cuối chuỗi host.

API_HOST=api.example.com# Không có khoảng trắng ở đây
API_HOST= api.example.com # Khoảng trắng ở đầu này sẽ gây ra lỗi ENOTFOUND
API_HOST="api.example.com" # Một số trình phân giải sẽ bao gồm cả dấu ngoặc kép vào chuỗi

Giải pháp

Giải pháp A: Khắc phục sự cô lập của Docker

Các container nổi tiếng với việc bị cô lập DNS. Nếu mã của bạn hoạt động trên máy tính cá nhân nhưng thất bại bên trong container Docker, có khả năng container đó không kế thừa được các thiết lập DNS của máy chủ. Bạn có thể ép buộc container sử dụng một trình phân giải công cộng đáng tin cậy như Google (8.8.8.8) hoặc Cloudflare (1.1.1.1).

Hãy thử thêm flag --dns vào lệnh chạy của bạn:

docker run --dns 8.8.8.8 my-node-app

Trong một tệp docker-compose.yml, nó sẽ trông như thế này:

services:
  app:
    image: my-node-app
    dns:
      - 8.8.8.8
      - 1.1.1.1

Giải pháp B: Xử lý Proxy của doanh nghiệp

Môi trường doanh nghiệp thường định tuyến tất cả lưu lượng truy cập qua một proxy như Zscaler hoặc Blue Coat. Không giống như trình duyệt, Node.js không tự động tuân theo các thiết lập proxy của hệ thống. Để kết nối ra thế giới bên ngoài, bạn phải truyền các yêu cầu của mình qua một proxy agent một cách rõ ràng.

const HttpsProxyAgent = require('https-proxy-agent');
const axios = require('axios');

// Sử dụng URL proxy nội bộ của công ty bạn
const agent = new HttpsProxyAgent('http://proxy.internal.company:8080');
axios.get('https://api.external.com', { httpsAgent: agent });

Giải pháp C: Tối ưu hóa DNS Caching trong Node.js

Node.js sử dụng getaddrinfo ở cấp độ hệ điều hành, đây là một hoạt động đồng bộ trong thread pool nội bộ. Dưới tải trọng lớn—chẳng hạn như 1.000 yêu cầu mỗi giây—đây có thể trở thành một nút thắt cổ chai. Nếu bạn đang gặp giới hạn DNS hoặc thấy các lỗi ENOTFOUND không liên tục, hãy triển khai bộ nhớ đệm (cache) cục bộ. Module dnscache là một cứu cánh trong trường hợp này.

require('dnscache')({
  enable: true,
  ttl: 300, // Lưu bộ nhớ đệm trong 5 phút
  cachesize: 1000
});

Xác minh

Để xác nhận việc sửa lỗi, hãy chạy một script kiểm tra độc lập. Script này bỏ qua toàn bộ logic ứng dụng của bạn để kiểm tra kết nối thô. Lưu tệp này với tên test-dns.js:

const dns = require('dns');

const host = 'api.paymentservice.com';

dns.lookup(host, (err, address, family) => {
  if (err) {
    console.error('DNS Lookup Thất bại:', err.code);
  } else {
    console.log(`Thành công! IP: ${address} (IPv${family})`);
  }
});

Thực thi lệnh node test-dns.js. Nếu nó in ra một địa chỉ IP, môi trường của bạn đã ổn định.

Bài học kinh nghiệm

Hầu hết các lỗi ENOTFOUND là do sai sót trong cấu hình chứ không phải lỗi logic. Hãy luôn làm sạch các biến môi trường của bạn. Luôn xác minh network bridge của Docker.

Khi xây dựng hạ tầng đám mây, tôi luôn kiểm tra kỹ các dải CIDR và subnet để đảm bảo việc định tuyến là khả thi. Tôi sử dụng Công cụ tính Subnet này để xác minh rằng VPC của mình không vô tình bị cô lập. Cuối cùng, tôi luôn bao gồm một bước kiểm tra "pre-flight" trong các script khởi động. Nếu ứng dụng không thể phân giải các API cốt lõi trong khi khởi động, nó nên dừng lại ngay lập tức thay vì âm thầm thất bại sau đó.