PAYATHON 2026

Self-Hosting Supabase 无法使用 Logs Explorer

数据阿明

结论

Self-Hosting 不会连接 Supabase Cloud 的组织、订阅和计费系统，所以下面两个接口返回 404 通常属于正常现象：

/api/integrations/default-org-slug?expand=true
/api/projects/default/billing/subscription

这两个请求用于 Studio 与云端服务、组织或订阅功能之间的交互，不是 Logs Explorer 获取日志数据的接口。不要通过伪造接口响应来处理这些 404。

Logs Explorer 显示 502 UNKNOWN，通常说明 Studio 无法访问自托管的日志分析服务，或者日志采集链路配置有误。排查重点应放在 analytics（Logflare）、Vector 和 Studio 之间的连接上，而不是上述两个 404。

Logs Explorer 的依赖关系

自托管环境中的日志查询大致经过以下链路：

Supabase services
        ↓
      Vector
        ↓
analytics / Logflare
        ↓
      Studio
        ↓
 Logs Explorer

仅部署数据库、Auth、REST、Storage 和 Studio，无法保证 Logs Explorer 正常使用。analytics 服务未启动、健康检查失败、访问令牌不一致，或者 Studio 配置了浏览器无法解析的内部地址，都可能引发 502。

排查步骤

1. 确认日志相关容器正在运行

在 Supabase Self-Hosting 的 Docker Compose 目录中查看服务状态：

docker compose ps

重点检查名称中包含以下内容的服务：

studio
analytics
vector

如果没有 analytics，当前部署文件可能未包含日志分析组件。如果该服务存在，但状态是 unhealthy、restarting 或 exited，需要先解决它的启动问题。

查看相关日志：

docker compose logs --tail=200 analytics
docker compose logs --tail=200 vector
docker compose logs --tail=200 studio

主要检查以下问题：

  • 数据库连接失败
  • token 或 API key 不匹配
  • 无法连接 analytics:4000
  • Vector 写入日志失败
  • 数据表迁移失败
  • DNS、端口或容器网络错误

2. 检查 Studio 到 analytics 的地址

在 Docker Compose 网络内，Studio 通常应通过服务名访问 analytics。不要使用宿主机的局域网 IP，也不要使用容器中的 localhost。

配置一般类似：

services:
  studio:
    environment:
      LOGFLARE_URL: http://analytics:4000

下面这种写法通常无法正常工作：

LOGFLARE_URL: http://localhost:4000

对 Studio 容器来说，localhost 指向 Studio 容器本身，而不是 analytics 容器。

有些 Supabase 版本会要求浏览器直接访问日志服务。此时需要配置浏览器可以访问的外部 URL，并通过反向代理暴露对应路径。具体变量名会随 Self-Hosting 版本变化，请以当前版本附带的 .env.example 和 docker-compose.yml 为准，不要直接照搬其他版本的配置。

3. 核对 Logflare 访问令牌

Studio、analytics 和 Vector 使用的令牌必须相互对应。常见配置会包含类似变量：

LOGFLARE_PUBLIC_ACCESS_TOKEN=replace-with-a-long-random-token
LOGFLARE_PRIVATE_ACCESS_TOKEN=replace-with-another-long-random-token

Compose 文件应引用同一组变量，例如：

services:
  studio:
    environment:
      LOGFLARE_PUBLIC_ACCESS_TOKEN: ${LOGFLARE_PUBLIC_ACCESS_TOKEN}
      LOGFLARE_PRIVATE_ACCESS_TOKEN: ${LOGFLARE_PRIVATE_ACCESS_TOKEN}

  analytics:
    environment:
      LOGFLARE_PUBLIC_ACCESS_TOKEN: ${LOGFLARE_PUBLIC_ACCESS_TOKEN}
      LOGFLARE_PRIVATE_ACCESS_TOKEN: ${LOGFLARE_PRIVATE_ACCESS_TOKEN}

不同版本的变量名和注入位置可能不同。排查时需要确认：

  • .env 中的变量不为空；
  • Studio 和 analytics 使用的是同一组 token；
  • 修改 .env 后已经重新创建容器；
  • token 中没有多余的引号、换行或空格。

