Cài đặt native

Bài này hướng dẫn cài Elasticsearch và Kibana bằng gói Debian trên Ubuntu hoặc Debian. Cài đặt native phù hợp khi bạn muốn làm quen với systemd, file cấu hình và log của dịch vụ. Nếu bạn muốn tạo rồi xóa môi trường nhanh bằng container, hãy xem Cài đặt bằng Docker Compose.

Mục lục

• Tổng quan và mục tiêu
• Chuẩn bị máy
  • Tài nguyên tối thiểu
  • Kiểm tra phiên bản hệ điều hành
• Thêm repository chính thức
• Cài Elasticsearch và Kibana
• Khởi động Elasticsearch
• Đặt mật khẩu và kiểm tra API
• Khởi động và đăng nhập Kibana
• Các file, thư mục và log quan trọng
• Dừng hoặc gỡ cài đặt
• Troubleshooting
  • Cổng 9200 hoặc 5601 đã được sử dụng
  • Elasticsearch không đủ bộ nhớ
  • Service failed khi khởi động
  • Lỗi quyền hoặc lỗi chứng chỉ
• Bước tiếp theo

Tổng quan và mục tiêu

Elasticsearch là dịch vụ lưu trữ và tìm kiếm dữ liệu. Kibana là giao diện web dùng để gửi request, khám phá dữ liệu và tạo biểu đồ. Trong bài này, cả hai dịch vụ chạy trên cùng một máy:

Quy trình có bốn phần. Bạn chuẩn bị máy, thêm repository chính thức, cài hai package cùng version, rồi khởi động và kiểm tra từng dịch vụ. Làm theo thứ tự giúp tách lỗi cài đặt khỏi lỗi cấu hình.

Chuẩn bị máy

Tài nguyên tối thiểu

Dùng Ubuntu 22.04/24.04 LTS hoặc Debian 12 trên kiến trúc được Elastic hỗ trợ. Bạn cần một tài khoản có quyền sudo, kết nối Internet và một terminal.

Để học local, nên có ít nhất 4 GiB RAM và 10 GiB dung lượng trống. Elasticsearch dùng heap (vùng nhớ JVM dành cho dữ liệu và execution) cùng với bộ nhớ ngoài heap, nên máy chỉ có 2 GiB RAM dễ bị OOM (hết bộ nhớ). Không chạy Elasticsearch bằng tài khoản root; package sẽ tạo user dịch vụ riêng.

Kiểm tra nhanh tài nguyên trước khi cài:

free -h

df -h /

# Elasticsearch dùng memory-mapped files; giá trị này nên là 262144 hoặc cao hơn.
sysctl vm.max_map_count

Nếu vm.max_map_count nhỏ hơn 262144, đặt giá trị cho lần khởi động hiện tại và lưu lại sau reboot:

sudo sysctl -w vm.max_map_count=262144
echo 'vm.max_map_count=262144' | sudo tee /etc/sysctl.d/99-elasticsearch.conf
sudo sysctl --system

Kiểm tra phiên bản hệ điều hành

Xác nhận hệ điều hành và kiến trúc trước khi thêm repository. Hai lệnh này cũng hữu ích khi cần cung cấp thông tin cho việc troubleshooting:

. /etc/os-release
printf 'OS: %s %s\n' "$ID" "$VERSION_ID"
uname -m

Nếu hệ điều hành không phải Ubuntu hoặc Debian, không dùng nguyên các lệnh APT trong bài. Hãy chuyển sang Cài đặt bằng Docker Compose hoặc tài liệu package chính thức cho hệ điều hành của bạn.

Thêm repository chính thức

Package từ repository của Elastic giúp apt nhận bản cập nhật và dependency đúng cách. Ta thêm khóa ký package vào keyring riêng thay vì dùng cách apt-key cũ.

sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg

curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch \
  | sudo gpg --dearmor --yes -o /usr/share/keyrings/elasticsearch-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/9.x/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/elastic-9.x.list

sudo apt-get update
apt-cache policy elasticsearch kibana

test -s /usr/share/keyrings/elasticsearch-keyring.gpg
cat /etc/apt/sources.list.d/elastic-9.x.list

Cài Elasticsearch và Kibana

Cài hai package trong cùng một lệnh. Cách này giảm khả năng APT cập nhật một package giữa hai lần cài riêng biệt:

sudo apt-get install -y elasticsearch kibana

Ngay sau đó, kiểm tra version đã cài. Elasticsearch và Kibana phải cùng version đầy đủ, không chỉ cùng major version:

