Metabase

Cài Metabase từ Kho ứng dụng, tạo tài khoản quản trị sau khoá thiết lập, kết nối các database nó với tới được, sao lưu file H2 và cập nhật an toàn.

Cập nhật 09/10/2026 · 9 phút đọc

Metabase là công cụ phân tích dữ liệu (BI): bạn kết nối nó với một database, rồi dựng câu hỏi, biểu đồ và dashboard mà người không biết SQL vẫn đọc và lọc được. Hãy chọn Metabase khi bạn cần dashboard dùng chung về doanh số, đơn hàng hay dữ liệu ứng dụng. Trang này hướng dẫn cài Metabase từ Kho ứng dụng, thiết lập lần đầu, những database nó kết nối được từ container của ZoPanel, sao lưu và cập nhật.

Yêu cầu

Mục	Giá trị
Image	`metabase/metabase:v0.63.x`
Giới hạn RAM	1536 MB, 1 CPU
Đĩa trống để cài	Khoảng 2,6 GB trên ổ của Docker ở lần cài đầu (image cộng 1 GB chừa lại cho máy chủ)
Docker	Đã cài trên máy chủ (Kho ứng dụng → Cài Docker)
Tên miền	Tên miền hoặc tên miền phụ có bản ghi A trỏ về máy chủ, ví dụ `bi.example.com`
Nguồn dữ liệu	Một database mà Metabase kết nối được qua mạng; đọc mục Kết nối database trước khi cài

Quan trọng: Metabase không kết nối được tới database MariaDB hay PostgreSQL nằm trên cùng máy chủ. Hãy đọc mục Kết nối database trước để chắc chắn nguồn dữ liệu của bạn truy cập được.

Cài Metabase

Với quản trị viên

Mở Kho ứng dụng. Nếu thấy Cần cài Docker, bấm Cài Docker trước.
Trên thẻ Metabase, bấm Cài đặt.

Điền hộp thoại:

