疑难解答

以下是你最有可能遇到的故障模式，以及如何度过其中每一个。

端点卡在 `Pending`

症状： 一个端点在创建时于 Pending 停留超过几秒。控制台不显示任何错误；CLI 显示相同的状态。

可能原因： 计算 pod 无法被调度。最常见的原因是集群压力（没有节点有请求的 CPU 或内存空闲）或一个过期的镜像拉取凭据。两者都是运维方侧的问题。

该怎么做：

等待 60 秒。瞬时压力通常在另一个端点挂起后就会消散。
如果它没有消散，删除该端点并重新创建。控制平面会在另一个节点上重试调度。
如果重新创建也落在 Pending，说明集群不健康。在 GitHub 跟踪器提交一个报告，附上端点 id 和挂钟时间。

首次连接时出现 `FATAL: endpoint unavailable`

症状： psql 在对一个全新创建的端点的第一次连接时，或在长时间空闲之后，返回 FATAL: endpoint unavailable。

可能原因： 冷启动竞态。端点状态为 Stopped，你的数据包唤醒了它，但 Postgres 在你的客户端放弃时仍在将 WAL 重放到分支 HEAD。

该怎么做： 重试连接。冷启动通常在 300–500 毫秒内完成，但一个全新创建项目的第一次唤醒，或 24 小时以上空闲之后的一次，在 pageserver 页面缓存预热期间可能需要 10–30 秒。如果你允许至少一次重试，大多数驱动都能容忍这一点；原始的 psql 默认不会重试。

# psql with one explicit retry
for i in 1 2; do psql "$URI" -c '\q' && break; sleep 5; done

如果端点在 30 秒后仍然不可用，pod 本身可能已经失败 —— 在控制台中检查状态并参照上面的 Pending 指引。

从一个新 IP 连接被拒绝 / 超时

症状： 一个之前连接正常的客户端在移动到新网络后被拒绝或超时，或者一个全新预置的主机根本无法到达项目。

可能原因： 项目有一个 IP 白名单，而新客户端的地址在每个列出的 CIDR 之外。未列入白名单的来源会在代理处被拒绝，且该阻断覆盖唤醒路径。

该怎么做： 添加客户端的 CIDR（keon ip-allow add <cidr>）或清空列表，然后等待约 30 秒让更改传播到代理。

`keon connection-string` 返回 `branch_not_found`

症状：

$ keon connection-string my-feature --project prj_abc...
Error: branch_not_found: my-feature

……但该分支在控制台中存在。

可能原因： 名称与你所定位项目中的某个分支不匹配 —— 通常是拼写错误，或错误的 --project。CLI 会按 id 或按名称解析一个分支，无论你是将其作为位置参数还是通过 --branch 传入，因此一个确实存在的名称无论哪种方式都会解析。

该怎么做： 确认分支名称和项目：

keon branches list --project prj_abc...
keon connection-string my-feature --project prj_abc...

登录返回 `access_denied`

症状： Google 或 GitHub OAuth 完成，但控制台重定向到一个引用 access_denied 的错误页面。

可能原因： 在我们接纳新账户期间，登录可能被一个邮箱白名单门控。如果你的地址尚未被启用，登录回调会拒绝它。

该怎么做： 联系你的运维方以启用你的地址。一旦它被加入白名单，登录会在下一次尝试时正常完成。

控制台会话中途过期

症状： 控制台工作一段时间，然后突然在每个 API 调用上返回 401，直到你登出并重新登录。

可能原因： 由 cp 签名的 JWT 已过期且其刷新窗口已失效。控制台铸造一个短生命周期的 JWT（约 15 分钟），并且在你活跃期间，在后台针对 /v1/auth/refresh 刷新它。刷新窗口固定为自登录起 12 小时：一个活跃会话会无限期地续期，但一个在该窗口之后被搁置未动的标签页将不再能刷新。

该怎么做： 登出并重新登录。对于无头或长期运行的自动化，使用一个 nsk_ API 密钥而非浏览器会话 —— API 密钥不会过期且需显式吊销。参见身份验证。

在哪里提交缺陷

对于此处未涵盖的任何内容：

产品缺陷和功能请求： GitHub 跟踪器。
安全漏洞：安全 —— 绝不在公开跟踪器上提交。

具体的复现步骤、受影响的 id（项目、分支、端点），以及一个挂钟时间戳，会大幅缩短往返时间。

端点卡在 Pending

首次连接时出现 FATAL: endpoint unavailable