🔐 CipherPulse · 暗流脉冲协议架构白皮书

1. 项目愿景与设计哲学

CipherPulse 是一套专为 高丢包、高延迟、非受控 网络环境（如跨境 VPS、IoT 边缘设备）设计的轻量级服务器遥测系统。

不同于传统的 Prometheus/Zabbix，CipherPulse 假设网络是恶劣的，节点是不可信的，并基于此前提构建了以下核心哲学：

🔕 聋子模式 (Deaf Mode)

Agent 采用单向广播设计，0 入站端口。从物理层面杜绝攻击者通过监控端口渗透服务器的可能。

🚀 UDP 优先 (UDP First)

放弃 TCP 的握手与重传机制，采用应用层 滑动窗口冗余 (Sliding Window Redundancy) 对抗丢包，实现”发射后不管”。

🛡️ 先锋令牌 (Token-First)

将鉴权前置到数据包头部，配合 Master 端内存缓存，实现纳秒级的抗 DDoS 解析能力。

⚡ SSH 即刻初始化 (SSH Provisioning)

借鉴 Komari 的 SSH 快速部署理念，所有关键约定在首次 TCP 短暂连接时通过 SSH 统一下发。Agent 无需内置复杂加密逻辑，配置直接通过 SSH 安全通道注入，部署如同执行一条命令。

2. 系统架构

2.1 Agent (探针端)

职责: 采集系统指标 → 组装 UDP 包 → 多路单向广播

核心特性:

Client-side HA: 支持向多个 Master IP 同时广播，实现客户端侧的高可用，无单点故障
JIT Memory: 无配置文件落地，配置通过 SSH 一次性注入内存，硬盘零痕迹
Resource: 目标 < 10MB 内存，CPU 占用 < 0.1%

2.2 Master (服务端)

职责: 接收 UDP → 安全过滤 → 冗余去重 → 批量落库

核心组件:

组件	职责
Packet Filter	基于 Token 和 Timestamp 的极速防火墙 (Fast Path)
Hot Pool	内存环形队列 (RingBuffer)，暂存最近 60 秒的高频数据
Batch Dumper	异步任务，每 10 秒将聚合数据写入 SQL 数据库
Provisioner	SSH 配置下发服务，仅在维护窗口启用

3. 部署流程：SSH 即刻初始化

借鉴 Komari 的核心洞察：CipherPulse Agent 的所有密钥、Token、Master 地址等配置，不需要内置在二进制里，而是在部署时通过 SSH 一次性统一下发。

3.1 部署流程 (Single Command)

# 在 Master 上为新节点生成配置并获取一键部署命令
$ cipherpulse-cli enroll --node "hk-node-01" --masters "1.2.3.4:5555,5.6.7.8:5555"

[+] Generating enrollment package for node: hk-node-01
[+] Master: 1.2.3.4:5555 (primary), 5.6.7.8:5555 (secondary)
[+] Token: cp_Tkn_a8f3k9x2m...  (32 bytes, auto-generated)
[+] NodeID: a1b2c3d4e5f6...     (hardware fingerprint, auto-derived)
[+] Valid for: 300 seconds (maintenance window)

# 输出：一键部署命令
$ curl -fsSL "https://master.example.com/install.sh" | \\
    NODE_ID=a1b2c3d4e5f6 TOKEN=cp_Tkn_a8f3k9x2m... \\
    MASTERS=1.2.3.4:5555,5.6.7.8:5555 sh

3.2 SSH 配置下发协议 (Provision Flow)

┌─────────────────────────────────────────────────────────────────┐
│                     TCP 握手 (短暂, < 2s)                         │
│  Node ──── SSH ───────────────────────────────────────► Master   │
│                                                                 │
│  1. Node 发送 NodeID + Enrollment Token                          │
│  2. Master 验证 Enrollment Window 是否开启                        │
│  3. Master 生成并加密下发:                                        │
│     - SessionToken (32 bytes, 用于 UDP 鉴权)                      │
│     - Master IP List (多播地址列表)                               │
│     - Probe Interval (上报频率, 默认 1Hz)                         │
│     - SchemaID (数据格式版本)                                     │
│     - (可选) TOTP Seed (用于后续 Token 刷新)                       │
│  4. Node 接收后写入内存配置表, 清除明文痕迹                         │
│  5. TCP 连接关闭, Node 进入纯 UDP 广播模式                         │
└─────────────────────────────────────────────────────────────────┘

