Giải pháp nhanh TL;DR
Thông thường, lỗi này cho biết máy chủ PostgreSQL của bạn không chạy hoặc không được cấu hình để chấp nhận kết nối từ máy khách của bạn. Đầu tiên, hãy thử khởi động lại dịch vụ PostgreSQL của bạn:
sudo systemctl start postgresql
# Hoặc, nếu nó đã chạy, hãy khởi động lại
sudo systemctl restart postgresql
Nếu việc khởi động lại đơn giản không khắc phục được, vấn đề thường nằm ở cấu hình pg_hba.conf không chính xác. Bạn sẽ cần đảm bảo địa chỉ IP của máy khách (hoặc localhost) có quyền kết nối.
Nguyên nhân gốc rễ chi tiết
Thông báo lỗi:
psql: error: connection to server on host "localhost" (127.0.0.1), port 5432 failed: Connection refused
Thông báo này có nghĩa là ứng dụng khách của bạn (psql) đã cố gắng kết nối với máy chủ PostgreSQL trên localhost (127.0.0.1), cổng 5432. Tuy nhiên, máy chủ đã từ chối rõ ràng nỗ lực kết nối. Điều quan trọng cần lưu ý là điều này khác với lỗi hết thời gian kết nối (connection timeout), xảy ra khi máy chủ không phản hồi gì cả.
Tại sao điều này xảy ra? Dưới đây là những nguyên nhân phổ biến nhất gây ra lỗi "Connection refused":
- Máy chủ PostgreSQL không chạy: Đây là lời giải thích đơn giản nhất. Nếu dịch vụ PostgreSQL không hoạt động, sẽ không có gì để chấp nhận kết nối.
- Giá trị
listen_addresseskhông chính xác trongpostgresql.conf: PostgreSQL thường mặc định chỉ lắng nghe trênlocalhost. Nếu bạn đang cố gắng kết nối từ một máy khác hoặc nếu cài đặtlisten_addressessai, các kết nối sẽ bị từ chối. - Cấu hình xác thực không đúng trong
pg_hba.conf: Ngay cả khi máy chủ đang chạy và lắng nghe, nó vẫn dựa vàopg_hba.conf(Xác thực dựa trên máy chủ) để quản lý quyền truy cập của máy khách. Tệp này chỉ định những máy chủ nào có thể kết nối, đến những cơ sở dữ liệu nào, với những người dùng nào và sử dụng phương pháp xác thực nào. Nếu kết nối của máy khách không phù hợp với một mục được phê duyệt, quyền truy cập sẽ bị từ chối. - Tường lửa chặn kết nối: Tường lửa (như
ufwhoặcfirewalldtrên Linux, hoặc Windows Firewall) có thể đang chặn các kết nối đến cổng 5432 trên máy chủ. - Số cổng không chính xác: Máy chủ PostgreSQL có thể đang hoạt động trên một cổng khác ngoài cổng 5432 tiêu chuẩn. Nếu máy khách của bạn cố gắng kết nối đến sai cổng, nó sẽ thất bại.
Các phương pháp khắc phục
1. Xác minh trạng thái dịch vụ PostgreSQL
Hãy bắt đầu bằng cách xác nhận máy chủ PostgreSQL của bạn đang thực sự chạy. Các lệnh chính xác mà bạn sẽ sử dụng phụ thuộc vào hệ điều hành của bạn và cách PostgreSQL được cài đặt.
Linux (các bản phân phối dựa trên systemd như Ubuntu, Debian, CentOS 7+, Fedora):
# Kiểm tra trạng thái
sudo systemctl status postgresql
# Nếu nó không chạy, hãy khởi động
sudo systemctl start postgresql
# Nếu nó đang chạy nhưng bạn nghi ngờ có vấn đề, hãy khởi động lại
sudo systemctl restart postgresql
# Kích hoạt để khởi động cùng hệ thống
sudo systemctl enable postgresql
macOS (cài đặt Homebrew):
# Khởi động PostgreSQL
brew services start postgresql
# Khởi động lại PostgreSQL
brew services restart postgresql
# Kiểm tra trạng thái
brew services list | grep postgresql
2. Kiểm tra postgresql.conf cho listen_addresses
Tham số listen_addresses trong postgresql.conf quy định các giao diện mạng mà PostgreSQL giám sát cho các kết nối đến. Nếu nó được cấu hình cho 'localhost' và bạn đang cố gắng kết nối từ một máy từ xa (hoặc thậm chí là một vùng chứa Docker trên cùng một máy chủ), kết nối của bạn sẽ bị từ chối.
Tìm postgresql.conf:
# Đối với Debian/Ubuntu
sudo find / -name postgresql.conf 2>/dev/null
# Đường dẫn phổ biến: /etc/postgresql/<version>/main/postgresql.conf
# Đối với macOS (Homebrew)
# /usr/local/var/postgres/postgresql.conf
Khi bạn đã tìm thấy tệp, hãy mở nó và tìm dòng listen_addresses:
#postgresql.conf
listen_addresses = 'localhost' # các địa chỉ IP để lắng nghe;
Để cho phép kết nối từ bất kỳ địa chỉ IP nào, hãy thay đổi nó thành như sau. Hãy cẩn thận với cài đặt này; luôn kết hợp nó với các quy tắc pg_hba.conf mạnh mẽ để đảm bảo bảo mật phù hợp:
#postgresql.conf
listen_addresses = '*'
Sau khi thực hiện thay đổi này, hãy nhớ khởi động lại PostgreSQL:
sudo systemctl restart postgresql
3. Cấu hình xác thực dựa trên máy chủ trong pg_hba.conf
pg_hba.conf là tệp cấu hình xác thực máy khách của PostgreSQL. Nó là bộ quy tắc cho biết ai có thể kết nối, từ đâu, đến cơ sở dữ liệu nào và bằng phương pháp xác thực nào.
Tìm pg_hba.conf: Tệp này thường được tìm thấy trong cùng thư mục với postgresql.conf.
Mở pg_hba.conf. Bạn sẽ cần thêm hoặc sửa đổi các mục để cho phép kết nối của mình. Dưới đây là một số ví dụ phổ biến để hướng dẫn bạn:
Để cho phép kết nối cục bộ (từ cùng một máy) bằng mật khẩu:
# KIỂU CƠ SỞ DỮ LIỆU NGƯỜI DÙNG ĐỊA CHỈ PHƯƠNG THỨC
host all all 127.0.0.1/32 md5
host all all ::1/128 md5
Để cho phép kết nối từ một địa chỉ IP cụ thể (ví dụ: 192.168.1.100) bằng mật khẩu:
# KIỂU CƠ SỞ DỮ LIỆU NGƯỜI DÙNG ĐỊA CHỈ PHƯƠNG THỨC
host all all 192.168.1.100/32 md5
Để cho phép kết nối từ toàn bộ mạng con (ví dụ: bất kỳ máy chủ nào trong 192.168.1.0/24) bằng mật khẩu:
# KIỂU CƠ SỞ DỮ LIỆU NGƯỜI DÙNG ĐỊA CHỈ PHƯƠNG THỨC
host all all 192.168.1.0/24 md5
Để cho phép tất cả các kết nối (sử dụng hết sức thận trọng và chỉ dành cho môi trường phát triển!):
# KIỂU CƠ SỞ DỮ LIỆU NGƯỜI DÙNG ĐỊA CHỈ PHƯƠNG THỨC
host all all 0.0.0.0/0 md5
Quan trọng: Để bảo mật mật khẩu mạnh hơn, hãy thay thế md5 bằng scram-sha-256, đặc biệt nếu bạn đang sử dụng PostgreSQL 10 trở lên. Điều quan trọng là phải đảm bảo bạn đã thiết lập người dùng với mật khẩu. Ví dụ, bạn có thể sử dụng ALTER USER youruser WITH PASSWORD 'yourpassword'; để đặt mật khẩu.
Sau khi bạn đã thực hiện các thay đổi này, hãy tải lại cấu hình của PostgreSQL. Không cần khởi động lại hoàn toàn cho các bản cập nhật pg_hba.conf:
sudo systemctl reload postgresql
4. Kiểm tra quy tắc tường lửa
Tường lửa của hệ thống của bạn có thể đang chặn các kết nối đến cổng mặc định của PostgreSQL, 5432.
Linux (UFW - Uncomplicated Firewall, phổ biến trên Ubuntu/Debian):
# Kiểm tra trạng thái UFW
sudo ufw status verbose
# Cho phép kết nối trên cổng 5432 (cổng PostgreSQL mặc định)
sudo ufw allow 5432/tcp
# Hoặc cho phép từ một địa chỉ IP cụ thể
sudo ufw allow from 192.168.1.100 to any port 5432
# Tải lại UFW để áp dụng các thay đổi
sudo ufw reload
Linux (firewalld, phổ biến trên CentOS/RHEL/Fedora):
# Kiểm tra trạng thái firewalld
sudo firewall-cmd --state
# Cho phép kết nối trên cổng 5432
sudo firewall-cmd --add-port=5432/tcp --permanent
sudo firewall-cmd --reload
Tường lửa Windows:
Trên Windows, bạn sẽ cần cấu hình tường lửa thủ công. Mở Windows Defender Firewall with Advanced Security. Điều hướng đến Inbound Rules, sau đó tạo một quy tắc mới để cho phép các kết nối TCP cụ thể trên cổng 5432.
5. Xác minh số cổng
Luôn kiểm tra kỹ rằng ứng dụng khách của bạn đang cố gắng kết nối đến đúng cổng. Mặc dù 5432 là mặc định, điều này có thể được thay đổi trong tệp postgresql.conf của bạn:
#postgresql.conf
port = 5432 # (thay đổi yêu cầu khởi động lại)
Nếu bạn sửa đổi cài đặt này, bạn phải khởi động lại dịch vụ PostgreSQL của mình để thay đổi có hiệu lực.
Nếu PostgreSQL không chạy trên cổng mặc định, hãy nhớ chỉ định nó khi kết nối bằng psql:
psql -h localhost -p 5432 -U your_user -d your_database
Các bước xác minh
Khi bạn đã áp dụng một bản sửa lỗi, đã đến lúc xác minh. Hãy thử kết nối lại với máy chủ PostgreSQL của bạn bằng psql:
psql -h localhost -U postgres -d postgres
Hãy nhớ thay thế localhost, postgres (cho người dùng) và postgres (cho cơ sở dữ liệu) bằng thông tin kết nối cụ thể của bạn. Nếu mọi thứ hoạt động, bạn sẽ được nhắc nhập mật khẩu (nếu được cấu hình) và sau đó được chào đón bởi dấu nhắc lệnh psql, thường trông giống như postgres=#.
Vẫn gặp vấn đề? Hãy tìm hiểu sâu hơn nhật ký máy chủ PostgreSQL để biết các thông báo lỗi chi tiết hơn. Những thông báo này thường cung cấp các manh mối quan trọng. Vị trí tệp nhật ký không phải lúc nào cũng nhất quán, nhưng bạn sẽ thường tìm thấy chúng trong các thư mục như /var/log/postgresql/ hoặc trực tiếp trong thư mục dữ liệu PostgreSQL của bạn.