dpkg-query -W -f='${Package} ${Version}\n' elasticsearch kibana

Nếu version khác nhau, xem các version có thể cài và chọn cùng một chuỗi version. Chuỗi version phải lấy từ output thực tế của máy, không đoán bằng cách bỏ phần revision:

apt-cache madison elasticsearch
apt-cache madison kibana

# Ví dụ cú pháp; thay <VERSION> bằng một version xuất hiện ở cả hai lệnh trên.
sudo apt-get install elasticsearch=<VERSION> kibana=<VERSION>

Khởi động Elasticsearch

Package tạo service elasticsearch, nhưng không tự ý mở service ra Internet. Bật service để khởi động cùng hệ điều hành và chạy ngay trong phiên hiện tại:

sudo systemctl daemon-reload
sudo systemctl enable --now elasticsearch.service
sudo systemctl status elasticsearch.service --no-pager

active (running) chỉ cho biết process đang sống. Ta vẫn cần kiểm tra API và log. Nếu service đang activating, chờ vài giây rồi kiểm tra lại vì JVM cần thời gian khởi tạo:

systemctl is-active elasticsearch.service
sudo journalctl -u elasticsearch.service -n 100 --no-pager

Trong các bản Elastic hiện đại, security thường được bật mặc định. Package có thể tạo CA HTTP và thông tin xác thực trong lần chạy đầu tiên. Vì vậy, đừng mặc định rằng http://localhost:9200 là endpoint hợp lệ; hãy kiểm tra scheme và file CA mà package đã tạo.

Đặt mật khẩu và kiểm tra API

User elastic là tài khoản quản trị tích hợp cho cluster. Nếu package chưa in mật khẩu khởi tạo hoặc bạn cần đặt lại mật khẩu, chạy lệnh sau trên chính máy cài Elasticsearch:

sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic

Lệnh in một mật khẩu mới. Lưu nó trong password manager, không commit vào Git và không đưa vào shell history nếu máy dùng chung.

CA HTTP thường nằm ở /etc/elasticsearch/certs/http_ca.crt. Dùng CA này để kiểm tra endpoint bảo mật:

export ELASTIC_PASSWORD='thay-bang-mat-khau-vua-nhan'

curl --fail --silent --show-error \
  --cacert /etc/elasticsearch/certs/http_ca.crt \
  -u "elastic:${ELASTIC_PASSWORD}" \
  https://localhost:9200

Response thành công chứa các trường như name, cluster_name và version. Gọi health API để biết trạng thái cluster:

curl --fail --silent --show-error \
  --cacert /etc/elasticsearch/certs/http_ca.crt \
  -u "elastic:${ELASTIC_PASSWORD}" \
  'https://localhost:9200/_cluster/health?pretty'

Cluster một node dùng để học thường có trạng thái yellow vì replica chưa được phân bổ. yellow vẫn cho phép thực hành indexing và search. red nghĩa là có shard không khởi động được; hãy xem Service failed khi khởi động và log trước khi tiếp tục.

Khởi động và đăng nhập Kibana

Kibana cần kết nối đến Elasticsearch trước khi phục vụ giao diện. Với cài đặt package hiện đại, cách an toàn nhất cho lab là dùng enrollment token (mã ghép nối một lần) do Elasticsearch tạo.

sudo /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s kibana

sudo systemctl enable --now kibana.service
sudo systemctl status kibana.service --no-pager
sudo journalctl -u kibana.service -n 100 --no-pager

Khi giao diện tải xong, vào Discover hoặc Dev Tools để xác nhận Kibana đã nói chuyện được với Elasticsearch. Bài Kibana Dev Tools sẽ giải thích cách gửi request thuận tiện hơn curl.

Các file, thư mục và log quan trọng

Cài đặt package tách cấu hình, dữ liệu và log. Biết đúng vị trí giúp bạn chẩn đoán lỗi mà không cần sửa file ngẫu nhiên:

Xem log bằng journalctl thường dễ hơn mở file trực tiếp:

sudo journalctl -u elasticsearch.service -f
sudo journalctl -u kibana.service -f

Nhấn Ctrl+C để dừng theo dõi. Chỉ đọc log từ thư mục /var/log khi cần đối chiếu; tránh dùng sudo chmod -R 777 vì cách đó che giấu lỗi quyền và tạo rủi ro bảo mật.

Dừng hoặc gỡ cài đặt

Dừng service trước khi thao tác package hoặc dữ liệu:

