使用 Prometheus 和 Grafana 的指标 API（自托管）

自托管 Prometheus 和 Grafana 可以让你完全控制数据保留、告警路由和仪表盘。Supabase Metrics API 可以接入任何标准的 Prometheus 抓取任务，所以你可以把所有东西都在本地、虚拟机上或 Kubernetes 中运行。

🌐 Self-hosting Prometheus and Grafana gives you full control over retention, alert routing, and dashboards. The Supabase Metrics API slots into any standard Prometheus scrape job, so you can run everything locally, on a VM, or inside Kubernetes.

只有在你需要完全手动控制（自定义抓取拓扑、自行托管的 Prometheus 或非标准认证）时才使用这个指南。

🌐 Use this guide only if you need full manual control (custom scrape topology, self-hosted Prometheus or non-standard auth).

否则，可以使用 Supabase 仪表板中提供的 Grafana Cloud 集成。

🌐 Otherwise, use the Grafana Cloud integration available in the Supabase Dashboard.

架构 #

🌐 Architecture

Prometheus 每分钟使用 HTTP 基本认证抓取 https://<project-ref>.supabase.co/customer/v1/privileged/metrics。
Grafana 从 Prometheus 读取数据并渲染仪表盘/报警。
Prometheus Alertmanager 或你喜欢的系统在 Prometheus 规则触发时发送通知（可选）。

1. 部署 Prometheus #

🌐 1. Deploy Prometheus

使用你喜欢的方法（Docker、Helm、二进制文件）安装 Prometheus。然后在 prometheus.yml 中添加一个针对 Supabase 的任务：

🌐 Install Prometheus using your preferred method (Docker, Helm, binaries). Then add a Supabase-specific job to prometheus.yml:

1
scrape_configs:
2
  - job_name: 'supabase'
3
    scrape_interval: 60s
4
    metrics_path: /customer/v1/privileged/metrics
5
    scheme: https
6
    basic_auth:
7
      username: username
8
      password: '<secret API key (sb_secret_...)>'
9
    static_configs:
10
      - targets:
11
          - '<project-ref>.supabase.co:443'
12
        labels:
13
          project: '<project-ref>'

将抓取间隔保持在60秒，以匹配Supabase的刷新节奏。
如果你在代理后面运行 Prometheus，确保它可以建立到 *.supabase.co 的出站 HTTPS 连接。
将秘密（秘密 API 密钥）存储在你的秘密管理器中，或者通过环境变量注入它们。

2. 部署 Grafana #

🌐 2. Deploy Grafana

安装 Grafana（Docker 镜像、Helm chart 或软件包）并将其连接到 Prometheus：

🌐 Install Grafana (Docker image, Helm chart, or packages) and connect it to Prometheus:

在 Grafana 中，进入 连接 → 数据源 → 添加数据源。
选择 Prometheus，将 URL 设置为你的 Prometheus 端点（例如 http://prometheus:9090），然后点击 保存并测试。

3. 导入 Supabase 仪表板 #

🌐 3. Import Supabase dashboards

去 仪表板 → 新建 → 导入。
把 supabase-grafana/dashboard.json 的内容粘贴过来。
在提示时选择你的 Prometheus 数据源。

你现在有超过200个可用于生产的面板，涵盖了CPU、IO、WAL、复制、索引膨胀和查询吞吐量。

🌐 You now have over 200 production-ready panels covering CPU, IO, WAL, replication, index bloat, and query throughput.

Supabase Grafana dashboard showcasing database metrics

4. 配置提醒 #

🌐 4. Configure alerting

将示例规则从 docs/example-alerts.md 导入到 Prometheus 或 Grafana 告警中。
根据你项目的规模调整阈值（例如磁盘使用率、长时间运行的事务、连接饱和度）。
通过 Alertmanager、Grafana OnCall、PagerDuty 或任何其他支持的目标发送通知。

5. 操作小贴士 #

🌐 5. Operating tips

**多个项目：**为每个项目引用添加一个抓取任务，这样你就可以清晰地分开指标和标签。
调整规模指南: 将这些仪表板与 Supabase 的查询性能报告和顾问配合使用，以决定何时优化或升级。
安全性： 定期更换 Secret API 密钥，并相应更新 Prometheus 配置。