故障排查
alpha 时期常见的故障模式以及如何恢复。
Kisenon 处于 alpha 阶段。这里是您最可能遇到的故障模式， 以及如何越过每一个。
端点卡在 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 指引。
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 的错误页面。
可能原因： 在 alpha 期间，登录由一个邮箱允许列表把守。 如果您的地址尚未被纳入，登录回调会在原则上拒绝它。
怎么做： 在 Alpha 访问 申请。一旦您的地址被添加到 允许列表，登录会在下一次尝试时正常完成。
控制台会话在会话中途过期
症状： 控制台工作了一阵子，然后突然在每个 API 调用上返回 401， 直到您登出再登录。
可能原因： 由 cp 签名的 JWT 过期了，并且它的刷新窗口已经结束。
控制台铸造一个短期的 JWT（约 15 分钟），并且在您处于活跃状态时，
在后台对照 /v1/auth/refresh 刷新它。刷新窗口固定为从登录起 12 小时：
一个活跃的会话会无限期续期，但一个被搁置超过那个窗口的标签页就无法
再刷新了。
怎么做： 登出再登录。对于无头或长期运行的自动化，请使用一个
nsk_ API 密钥而非浏览器会话 —— API 密钥不会过期，且只被显式撤销。
参见 身份验证。
在哪里提交 bug
对于这里未涵盖的任何东西：
- 产品 bug 和功能请求： GitHub 追踪器。
- 安全漏洞：安全 —— 绝不在公开追踪器上。
具体的复现步骤、受影响的 id（项目、分支、端点），以及一个挂钟时间戳 会大幅缩短往返时间。