EasyTier Cloudflare Relay — 技术文档

4. 协议实现详解

4.1 ZCPacket / PeerManagerHeader（对标 packet/mod.rs）

每个 WebSocket 二进制帧 = 16 字节头 + payload，全部小端：

偏移  长度  字段
0     4    from_peer_id   u32 LE
4     4    to_peer_id     u32 LE
8     1    packet_type    u8   (见下表)
9     1    flags          u8   (bitfield)
10    1    forward_counter u8
11    1    reserved       u8
12    4    len            u32 LE  (= payload 长度)

PacketType（与官方枚举值逐一核对）：

Data=1  HandShake=2  Ping=4  Pong=5  RpcReq=8  RpcResp=9
ForeignNetworkPacket=10  KcpSrc=11  KcpDst=12
NoiseHandshakeMsg1/2/3=13/14/15  QuicSrc=16  QuicDst=17
RelayHandshake=20  RelayHandshakeAck=21

flags 位（bitflags 对齐）：ENCRYPTED=0x01 LATENCY_FIRST=0x02 EXIT_NODE=0x04 NO_PROXY=0x08 COMPRESSED=0x10 LIVENESS_PROBE=0x20 NOT_SEND_TO_TUN=0x40 LIVENESS_ECHO=0x80。

转发语义（peer_manager.rs）：

• forward_counter 每跳 +1，> 7 丢弃；
• forward_counter > 2 时清除 LATENCY_FIRST 位。

历史踩坑：早期版本曾按 16bit 解析 packet_type（照抄了某个错误第三方实现）， | QuicSrc/RelayHandshake 枚举值也被抄错。本实现已逐一对照官方源码修正并锁定测试。

4.2 Protobuf：静态代码生成（关键工程决策）

Cloudflare Workers 禁止 eval / new Function，而 protobufjs 反射模式 （Root.fromJSON + 运行期 codegen）恰恰依赖动态代码生成——这是第三方项目 在真机部署时报 Codegen not supported 的根因。

本方案：tools/regen_proto.sh 用 pbjs 从官方 .proto 生成静态模块：

pbjs -t static-module -w esm --es6 --force-long \
  --no-create --no-verify --no-convert --no-delimited --no-typeurl --no-service \
  -o src/proto_gen.js  peer_rpc.proto common.proto error.proto

产物仅含 encode/decode，零运行时代码生成；--force-long + long.js 保证 int64（transaction_id、session_id、peer_route_id）精度。

4.3 握手（对标 peer_manager.rs::handle_handshake）

请求 HandshakeRequest{ magic, my_peer_id, version, features[], network_name, network_secret_digest }：

1. magic != 0xd1e1a5e1 或 version != 1 → 关闭连接；
2. peer_id 非法（0 / 保留 ID / 与服务端相同）→ 关闭；
3. 摘要校验：
   • 配置了 NETWORK_SECRETS → 用 SipHash-1-3（siphash.js，与官方 NetworkIdentity::digest() 相同的算法与密钥派生）计算期望摘要并比对；
   • STRICT_DIGEST=1 → 同网络名已有不同摘要 → 拒绝（防抢占）；
   • 否则按 网络名:摘要 建立分组；
4. 响应：镜像客户端 features（客户端宣告 liveness-echo-v1 时回显之， 否则宣告 SERVER_FEATURES），network_name 填服务端名（与客户端不同 ⇒ 外部网络中继模式，官方公共服务器同款行为）；
5. 立即推送全量路由（SyncRouteInfoRequest），并增量广播给组内其他成员。

4.4 RPC 层（对标 rpc_types + rpc/）

分帧：ZCPacket(payload = RpcPacket{ body = RpcRequest{ request = <inner> } })， 响应用 RpcResponse{ response = <inner> } 包裹，transaction_id（int64）原样回传。

descriptor 三元组语义（对标 service_registry.rs::ServiceKey，实测校正）：

domain_name = 客户端网络名（服务按 domain 注册）
service_name = "OspfRouteRpc" / "PeerCenterRpc"
proto_name  = prost 服务短名，与 service_name 相同（如 "OspfRouteRpc"）

这是本项目实测发现的最隐蔽兼容性坑：早期实现把 proto_name 写成 "peer_rpc" （.proto 文件名），与官方 prost 生成的服务短名不符，导致客户端按 ServiceKey 查不到服务、SyncRouteInfo 全部超时。本实现入站兼容两种取值， 出站统一使用官方语义。

method_index 为 1-based（对标 easytier-proto/build/rpc.rs：Method::new((i + 1) as u8)）：

