健康检查与就绪探针

wesgine 的 /health 与 /metrics 基础设施路由。

端点

健康检查

GET /health

• 无需认证
• 表达进程 liveness
• 返回 Hypervisor 生命周期状态

Prometheus 指标

GET /metrics

• 公开或需 admin token
• Prometheus 格式指标输出

生命周期状态

Hypervisor 的三种生命周期状态：

SDK:

hyp.LifecycleState() string // starting | ready | draining
hyp.StartedAt() time.Time   // 进程 boot 完成时刻

启动时序（INV-SERVE-REACHABLE-01）

wesgine serve 到达"可被探活"所需的时间必须是有界常数，不得正比于租户数或数据库体积。

顺序约束

router.Start（绑端口）→ sdnotify.Ready() → ActivatePersisted（后台 goroutine）

ActivatePersisted 在 sdnotify.Ready() 之后、后台 goroutine 里跑。

为什么这很重要

每一个盯着这个进程的监督者都用固定超时判死：

• systemd TimeoutStartSec
• teleclaw watchdog 5s 探针 × 3 次
• 负载均衡器

把一个随数据增长的操作放在可达性之前，等于保证部署跑够久之后必然穿过某个固定阈值。

Cell 中间件与温度

Gateway 中间件对不同温度的 Cell 有不同行为：

热身可被取消

ActivatePersisted 的循环每轮查 ctx.Err()：

• SIGTERM 后停止继续 boot
• 避免在已排空的 Cell 上继续 boot
• 防止 TimeoutStopSec 升级成 SIGKILL

跳过热身不损失正确性

Cool/Cold Cell 的请求由中间件处理：

• Cool 首请求同步 WarmUp
• Cold 回 503 + Retry-After

代价：Cron/IMAP 推迟到下次热身才恢复——用可预期的延迟换掉不可预期的不可达。

消费方探活

wesclaw 桌面

// HealthHandler.Check 调用 h.DB.PingContext(ctx) 验证 wesclaw.db 可达

wesclaw SaaS

引擎 LifecycleState() != "ready" 时返回 503。

teleclaw

EngineHealthWatchdog 每轮探针：

• 5s 超时 × 3 次失败判死
• activating 状态不判死
• 重启前先 reset-failed

版本信息

hyp.Version() string // SDK 版本

启动后记录版本——版本降级可能静默毁数据（2026-09 teleclaw 实证）。