尧图网页设计 
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 adminApponError的处理值得注意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必须通过配置文件、环境变量或在数据库配置表中设置修改后需重启进程参数类型默认值环境变量说明admin-server-hostString跟随server-hostPGRST_ADMIN_SERVER_HOST管理服务器绑定的主机地址默认继承server-hostadmin-server-portInt无默认不启用PGRST_ADMIN_SERVER_PORT管理服务器监听端口不能等于server-portadmin-server-unix-socketString无PGRST_ADMIN_SERVER_UNIX_SOCKET绑定的 Unix 域套接字路径若设置优先级高于admin-server-portadmin-server-unix-socket-modeString660PGRST_ADMIN_SERVER_UNIX_SOCKET_MODEUnix 套接字文件权限必须是600~777之间的合法八进制数上述参数在 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-portadmin-server-unix-socket /tmp/pgrst-admin.sock admin-server-unix-socket-mode 660admin-server-unix-socket-mode的合法取值范围为600到777八进制。对应源码在 Config.hs 的parseSocketFileMode未设置时默认432即八进制660解析出的权限值若小于600384或大于777511会直接报错。环境变量方式所有管理参数均可通过环境变量注入例如export PGRST_ADMIN_SERVER_PORT3001 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 Checklive 与 ready启用 Admin Server 后会得到live与ready两个健康检查端点。二者均返回状态码 空响应体适合配合curl -I、KuberneteshttpGet探针或负载均衡健康检查使用。live进程存活探测live端点验证 PostgREST 是否正在其配置的端口上运行存活时返回200 OK否则返回500。验证示例admin-server-port为3001curl -I http://localhost:3001/liveHTTP/1.1 200 OK从源码看live的判定依据是checkMainAppLive见 App.hs它同时检查两件事主服务器线程是否仍在运行通过Weak ThreadId的deRefWeak与threadStatus判断主线程是否处于ThreadRunning/ThreadBlocked状态主监听 Socket 是否有效对 TCP 套接字直接调用getSocketName校验对 Unix 域套接字则检查套接字文件是否仍然存在doesPathExist。任一检查失败即判定主应用不存活返回500。ready就绪探测在live的基础上ready端点进一步检查连接池connection pool与Schema Cache的状态两者均健康时返回200 OK不健康时返回503。curl -I http://localhost:3001/readyHTTP/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提示尚未就绪主应用不存活 →500Schema Cache 加载完成isLoaded→200其他异常状态 →500。这与 test_admin.py 中的test_admin_ready_includes_schema_cache_state用例相互印证该测试通过PGRST_INTERNAL_SCHEMA_CACHE_QUERY_SLEEP500人为拉长 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端点非常适合作为 KubernetesreadinessProbePod 未就绪时探针返回503K8s 会将其从 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 地址。MetricsPrometheus 指标端点metrics端点提供Prometheus 文本格式text/plain的监控指标curl http://localhost:3001/metricsHTTP/1.1 200 OK Content-Type: text/plain; charsetutf-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 compliancePrometheus 抓取合规要求。指标分组详解指标定义见 observability.rst 与 Metrics.hs。Schema Cache 指标指标类型说明pgrst_schema_cache_query_time_secondsGauge最近一次 Schema Cache 加载的查询耗时秒pgrst_schema_cache_loads_totalCounterSchema Cache 累计加载次数带status标签SUCCESS/FAIL连接池指标指标类型说明pgrst_db_pool_timeouts_totalCounter连接池获取连接的超时总次数pgrst_db_pool_availableGauge当前可用的连接数pgrst_db_pool_waitingGauge等待获取连接池连接的请求数pgrst_db_pool_maxGauge连接池最大连接数对应db-pool配置其中pgrst_db_pool_available的数值由connected - inUse计算得出见 Metrics.hs需要借助连接追踪表才能准确维护这正是ConnTrack数据结构存在的原因。JWT 缓存指标指标类型说明pgrst_jwt_cache_requests_totalCounterJWT 缓存查找总次数pgrst_jwt_cache_hits_totalCounterJWT 缓存命中总次数pgrst_jwt_cache_evictions_totalCounterJWT 缓存驱逐总次数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端点打印的始终是当前进程内存中的最新缓存而非静态快照。端点行为速查表端点方法成功响应失败响应响应体/liveGET/HEAD200500空/readyGET/HEAD200503加载中/500主应用异常空/schema_cacheGET200—JSON 格式的运行时 Schema Cache/metricsGET200text/plain—Prometheus 文本格式指标其他路径GET404—空其中其他路径返回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均返回200test_admin_ready_includes_schema_cache_stateSchema 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探测进程存活检查主线程与主监听 Socketready在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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 adminApponError的处理值得注意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必须通过配置文件、环境变量或在数据库配置表中设置修改后需重启进程参数类型默认值环境变量说明admin-server-hostString跟随server-hostPGRST_ADMIN_SERVER_HOST管理服务器绑定的主机地址默认继承server-hostadmin-server-portInt无默认不启用PGRST_ADMIN_SERVER_PORT管理服务器监听端口不能等于server-portadmin-server-unix-socketString无PGRST_ADMIN_SERVER_UNIX_SOCKET绑定的 Unix 域套接字路径若设置优先级高于admin-server-portadmin-server-unix-socket-modeString660PGRST_ADMIN_SERVER_UNIX_SOCKET_MODEUnix 套接字文件权限必须是600~777之间的合法八进制数上述参数在 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-portadmin-server-unix-socket /tmp/pgrst-admin.sock admin-server-unix-socket-mode 660admin-server-unix-socket-mode的合法取值范围为600到777八进制。对应源码在 Config.hs 的parseSocketFileMode未设置时默认432即八进制660解析出的权限值若小于600384或大于777511会直接报错。环境变量方式所有管理参数均可通过环境变量注入例如export PGRST_ADMIN_SERVER_PORT3001 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 Checklive 与 ready启用 Admin Server 后会得到live与ready两个健康检查端点。二者均返回状态码 空响应体适合配合curl -I、KuberneteshttpGet探针或负载均衡健康检查使用。live进程存活探测live端点验证 PostgREST 是否正在其配置的端口上运行存活时返回200 OK否则返回500。验证示例admin-server-port为3001curl -I http://localhost:3001/liveHTTP/1.1 200 OK从源码看live的判定依据是checkMainAppLive见 App.hs它同时检查两件事主服务器线程是否仍在运行通过Weak ThreadId的deRefWeak与threadStatus判断主线程是否处于ThreadRunning/ThreadBlocked状态主监听 Socket 是否有效对 TCP 套接字直接调用getSocketName校验对 Unix 域套接字则检查套接字文件是否仍然存在doesPathExist。任一检查失败即判定主应用不存活返回500。ready就绪探测在live的基础上ready端点进一步检查连接池connection pool与Schema Cache的状态两者均健康时返回200 OK不健康时返回503。curl -I http://localhost:3001/readyHTTP/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提示尚未就绪主应用不存活 →500Schema Cache 加载完成isLoaded→200其他异常状态 →500。这与 test_admin.py 中的test_admin_ready_includes_schema_cache_state用例相互印证该测试通过PGRST_INTERNAL_SCHEMA_CACHE_QUERY_SLEEP500人为拉长 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端点非常适合作为 KubernetesreadinessProbePod 未就绪时探针返回503K8s 会将其从 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 地址。MetricsPrometheus 指标端点metrics端点提供Prometheus 文本格式text/plain的监控指标curl http://localhost:3001/metricsHTTP/1.1 200 OK Content-Type: text/plain; charsetutf-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 compliancePrometheus 抓取合规要求。指标分组详解指标定义见 observability.rst 与 Metrics.hs。Schema Cache 指标指标类型说明pgrst_schema_cache_query_time_secondsGauge最近一次 Schema Cache 加载的查询耗时秒pgrst_schema_cache_loads_totalCounterSchema Cache 累计加载次数带status标签SUCCESS/FAIL连接池指标指标类型说明pgrst_db_pool_timeouts_totalCounter连接池获取连接的超时总次数pgrst_db_pool_availableGauge当前可用的连接数pgrst_db_pool_waitingGauge等待获取连接池连接的请求数pgrst_db_pool_maxGauge连接池最大连接数对应db-pool配置其中pgrst_db_pool_available的数值由connected - inUse计算得出见 Metrics.hs需要借助连接追踪表才能准确维护这正是ConnTrack数据结构存在的原因。JWT 缓存指标指标类型说明pgrst_jwt_cache_requests_totalCounterJWT 缓存查找总次数pgrst_jwt_cache_hits_totalCounterJWT 缓存命中总次数pgrst_jwt_cache_evictions_totalCounterJWT 缓存驱逐总次数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端点打印的始终是当前进程内存中的最新缓存而非静态快照。端点行为速查表端点方法成功响应失败响应响应体/liveGET/HEAD200500空/readyGET/HEAD200503加载中/500主应用异常空/schema_cacheGET200—JSON 格式的运行时 Schema Cache/metricsGET200text/plain—Prometheus 文本格式指标其他路径GET404—空其中其他路径返回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均返回200test_admin_ready_includes_schema_cache_stateSchema 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探测进程存活检查主线程与主监听 Socketready在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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考