3.3 下发数据结构 (Provisioning Payload)

通过 SSH 加密通道下发的完整配置项：

字段	长度	说明
SessionToken	32B	用于 UDP 脉冲包鉴权
MasterCount	1B	Master 节点数量 (1-4)
Master[i].IP	4B/16B	IPv4 或 IPv6 地址
Master[i].Port	2B	UDP 端口
ProbeInterval	2B	上报间隔 (毫秒, 默认 1000)
SchemaID	1B	数据格式版本 (0x01)
TokenTTL	4B	Token 有效期 (秒)
TOTPSeed	32B	(可选) 动态刷新用种子

4. PulseProto 通信协议标准 (v1.1)

传输层: UDP
字节序: Big-Endian (网络字节序)
包大小: 控制在 MTU 安全值 (508 Bytes) 以内

4.1 类型 A：脉冲包 (Pulse Packet)

用途: 高频上报监控数据（1Hz）
鉴权: SessionToken + Strict Time Window + IP Binding

Offset	Length	Field	Description
0x00	8	SessionToken	会话令牌。Master 查表验证，并校验源 IP 是否匹配
0x08	4	Timestamp	Unix 时间戳。Master 校验 `abs(Now - TS) < 5s`，超时丢弃
0x0C	1	Redundancy	冗余度 N (固定为 3，包含 T, T-1, T-2)
0x0D	1	SchemaID	数据格式版本。支持未来扩展 (0x01: 基础，0x02: IO 增强)
0x0E	Var	Payload	3 组 MetricBlock 数据体

数据体结构 (SchemaID = 0x01) — 12 Bytes / 组

[0]     uint8  : CPU 使用率 (0-100)
[1]     uint8  : 内存 使用率 (0-100)
[2-3]   uint16 : Ping 延迟 (ms)
[4-7]   uint32 : 入网流量增量 (Bytes)
[8-11]  uint32 : 出网流量增量 (Bytes)

5. 安全与抗攻击模型

5.1 注册开关 (Registration Switch)

SSH 配置下发阶段（称为 Provision Window）是唯一的节点准入窗口。

Master 默认拒绝所有未授权节点的 Provision 请求
管理员手动开启维护窗口（如 5 分钟）后，才允许新节点接入
窗口关闭后，任何新节点无法获得 SessionToken，从物理层面杜绝女巫攻击

5.2 纵深防御体系 (Defense in Depth)

防御层级	针对威胁	防御手段
L0	入网防御 / 非法入服	SSH Provision Window 机制。窗口关闭 = 物理隔离
L1	格式防御 / 解析炸弹	包长度不合法或 SchemaID 未知，直接丢弃
L2	时效防御 / 重放攻击	检查 Timestamp。超过 ±5 秒的包直接丢弃
L3	信任防御 / IP 欺骗	TOFU 原则。Token 首次使用时绑定源 IP，后续 IP 变更即报警
L4	限流防御 / 爆破 / 扫描	全局每秒仅限 5 个新 Provision 请求；单 IP 频繁错误触发黑洞

6. 数据可靠性策略

滑动窗口冗余 (Sliding Window Redundancy)

为了在恶劣网络下保持监控曲线平滑，每个数据包携带当前秒 + 过去 2 秒的数据。

发送端: 维护一个长度为 3 的 RingBuffer，每次发送 [T, T-1, T-2]。

接收端:

收到包 N。如果 T-1 数据已存在（之前的包 N-1 到达了），忽略冗余数据
如果 T-1 数据缺失（之前的包 N-1 丢了），从包 N 中提取 T-1 并自动补全

效果: 容忍 66% 的连续丢包率，监控图表依然连续无断点。

7. 开发路线图

Phase 1: 核心验证 (Current Focus)

实现 SSH Provision Server (配置下发端)
实现 Enrollment CLI 工具 (一键生成部署命令)
实现 UDP Server 原型，打印接收到的指标

Phase 2: Agent 构建

实现 SSH Provision Client (接收配置注入内存)
实现 /proc/stat 读取与 ethtool 网卡流量采集
实现多 Master 轮询发送逻辑

Phase 3: Master 工程化

实现 RingBuffer 内存池与滑动窗口去重逻辑
集成 SQLite 持久化
实现 Provision Window 管理接口

Phase 4: 可视化

提供 Snapshot API
开发极简 HTML 前端展示