VPS 搭建 Metabase（2026）：Docker、PostgreSQL、数据库连接、仪表盘与备份

Metabase Web 服务本身不重，但 Java 堆内存、查询结果、定时任务和 PostgreSQL 会同时占用资源：

准备 bi.example.com，将 DNS A/AAAA 记录指向 VPS，只开放 SSH、HTTP 和 HTTPS。Metabase 应用数据库可以与分析数据源分离，PostgreSQL、Redis 和内部数据库不要直接暴露到公网。部署前可参考 VPS 配置怎么选。

sudo apt update
sudo apt install -y ca-certificates curl git openssl
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker

sudo mkdir -p /opt/metabase
sudo chown -R "$USER":"$USER" /opt/metabase
cd /opt/metabase
mkdir -p backups

生产环境不要使用 metabase/metabase:latest。固定 Metabase、PostgreSQL 和缓存服务版本，升级前记录镜像 digest 与 Compose 配置。.env 只保存在服务器，并设置 chmod 600。

Metabase 的应用数据库保存用户、问题、仪表盘、权限和连接配置。分析数据可以连接已有业务数据库，但建议使用只读账号：

MB_DB_TYPE=postgres
MB_DB_DBNAME=metabase
MB_DB_PORT=5432
MB_DB_USER=metabase
MB_DB_PASS=change-a-long-password
MB_DB_HOST=postgres
MB_JETTY_PORT=3000
MB_ENCRYPTION_SECRET_KEY=replace-with-a-random-secret

下面是一个最小 Compose 结构，实际环境变量以当前 Metabase 版本文档为准：

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: metabase
      POSTGRES_USER: metabase
      POSTGRES_PASSWORD: ${MB_DB_PASS}
    volumes:
      - postgres_data:/var/lib/postgresql/data
  metabase:
    image: metabase/metabase:v0.56.0
    restart: unless-stopped
    depends_on:
      - postgres
    ports:
      - "127.0.0.1:3000:3000"
    env_file:
      - .env
volumes:
  postgres_data:

启动前检查变量、端口和卷：

docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 metabase

首次启动会执行数据库迁移，几分钟内访问页面可能返回 503。等待容器健康后再进行初始化，不要因为页面暂时打不开就删除 PostgreSQL volume。

首次访问 http://127.0.0.1:3000 或临时域名时，创建管理员、组织信息和第一条数据源连接。连接生产数据库时建议：

• 创建只读数据库用户，只授予报表所需 schema 和表权限。
• 使用内网地址或 Docker 网络连接，避免把数据库端口开放公网。
• 为每个数据源设置明确的名称、负责人和用途。
• 大查询使用副本、数据仓库或汇总表，避免影响线上交易库。

先创建一个简单问题验证连接、时区、编码和权限，再建立仪表盘。SQL 查询中不要把密码、Token 或敏感个人信息写入问题和公开注释。

在宿主机使用 Nginx 终止 TLS，将域名转发到 Metabase 的本地端口：

sudo apt install -y nginx certbot python3-certbot-nginx
sudo nano /etc/nginx/sites-available/metabase

server {
    listen 80;
    server_name bi.example.com;
    client_max_body_size 20m;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }
}

sudo ln -s /etc/nginx/sites-available/metabase /etc/nginx/sites-enabled/metabase
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d bi.example.com

也可以使用 Caddy 自动申请证书，参考 VPS 用 Caddy 反向代理完全指南。如果出现登录重定向、Cookie 或 iframe 错误，检查站点 URL、HTTPS 设置和 X-Forwarded-Proto。

Metabase 的权限应按数据敏感级别设计：

• 普通成员只访问已脱敏的集合和仪表盘。
• 分析师可以创建问题，但不能修改生产数据库结构。
• 管理员负责数据源、权限、审计和备份，不参与日常查询。
• 客户或外部用户使用独立组和专用仪表盘，不要直接分享内部链接。

公开分享、嵌入式仪表盘和匿名访问必须单独评估。关闭不需要的公开链接，并定期检查已生成的分享 Token。API 集成使用独立账号和 Token，放在密钥管理系统中，不要提交到 Git。

Metabase 仪表盘一次加载多个问题，大量并发时容易让数据库出现连接和 CPU 峰值。优化顺序建议是：

1. 检查慢查询、全表扫描和缺少索引的过滤字段。
2. 为高频报表建立汇总表或物化视图。
3. 在 Metabase 中设置结果缓存和合理的刷新周期。
4. 限制单个用户的查询并发和最大返回行数。
5. 将分析查询转移到只读副本或独立数仓。

不要把缓存当作数据库备份。缓存失效后，所有仪表盘同时刷新可能造成瞬时压力，定时刷新应错开时间。

Metabase 可以通过 SMTP 发送密码重置、仪表盘订阅和告警通知。配置后先给管理员发送测试邮件，再启用团队订阅。检查 SPF、DKIM、DMARC、PTR 和 SMTP 出站端口，避免报告进入垃圾箱。

订阅任务由应用后台执行，查看日志确认任务是否成功：

docker compose logs --tail=200 metabase | grep -Ei "email|pulse|error"

报告收件人离职后要及时移除，避免敏感数据继续发送。

Metabase 应用数据库保存仪表盘、问题、用户、权限和数据源配置，必须与业务数据源分别备份：

mkdir -p /opt/metabase/backups
docker compose exec -T postgres pg_dump -U metabase metabase | gzip > /opt/metabase/backups/metabase-$(date +%F).sql.gz
cp .env docker-compose.yml /opt/metabase/backups/
docker compose config > /opt/metabase/backups/compose-$(date +%F).yaml

如果数据源本身也由你维护，还要按其数据库规则备份业务数据。备份完成后同步到另一台 VPS 或对象存储，对 .env 和密钥文件加密。至少每月在隔离环境恢复一次，验证管理员登录、数据源连接、仪表盘、订阅和权限。

备份策略可以结合 Restic、Rclone 与 Docker 数据库恢复演练。

Metabase 升级通常会迁移应用数据库，插件和数据库驱动也可能发生变化。推荐流程：

1. 记录当前镜像 digest、Java 参数、数据库版本和驱动。
2. 备份应用数据库与 Compose 配置。
3. 在测试环境升级，验证登录、查询、仪表盘、订阅和嵌入。
4. 生产环境开启维护窗口，拉取固定版本并等待迁移完成。
5. 检查日志和健康状态，确认无误后恢复访问。

docker compose pull
docker compose up -d
docker compose logs --tail=300 metabase
docker compose ps

如果新版本迁移失败，不要直接把旧镜像接回已经迁移的数据库。先从备份恢复到隔离环境，确认旧版本和数据兼容后再决定回滚。

• Metabase 和应用 PostgreSQL 容器正常运行，版本已固定。
• HTTPS、反向代理头、站点 URL 和登录 Cookie 配置正确。
• 数据源使用只读账号，数据库没有暴露公网。
• 权限、公开分享、嵌入和 API Token 已按最小权限配置。
• SMTP、密码重置、仪表盘订阅和告警测试成功。
• 应用数据库、业务数据源、配置和密钥已异地备份。
• 已完成隔离环境恢复演练，并记录恢复时间。

Metabase 自托管的关键不只是把图表显示出来，而是确保数据源权限、查询性能、分享边界和应用数据库都可控。先从只读数据源和少量核心仪表盘开始，再逐步接入缓存、只读副本和自动化报表，VPS 才能稳定支撑团队的数据分析工作。

延伸阅读：

• VPS Docker Compose 生产环境怎么配
• VPS 备份恢复演练怎么做