Giải quyết lỗi kết nối mạng và Connection refused
Lỗi Connection refused xảy ra khi client cố gắng kết nối đến cổng (port) mà không có dịch vụ nào đang lắng nghe, hoặc bị tường lửa chặn.
Bước đầu tiên là xác minh xem dịch vụ Neo4j có đang chạy và lắng nghe trên cổng mặc định 7687 (HTTP) và 7689 (BOLT) hay không.
Thực thi lệnh sau để kiểm tra trạng thái cổng:
sudo ss -tlnp | grep -E '7687|7689'
Kết quả mong đợi: Bạn thấy dòng output hiển thị trạng thái LISTEN trên địa chỉ 0.0.0.0 hoặc 127.0.0.1 cho cả hai cổng. Nếu không thấy, dịch vụ chưa khởi động thành công hoặc cấu hình sai.
Khắc phục lỗi tường lửa UFW
Nếu dịch vụ đang chạy nhưng client ở máy khác không thể kết nối, nguyên nhân thường do UFW (Uncomplicated Firewall) chặn cổng.
Cổng mặc định của Neo4j là 7687 cho giao diện web (Bolt Browser) và 7689 cho giao thức BOLT (dùng cho driver). Cần mở cả hai.
sudo ufw allow 7687/tcp
sudo ufw allow 7689/tcp
sudo ufw status
Kết quả mong đợi: Lệnh status hiển thị hai dòng mới với trạng thái ALLOW cho cổng 7687 và 7689.
Chỉnh sửa neo4j.conf để cho phép kết nối ngoài
Mặc định, Neo4j Server chỉ lắng nghe trên localhost (127.0.0.1). Để cho phép truy cập từ máy khác, phải thay đổi địa chỉ bind trong file cấu hình.
Mở file cấu hình chính bằng trình soạn thảo nano hoặc vim:
sudo nano /etc/neo4j/neo4j.conf
Tìm và thay đổi (hoặc thêm mới) các dòng sau. Xóa dấu # nếu có và thay 127.0.0.1 bằng 0.0.0.0:
dbms.connector.http.listen_address=0.0.0.0:7687
dbms.connector.bolt.listen_address=0.0.0.0:7689
Lưu file và thoát. Sau đó khởi động lại dịch vụ để áp dụng:
sudo systemctl restart neo4j
sudo systemctl status neo4j
Kết quả mong đợi: Trạng thái dịch vụ là active (running) và không có lỗi khởi động.
Verify kết quả
Từ một máy khác cùng mạng LAN, thử truy cập giao diện web:
curl -v http://YOUR_SERVER_IP:7687
Hoặc dùng driver (ví dụ Python hoặc Java) để connect qua cổng 7689. Nếu thành công, bạn sẽ thấy phản hồi HTTP 200 hoặc kết nối BOLT được thiết lập.
Khắc phục lỗi thiếu bộ nhớ (OOM) và điều chỉnh Heap Size
Hiểu về cơ chế phân bổ bộ nhớ của Neo4j
Neo4j sử dụng bộ nhớ RAM cho hai mục đích chính: Heap (Java Heap cho logic xử lý, Cypher engine) và Off-heap (Page Cache cho lưu trữ dữ liệu graph).
Lỗi Out Of Memory (OOM) thường xảy ra khi Heap quá nhỏ (gây tràn khi chạy truy vấn phức tạp) hoặc Page Cache quá lớn (khiến hệ thống Linux giết tiến trình neo4j để giải phóng RAM).
Định cấu hình heap size trong neo4j.conf
Mặc định, Neo4j phân bổ 2GB cho heap và 2GB cho page cache. Trên server production, bạn cần tùy chỉnh dựa trên tổng RAM của máy.
Quy tắc chung: Dành khoảng 50-60% RAM cho Page Cache, 20-25% cho Heap, còn lại cho hệ điều hành và các dịch vụ khác.
Mở file cấu hình:
sudo nano /etc/neo4j/neo4j.conf
Tìm và chỉnh sửa các tham số sau (ví dụ cho máy có 16GB RAM):
dbms.memory.heap.initial_size=2g
dbms.memory.heap.max_size=4g
dbms.memory.pagecache.size=8g
Lưu ý: Đơn vị có thể là `m` (megabyte) hoặc `g` (gigabyte). Giá trị `max_size` phải lớn hơn hoặc bằng `initial_size`.
Sau khi lưu, khởi động lại dịch vụ:
sudo systemctl restart neo4j
Kết quả mong đợi: Neo4j khởi động thành công mà không bị lỗi `java.lang.OutOfMemoryError`.
Xử lý lỗi OOM Killer của Linux
Nếu Neo4j bị tắt đột ngột và log hiển thị "Out of memory: Kill process...", nghĩa là hệ điều hành đã giết nó. Điều này xảy ra khi Page Cache được cấu hình quá lớn, chiếm hết RAM vật lý.
Kiểm tra log của kernel để xác nhận:
dmesg | grep -i "out of memory"
grep "Kill process" /var/log/syslog
Nếu xác nhận là do OOM Killer, bạn phải giảm giá trị `dbms.memory.pagecache.size` xuống.
Ví dụ: Giảm từ 8g xuống 4g trong file `/etc/neo4j/neo4j.conf`:
dbms.memory.pagecache.size=4g
Khởi động lại và theo dõi:
sudo systemctl restart neo4j
sudo systemctl status neo4j
Kết quả mong đợi: Dịch vụ chạy ổn định, không bị giết bởi OOM Killer trong quá trình tải dữ liệu lớn.
Verify kết quả
Sử dụng công cụ `jstat` hoặc xem file log để xác nhận kích thước bộ nhớ đang sử dụng thực tế.
cat /proc/$(pgrep -f neo4j)/status | grep VmRSS
Hoặc truy cập vào giao diện Admin của Neo4j (cần quyền admin), vào tab "System" hoặc "Memory" để xem biểu đồ phân bổ bộ nhớ thời gian thực.
Sử dụng log file để debug lỗi khởi động và runtime
Vị trí các file log quan trọng
Neo4j ghi log theo chuẩn Unix, lưu trữ tại thư mục `/var/log/neo4j/`. Có ba loại log chính:
- neo4j.log: Log chính, chứa thông tin về sự kiện khởi động, lỗi Java, và các cảnh báo quan trọng.
- query.log: Ghi lại tất cả các câu truy vấn Cypher được thực thi (cần bật trong config).
- slow.log: Ghi lại các truy vấn chạy chậm hơn ngưỡng quy định.
Debug lỗi khởi động (Startup Errors)
Khi dịch vụ không lên, nguyên nhân thường nằm ở vài dòng cuối cùng của file `neo4j.log`.
Sử dụng lệnh `tail` để xem 50 dòng cuối cùng:
sudo tail -n 50 /var/log/neo4j/neo4j.log
Nếu log quá dài, tìm kiếm các từ khóa lỗi cụ thể:
sudo grep -i "error\|exception\|failed" /var/log/neo4j/neo4j.log | tail -n 20
Kết quả mong đợi: Bạn thấy rõ dòng lỗi như `Address already in use`, `Permission denied`, hoặc `Configuration exception` chỉ ra nguyên nhân chính xác.
Đưa log ra Console để debug nhanh
Để debug trực tiếp trên terminal mà không cần mở file log, bạn có thể cấu hình Neo4j ghi log ra stdout/stderr hoặc tăng mức độ log (log level).
Chỉnh sửa file `/etc/neo4j/neo4j.conf`:
dbms.logging.level=DEBUG
log4j2.logLevel=DEBUG
Khởi động lại dịch vụ:
sudo systemctl restart neo4j
Theo dõi log theo thời gian thực:
sudo tail -f /var/log/neo4j/neo4j.log
Sau khi debug xong, nhớ quay lại đặt `dbms.logging.level=INFO` để tránh log quá nặng ảnh hưởng hiệu năng.
Kiểm tra quyền truy cập thư mục log
Đôi khi Neo4j không ghi log được do thiếu quyền trên thư mục log.
Kiểm tra quyền sở hữu của thư mục log:
ls -ld /var/log/neo4j
Đảm bảo user `neo4j` là chủ sở hữu. Nếu sai, sửa lại:
sudo chown -R neo4j:neo4j /var/log/neo4j
sudo chmod 755 /var/log/neo4j
Kết quả mong đợi: Dịch vụ có thể ghi log bình thường, file log tăng kích thước khi có hoạt động.
Verify kết quả
Thực hiện một truy vấn Cypher đơn giản và kiểm tra xem nó xuất hiện trong log (nếu bật query log):
neo4j-admin cypher-shell -u neo4j -p PASSWORD "RETURN 1"
sudo grep "RETURN 1" /var/log/neo4j/query.log
Nếu thấy dòng truy vấn, hệ thống logging đang hoạt động tốt.
Mẹo tối ưu hóa cấu hình cho môi trường Production
Tối ưu hóa I/O và Disk Cache
Graph database phụ thuộc rất nhiều vào tốc độ đọc ghi đĩa (I/O). Trong môi trường Production, nên tắt swap hoặc giới hạn swap để tránh hiệu năng bị sụt giảm nghiêm trọng khi RAM đầy.
Kiểm tra mức độ sử dụng swap:
free -h
Nếu muốn tắt swap hoàn toàn (chỉ nên làm khi RAM đủ lớn):
sudo swapoff -a
Để tắt vĩnh viễn, xóa dòng liên quan đến swap trong file `/etc/fstab`:
sudo nano /etc/fstab
Comment dòng chứa từ "swap" bằng cách thêm dấu `#` vào đầu dòng.
Cấu hình Thread Pool và Worker
Tăng số lượng luồng (thread) để xử lý nhiều truy vấn song song hơn, nhưng không nên vượt quá số nhân CPU vật lý (physical cores).
Chỉnh sửa `/etc/neo4j/neo4j.conf`:
dbms.connector.http.max_connections=500
dbms.connector.bolt.max_connections=500
dbms.memory.threads.io=4
Lưu ý: Tăng `max_connections` chỉ có ý nghĩa nếu bạn có nhiều client đồng thời. Tăng quá mức sẽ gây tải CPU cao và làm chậm phản hồi.
Bật tính năng High Availability (HA) hoặc Backup tự động
Trong Production, dữ liệu là quan trọng nhất. Hãy đảm bảo đã cấu hình backup tự động hàng ngày vào một máy chủ lưu trữ khác hoặc cloud storage.
Sử dụng lệnh `neo4j-admin dump` trong cron job (ví dụ: 2h sáng):
(crontab -u neo4j 2>/dev/null; echo "0 2 * * * /usr/bin/neo4j-admin dump --to=/backup/neo4j-backup-$(date +\%F).db -p PASSWORD") | crontab -u neo4j -
Đảm bảo thư mục `/backup` tồn tại và user `neo4j` có quyền ghi vào đó.
Giám sát hiệu năng (Monitoring)
Sử dụng Prometheus và Grafana để giám sát Neo4j là tiêu chuẩn vàng trong vận hành. Neo4j hỗ trợ xuất metrics ra dạng Prometheus.
Bật metrics trong `/etc/neo4j/neo4j.conf`:
dbms.metrics.enabled=true
dbms.metrics.export.prometheus=true
Sau đó cấu hình Prometheus để scrape endpoint `http://localhost:7687/metrics`.
Verify kết quả
Thực hiện một truy vấn phức tạp (ví dụ: tìm đường đi ngắn nhất trên tập dữ liệu lớn) và quan sát:
- Thời gian phản hồi (Latency) có giảm so với cấu hình mặc định không.
- Không có cảnh báo OOM trong log.
- Độ trễ I/O (I/O wait) ở mức chấp nhận được (kiểm tra bằng `iostat -x 1`).
Kiểm tra xem backup file đã được tạo đúng lịch trình:
ls -lh /backup/
Nếu thấy file backup mới được tạo vào khung giờ đã định, hệ thống vận hành đã ổn định.
Điều hướng series:
Mục lục: Series: Triển khai Database Graph với Neo4j và Ubuntu 24.04
« Phần 6: Sao lưu, khôi phục và cấu hình tự động hóa Neo4j