A2X 心跳保活模块设计
适用 v0.1.8+。本文件面向运维 / 开发者。基本用法见 README.md 与 client/README.md 的相关章节;本文聚焦设计原理、文件布局、模块依赖与状态机不变式。
1. 定位与设计原则
注册中心默认行为:服务一旦注册,永久存在直到显式 deregister。这会让 crash / OOM / 网络断的服务在注册表里留下"幽灵条目"。
心跳模块为每个 service 引入一个带 TTL 的租约:客户端必须周期性续约,否则 sweeper 把服务从可见列表中剔除(mark unhealthy),grace period 之后真正删除。设计严格遵守 A2X 项目的两条铁律:
| 层级 | 默认 | 启用方式 | 行为 |
|---|---|---|---|
| 注册中心整体 | 心跳模块始终加载 | — | 仅当 namespace 显式启用 + 客户端显式声明 TTL 时才生成 lease;其他情况零开销 |
| Namespace | lease_config.enabled=false |
admin POST /api/datasets/{ds}/lease-config |
默认 namespace 永远不接受 lease_ttl;既有数据集与既有客户端零影响 |
三档租约状态:
| 状态 | 触发 | 对外行为 |
|---|---|---|
| HEALTHY | 注册成功 / 收到心跳 | list_services 出现;reserve 可选;get_agent 正常 |
| UNHEALTHY | TTL 过期 | list_services 默认过滤(?include_unhealthy=true 才可见);reserve 跳过;get_agent 仍返回 |
| HARD-DELETED | UNHEALTHY 持续 grace_period |
sid 彻底消失,api_config.json 重写 |
关键不变式:心跳过期不直接删除,留出 grace 窗口;任何阶段收到心跳都回到 HEALTHY;硬删走和 admin DELETE 一模一样的代码路径(无第二条删除分支)。
2. 数据模型
2.1 RegistryEntry.lease_ttl(持久化)
a2x_registry/register/models.py 的 RegistryEntry 新增字段:
class RegistryEntry(BaseModel):
...
lease_ttl: Optional[int] = None
| 取值 | 含义 |
|---|---|
None |
永久服务 / 来自 user_config.json / 注册时 namespace 没启用心跳 / 客户端没传 TTL |
int > 0 |
客户端注册时声明的 TTL(秒);服务端用它来计算续约后的新 expires_at |
为什么必须持久化:注册中心重启后面对一个已注册的服务,必须知道"客户端期望我用多长 TTL 来续约"。否则下次心跳来了不知道把 expires_at 设到多远。
序列化策略:None 值不写入 api_config.json(omit-when-None)—— 这样心跳启用前注册的服务的输出与新版本 byte-equal,向前兼容 lockfile 测试依赖此。
2.2 HeartbeatLease(内存)
a2x_registry/heartbeat/models.py:
@dataclass
class HeartbeatLease:
ttl_seconds: int # 来自 RegistryEntry.lease_ttl
grace_period_seconds: int # 来自 namespace 的 lease_config
expires_at: float # monotonic 时钟:HEALTHY → UNHEALTHY 时刻
grace_deadline: float # monotonic:UNHEALTHY → 硬删时刻
last_heartbeat_at: float # monotonic
state: HBState # HEALTHY | UNHEALTHY
为什么不持久化运行时状态:① expires_at 每次心跳都变 → 持久化等于把心跳成本放大成磁盘 I/O;② 重启后跨时间是脏的(磁盘上的值实际已过期);③ 重启已经有 grace_period 兜底机制。
重启恢复:a2x_registry/backend/startup.py 在 warmup 中读取所有 lease_ttl != None 的 entry,调 HeartbeatStore.recover_from_persisted,给每个 entry 重新植入一个 UNHEALTHY 状态的 lease,grace_deadline = now + grace_period。客户端有一个 grace 窗口重新心跳,否则 sweeper 硬删。
3. Per-namespace 配置
database/<namespace>/
├── service.json
├── api_config.json
├── register_config.json
├── vector_config.json
├── auth_config.json
├── lease_config.json # 新增 —— 缺失即 enabled=false
└── ...
lease_config.json schema(a2x_registry/register/store.py LEASE_CONFIG_DEFAULT):
{
"enabled": true,
"min_ttl": 10,
"max_ttl": 3600,
"grace_period": 300,
"schema_version": 1
}
读取走 RegistryStore.load_lease_config() → RegistryService.get_lease_config()(lazy 缓存)。写入走 admin-or-anon 网关:未启用 auth 模块的注册中心允许任何调用方配置(开发友好);启用 auth 后必须 admin 角色。set_lease_config 同步缓存失效。
4. 四角矩阵
客户端注册 (POST /api/datasets/{ds}/services/a2a) 时可以传 lease_ttl。组合矩阵:
namespace enabled |
client lease_ttl |
结果 |
|---|---|---|
| ❌ | ❌ | ✅ 永久服务(向前兼容) |
| ❌ | ✅ | 400 heartbeat_not_supported |
| ✅ | ❌ | 400 ttl_required + 响应 body 携带 min_ttl / max_ttl |
| ✅ | ✅ in range | ✅ 200 + 响应含 lease_ttl / lease_expires_at |
| ✅ | ✅ out of range | 400 ttl_out_of_range + 响应含 min_ttl / max_ttl |
校验逻辑集中在 a2x_registry/heartbeat/store.py 的 HeartbeatStore.validate() —— 纯检查、无副作用。注册流程:
1. router 调 store.validate(ds, ttl) # 4-corner 矩阵;可能 raise HeartbeatError
2. router 调 svc.register_a2a(req, ctx) # 落 RegistryEntry,lease_ttl 字段写入磁盘
3. router 调 store.install(ds, sid, ttl) # 在内存 HeartbeatStore 安装 lease(健康态)
4. router 返回 RegisterResponse{..., lease_ttl, lease_expires_at}
先 validate,再 register,再 install:validate 没副作用所以可前置;register 成功后才 install lease,避免"注册失败但留下幽灵 lease"。
错误响应统一通过 _run 的 HeartbeatError → 400 分支,body 形如:
{
"detail": {
"code": "ttl_out_of_range",
"detail": "lease_ttl=999 out of range [10, 3600] for namespace 'foo'.",
"min_ttl": 10,
"max_ttl": 3600
}
}
客户端 SDK 用 code 字段派发到 A2XTTLOutOfRangeError / A2XTTLRequiredError / A2XHeartbeatNotSupportedError(详见客户端 README)。
5. 端点
5.1 配置
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | /api/datasets/{ds}/lease-config |
匿名 | 读 namespace 配置,SDK 探测用 |
| POST | /api/datasets/{ds}/lease-config |
admin-or-anon | 启用 / 改 / 关 |
5.2 心跳
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| POST | /api/datasets/{ds}/services/{sid}/heartbeat |
跟随 namespace 的 authorize 策略 |
续约;可选 body {status?} 顺手更新 agent_card.status |
| DELETE | /api/datasets/{ds}/services/{sid}/heartbeat |
同上 | 默认软撤销(mark unhealthy + 走 grace);{permanent: true} 直接硬删 |
注册端点本身(POST /services/a2a / /services/generic)在 request body 上新增 lease_ttl 可选字段,响应 body 新增 lease_ttl / lease_expires_at。其他既有字段不变。
6. List / Reserve 的过滤
新增 query 参数 include_unhealthy,默认 false:
GET /api/datasets/{ds}/services?include_unhealthy=false # 默认,过滤掉 UNHEALTHY
GET /api/datasets/{ds}/services?include_unhealthy=true # 运维查全部(含 UNHEALTHY,不含 HARD-DELETED)
include_unhealthy 与既有 include_leased 独立、可叠加;一个服务可能同时被预约且心跳过期。
POST /reservations 自动跳过 unhealthy 候选——你不想锁住一个反正不可达的服务。
实现:a2x_registry/register/service.py 的 RegistryService.is_unhealthy(ds, sid) -> bool 是一个回调代理,默认实现是 lambda d, s: False(heartbeat 模块未加载时);backend startup 把 HeartbeatStore.is_unhealthy 注入进来。Router 在 list/reserve 循环里调 svc.is_unhealthy(...)。register/ 永远不 import heartbeat/。
7. Sweeper
a2x_registry/heartbeat/sweeper.py:单一后台 daemon thread,周期 5s(生产默认)。每次 tick:
newly_unhealthy, to_hard_delete = store.sweep_tick(now=time.monotonic())
for (ds, sid) in to_hard_delete:
registry_svc.deregister(ds, sid, caller=SYSTEM_CTX)
SYSTEM_CTX 是合成的 admin AuthContext(a2x_registry/heartbeat/system_ctx.py),让 sweeper 走和"admin 手动 DELETE"完全相同的代码路径。任何 sweeper 异常都被 try/except 包住记 warning,不会让 daemon 线程崩溃。
测试驱动方式:sweep_once() 暴露给单元测试,可以同步驱动状态机;sweep_tick(now=...) 接受外部时间钟避免 sleep。
8. 模块依赖图
┌────────────────────────────┐
│ common/auth_context (中立) │ (auth & heartbeat 都用)
└────────────────────────────┘
┌──────────────────────────┐ set_unhealthy_check
│ register/ service │ ◄──────────callback────────┐
│ store │ │
│ models │ │
│ (没有 import │ │
│ heartbeat/) │ │
└────────────┬─────────────┘ │
▲ │
│ deregister(SYSTEM_CTX) │
│ │
┌────────────┴─────────────┐ ┌──────────────────┴─────┐
│ backend/ routers/ │ │ heartbeat/ store │
│ dataset │ ──────► │ sweeper │
│ heartbeat │ read+ │ router │
│ startup │ install│ deps │
└──────────────────────────┘ └─────────────────────────┘
关键 invariants:
register/*永远不 importheartbeat/*(grep 验证:0 命中)heartbeat/store.py不知道 FastAPI / HTTP / 路由(pure Python,可单测)- 一条 callback 连接两侧:
registry_svc.set_unhealthy_check(heartbeat_store.is_unhealthy)
9. 客户端 SDK
client/a2x_registry_client/heartbeat.py:
HeartbeatRenewer—— per-(ds, sid) daemon thread,每ttl/3秒发一次心跳,指数退避,daemon=True 不阻塞进程退出HeartbeatRegistry—— per-client 管理器AsyncHeartbeatRenewer/AsyncHeartbeatRegistry—— 异步客户端用asyncio.Task
SDK 公开方法(client.py):
client.register_agent(..., lease_ttl=60, auto_renew=True) # 注册即起后台续约
client.heartbeat(ds, sid, status=None) # 手动续约
client.drain(ds, sid) # status=offline,保留 entry
client.shutdown(*, permanent=False, ...) # 批量撤销 lease 或硬删
client.close() # 停所有 renewer,关 transport
所有 lifecycle hook 都是 opt-in:默认 auto_renew=False、auto_deregister=False、不装 SIGTERM/atexit handler,避免与业务方的信号处理冲突。
10. 三类 TTL 在 A2X 里彼此独立
A2X 现在有三类 TTL,互不耦合:
| 类别 | 实例 | 谁配置 | 持有者 | 失效后果 |
|---|---|---|---|---|
| 独占锁 | reservation lease | 调用方 reserve 时传 | 任意 holder | 锁释放,他人可抢 |
| 存活租约 | service heartbeat(本文档) | 客户端注册时传,namespace 限 [min, max] |
服务本身 | mark unhealthy → 硬删 |
| 过期权限 | ApiKey.expires_at(Phase 1 占位) | admin 创建 key 时传 | API key | 凭据失效 |
底层数据结构 _Lease (reservation) 和 HeartbeatLease 形状相似但有意保持分开:
- 端点分开:
/reservations/...vs/services/{sid}/heartbeat - 配置文件分开:namespace 用
lease_config.json控制心跳;reservation 用 request body - Sweeper 分开:reservation 懒扫描;心跳后台 daemon
- 审计事件分开
Refactor 建议(不在本 Phase 实施):未来若引入第 3 类后台 lease(如 API-key 自动过期),可以提炼一个公共 Lease 基类与统一 sweeper。当前 ROI 低(约一文件、两行 save)。
11. 向前兼容承诺
具体落到可测的承诺:
- 没启用 lease_config 的 namespace → 行为与心跳模块未存在时 byte-equal。回归测试:tests/heartbeat/test_back_compat.py,全部既有 142 个 server 测试不修改任何源码全绿。
- 注册时不传
lease_ttl→ 服务永久,api_config.json的 entry 不写lease_ttl字段(byte-equal pre-heartbeat output)。回归测试同上。 - 既有 SDK 客户端 → 不传
lease_ttl/ 不调heartbeat()/ 不使用auto_renew,注册端点行为不变;额外的lease_ttl/lease_expires_at响应字段对旧客户端是无害的(Pydantic 忽略未知字段)。
12. 进一步阅读
- client/README.md §2.6 —— 客户端心跳基本用法
- tests/heartbeat/ —— 40 个 server 测试,对照本文档每个不变式逐项验证
- client/tests/test_heartbeat_renewer.py —— 客户端 renewer 测试