PgHero Docker 部署指南：从安装、认证到多数据库与 Kubernetes 生产实践

数据库可观测性运维【免费下载链接】pgheroA performance dashboard for Postgres项目地址https://gitcode.com/gh_mirrors/pg/pghero点击查看免费下载本文围绕 PgHero 官方 Docker 部署方式guides/Docker.md展开覆盖镜像拉取、环境变量配置、Basic Auth、历史 Query/Space 统计、系统指标采集Amazon RDS 与 Google Cloud SQL、多数据库定制、健康检查与 Kubernetes 部署以及 4.0 升级迁移。读者可以按本文步骤独立搭建一套可用的 PgHero 性能监控面板并理解各配置项在源码中的真实作用。什么是 PgHero DockerPgHero 是一个面向 PostgreSQL 的性能仪表盘官方同时提供两种安装方式Docker 镜像与 Rails 引擎。对于不想引入 Rails 依赖、希望以独立容器快速监控一个或多个 Postgres 实例的场景Docker 镜像是成本最低的路径。PgHero 官方镜像发布在 Docker Hub镜像名为ankane/pghero容器内部基于 Rack/Rails 应用封装镜像自带bin/rake因此除了启动仪表盘之外还可以直接在容器中运行 PgHero 的采集、清理等 rake 任务。这一点是理解下文所有命令的前提。安装与启动拉取镜像docker pull ankane/pghero启动仪表盘docker run -ti -e DATABASE_URLpostgres://user:passwordhostname:5432/dbname -p 8080:8080 ankane/pghero参数说明DATABASE_URL被监控数据库的连接串。用户名或密码中包含特殊字符时必须做 URL 编码例如密码中的需写成%40、:写成%3A。-p 8080:8080将容器 8080 端口映射到宿主机访问http://localhost:8080打开仪表盘。如果被监控的数据库跑在宿主机上容器内不能直接使用localhost访问宿主机应改用host.docker.internal作为主机名在 Linux 上还需要额外加上--add-hosthost.docker.internal:host-gateway参数。启动后即进入仪表盘可查看总览、连接数、慢查询、实时查询、索引、空间、系统指标配置后等页面。对应页面路由定义在 config/routes.rb例如根路径root to: home#index指向总览页。从源码结构看当没有提供pghero.yml配置文件时DATABASE_URL会被解析为默认配置中的主数据库见 lib/pghero.rb 中default_config方法。DATABASE_URL实际上会映射到PgHero::Connection连接模型连接建立时还会自动附加connect_timeout5作为安全兜底见 lib/pghero/database.rb。认证Authentication仪表盘默认完全开放。如果需要保护有两种方式。方式一内置 Basic Auth通过环境变量开启 HTTP Basic 认证docker run -e PGHERO_USERNAMElink -e PGHERO_PASSWORDhyrule ...源码中对应实现位于 app/controllers/pg_hero/home_controller.rbhttp_basic_authenticate_with name: PgHero.username, password: PgHero.password if PgHero.password即只要设置了PGHERO_PASSWORD全部页面路由都会要求 Basic 认证用户名默认读取PGHERO_USERNAME两个变量都可覆盖为空值或缺失。二者读取逻辑见 lib/pghero.rb优先取pghero.yml中的username/password再回落到环境变量。方式二反向代理认证可以将 PgHero 置于反向代理之后由代理层完成认证例如OAuth2 ProxyOAuth/OIDC 网关AWS ALB Authentication负载均衡器级别的认证Google Identity-Aware ProxyIAP。此时 PgHero 内部可以不开启 Basic Auth认证完全交给代理层适合对接企业统一身份体系。Query Stats查询统计查询统计功能可以从仪表盘界面一键开启。开启动作对应路由POST /enable_query_stats控制器方法enable_query_stats调用数据库的enable_query_stats见 app/controllers/pg_hero/home_controller.rb。底层依赖 PostgreSQL 的pg_stat_statements扩展PgHero 通过检测pg_available_extensions判断可用性、通过pg_extension判断是否已启用见 lib/pghero/methods/query_stats.rb。如果开启过程中遇到权限不足等问题请参阅 Query Stats 指南。Historical Query Stats历史查询统计默认的查询统计只反映当前统计周期。要按时间追踪查询表现需要额外建表并定时采集。建表以下 SQL 可以在被监控数据库或另一个专门的统计数据库中执行CREATE TABLE pghero_queries ( id bigserial PRIMARY KEY, query text ); CREATE INDEX ON pghero_queries USING hash (query); CREATE TABLE pghero_query_stats ( id bigserial PRIMARY KEY, database text, user text, query_id bigint, query_hash bigint, total_time float, calls bigint, captured_at timestamp ); CREATE INDEX ON pghero_query_stats (database, captured_at);字段说明pghero_queries查询文本字典表query_id通过哈希索引的query字段关联pghero_query_stats每次采样的快照total_time总耗时毫秒、calls调用次数、captured_at采样时间。如果统计表放在另一个数据库中需要额外设置PGHERO_STATS_DATABASE_URL环境变量让采集命令把统计数据写入独立库。对应源码读取位置为 lib/pghero.rb 的stats_database_url。定时采集建议每 5 分钟执行一次docker run -ti -e DATABASE_URL... ankane/pghero bin/rake pghero:capture_query_stats该任务定义在 lib/tasks/pghero.rake内部调用PgHero.capture_query_stats遍历所有配置数据库并逐个采样见 lib/pghero.rb。采样逻辑位于lib/pghero/methods/query_stats.rb支持按current/historical模式聚合。完成首次采集后Queries 标签页会出现时间范围滑块可按时间窗查看历史查询趋势对应视图 app/views/pg_hero/home/_query_stats_slider.html.erb。清理旧数据docker run -ti -e DATABASE_URL... ankane/pghero bin/rake pghero:clean_query_stats KEEP_DAYS14KEEP_DAYS决定保留最近 N 天的数据其余删除。任务内部把KEEP_DAYS换算成before时间点再调用PgHero.clean_query_stats逐数据库清理见 lib/tasks/pghero.rake 与 lib/pghero.rb。Historical Space Stats历史空间统计类似地空间占用表/索引大小也可以按时间记录。建表CREATE TABLE pghero_space_stats ( id bigserial PRIMARY KEY, database text, schema text, relation text, size bigint, captured_at timestamp ); CREATE INDEX ON pghero_space_stats (database, captured_at);记录每个 schema 下每个 relation 在某时刻的size字节。定时采集建议每天执行一次docker run -ti -e DATABASE_URL... ankane/pghero bin/rake pghero:capture_space_stats同样定义于 lib/tasks/pghero.rake调用PgHero.capture_space_statslib/pghero.rb空间统计的具体采样实现在lib/pghero/methods/space.rb中。清理旧数据docker run -ti -e DATABASE_URL... ankane/pghero bin/rake pghero:clean_space_stats KEEP_DAYS90System Stats系统指标CPU 使用率、IOPS 等系统级指标目前支持 Amazon RDS 与 Google Cloud SQL 两种托管服务通过各自的监控 API 拉取。Amazon RDS设置以下环境变量AWS_ACCESS_KEY_IDmy-access-key AWS_SECRET_ACCESS_KEYmy-secret AWS_REGIONus-east-1 PGHERO_DB_INSTANCE_IDENTIFIERmy-instance需要对应的 IAM 策略{ Version: 2012-10-17, Statement: [ { Effect: Allow, Action: cloudwatch:GetMetricStatistics, Resource: * } ] }即要求访问 AWS CloudWatch 的GetMetricStatistics权限来读取 RDS 实例的监控指标。注意PGHERO_DB_INSTANCE_IDENTIFIER只在未使用配置文件时生效。从 lib/pghero.rb 可见环境变量会被注入默认配置中唯一数据库的aws_db_instance_identifier字段一旦使用pghero.yml则必须在配置文件的数据库条目里显式声明该字段参考 lib/pghero/database.rb 的注释。Google Cloud SQL设置以下环境变量GOOGLE_APPLICATION_CREDENTIALSpath/to/credentials.json PGHERO_GCP_DATABASE_IDmy-project:my-instance其中GOOGLE_APPLICATION_CREDENTIALS指向服务账号 JSON 密钥文件PGHERO_GCP_DATABASE_ID格式为项目ID:实例ID。服务账号需要具备 Monitoring Viewer监控查看器角色才能读取 Cloud SQL 监控数据。定制化与多数据库pghero.yml配置格式创建pghero.yml支持同时配置多个数据库和全局行为参数databases: main: url: % ENV[DATABASE_URL] % # System stats # aws_db_instance_identifier: my-instance # gcp_database_id: my-project:my-instance # Add more databases # other: # url: % ENV[OTHER_DATABASE_URL] % # Minimum time for long running queries # long_running_query_sec: 60 # Minimum average time for slow queries # slow_query_ms: 20 # Minimum calls for slow queries # slow_query_calls: 100 # Minimum connections for high connections warning # total_connections_threshold: 500 # Explain functionality # explain: true / false / analyze # Statement timeout for explain # explain_timeout_sec: 10 # Visualize URL for explain # visualize_url: https://... # Time zone # time_zone: Pacific Time (US Canada)配置项含义与源码对照配置项作用源码位置databases.id.url各数据库连接串支持 ERB 引用环境变量lib/pghero/database.rbdatabases.id.aws_db_instance_identifierRDS 实例 ID启用 RDS 系统指标lib/pghero/database.rbdatabases.id.gcp_database_idCloud SQL 实例 ID启用 GCP 系统指标lib/pghero/database.rblong_running_query_sec长查询判定阈值秒默认 60lib/pghero.rbslow_query_ms慢查询平均耗时阈值毫秒默认 20lib/pghero.rbslow_query_calls慢查询最低调用次数默认 100lib/pghero.rbtotal_connections_threshold高连接数告警阈值默认 500lib/pghero.rbexplainEXPLAIN 功能true/false/analyzelib/pghero.rbexplain_timeout_secEXPLAIN 语句超时秒默认 10lib/pghero.rbvisualize_urlEXPLAIN 结果可视化 URLlib/pghero.rbtime_zone仪表盘时区lib/pghero/engine.rb几点值得注意的源码细节配置值存在文件 → 全局 → 环境变量的三级回退链。例如slow_query_ms在 lib/pghero/database.rb 中依次取数据库级配置、全局配置、默认值配置文件使用 ERB 渲染后经 YAML 解析YAML.safe_load支持 aliases见 lib/pghero.rb因此可以放心使用% ENV[...] %引用环境变量这些参数同样可以分别用PGHERO_LONG_RUNNING_QUERY_SEC、PGHERO_SLOW_QUERY_MS等环境变量覆盖lib/pghero.rb完整的配置模板含username/password、stats_database_url、AWS 配置、disable_kill、filter_data等更多选项可参考 Rails 安装时生成的模板文件 lib/generators/pghero/templates/config.yml.tt。构建自定义镜像创建DockerfileFROM ankane/pghero COPY pghero.yml /app/config/pghero.yml构建docker build -t my-pghero .容器内配置文件的默认加载路径为/app/config/pghero.yml对应源码config_path默认值config/pghero.yml见 lib/pghero.rb。构建完成后用docker run启动my-pghero即可。部署Deployment健康检查使用/health端点做健康检查返回 HTTP200即表示健康。Kubernetes 的 liveness/readiness probe、负载均衡的健康检查都可以指向该端点。Kubernetes 部署如果要在 Kubernetes 中带配置文件运行无需重建镜像通过 ConfigMap 挂载配置文件即可。先创建 ConfigMap--- apiVersion: v1 kind: ConfigMap metadata: name: pghero data: pghero.yml: |- databases: main: url: % ENV[DATABASE_URL] % # Add more databases # other: # url: % ENV[OTHER_DATABASE_URL] % # Minimum time for long running queries # long_running_query_sec: 60 # Minimum average time for slow queries # slow_query_ms: 20 # Minimum calls for slow queries # slow_query_calls: 100 # Minimum connections for high connections warning # total_connections_threshold: 500 # Explain functionality # explain: true / false / analyze # Statement timeout for explain # explain_timeout_sec: 10 # Visualize URL for explain # visualize_url: https://... # Time zone # time_zone: Pacific Time (US Canada)再创建 Deployment把 ConfigMap 作为单文件挂载到/app/config/pghero.yml--- apiVersion: apps/v1 kind: Deployment metadata: name: pghero labels: app: pghero spec: selector: matchLabels: app: pghero replicas: 1 template: metadata: labels: app: pghero spec: containers: - name: pghero image: ankane/pghero imagePullPolicy: Always volumeMounts: - name: pghero-configmap mountPath: /app/config/pghero.yml readOnly: true subPath: pghero.yml volumes: - name: pghero-configmap configMap: defaultMode: 0644 name: pghero要点mountPath必须指向容器内的/app/config/pghero.yml使用subPath: pghero.yml挂载单个文件避免 ConfigMap 的目录挂载覆盖容器内其他文件DATABASE_URL仍通过环境变量注入ConfigMap 中的 ERB% ENV[DATABASE_URL] %会在容器启动时由 PgHero 渲染解析。权限建议强烈建议为 PgHero 创建专用数据库用户只授予监控所需的只读权限而不是使用超级用户。具体权限清单与授权 SQL 请参考 Permissions 指南。这也是历史统计采集任务安全运行的基线。升级到 4.0如果你启用了历史查询统计Historical Query Stats升级到 PgHero 4.0 时需要迁移统计表结构。4.0 将查询文本从pghero_query_stats.query拆分为独立的pghero_queries表并以query_id关联。迁移 SQLCREATE TABLE pghero_queries ( id bigserial PRIMARY KEY, query text ); CREATE INDEX ON pghero_queries USING hash (query); ALTER TABLE pghero_query_stats ADD COLUMN query_id bigint; INSERT INTO pghero_queries (query) SELECT DISTINCT query FROM pghero_query_stats WHERE query IS NOT NULL; UPDATE pghero_query_stats SET query_id pghero_queries.id, query NULL FROM pghero_queries WHERE pghero_queries.query pghero_query_stats.query; ALTER TABLE pghero_query_stats DROP COLUMN query; VACUUM (FULL, ANALYZE) pghero_query_stats;执行顺序建立pghero_queries字典表给pghero_query_stats增加query_id列将去重后的 query 文本灌入字典表用query文本回填query_id并清空原query列删除旧query列VACUUM (FULL, ANALYZE)收缩并重建表消除历史数据带来的膨胀。完成迁移后历史统计功能与 4.0 的新表结构保持一致。Rails 方式升级可参考 Rails 指南。小结从一条docker run命令到带认证、历史统计、多数据库、云监控和 Kubernetes 编排的完整监控体系PgHero 的 Docker 部署方式覆盖了从开发到生产的全部常见场景。理解pghero.yml的配置层级与各环境变量的回退规则就能精确控制仪表盘的每一项行为而历史统计的采集/清理任务配合调度器则是让 Queries 与 Space 页面具备趋势分析能力的前提。赞分享数据库可观测性运维【免费下载链接】pgheroA performance dashboard for Postgres项目地址https://gitcode.com/gh_mirrors/pg/pghero点击查看免费下载相关推荐Django双因素认证完全指南从安装到生产部署Django双因素认证完全指南从安装到生产部署 为什么需要双因素认证 你是否还在仅依靠密码保护Django应用2024年OWASP报告显示81%的数据泄应用安全后端Litestream 生产部署完整指南从 systemd、Docker 到 KubernetesLitestream 生产部署完整指南从 systemd、Docker 到 Kubernetes Litestream 是一款面向 SQLite 的轻量级流式数据库数据同步灾备高可用WiFi-DensePose 生产部署指南从单机 Docker 到 Kubernetes、多云与可观测体系实战WiFi DensePose 生产部署指南从单机 Docker 到 Kubernetes、多云与可观测体系实战 本篇技术指南以 archive/v1/docs人工智能计算机视觉物联网智能家居后端嵌入式上一篇前端工程化趋势lint-staged 在现代开发中的角色下一篇为什么选择OpenTrashmail开源临时邮件解决方案的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考