• OspfRouteRpc.SyncRouteInfo = 1
• PeerCenterRpc.ReportPeers = 1，GetGlobalPeerMap = 2

压缩：本端不启用（algo=None）；收到压缩请求仅记录不处理（当前协商路径不会出现）。

4.5 路由同步（对标 peer_ospf_route.rs）

入站 SyncRouteInfoRequest 处理：

1. 解码 my_peer_id / my_session_id / is_initiator / peer_infos.items[] / conn_info；
2. 记录会话（dst_session_id），响应 SyncRouteInfoResponse{ is_initiator: !req.is_initiator, session_id: 本端会话 }（角色取反为官方语义）；
3. 逐条合并 RoutePeerInfo，合并规则（官方语义）：
   • peer_route_id 变化 = 新路由实例（节点重启），无条件替换（处理版本回退）；
   • 否则 version 只增不减；
4. 回推本端路由视图。

出站推送（全量/增量）：

• 新连接 / 会话重置 → 全量；否则仅推送 version 高于对端已知版本的条目；
• RouteConnBitmap 星型拓扑：服务端与每个已握手 peer 相连，bitmap 位图编码；
• wire 层重组（wire.js）：对端上报过的 RoutePeerInfo 保留原始字节， 推送时逐字节搬运。这保留了官方未来新增字段（未知 field number）的透传能力， 对标官方 route_peer_wire.rs 的 raw_peer_infos 机制；对象路径仅作兜底。

广播时机：新 peer 加入 / peer 离开 / 收到新 RoutePeerInfo / ReportPeers 变化。

4.6 PeerCenter（对标 peers/peer_center/）

• ReportPeers(my_peer_id, {direct_peers: {pid: {latency_ms}}})： 整体替换该上报方的条目（官方 server.rs::report_peers 语义），TTL 180s 自动过期；
• GetGlobalPeerMap(digest)：digest 与服务端一致 → 回空响应（客户端保留缓存）， 否则回全量 GlobalPeerMap + 新 digest；
• digest：SHA-256(排序键+延迟) 前 8 字节 → u64。 （官方用 DefaultHasher，两端无需一致——digest 只用于"变没变"的自比较，客户端总是接受服务端给的值。）

4.7 心跳（对标 ping/pong + liveness-echo）

• 入站 Ping → 回 Pong，payload 原样回显，from/to 交换；客户端 Ping 带自增 seq，故不能用 setWebSocketAutoResponse 模板应答（该 API 仅支持固定字节匹配）；
• 客户端宣告 liveness-echo-v1（features 镜像确认后）会在业务包上带 LIVENESS_ECHO flag——本实现把这些包同样视为活性信号（每条消息都会 _touch，天然覆盖）；
• 服务端主动探活：空闲超阈值发 Ping，半开连接因写失败触发 close 事件被立即清理。

8. 状态持久化

PeerManager.toPersisted() 序列化（节流落盘：脏标记 + ≥30s 间隔 + 成员变化短 alarm 提前触发）：

• 服务端身份（peerId/hostname——重启不变，客户端无需重新学习路由实例）；
• 各分组的 RoutePeerInfo（含 raw 字节）与版本号；
• 条目来源元数据（infoSource=direct/transit、reporters 集合、emptySince）—— 重启后幽灵防线 d/e/f 的判定依据不丢失（持久化格式 v4）；
• digest 注册表（STRICT_DIGEST 判定依据）；
• 会话表。

loadPersisted() 对损坏数据（字段缺失/类型错误）静默丢弃并继续—— DO 存储异常不应导致整个房间不可用。

9. KV 审计与管理端黑名单

实现模块：src/audit.js（AuditStore），由 RelayRoom DO 持有（this.audit）。

9.1 键值布局（每类信息只占一条 KV 键）

键前缀（v1.4.1 起为项目名 easytier-cf-relay:，此前为 et-relay:）： 首次冷启动时若新前缀键完全为空，自动回读旧前缀键完成一次性迁移 （数据随正常刷盘写入新键）；新旧前缀绝不混用，旧键保留不删（确认运行 正常后可在 Cloudflare 控制台手动清理）。

共 11 条键，全生命周期不变。记录类为定长环形缓冲（默认上限 100 条/类， 管理页「记录设置」可单独调整）；黑名单上限为硬设置（BLACKLIST_LIMIT，默认 1000）。 记录查询支持 type=all：七类记录在内存合并（每条附 type 字段），按全局 id （全局单调递增 = 时间序）倒序分页——不引入任何新 KV 键；all 模式删除按 id 跨类型匹配，admin 硬记录永不删除。

9.2 三级写入路径（免费额度成本控制）

事件发生 ──► 内存数组（零成本）
              │  alarm 周期（15s）：脏即写 DO storage（SQLite，防休眠丢失）
              ▼
         KV 镜像 ──► 仅脏键、按 RECORD_FLUSH_MS（默认 10 分钟）节流；
                     管理端操作完成后强制刷（黑名单立即生效）

KV 免费额度 1000 写/天：默认间隔下每键理论最大 144 写/天；实际只在有新事件的 刷写周期产生写入，典型小网络全类合计每天数十次。读取仅发生在冷启动且 DO storage 为空时（每键一次，用于恢复）。v1.3.0 起两类高频事件不再产生写入：查看事件不记录 （原先管理页 10s 自动刷新每 5 分钟折叠一次）、黑名单拒绝不记录（重连风暴下原先 每秒可产生一条），拒绝改由 blRejected 内存计数器观测（零写入）。

9.3 硬设置与软设置

• 硬设置（wrangler.toml，管理页不可改）：ADMIN_AUDIT（管理端审计开关）、 ADMIN_AUDIT_LIMIT（其上限）、BLACKLIST_LIMIT、RECORD_FLUSH_MS、RECORD_DEFAULT_LIMIT。 admin 类记录在管理页不可删除（防审计自擦除）；
• 软设置（管理页「记录设置」）：六类数据记录各自的开/关与条数上限 （存 DO storage audit_state，运行时生效，收紧上限时立即裁剪旧记录）。

9.4 黑名单拦截（双层，免费额度优化）

内部端点防伪造（v1.4.1）：Worker 入口会把带 Upgrade: websocket 头的 任意路径请求原样转发到 DO，而 /internal/* 端点自身不鉴权（鉴权在入口完成）。 DO 现对「Upgrade 头 + 内部路径」的组合直接 404——堵住「伪造升级头绕过 ADMIN_TOKEN/METRICS_TOKEN 直达内部端点（读统计/删记录）」的绕过路径 （升级请求必须原样转发，入口层无法改写副本，故统一在 DO 层拦截）。 另：未知路径的非升级请求在 Worker 入口被 tar pit（TARPIT_UNKNOWN， 挂起不响应，不泄露 404 指纹；EasyTier 客户端只走升级不受影响）。

边缘层要点：

• CF-Connecting-IP 由 Cloudflare 边缘注入，客户端不可伪造（生产环境）；
• KV 为最终一致（约 1 分钟）：新拉黑的 IP 在窗口内由 DO 层兜底拦截； 解除封锁后至多约 1 分钟内恢复可连（本地 dev 的 miniflare KV 为即时一致）；
• KV 读失败时放行走 DO 权威检查（边缘 fail-open、DO fail-closed）；
• isolate 缓存（v1.4.0，IP_BLOCK_CACHE_MS，默认 30s，0 关闭）：TTL 内的 WS 升级复用缓存的 bl:socket 解析结果——只延后拦截、绝不漏放，缓存未命中 （含 KV 读失败）照旧放行走 DO 权威检查。代价仅是新拉黑 IP 的边缘拦截至多 延后「KV 最终一致窗口（约 1 分钟）+ TTL」，窗口内由 DO 层兜底拦截；
• 未绑定 AUDIT_KV 时边缘层自动跳过，仅 DO 层拦截（功能不变）；
• KV 读为「每 TTL 至多 1 次 + 冷启动」量级（免费额度 10 万读/天，重连风暴时 也不再与重连次数成正比）。

各层拒绝均不写记录，只递增 counters.blRejected（DO 层，总览页「黑名单拦截」 可见；边缘层拒绝不经过 DO，不计数，可在 Cloudflare 分析中查看）。

管理操作自动拉黑（v1.4.2 起粒度与操作对象对齐）：踢出节点 → peer 类；删除分组 → digest 类（完整「网络名:摘要」，抢占者被精确拦截、正主不受影响）；删除摘要注册 → digest 类（被删注册的完整粒度）；断开连接 → socket 类（已知 IP 时）。 存量 group 类数据与手工添加的纯网络名格式继续生效（digest 类回退匹配）。 黑名单页支持手工添加、单个/批量移除（解除封锁）与清空。

RPC 源绑定（v1.4.2，外部审查修复）：全部 RPC（请求与响应、无论目标是 服务端还是经转发的其它节点）统一校验——未握手连接不处理；包头 from_peer_id 必须与连接注册身份一致，否则丢弃并计入 counters.forgeries。修复前 server-destined 分支不经过转发路径的身份校验，存在冒名自报覆盖路由的盲区。

9.5 事件来源（挂钩点）

• 连接/节点/分组/摘要事件：room.js 生命周期路径（_acceptSocket / webSocketClose / _handleHandshake / _cleanupPeer）；
• 路由与互联事件：PeerManager 纯逻辑层通过可选 onEvent 钩子发射 （route-add / route-remove / group-remove / pc-report / pc-remove， 带原因标签：peer-left / reporter-gone / expire / admin / reconnect）， room 层转发给 AuditStore——纯逻辑层不依赖审计，单测不受影响；
• 管理端审计：Worker 入口将 CF-Connecting-IP 注入 x-admin-ip 转发给 DO， DO 在内部端点记录登录（同一 IP 10 分钟去重）与操作（action 明细）； 查看（view）不记录（v1.3.0）。

9.6 审计数据最小化（v1.6.0）

两项独立开关（均默认关闭，配置见部署手册 §5.6）：

• AUDIT_IP_MASK：record() 写入时对 ev.ip 打码——IPv4 保留 /16 前缀 （1.2.3.4 → 1.2.x.x，含 IPv4-mapped IPv6）、IPv6 保留前 4 组。 仅影响记录展示：黑名单存储、踢人拉黑（使用连接上的完整 ws._clientIp）、 边缘层 KV 拦截均不受影响；旧记录不回填。
• AUDIT_RETENTION_DAYS：alarm 内至多每小时一次调用 audit.pruneExpired(now)，按记录 ts 过滤超过 N 天的条目；仅清理 6 类 运行记录（admin 硬审计豁免），清理后标记脏键随下一轮 flush 同步 DO storage 与 KV 镜像。空闲期 alarm 退避至 300s 不影响清理粒度 （节流锚点为 1h）。

13. 代码结构参考

easytier-cf-relay/
├── src/
│   ├── index.js          # Worker 入口：/health、/metrics 与管理端（自定义安全路径+token）、WS 升级、房间路由
│   ├── room.js           # RelayRoom DO：连接生命周期、握手、转发、alarm 清扫、管理端内部端点、审计挂接
│   ├── peer_manager.js   # 分组/peer 表/路由信息（direct/transit 来源）/会话/持久化（纯逻辑，可单测；onEvent 钩子）
│   ├── audit.js          # KV 审计：六类事件记录 + 管理端硬审计 + 四类黑名单（每类一条 KV 键）+ IP 打码/留存清理（v1.6）
│   ├── prometheus.js     # Prometheus 文本格式输出（_stats JSON → text exposition，v1.6）
│   ├── rpc.js            # RPC 编解码 + OspfRouteRpc/PeerCenterRpc 处理（含身份校验）
│   ├── admin_ui.js       # Web 管理端单页（浅色默认 + 明暗/主色/圆角可定制 + 可收缩侧栏 + 总览瀑布流（趋势全宽双轴/卡片收起记忆/板块显隐）+ 设置与帮助模块 + 移动适配，API 全鉴权，v1.6 翻新）
│   ├── assets.js         # 内嵌 favicon PNG
│   ├── proto.js          # protobuf 类型入口（Long 配置、短名映射）
│   ├── proto_gen.js      # pbjs 静态生成（勿手改；regen 见 tools/）
│   ├── wire.js           # protobuf wire 层：未知字段保留、RoutePeerInfo 原字节重组
│   ├── packet.js         # ZCPacket 16B 头解析/构造/转发改写
│   ├── siphash.js        # SipHash-1-3（network_secret 摘要）+ hex/随机字节
│   └── constants.js      # 协议常量（PacketType/flags/MAGIC…）
├── tools/
│   ├── regen_proto.sh    # 从官方 .proto 重新生成 proto_gen.js
│   ├── proto_filter.json
│   └── make_release.mjs  # 发行流程脚本（白名单复制/清理规则/禁词扫描/--check）
├── wrangler.toml         # 部署配置（变量说明见部署手册）
└── docs/                 # 技术文档 / 部署手册 / 更新日志 / 客户端设置兼容性

协议对齐依据（官方源码，tag v2.6.4）： easytier-core/src/packet/mod.rs、peers/peer_manager.rs、peers/peer_ospf_route.rs、 peers/peer_center/{server.rs,instance.rs}、rpc/service_registry.rs、 easytier-proto/proto/{peer_rpc,common,error}.proto、easytier-proto/build/rpc.rs。

参考：EasyTier 官方仓库 ｜ Cloudflare Durable Objects 文档 ｜ DO 定价