sudo systemctl disable --now kibana.service
sudo systemctl disable --now elasticsearch.service

Gỡ package nhưng giữ lại file cấu hình:

sudo apt-get remove elasticsearch kibana

Gỡ cả package và file cấu hình do package quản lý:

sudo apt-get purge elasticsearch kibana
sudo apt-get autoremove

purge không phải lúc nào cũng xóa dữ liệu trong /var/lib/elasticsearch. Nếu muốn xóa toàn bộ dữ liệu lab, kiểm tra kỹ đường dẫn rồi mới xóa:

sudo du -sh /var/lib/elasticsearch /var/lib/kibana 2>/dev/null || true
# Chỉ chạy sau khi đã xác nhận đây là dữ liệu lab có thể mất.
sudo rm -rf /var/lib/elasticsearch /var/lib/kibana

Troubleshooting

Cổng 9200 hoặc 5601 đã được sử dụng

Xem process đang lắng nghe cổng nào:

sudo ss -ltnp | grep -E ':(9200|5601)\b' || true

Nếu chính service cũ đang chạy, không khởi động thêm một instance thứ hai. Nếu một ứng dụng khác dùng cổng, dừng ứng dụng đó hoặc đổi port có chủ đích trong file cấu hình tương ứng. Sau khi đổi, kiểm tra endpoint mới và cập nhật URL trong Kibana.

Elasticsearch không đủ bộ nhớ

Dấu hiệu thường gặp là service bị kill, log có OutOfMemoryError, hoặc status=137. Kiểm tra RAM và log kernel:

free -h
sudo journalctl -k -n 100 --no-pager | grep -i -E 'oom|killed process' || true
sudo journalctl -u elasticsearch.service -n 150 --no-pager

Đừng tăng heap một cách mù quáng. Heap lớn hơn không tạo thêm RAM. Trên máy lab có 4 GiB RAM, có thể đặt heap 1 GiB bằng file riêng:

sudo install -d -o root -g elasticsearch -m 0750 /etc/elasticsearch/jvm.options.d
printf '%s\n' '-Xms1g' '-Xmx1g' \
  | sudo tee /etc/elasticsearch/jvm.options.d/heap.options
sudo systemctl restart elasticsearch.service

Giữ -Xms và -Xmx bằng nhau để heap không thay đổi trong lúc chạy. Nếu máy vẫn thiếu bộ nhớ, tắt ứng dụng không cần thiết hoặc dùng Docker với giới hạn tài nguyên phù hợp; không cố chạy cluster lớn trên máy nhỏ.

Service failed khi khởi động

Lấy trạng thái và vài dòng log quanh lỗi đầu tiên:

sudo systemctl status elasticsearch.service --no-pager -l
sudo journalctl -u elasticsearch.service -b --no-pager -n 200
sudo systemctl status kibana.service --no-pager -l
sudo journalctl -u kibana.service -b --no-pager -n 200

Các nguyên nhân thường gặp là YAML sai cú pháp, version hai package không khớp, vm.max_map_count thấp, heap quá lớn hoặc thư mục dữ liệu không còn đúng quyền. Sửa một thay đổi mỗi lần, kiểm tra log rồi mới restart. Nếu lỗi xuất hiện ngay sau khi sửa file, hoàn nguyên bản sao gần nhất để xác định nguyên nhân.

Lỗi quyền hoặc lỗi chứng chỉ

Kiểm tra user của service và quyền đọc file cấu hình/CA:

systemctl show -p User,Group elasticsearch.service
sudo namei -l /etc/elasticsearch/certs/http_ca.crt
sudo ls -l /etc/elasticsearch/certs/http_ca.crt

Dùng --cacert /etc/elasticsearch/certs/http_ca.crt thay vì -k khi gọi HTTPS. -k bỏ qua việc xác minh chứng chỉ và chỉ nên dùng để cô lập lỗi trong một lab tạm thời; nó không phải cách sửa cấu hình.

Nếu curl báo 401, endpoint đã hoạt động nhưng thông tin xác thực sai. Nếu báo lỗi CA, kiểm tra đúng scheme (https) và đúng đường dẫn CA trước khi tạo lại password. Nếu Kibana không kết nối được, đọc log Kibana để biết nó đang dùng endpoint nào rồi đối chiếu với elasticsearch.yml.

Bước tiếp theo

Bạn đã có một Elasticsearch node và Kibana chạy dưới systemd. Tiếp tục theo lộ trình: