PostgREST Admin Server 完全指南：健康检查、Prometheus 指标与运行时 Schema Cache

PostgREST Admin Server 完全指南：健康检查、Prometheus 指标与运行时 Schema Cache

【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrest

本文以 PostgREST 仓库的 admin_server.rst 为骨架，系统讲解 Admin Server 的启用方式、四个内置端点（live、ready、schema_cache、metrics）的行为与判定逻辑，并结合 Admin.hs、Config.hs 等源码与 test_admin.py 测试用例，深入说明其底层实现原理。读完本文，你将掌握如何为 PostgREST 实例配置独立的管理端口、接入 Kubernetes 探针或负载均衡健康检查，以及如何用 Prometheus 格式的指标监控连接池、Schema Cache 与 JWT 缓存的实时状态。

Admin Server 是什么

PostgREST 提供了一台与管理相关的独立服务器（Admin Server）。它不承载任何业务 API 请求，而是专门服务于运维与可观测性需求，例如：

• 探测 PostgREST 进程是否存活（Live Probe）；
• 探测 PostgREST 是否已准备好接收客户端请求（Ready Probe）；
• 导出 Prometheus 格式的运行指标（Metrics）；
• 导出运行时 Schema Cache 的完整内容（Runtime Schema Cache）。

Admin Server 默认不启用，需要显式设置admin-server-port或admin-server-unix-socket配置项后才会监听。从源码看，其启动入口是 src/library/PostgREST/Admin.hs 中的runAdmin：当配置中存在管理 Socket 时，PostgREST 会forkIO一个独立的 Warp 服务器线程，与公共 API 服务器并行运行：

runAdmin appState maybeAdminSocket checkMainAppLive settings = do conf <- getConfig appState whenJust maybeAdminSocket $ \adminSocket -> do address <- resolveSocketToAddress adminSocket void . forkIO $ handle onError $ Warp.runSettingsSocket (adminServerSettings conf address) adminSocket adminApp

onError的处理值得注意：Admin Server 一旦崩溃，会被视为不可恢复的错误，直接杀掉整个 PostgREST 进程（killApp appState），避免出现"主服务存活但失去管理能力"的"僵尸"状态。

与公共 API 服务器的关系

• Admin Server 与公共 API 服务器是两套独立的监听端点，互不干扰；
• 公共 API 端口由server-port（默认3000）控制，管理端口由admin-server-port控制；
• 在 Config.hs 中，parseAdminServerPort会校验管理端口不能与server-port相同，否则启动会直接失败（错误信息为admin-server-port cannot be the same as server-port）。

启用与配置 Admin Server

配置参数一览

以下四个参数专用于 Admin Server，均不可热重载（Reloadable = N），必须通过配置文件、环境变量或在数据库配置表中设置，修改后需重启进程：

上述参数在 configuration.rst 中有完整定义，并与 Config.hs 中的解析逻辑一一对应。

最小配置示例

在postgrest.conf中启用 TCP 形式的管理服务器：

# 公共 API 服务器（默认 3000） server-port = 3000 # Admin Server admin-server-host = "127.0.0.1" admin-server-port = 3001

重启后即可访问：

curl -I "http://localhost:3001/live"

使用 Unix 域套接字

若希望管理端点完全不暴露于网络（仅本机进程可访问），可使用 Unix 域套接字。设置后会覆盖admin-server-port：

admin-server-unix-socket = "/tmp/pgrst-admin.sock" admin-server-unix-socket-mode = "660"

admin-server-unix-socket-mode的合法取值范围为600到777（八进制）。对应源码在 Config.hs 的parseSocketFileMode：未设置时默认432（即八进制660）；解析出的权限值若小于600（384）或大于777（511）会直接报错。

环境变量方式

所有管理参数均可通过环境变量注入，例如：

export PGRST_ADMIN_SERVER_PORT=3001 export PGRST_ADMIN_SERVER_UNIX_SOCKET="/tmp/pgrst-admin.sock"

注意：若同时设置PGRST_ADMIN_SERVER_UNIX_SOCKET，它将优先于PGRST_ADMIN_SERVER_PORT生效。

多实例部署：Admin 端口不共享

当多个 PostgREST 实例通过server-reuseport = true（启用SO_REUSEPORT）共享同一个公共 API 主机与端口时，操作系统的负载均衡会把新连接分发到各实例。但管理端口不会被共享：

• 每个实例必须使用不同的admin-server-port，否则后启动的实例会因地址被占用而启动失败；
• 官方文档明确指出：Admin 端口不共享，因此就绪检查（readiness check）总能精确命中某一个特定实例。

该约束在 configuration.rst 中也有强调：

When running multiple PostgREST instances on the sameserver-port, use a differentadmin-server-portfor each instance. Admin ports are not shared between instances, so readiness checks always target one specific PostgREST instance.

Health Check：live 与 ready

启用 Admin Server 后，会得到live与ready两个健康检查端点。二者均返回状态码 + 空响应体，适合配合curl -I、KuberneteshttpGet探针或负载均衡健康检查使用。

live：进程存活探测

live端点验证 PostgREST 是否正在其配置的端口上运行：

• 存活时返回200 OK；
• 否则返回500。

验证示例（admin-server-port为3001）：

curl -I "http://localhost:3001/live"

HTTP/1.1 200 OK

从源码看，live的判定依据是checkMainAppLive（见 App.hs），它同时检查两件事：

1. 主服务器线程是否仍在运行：通过Weak ThreadId的deRefWeak与threadStatus判断主线程是否处于ThreadRunning/ThreadBlocked状态；
2. 主监听 Socket 是否有效：对 TCP 套接字直接调用getSocketName校验；对 Unix 域套接字则检查套接字文件是否仍然存在（doesPathExist）。

任一检查失败即判定主应用不存活，返回500。

ready：就绪探测

在live的基础上，ready端点进一步检查连接池（connection pool）与Schema Cache的状态：

• 两者均健康时返回200 OK；
• 不健康时返回503。

curl -I "http://localhost:3001/ready"

HTTP/1.1 200 OK

结合 Admin.hs 的实现，ready的实际判定逻辑比文档描述更精细：

status | isPending = HTTP.status503 -- Schema Cache 加载中 | not isMainAppLive = HTTP.status500 -- 主应用不存活 | isLoaded = HTTP.status200 -- Schema Cache 已加载完成 | otherwise = HTTP.status500

也就是说：

• Schema Cache 正在加载（isPending）→503，提示"尚未就绪"；
• 主应用不存活 →500；
• Schema Cache 加载完成（isLoaded）→200；
• 其他异常状态 →500。

这与 test_admin.py 中的test_admin_ready_includes_schema_cache_state用例相互印证：该测试通过PGRST_INTERNAL_SCHEMA_CACHE_QUERY_SLEEP=500人为拉长 Schema Cache 查询时间，再用 400ms 的statement_timeout令其加载失败，此时访问/ready应得到失败状态码，证明 ready 探测确实感知 Schema Cache 的加载状态。

503 状态下的自动恢复

当ready返回503时，PostgREST 会尝试通过**自动恢复（Automatic Recovery）**机制回到健康状态（见 connection_pool.rst）：

• 连接丢失后，服务器会无限次重试，采用指数退避，最大退避间隔 32 秒；
• 恢复过程中会重载 Schema Cache 与配置，确保状态一致；
• 每次重试都会记录日志；
• 重试期间，面向客户端的请求会收到503 Service Unavailable与Retry-After: x响应头，其中x为下一次重试的等待秒数；
• 仅当错误被判定为致命（如密码认证失败、内部错误）时才停止重试；
• 可通过db-pool-automatic-recovery = false关闭该机制。

因此，ready端点非常适合作为 KubernetesreadinessProbe：Pod 未就绪时探针返回503，K8s 会将其从 Service 端点中摘除，避免流量打到未就绪实例。

多网卡 / 多实例的注意事项

官方文档特别提示：如果机器有多个网络接口且多个 PostgREST 实例共享同一个端口，必须在每个实例的配置中指定唯一的主机名（server-host），健康检查才能正确工作。此时不要使用!4、*等特殊通配地址，否则健康检查可能产生误报（false positive）。

server-host支持的特殊取值（默认!4，见 configuration.rst）：

• *：任意 IPv4 或 IPv6 地址；
• *4：任意 IPv4 或 IPv6 地址，优先 IPv4；
• !4：任意 IPv4 地址；
• *6：任意 IPv4 或 IPv6 地址，优先 IPv6；
• !6：任意 IPv6 地址。

Metrics：Prometheus 指标端点

metrics端点提供Prometheus 文本格式（text/plain）的监控指标：

curl "http://localhost:3001/metrics"

HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 # HELP pgrst_schema_cache_query_time_seconds The query time in seconds of the last schema cache load # TYPE pgrst_schema_cache_query_time_seconds gauge pgrst_schema_cache_query_time_seconds 1.5937927e-2 # HELP pgrst_schema_cache_loads_total The total number of times the schema cache was loaded # TYPE pgrst_schema_cache_loads_total counter pgrst_schema_cache_loads_total 1.0 ...

从 Admin.hs 的源码可见，该端点显式设置了Content-Type: text/plain，注释中特别说明"Content-Type is required for prometheus compliance"（Prometheus 抓取合规要求）。

指标分组详解

指标定义见 observability.rst 与 Metrics.hs。

Schema Cache 指标

连接池指标

其中pgrst_db_pool_available的数值由connected - inUse计算得出（见 Metrics.hs），需要借助连接追踪表才能准确维护，这正是ConnTrack数据结构存在的原因。

JWT 缓存指标

GHC 运行时指标

PostgREST 还支持导出 GHC RTS（运行时系统）指标，前缀为ghc_*，包括 GC 次数、内存分配、最大存活字节数、CPU 与墙钟时间等。这些指标对监控进程健康、诊断内存压力与 GC 行为很有价值。

要启用它们，需要在启动 PostgREST 时打开 RTS 统计：

postgrest +RTS -T -RTS

启用后metrics端点会额外输出如下样本：

# HELP ghc_gcs_total Total number of GCs # TYPE ghc_gcs_total counter ghc_gcs_total 1 # HELP ghc_allocated_bytes_total Total bytes allocated # TYPE ghc_allocated_bytes_total counter ghc_allocated_bytes_total 12345678

可用的 GHC 指标包括：ghc_gcs_total、ghc_major_gcs_total、ghc_allocated_bytes_total、ghc_max_live_bytes、ghc_max_mem_in_use_bytes、ghc_mutator_cpu_seconds_total、ghc_gc_cpu_seconds_total、ghc_elapsed_seconds_total。

在 Metrics.hs 中可以看到，只有getRTSStatsEnabled返回真（即+RTS -T已开启）时才会注册ghcMetrics，与文档描述完全一致。

Runtime Schema Cache：查看运行时缓存

schema_cache端点打印 PostgREST运行时的 Schema Cache 内容，即以 JSON 形式输出当前进程内存中缓存的数据库元数据：

curl "http://localhost:3001/schema_cache"

{ "dbMediaHandlers": ["..."], "dbRelationships": ["..."], "dbRepresentations": ["..."], "dbRoutines": ["..."], "dbTables": ["..."] }

从 Admin.hs 的源码看，该端点从AppState.getSchemaCache读取当前缓存并通过 Aeson 序列化返回，200状态码 + JSON 响应体。

五个字段的含义：

• dbTables：数据库中的表（含列、约束等元数据）；
• dbRelationships：表之间的外键关系；
• dbRoutines：可经 RPC 调用的数据库函数；
• dbRepresentations：资源表示（representation）信息；
• dbMediaHandlers：媒体类型处理器。

该端点对调试"为何某个表/关系/RPC 未出现在 API 中"非常有用——因为 API 的读写计划完全基于这份 Schema Cache 生成（见 SchemaCache.hs）。仓库的 Schema Cache 快照测试 提供了各字段的完整示例输出，例如test_schema_cache_snapshot[dbTables].yaml、test_schema_cache_snapshot[dbRelationships].yaml等，可对照理解各字段的实际数据结构。

注意：Schema Cache 是运行时状态，会随配置重载、数据库变更通知（LISTEN通道）而更新；schema_cache端点打印的始终是当前进程内存中的最新缓存，而非静态快照。

端点行为速查表

其中"其他路径返回404"同样来自源码：admin应用对未匹配的路径统一响应404（见 Admin.hs），表明 Admin Server 只暴露上述四个端点，不存在任何隐藏的调试接口。

测试验证

仓库的 test_admin.py 覆盖了 Admin Server 的核心行为，可作为行为契约参考：

• test_admin_schema_cache：/schema_cache返回200，且响应体包含"dbTables"键与真实表数据；
• test_admin_ready_w_channel/test_admin_ready_wo_channel：无论db-channel-enabled开启与否，/ready均返回200；
• test_admin_ready_includes_schema_cache_state：Schema Cache 加载失败时/ready返回失败状态；
• 此外还有针对/live、/metrics的断言，以及 postgrest.py 中"等待/ready返回 503"的启动辅助逻辑。

同时，postgrest check子命令也会验证 Admin Server 的可达性——test_cli.py 显示，当管理端点可达时输出OK: http://[host]:port/ready，不可达时则输出ERROR并附带原因（连接拒绝、URL 非法等）。

实战：完整部署示例

以下是一个融合了本文全部要点的完整配置示例：

# ---------- 公共 API 服务器 ---------- server-host = "127.0.0.1" server-port = 3000 # 多实例共享端口（K8s 滚动发布时常用） server-reuseport = true # ---------- Admin Server ---------- # 每个实例必须有独立的管理端口 admin-server-host = "127.0.0.1" admin-server-port = 3001 # 或者改用 Unix 套接字（优先级更高，不暴露网络） # admin-server-unix-socket = "/tmp/pgrst-admin.sock" # admin-server-unix-socket-mode = "660" # ---------- 健康检查配套 ---------- # 启用自动恢复（默认开启） db-pool-automatic-recovery = true

部署后即可：

# 存活探测 curl -I "http://127.0.0.1:3001/live" # 就绪探测 curl -I "http://127.0.0.1:3001/ready" # 抓取 Prometheus 指标 curl "http://127.0.0.1:3001/metrics" # 查看运行时 Schema Cache curl "http://127.0.0.1:3001/schema_cache"

若在 Kubernetes 中，可将/live配为livenessProbe、/ready配为readinessProbe；多副本共享端口时务必为每个副本分配唯一的admin-server-port，并保证server-host取值具体明确（不使用*、!4等通配），以确保健康检查结果精确对应到单个实例。

小结

• Admin Server 由admin-server-port或admin-server-unix-socket启用，与公共 API 服务器完全隔离，仅提供运维端点；
• live探测进程存活（检查主线程与主监听 Socket），ready在live基础上叠加 Schema Cache 加载状态，失败时配合自动恢复机制与Retry-After头平滑收敛；
• metrics以 Prometheus 文本格式暴露 Schema Cache、连接池、JWT 缓存与 GHC RTS 指标，是监控 PostgREST 健康度的核心数据源；
• schema_cache可随时导出进程内存中的完整数据库元数据缓存，是排查"表/关系/函数为何不可用"的第一手调试工具；
• 所有端点的行为均可在 Admin.hs 中找到一一对应的实现，并有 test_admin.py 提供自动化验证。

【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrest