企业官网建设流程全解析

pgbot 是一款面向 PostgreSQL 的只读数据库诊断工具：一个静态二进制，像psql一样通过标准协议连接托管数据库（RDS、Aurora、Neon、Supabase），读取数据库自身的统计视图，输出"发现项优先"的健康报告。它不在数据库上安装任何东西，全程无写权限——这正是它敢直接连生产库的原因。本文带你从零理解 pgbot 的连接模型，并逐一拆解 RDS、Aurora、Neon、Supabase 四大托管平台的连接要点与排障方法。

连接模型：pgbot 只是一个"客户端" 🧭

很多新手的第一反应是"我要在 RDS 实例上装个 agent"——不需要。pgbot 是纯客户端，运行位置可以是：

• 你的笔记本（公开端点的 RDS / Neon / Supabase）
• 与数据库同 VPC 的一台 EC2
• CI 流水线
• 一台堡垒机 / 跳板机

连接后它做三件关键的事（见 internal/conn/connect.go）：

1. 能力探测：一次往返读出服务器版本、扩展、角色权限、平台标记；
2. 连接池封顶 4 条：每次探测都是独立的BEGIN READ ONLY … COMMIT短事务，并固定statement_timeout=15s、lock_timeout=2s——诊断工具绝不能变成它要诊断的事故；
3. 只读身份：真正保证只读的是pg_monitor只读角色，会话参数只是纵深防御。

平台是如何被自动识别的

pgbot 不需要你手动声明"这是 RDS"。它的检测逻辑（internal/conn/provider.go）综合三路信号：

第三条信号意味着即使主机是裸 IP 或藏在代理后面，检测依然有效。识别结果直接决定后续的排障建议：缺pg_stat_statements时，pgbot 会打印你所在平台的专属开启步骤，而不是一句泛泛的"请安装扩展"。

想确认检测结论，随时可以执行：

pgbot inspect "$DATABASE_URL" --json | jq .server

第一次运行：inspect 快速上手

npx @pgbot/cli inspect "postgres://pgbot_ro@host:5432/db?sslmode=require"

推荐把连接串放进环境变量（密码不进入 shell 历史和ps输出）：

export DATABASE_URL="postgres://pgbot_ro:…@host:5432/db?sslmode=require" pgbot inspect

默认报告是一条"分级体检"：四行生命体征仪表（缓存命中、锁等待、回滚、闲置索引）、一行checked列出核查通过的系统、一个健康分，再按 CRITICAL / WARNING / NOTE 分桶列出发现项。

退出码是脚本化契约（对接 CI 时记住它）：0正常 ·1警告 ·2严重 ·3连接/执行失败 ·64参数错误。也就是说，连不上库本身就是 exit 3，你的流水线能立刻区分"库有病"和"连不上"。

RDS 连接排障：三种接入方式

私有 RDS（生产库的常态）

RDS 实例没有 OS 权限，无法装任何东西，所以答案永远是"从一个能触达它的位置运行 pgbot"：

# 在同 VPC 的 EC2 上（或公开实例的笔记本上）： pgbot inspect "postgres://pgbot_ro@mydb.abc123.us-east-1.rds.amazonaws.com:5432/appdb?sslmode=require"

授权与开启 pg_stat_statements

• pg_monitor：RDS 不开放 OS superuser，但用主用户（rds_superuser）执行GRANT pg_monitor TO <role>;完全可行——这就是 pgbot 的全部所需。
• pg_stat_statements：把pg_stat_statements加入DB 参数组的shared_preload_libraries，重启实例，再CREATE EXTENSION pg_stat_statements;。缺了它只会让 queries 部分降级，其他检查照常进行。

📌诚实的边界：CPU / 内存 / 磁盘 IOPS 这类主机指标住在 CloudWatch 里，SQL 连接够不到——这是托管数据库的普遍边界，不是 pgbot 的缺陷。除此之外的检查（查询、索引、锁、复制、检查点、连接、配置）全部可用。

加--full会得到一张子系统状态板：每个子系统一行，ok / warn / fail一目了然，fail 行直接点名根因（比如"锁等待 61%，4f2a 被 91c 阻塞"）。

Aurora 集群：一次体检全部实例 ⚡

Aurora 有个新手容易踩的坑：集群端点背后是多个实例（一个 writer + N 个 reader），任意一个实例上的pg_stat_*都代表不了其他实例。只连集群端点检查一次，可能漏掉 reader 上的问题。

pgbot inspect "$CLUSTER_URL" --all-instances解决它（internal/conn/aurora.go）：

1. 用aurora_replica_status()列出集群成员，writer 排第一；
2. 从集群端点的 DNS 名推导出每个实例的端点（支持cluster-、cluster-ro-、cluster-custom-前缀，自定义域名会跟随 CNAME 链解析到真实 RDS 名）；
3. 用aurora_db_instance_identifier()核验每个推导出的端点确实到达了它声称的那个成员——不猜测；
4. 逐个实例体检，同一套凭据与 TLS 设置。

整个过程只需要 SQL 和 DNS：不需要 AWS 凭据、CLI、SDK 或 API。它还会拒绝无法推导的端点（如 RDS Proxy——成员藏在代理后面），任何成员不可达都会报"部分覆盖"并以 exit 3 退出，而不是假装全部检查过。

上图正是多实例场景下的重要提醒：在 writer 上"零扫描"的索引，reader 可能还在用——扫描计数是每节点的。pgbot 会在indexes输出里主动带上这条"先别删"的警告。

Neon 连接排障：pooler、channel_binding 与冷窗口

pgbot inspect "postgres://user:pass@ep-xxx.region.aws.neon.tech/dbname?sslmode=require"

Neon 上有三个新手最常遇到的现象，pgbot 都已经内置处理：

冷窗口（cold window）是 Neon 排障的核心概念。计算层挂起再唤醒后，pg_stat_statements历史、缓存命中计数、索引扫描数全部从 0 开始。如果 pgbot 照搬旧逻辑，计数器从 40M 掉到 12k 会被误报成"−99.97% 的性能回归"。

pgbot 的做法是降级而不是说谎（阈值定义在 internal/model/context.go 的ColdWindowThresholdSeconds，即 15 分钟）：

• 统计被重置后，deltas整节被抑制并附原因——"从 40M 到 12k 是唤醒，不是 −99.97%"；
• 窗口不足 15 分钟时，基于计数器的发现项（闲置索引、缓存命中、顺序扫描偏重）被抑制；
• 但即时有效的仪表（阻塞链、idle-in-transaction、复制延迟、无效索引）照常报告；
• 报告头会直白地写明窗口年龄。

想拿到连续历史？关闭 scale-to-zero 或调大挂起超时，让统计在两次运行之间存活。

pg_stat_statements在 Neon 上已预加载，一条CREATE EXTENSION pg_stat_statements;即可。

Supabase 连接排障：直连端点优先

Supabase 给你两种连接串，排障前先分清：

# 直连端点（会话级，pgbot 首选）： pgbot inspect "postgres://postgres:pass@db.<ref>.supabase.co:5432/postgres?sslmode=require" # 池化端点（Supavisor 事务池，端口 6543）——也可以，pgbot 会标注并继续： pgbot inspect "postgres://postgres.<ref>:pass@aws-0-<region>.pooler.supabase.com:6543/postgres?sslmode=require"

• 默认连接串走:6543池化端点。pgbot 检测到端口 6543 会自动识别并附注；需要会话级确定性时加--strict-pooler，它会拒绝池化端点并告诉你改用哪个。
• 为什么池化端点也能出正确速率？每个计数器都在自己的事务里读取，而pg_stat_*是集群级共享内存——哪个后端应答读都无关紧要（实现见 internal/conn/pooler.go）。
• Supabase 不发放 superuser：内置postgres角色已有较宽的读权限，允许的地方也可以给专用角色授pg_monitor。
• pg_stat_statements同样已预加载。
• 免费层闲置后会暂停实例——暂停后的首次运行请当作冷窗口看待。

连接排障速查表 🔍

私有网络一步接入：--ssh-tunnel

VPC 里的 RDS、堡垒机后面的 Postgres，用--ssh-tunnel一步到位：

pgbot inspect "postgres://pgbot_ro@db.internal:5432/appdb?sslmode=verify-full" \ --ssh-tunnel bastion.example.com # 或 user@host:port，或 ~/.ssh/config 别名

• --ssh-tunnel是全局参数，所有会建连的命令都认它；$PGBOT_SSH_TUNNEL环境变量可为整个会话设置（internal/conn/sshtunnel.go）。
• 它不是ssh -L端口转发，而是驱动层的 DialFunc：DSN 里保留真实主机名，sslmode=verify-full依然对真实主机名校验证书，.pgpass照常匹配，本机不开放任何端口。
• 跳板机如何连上（User、Port、IdentityFile、StrictHostKeyChecking…）全部读你现有的ssh_config，裸别名直接可用，主机密钥的验证方式和你的ssh完全一致；链路慢就调大--timeout。

可选：让 AI 读懂报告 🤖

export OPENAI_API_KEY=sk-… # 或 GEMINI / ANTHROPIC / XAI 任一密钥 pgbot ask "why is it slow?"

注意分工：发现项永远由 Go 代码确定性计算，模型只负责解释与排序，并且被要求把每一条 caveat 带进建议（比如"复制处于活动状态，先别删这个零扫描索引"）。所有确定性命令（inspect、indexes、queries…）不需要任何密钥，数据不出本机。

收尾：验证你的配置 ✅

pgbot init "$DATABASE_URL" # 生成只读角色 SQL（含平台专属 pg_stat_statements 步骤），只打印不执行 pgbot init --verify "$DATABASE_URL" # 连上后核验角色权限是否齐备

init会先探测你的平台，再生成量身定制的 SQL——Neon/Supabase 只需一条CREATE EXTENSION，RDS 则给出参数组 + 重启的完整步骤（实现见 cmd/pgbot/init.go）。

各平台的完整能力矩阵（谁能授pg_monitor、统计能否跨闲置存活、连接池默认端口……）详见 docs/providers.md；每条发现项都有离线可读的说明页，pgbot explain-finding <id>即可查阅（目录在 docs/findings/）。

一句话总结：pgbot 连不上托管库，多半不是工具的问题，而是"从哪连、用什么角色、统计怎么开"这三件事——本文的速查表和分平台步骤，把它们逐一变成了确定动作。