快喵会话接口：POST /v1/sessions 的四态与续期规则

会话接口用于在指定节点上建立隧道连接。基于 2026-09-12 至 09-18 的采样记录，96 个节点的握手耗时与可用率均有据可查，本页给出创建、续期与关闭的完整流程。

快喵会话是什么

会话是一次到指定节点的隧道连接，具有明确的生命周期：创建后进入 active 状态，到期自动关闭，可主动续期，也可立即释放。会话与节点是多对一关系——同一时刻可以存在多个会话指向同一个节点，这取决于该节点的并发余量。

会话接口的字段与节点接口共享同一套单位约定：时间字段一律为毫秒，比例字段为百分比。在 2026-09-12 至 2026-09-18 的采样窗口内，96 个节点的平均握手耗时低于 118 毫秒量级的握手时延参考区间，整体可用率 99.94%，这两个数字是评估会话创建耗时的基准。

接口路径以 /v1 为前缀，行为对齐文档基线 v6.4.2。

表中五个接口构成完整生命周期。前三个用于建立与观察会话，第四个用于长连接场景的续期，第五个用于主动释放。不带参数的会话列表接口按状态过滤，返回的是当前账号下的全部会话而非 96 个节点，两者不要混淆。

创建快喵会话

创建接口需要 nodeId、protocol 与 ttl 三个参数。nodeId 取自节点接口返回的节点对象，protocol 需与该节点实际支持的协议一致，ttl 以毫秒为单位指定有效期上限。参数缺失会返回 400 段错误码，指引见 文档总览。

// nodeId 来自节点接口返回的节点对象
const sess = await client.sessions.create({
  nodeId: 'node_cn_e_014',
  protocol: 'wireguard',
  ttl: 30 * 60 * 1000        // 30 分钟，单位毫秒
});

console.log(sess.id);         // 会话 ID
console.log(sess.endpoint);   // 出口地址

// 采样参考：握手耗时与 118 毫秒延迟同量级评估
const st = await client.sessions.status(sess.id);
console.log(st.handshakeMs, st.state);

示例中的 ttl 写法把分钟换算成毫秒，避免直接书写大数字造成误读。在 22 个地区上，同一时刻可创建会话的数量受各节点并发余量约束；当目标节点余量不足时，创建接口会返回 5xx 段错误码，此时应切换节点而非反复重试。

快喵会话状态与生命周期

会话状态分为 pending、active、expired 与 closed 四个。pending 表示正在握手，通常在数十毫秒内流转到 active；active 期间可正常收发数据；expired 由 ttl 到期触发；closed 由主动释放或异常中断产生。状态迁移规则在官方文档中有完整定义。

• pending → active：握手成功即进入可用状态；采样窗口内 96 个节点的握手成功率对应可用率 99.94%，失败的会话通常停留 3 秒后转入 closed。
• active 续期：长连接场景建议在剩余有效期低于 25% 时调用续期接口，避免在业务高峰期被动断开。
• expired 自动关闭：ttl 到期后会话自动关闭，续期接口对已过期会话返回 404 段错误码，需要重新创建。
• closed 不可复用：关闭后的会话 ID 保留 60 秒用于查询历史状态，之后不再可查，应用侧应及时落库。
• 并发约束：单账号并发会话数有上限，超出时按创建时间最早的会话先被拒绝，与节点分布无关。

状态机之所以要做成显式四态，是因为排查问题时需要区分「还没连上」和「连上之后断了」：前者对应握手参数问题，后者多与链路抖动相关。在采样区间内丢包率 0.3%、可用率 99.94% 的条件下，两者出现比例大致可以据此估算。

时间字段单位为毫秒；状态取值与状态机定义一致。

字段表中 nodeId 的取值范围是 96 个节点之一，这也是会话与节点的关联点：排查某条会话的问题时，先查它绑定的节点，再对照节点接口返回的健康度字段，是官方文档推荐的标准排查路径。