# 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.

Source: https://zopanel.net/vi/docs/app-metabase  
Updated: 2026-10-09

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

1. Mở **Kho ứng dụng**. Nếu thấy **Cần cài Docker**, bấm **Cài Docker** trước.
2. Trên thẻ **Metabase**, bấm **Cài đặt**.
3. Đ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ủ. |

4. 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>`.
5. 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](/vi/docs/packages-limits).

## 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.

1. Mở website và vào tab **Docker**. Chờ trạng thái là `running`.
2. 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.
3. 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.
4. Bấm **Let's get started**.
5. 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.
6. Trả lời **What will you use Metabase for?** (hoặc chọn **Not sure yet**).
7. Thêm database ngay, hoặc bấm **I'll add my data later** để thử trước với **Sample Database**.
8. Chọn tuỳ chọn chia sẻ dữ liệu sử dụng và kết thúc bằng **Take me to Metabase**.
9. 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](/vi/docs/databases)).
- **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

1. 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.
2. 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).
3. 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](/vi/docs/updating).

## 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

- [Kho ứng dụng và lưu trữ S3](/vi/docs/apps)
- [Từng ứng dụng dùng để làm gì](/vi/docs/app-catalog)
- [Cơ sở dữ liệu](/vi/docs/databases)
- [Gói hosting và giới hạn](/vi/docs/packages-limits)
- [Tài liệu Metabase](https://www.metabase.com/docs/latest/), [Thêm database](https://www.metabase.com/docs/latest/databases/connecting) và [Sao lưu Metabase](https://www.metabase.com/docs/latest/installation-and-operation/backing-up-metabase-application-data)