Trường	Nội dung
Tên miền	Tên miền ứng dụng chạy, không gồm `http://`. Hệ thống tạo một website mới cho tên miền này.
Chủ sở hữu	Tài khoản hosting sở hữu ứng dụng. Giới hạn của gói tài khoản áp dụng cho container.
SSL miễn phí (Let's Encrypt)	Để bật. Chứng chỉ được cấp ở cuối quá trình cài nếu tên miền đã trỏ về máy chủ.

Bấm Cài đặt và theo dõi log tác vụ tới dòng Metabase is available at http://<tên miền>.
Nếu log báo SSL could not be issued yet, trỏ tên miền về máy chủ rồi bấm Cấp chứng chỉ trong tab SSL của website.

Metabase không có trường cài đặt bổ sung. ZoPanel đặt một biến, MB_DB_FILE=/metabase-data/metabase.db, để Metabase lưu dữ liệu của chính nó (người dùng, câu hỏi, dashboard, thông tin kết nối) trong một file database H2 nhúng trên volume dữ liệu của ứng dụng.

Với khách hàng

Khách tự cài từ Kho ứng dụng trong panel của mình khi gói cho phép; dòng hạn mức ở đầu trang cho biết còn bao nhiêu ứng dụng và bao nhiêu RAM. Metabase cần 1536 MB trong RAM (MB) của gói và một suất trong Gói hosting → Ứng dụng Docker. Xem Gói hosting và giới hạn.

Thiết lập lần đầu

Bản cài mới nằm sau khoá thiết lập: người đầu tiên mở Metabase sẽ thành quản trị viên, nên ZoPanel hiển thị trang "đang được thiết lập" cho mọi người khác tới khi bạn làm xong.

Mở website và vào tab Docker. Chờ trạng thái là running.
Trong thẻ Đang khoá thiết lập, bấm Mở ứng dụng (chỉ mình tôi). Metabase mở trong tab mới.
Lần khởi động đầu mất một đến hai phút. Nếu trang báo site đang bận hoặc Metabase đang khởi tạo, hãy chờ, trang tự tải lại.
Bấm Let's get started.
Chọn ngôn ngữ, rồi nhập họ tên, email, tên công ty hoặc nhóm và mật khẩu. Bấm Next. Tài khoản đầu tiên này là quản trị viên.
Trả lời What will you use Metabase for? (hoặc chọn Not sure yet).
Thêm database ngay, hoặc bấm I'll add my data later để thử trước với Sample Database.
Chọn tuỳ chọn chia sẻ dữ liệu sử dụng và kết thúc bằng Take me to Metabase.
Quay lại tab Docker, bấm Đã thiết lập xong — mở công khai.

Thiết lập cần thiết

Bấm biểu tượng lưới ở góc trên bên phải và chọn Admin:

Settings → General → Site URL: kiểm tra giá trị là https://<tên miền của bạn>. Link trong email và dashboard chia sẻ dùng địa chỉ này.
Settings → Email: Metabase gửi lời mời, đặt lại mật khẩu và đăng ký nhận dashboard qua SMTP. Hộp mail tạo trên panel dùng được: SMTP host = tên máy chủ mail của bạn, cổng 587 (STARTTLS) hoặc 465 (SSL), địa chỉ đầy đủ và mật khẩu.
People: mời đồng nghiệp và xếp họ vào nhóm.
Permissions: quyết định nhóm nào thấy database nào và có được viết SQL hay không.

Hãy cấp cho Metabase một user database chỉ đọc cho mỗi nguồn dữ liệu: nó chỉ cần quyền SELECT.

Kết nối database

Metabase chạy trong container sau tường lửa container của ZoPanel:

Đích	Được phép?
Database và API trên máy chủ khác, ở địa chỉ công khai	Có
Website trên máy chủ này qua tên miền công khai (80/443)	Có
Mail trên máy chủ này (25, 465, 587)	Có
MariaDB, PostgreSQL, Redis hoặc panel trên máy chủ này	Không
Mạng nội bộ (10.x, 172.16–31.x, 192.168.x, 100.64.x), loopback, metadata của cloud	Không

Trên thực tế:

Không thêm được database trên cùng máy chủ, dù bạn nhập host là gì (localhost, 127.0.0.1, IP công khai của máy chủ hay tên miền trỏ về nó). Bật Truy cập từ xa cho database cũng không thay đổi điều này: container bị chặn tới các cổng database của máy chủ.
Database trên máy chủ khác dùng được khi máy chủ đó cho phép kết nối từ IP công khai của máy chủ này. Nếu máy chủ kia chạy ZoPanel, mở Truy cập từ xa của database, thêm IP công khai của máy chủ này vào Địa chỉ IP / dải mạng được phép và dùng Chuỗi kết nối từ xa hiển thị (xem Cơ sở dữ liệu).
Database được quản lý (dịch vụ MySQL hay PostgreSQL trên cloud) dùng được khi có endpoint công khai và cho phép IP của máy chủ này. Endpoint ở địa chỉ VPC nội bộ thì không kết nối được.
SSH tunnel trong form kết nối của Metabase dùng được tới máy chủ khác, không dùng được tới chính máy chủ này (cổng 22 của máy chủ bị chặn với container).

Muốn làm dashboard cho database của cửa hàng hay ứng dụng nằm trên máy chủ này, cách thường dùng là cài Metabase trên một máy chủ thứ hai và kết nối qua Truy cập từ xa của máy chủ này.

Thêm database: Admin → Databases → Add a database, chọn loại (MySQL, MariaDB, PostgreSQL và các loại khác), điền host, cổng, tên database, user và mật khẩu, rồi bấm Save.

Dữ liệu nằm ở đâu và sao lưu

Dữ liệu ứng dụng nằm trong /var/lib/zopanel-apps/<instance>/, với <instance> là tên miền đổi dấu chấm thành gạch ngang (bi.example.com → bi-example-com). Container có tên zp-app-<instance>.

Đường dẫn trên máy chủ	Nội dung
`/var/lib/zopanel-apps/<instance>/data/metabase.db.mv.db`	Database H2 của Metabase: người dùng, câu hỏi, dashboard, kết nối đã lưu
`/var/lib/zopanel-apps/<instance>/.env`	Biến môi trường của container (chỉ root đọc được)

Dữ liệu báo cáo vẫn nằm ở database nguồn; Metabase chỉ lưu truy vấn và thiết lập.

ZoPanel sao lưu gì và không sao lưu gì: thẻ Sao lưu trong tab Docker của website sao lưu toàn bộ thư mục ứng dụng. Bản sao lưu tài khoản và sao lưu gia tăng gồm thư mục website, database và hộp mail của tài khoản. Chúng không gồm /var/lib/zopanel-apps, nên dashboard và người dùng của Metabase chỉ nằm trong bản sao lưu riêng của ứng dụng. Bản sao lưu cấu hình (.zpb) chỉ chứa bản ghi của panel về ứng dụng, không chứa dữ liệu của nó.

Để sao lưu Metabase, bấm Sao lưu ngay trong thẻ Sao lưu ở tab Docker của website. Quản trị viên còn đặt được Lịch (Tắt, Mỗi ngày hoặc Mỗi tuần; mặc định tắt) và số bản Giữ lại (1–60, mặc định 7), rồi bấm Lưu. Mỗi bản sao lưu nén /var/lib/zopanel-apps/<instance>/ thành /var/backups/zopanel-apps/<instance>/YYYYMMDD-HHMMSS.tar.gz, trong thư mục chỉ root đọc được và không tính vào dung lượng đĩa của tài khoản. Container được tạm dừng (pause, không phải stop) trong vài giây sao chép, nên file H2 được chép ở trạng thái nhất quán, như sau một lần mất điện. Các bản cũ vượt quá số Giữ lại bị xoá, và khi một lần sao lưu theo lịch thất bại, quản trị viên nhận cảnh báo Sao lưu thất bại.

Để khôi phục, quản trị viên bấm Khôi phục cạnh một bản sao lưu. Metabase được dừng và dữ liệu được thay bằng nội dung file nén; dữ liệu hiện tại được giữ riêng tới khi ứng dụng khôi phục khởi động được, và được đặt lại nếu nó không khởi động. Mọi thay đổi sau thời điểm sao lưu sẽ mất. Mỗi bản sao lưu còn có nút xoá (chỉ quản trị viên), và xoá ứng dụng kèm file của nó cũng xoá luôn các bản sao lưu. Khách hàng có thể bấm Sao lưu ngay và xem danh sách; việc đặt lịch và khôi phục do nhà cung cấp thực hiện.

Các file nén vẫn ở trên cùng máy chủ. Hãy chép những bản quan trọng ra ngoài (ví dụ bằng scp hoặc rclone từ /var/backups/zopanel-apps/<instance>/) và lưu ở dạng mã hoá, vì chúng chứa mật khẩu của các kết nối database đã lưu. Để khôi phục trên máy chủ khác, cài Metabase với cùng tên miền ở đó, chép file nén vào /var/backups/zopanel-apps/<instance>/ trên máy chủ mới rồi bấm Khôi phục trong thẻ Sao lưu của nó.

Metabase khuyên dùng database production (PostgreSQL hoặc MySQL) thay cho H2 với các bản cài quan trọng. Metabase của ZoPanel dùng H2 và database ứng dụng không chuyển được sang database trên cùng máy chủ, nên hãy sao lưu đều đặn (đặt Lịch trong thẻ Sao lưu).

Cập nhật Metabase

Sao lưu trước (Sao lưu ngay trong thẻ Sao lưu). Metabase chuyển đổi database ứng dụng khi khởi động và không hỗ trợ hạ phiên bản.
Trong tab Docker, bấm Cập nhật bản mới (chỉ quản trị viên; khách hàng nhờ nhà cung cấp).
Tác vụ kéo image trong danh mục và tạo lại container. Dữ liệu được giữ. Metabase gián đoạn một đến hai phút trong lúc khởi động.

Tag v0.63.x của danh mục đi theo dòng phát hành 0.63 của Metabase, nên Cập nhật bản mới mang về bản vá 0.63 mới nhất. Lên dòng Metabase mới hơn sẽ đến cùng bản cập nhật ZoPanel.

Xử lý sự cố

Hiện tượng hoặc thông báo	Cách xử lý
Khách truy cập thấy "This app is being set up"	Bấm Đã thiết lập xong — mở công khai trong tab Docker.
Trang báo site đang bận khoảng một phút sau khi cài, cập nhật hoặc khởi động lại	Metabase vẫn đang khởi động. Hãy chờ, trang tự tải lại.
Thêm database bị timeout hoặc "connection refused"	Database nằm trên máy chủ này hoặc trong mạng nội bộ, hoặc máy chủ từ xa chưa cho phép IP của máy chủ này. Xem mục Kết nối database.
`not enough disk space: this app needs about 2.6 GB free and the server has … GB; free some space first`	Giải phóng dung lượng đĩa rồi cài lại.
`Metabase needs 1536 MB of memory; your plan has … MB and your apps use … MB`	Tăng RAM (MB) của gói hoặc gỡ một ứng dụng khác.
`the app did not start listening: …`	Đọc Log ứng dụng trong tab Docker, rồi bấm Khởi động lại.
Metabase khởi động lại hoặc Log ứng dụng có `OutOfMemoryError`	Truy vấn nặng hoặc nhiều người dùng cùng lúc đã vượt 1536 MB. Giới hạn kết quả lớn, bật cache cho câu hỏi và tránh nhiều dashboard làm mới cùng lúc.
Email từ Metabase không tới	Kiểm tra Admin → Settings → Email; dùng cổng 587 hoặc 465 với hộp mail thật và thử bằng Send test email.

Xem thêm

← n8n Uptime Kuma →