实现节点协议 v1
了解节点与控制面的职责、注册、轮询、凭据更新与数据持久化。
节点程序负责实际代理流量,PPanel Edge 负责业务授权与配置。项目交付 HTTPS JSON 协议、类型化客户端、参考服务器、模拟器和契约套件,不交付真实代理二进制。完整请求/响应从 节点 OpenAPI 自动生成到端点参考。
生命周期
- 注册前生成并持久化
enrollment_id(UUID)。使用一次性令牌调用/api/v1/node/enroll。同令牌同 UUID 在 10 分钟内可重试并取回相同凭据。保存服务器 ID、agent token 和下一批次序号。 - 按服务端间隔轮询
/config、/users,保存 ETag 并原样发送If-None-Match。304 表示不变,空用户列表表示撤销全部用户。 - 心跳携带已应用配置 hash、每入站结果和
sent_at。配置应用失败保留上一有效配置并报告失败。配置收敛按 hash 比较。 - 收到
credentials时原子持久化新 token 并切换;旧 token 宽限期 10 分钟。服务器重复发送凭据直到节点成功切换。 - 流量批次先持久化再发送,收到确认后才删除;在线地址报告用于全局设备限制。
每个请求使用 Node-Protocol: 1、User-Agent: program/version,除注册外使用 Bearer。协议头是线上协议标识,不应因部署环境变量去前缀而自行更名。详情见可靠性规则和测试。