修改配置后，可以重新创建相关服务：

docker compose up -d --force-recreate analytics vector studio

这条命令会重建容器。执行前，请确认当前目录对应正确的 Compose 项目。

4. 检查 analytics 的数据库连接

analytics 通常需要把日志和相关元数据写入 PostgreSQL。如果数据库地址、端口、用户名、密码或数据库名配置错误，容器可能仍能启动，但查询接口无法正常工作。

请根据 analytics 容器日志核对连接配置。Compose 中可能有类似内容：

services:
  analytics:
    environment:
      DB_HOSTNAME: db
      DB_PORT: 5432
      DB_USERNAME: supabase_admin
      DB_PASSWORD: ${POSTGRES_PASSWORD}

这段配置仅用于说明排查方向，不代表所有版本都使用这些变量名。没有核对当前部署模板之前，不要直接新增变量或修改变量名。

5. 检查 Vector 是否成功投递日志

即使 analytics 可以访问，如果 Vector 没有成功采集或写入日志，Logs Explorer 仍可能没有内容，部分查询也可能失败。

检查 Vector 日志：

docker compose logs --tail=200 vector

常见异常包括：

connection refused
401 Unauthorized
403 Forbidden
DNS resolution failed
request timed out

出现 401 或 403 时，先核对 Logflare token。出现 connection refused 时，检查 analytics 的监听端口、健康状态和 Docker 网络。如果无法解析 analytics，确认两个服务是否加入了同一个 Compose 网络。

6. 检查反向代理和超时设置

如果 Studio 或 analytics 位于 Nginx、Traefik、Kong 等代理之后，502 也可能是代理无法连接上游造成的。

Nginx 配置可参考：

location / {
    proxy_pass http://studio:3000;
    proxy_http_version 1.1;

    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_connect_timeout 30s;
    proxy_read_timeout 120s;
}

如果 analytics 单独经过代理，还要确认 proxy_pass 指向正确的服务名和端口。不要只调整超时时间。上游地址错误或服务未启动时，延长超时并不能解决问题。

如何判断 502 的具体来源

在浏览器开发者工具中找到实际返回 502 的请求，检查它的 Request URL 和 Response Headers：

  • 请求发往 Studio 的 /api/.../analytics/... 路径时，通常是 Studio 代理 analytics 失败；
  • 请求直接发往 analytics 的域名或端口时，检查浏览器能否访问该地址；
  • 响应头来自 Nginx、Kong 或其他网关时，继续查看对应代理的错误日志；
  • analytics 返回 401、403 或 500 时，根据容器日志排查认证或数据库问题。

可以暂时忽略返回 404 的 billing 和 integrations 请求。判断问题时，应以实际触发 Logs Explorer 页面 502 的请求为准。

版本兼容问题

Self-Hosting 使用的 Studio、analytics、Vector 和 Compose 配置需要相互匹配。只升级 Studio 镜像，却继续使用旧版 Compose 文件或旧环境变量，是这类问题的常见原因。

建议按以下顺序处理：

  1. 确认各容器当前使用的镜像版本；
  2. 找到与这些版本对应的官方 Self-Hosting Compose 模板；
  3. 对比 studio、analytics 和 vector 的环境变量、端口、健康检查与依赖关系；
  4. 备份 .env 和数据库，再统一更新相关服务。

不要使用 latest 对部分容器进行混合升级。不同版本需要的变量和接口可能并不相同。

如果不需要 Logs Explorer

Logs Explorer 不是数据库、Auth、REST 或 Storage 正常运行的必要条件。如果暂时不需要集中查询日志，可以直接通过 Docker 查看：

docker compose logs -f

也可以单独查看某个服务：

docker compose logs -f auth
docker compose logs -f rest
docker compose logs -f storage

因此，这些 404 并不表示 Supabase 核心服务部署失败。需要修复的是产生 502 的日志分析链路。通常可以先确认 analytics 是否正常运行，再核对 Studio 的 LOGFLARE_URL 和访问令牌，最后检查 Vector 是否成功写入日志。

备注：内容仅供参考。