EasyTier Cloudflare Relay — 部署手册

1. 架构概览

EasyTier 客户端 (任意平台)
        │  wss://et.example.com/  (标准 WebSocket + EasyTier 二进制协议)
        ▼
Cloudflare Edge (Worker 入口 src/index.js)
        │  按 URL/Header/Query 选择房间 → 转发到 Durable Object
        ▼
RelayRoom Durable Object (src/room.js)
        │  握手鉴权 → 路由同步(OSPF) → 包转发
        ▼
同一网络的其他客户端（经中继兜底；P2P 打洞成功后直连，不再经过本节点）

纯 P2P 模式：节点在路由协议中宣告 avoid_relay_data（OSPF 大代价边）， 客户端之间优先直连；只有 P2P 打洞失败的流量才走中继兜底（可通过 RELAY_DATA=0 完全关闭数据面）。

2. 前置条件

3. 快速部署（5 分钟）

# 1. 进入项目目录
cd easytier-cf-relay

# 2. 安装依赖
npm install

# 3. 登录 Cloudflare（浏览器授权）
npx wrangler login

# 4. 部署
npx wrangler deploy

# 5. 验证（把 <name> 替换为 wrangler 输出的 Worker 名）
curl https://easytier-cf-relay.<你的子域>.workers.dev/health
# 期望: {"ok":true}

客户端即可用 wss://easytier-cf-relay.<你的子域>.workers.dev/ 作为节点地址。

可选：启用 KV 审计（记录 + 黑名单）——创建 KV namespace 并在 wrangler.toml 启用 AUDIT_KV 绑定（见 5.6 节）。不配置时功能自动降级为仅 DO storage 存储， 管理页功能不受影响。

本地验证（可选，无需账号）：

npx wrangler dev --port 8787
# 另一个终端：完整协议测试（44 项）
node test/e2e_test.mjs http://127.0.0.1:8787

本地 wrangler dev 会自动读取 .dev.vars（已 gitignore，不随 deploy 上传）， 其中预置了 E2E 测试所需的 METRICS_PATH / ADMIN_PATH 等 token。

4. 绑定自定义域名

方式 A：Custom Domain（推荐）

域名已托管在 Cloudflare 时，在 wrangler.toml 追加：

routes = [
  { pattern = "et.example.com", custom_domain = true }
]

重新 npx wrangler deploy。Cloudflare 会自动：

• 创建 DNS 记录
• 签发并轮换 TLS 证书（免费）

方式 B：Route + 手动 DNS

routes = [
  { pattern = "et.example.com/*", zone_name = "example.com" }
]

并在 Cloudflare DNS 面板为 et.example.com 添加任意 A/AAAA 记录（如 192.0.2.1，流量走 Worker 不回源）。

客户端 URL 格式

wss://et.example.com/

路径任意（/、/ws、/easytier 均可），与官方服务端行为一致——因为部分客户端 （含官方 GUI）会把用户配置的路径原样带到 WebSocket 升级请求里。

5. 配置参考

所有配置通过 wrangler.toml 的 [vars]（或 wrangler secret）设置，改完重新 deploy 生效。

5.1 基础配置

5.2 P2P 与转发行为

5.3 容量与超时

5.4 安全

# 示例：校验两个网络的密钥
[vars]
NETWORK_SECRETS = "{\"myteam\":\"s3cret!\",\"family\":\"home123\"}"

不配置 NETWORK_SECRETS 时，任何持有正确 (网络名, 密钥) 组合的客户端都可接入 ——与官方公共服务器 public.easytier.cn 的行为一致（不同密钥的网络天然隔离，互不可见）。

5.5 多房间分片（可选）

默认所有连接进同一个 DO 房间 "global"（同房间内按网络名+摘要自动分组隔离）。 需要物理隔离（例如不同租户）时：

[vars]
ROOM_HEADER = "X-Room"       # 按请求头分片
# 或
ROOM_QUERY = "room"          # 按 URL 查询参数分片，如 wss://et.example.com/?room=t1

5.6 KV 审计（记录 + 黑名单）

六类信息（网络分组 / 节点在线 / 路由信息 / 全局互联 / 连接列表 / 摘要注册表）的 连接与事件记录进 Workers KV，每类只占一条 KV 键（记录 7 条 + 黑名单 4 条，共 11 条）； 管理端另有黑名单（分四类：节点 PeerId / 网络分组 / 摘要注册 / 客户端 IP）。 记录查询页支持按类型筛选，类型下拉首项为**「全部」**（跨类型按时间合并视图，无需额外 KV 键）。

启用步骤（可选；不配置 KV 绑定时功能优雅降级——记录与黑名单仅存 Durable Object storage，管理页功能不变）：

# 1. 创建 KV namespace（免费计划自带）
npx wrangler kv namespace create AUDIT_KV
# 输出 id 后填入 wrangler.toml：

[[kv_namespaces]]
binding = "AUDIT_KV"
id = "<上面输出的 id>"

# 2. 重新部署
npx wrangler deploy

KV 键布局与写入策略详见技术文档 §9。免费额度核算： KV 免费计划 1000 写/天——默认 10 分钟节流下每键理论最大 144 写/天， 实际仅在有新事件的周期产生写入（典型小网络全类合计每天数十次），远低于限额； 读取主要为两处——冷启动且 DO storage 为空时（每键一次）与 WebSocket 升级时的 边缘黑名单检查（只读 bl:socket 一条键，v1.4.0 起有 isolate 缓存：默认每 30s 至多一次 KV 读，重连风暴时也只消耗每 TTL 一次读取）。

黑名单行为：管理页执行「踢出节点 / 删除分组 / 删除摘要注册 / 断开连接」时， 操作对象（PeerId / 网络名 / IP）自动进入对应类别黑名单并被拦截后续接入； 黑名单页可手工添加、移除（解除封锁）或清空。断开连接会拉黑该客户端 IP—— 若多个节点共用同一出口 IP，请谨慎使用（可先移除该 IP 再让其重连）。

IP 黑名单为双层拦截（v1.3.0）：Worker 入口先读 KV 直接 403（不唤醒 DO， 被拉黑客户端的重连风暴不消耗 DO 请求与时长计费），DO 层兜底。v1.4.0 起边缘 层 KV 读取带 isolate 缓存（IP_BLOCK_CACHE_MS，默认 30s），只延后拦截、 绝不漏放——缓存未命中（含 KV 读失败）照旧放行走 DO 层权威检查。因此：

• 解除 IP 封锁后，KV 传播完成前（通常数秒，最长约 1 分钟）+ 缓存 TTL 内， 边缘层可能仍拒绝该 IP；被新拉黑的 IP 在此窗口内会打到 DO 层被权威拦截；
• 黑名单拒绝不写入记录（防重连风暴刷爆记录列表），拒绝次数见总览页 「黑名单拦截」计数（DO 层口径；边缘层拒绝不经过 DO，不计数）。

事前限流（v1.4.1）：黑名单是事后拦截（需管理员操作或攻击已发生）， 单 IP 并发连接上限（MAX_CONNS_PER_IP，DO 升级层）补上事前缺口——同一 IP 的开放连接数达到上限后直接 429，无需先进入黑名单；拦截次数见总览页 「IP 限流」计数（ipLimited）。另：未知路径的非升级请求会被挂起不响应 （tar pit，TARPIT_UNKNOWN），不泄露 404 与行为指纹。

KV 键前缀（v1.4.1 起更名为 easytier-cf-relay:，此前为 et-relay:）： 首次启动新版本时自动把旧键数据迁移到新键（旧键保留不删，确认运行正常后可 在 Cloudflare 控制台手动清理）；无需任何手工操作。

多房间分片注意：KV 审计键为全局共享（各房间 DO 刷盘同一组键，以最后 刷盘的房间为准）。KV 审计与边缘 IP 拦截面向默认单房间部署；使用 ROOM_HEADER / ROOM_QUERY 分片时不建议启用 AUDIT_KV。

5.7 日志

5.8 监控与管理端

生产环境默认全部禁用（不配置即 404，零攻击面）。启用时务必使用 随机长路径 + 强 token 双重防线：

[vars]
HEALTH_PATH = "/h-a1b2c3d4"                # 可选，默认 /health
METRICS_PATH = "/m-a1b2c3d4"              # 用 openssl rand -hex 8 生成
METRICS_TOKEN = "长随机字符串"
ADMIN_PATH = "/console-e5f6a7"
ADMIN_TOKEN = "另一个长随机字符串"

要点：

• 鉴权失败统一返回 404（不暴露端点存在性）；token 比较为常数时间（防时序侧信道）；
• DO 内部端点（/internal/*）只接受 Worker 入口鉴权后的改写转发：带 Upgrade: websocket 头伪造内部路径的请求在 DO 层直接 404（v1.4.1， 防「升级头 + 内部路径」绕过 token 直达端点）；
• 管理端页面壳本身无数据（可公开访问），所有数据 API 均需 token；
• token 属于敏感信息：生产建议用 npx wrangler secret put METRICS_TOKEN 注入而非写进 toml；
• wrangler.toml 中的 [env.security] 测试环境变量不会随默认 wrangler deploy 上传；
• 管理页自动刷新间隔 30s（v1.4.0 起；且页面不可见时自动暂停），长开页面的请求量 约 2.9k/天，对免费额度（100k/天）占用很小，不需要时可关闭自动刷新； v1.6.0 起「额度观测 / 趋势」在服务端报告未配置 CF 凭证后，前端会记住状态并 跳过后续轮询（卡内提供「重新检测」入口），避免空转请求。

Prometheus 文本输出（v1.6.0）：启用 /metrics 后，追加 ?format=prometheus 即输出 Prometheus text exposition format（text/plain; version=0.0.4），25 个 easytier_ 命名空间指标（无 label 防高基数）：easytier_peers / easytier_groups / easytier_uptime_seconds / easytier_sockets / easytier_sockets_handshaked（gauge） 与 easytier_msgs_in_total / easytier_msgs_out_total / easytier_bytes_in_total / easytier_bytes_out_total / easytier_forwards_total / easytier_conns_total / easytier_errors_total / easytier_forgeries_total / easytier_blacklist_rejected_total / easytier_ip_limited_total / easytier_rate_limited_total / easytier_group_limited_total / easytier_alarms_total（counter）。抓取示例（自托管 Prometheus）：

scrape_configs:
  - job_name: easytier-relay
    scrape_interval: 60s
    metrics_path: /m-a1b2c3d4        # 你的 METRICS_PATH
    params:
      format: [prometheus]
    authorization:
      credentials: "<METRICS_TOKEN>"
    static_configs:
      - targets: ["<你的域名>"]

Grafana 可用 Prometheus 数据源直接画 easytier_peers、 rate(easytier_msgs_in_total[5m]) 等面板；拨测平台可继续用 JSON 端点或 /health。注意 counter 随 DO 重启归零（免费计划 DO 周期休眠回收），告警 建议基于 rate() / increase() 而非绝对值。

5.8.1 额度观测与趋势（v1.6，可选）

未配置时总览「额度观测」卡为自观测估算口径，行为与 v1.5 一致。配置下列项后 升级为账号级真实数据（全部可选，逐项独立生效）：

[vars]
CF_ACCOUNT_ID = "你的账号 ID"
CF_SCRIPT_NAME = "easytier-cf-relay"
AE_DATASET = "easytier-cf-relay"   # 与下方 dataset 一致

[[analytics_engine_datasets]]
binding = "AE"
dataset = "easytier-cf-relay"

# Token 一律 secret 注入（不要写在这里）：
#   npx wrangler secret put CF_API_TOKEN

行为说明：

• 真实额度（管理端 /api/quota）：服务端出站调 GraphQL Analytics API 统计当日 UTC 窗口的 workersInvocationsAdaptive 请求数（出站调用不占 100k 入站额度）；结果缓存 5 分钟（失败缓存 1 分钟），管理页 30s 自动刷新 不会打爆 API；查询失败自动回退自观测估算并在卡片标注原因。Token 只在 服务端使用，浏览器 / 日志 / 审计中不出现。
• 趋势图（管理端 /api/trends）：DO 每 ≥60s 向 AE 写一个计数快照 （约 1,440 点/天，免费计划含 100,000 点/天，打点不占请求额度）；查询走 AE SQL API，24h 窗口 15 分钟一桶、7d 窗口 1 小时一桶，SQL 分桶查询失败 自动回退原始点服务端聚合。未绑定 AE 时打点静默跳过、趋势卡提示未启用。
• GraphQL 免费计划可用性已于 v1.6 立项前复核（账号级 Workers 数据集可用； zone 级站点分析受限与本功能无关）；如官方 API 变更导致查询失败，功能 自动降级为估算口径，不影响其它功能。

6. 客户端接入

6.1 Linux / macOS（easytier-core CLI）

easytier-core \
  --network-name myteam \
  --network-secret s3cret! \
  --hostname node-a \
  -p wss://et.example.com/

实测输出（v2.6.4 官方客户端 + 本项目）：

INFO CORE::INSTANCE::CONNECTION: new peer connection added conn_info=PeerConnInfo { my_peer_id: ..., dst_peer_id: 10000001, ... }
INFO CORE::INSTANCE: new peer added peer_id=10000001

$ easytier-cli peer
| ipv4          | hostname | cost  | lat(ms) | tunnel | version           |
|---------------|----------|-------|---------|--------|-------------------|
| 10.126.0.1/24 | nodeA    | Local | -       | -      | 2.6.4-8428a89d    |
|               | easytier-cf-relay | p2p   | 3.88    | ws     | easytier-cf-relay/1.0.0 |
| 10.126.0.2/24 | nodeB    | relay(2) | 18.00 |        | 2.6.4-8428a89d    |

6.2 Windows GUI / macOS GUI / 手机端

• 网络名称：myteam
• 网络密钥：s3cret!
• 节点/Peer：wss://et.example.com/（新建一个节点条目填入即可）

6.3 Docker

docker run --name easytier -d --network host --cap-add NET_ADMIN \
  easytier/easytier:latest \
  --network-name myteam --network-secret 's3cret!' \
  -p wss://et.example.com/

6.4 兼容性矩阵

9. 故障排查 FAQ

Q1：客户端一直 connect timeout after 20s？

1. curl https://你的域名/health 确认 Worker 存活；
2. 检查 URL scheme 是 wss://（而非 ws://，Workers 强制 TLS）；
3. npx wrangler tail 看握手是否到达。到达但被拒（digest mismatch）说明密钥不对。

Q2：客户端握手成功但 easytier-cli peer 看不到服务端节点？ 通常是旧版本第三方实现的问题；本项目已实测 2.6.4 正常显示（hostname=easytier-cf-relay）。 若遇到，开启 LOG_LEVEL=debug 检查 rpc req ... service=OspfRouteRpc 日志行， 存在但无响应时请提 issue 附日志。

Q3：节点显示在线，但互相 ping 不通？

• 确认两端 --network-name 与 --network-secret 完全一致（STRICT_DIGEST=1 时不同摘要会被拒绝，日志有 digest mismatch）；
• RELAY_DATA=0 时中继不转发数据面，必须依赖 P2P 直连（打洞失败的组合无法通信），需要兜底请设 RELAY_DATA=1。

Q4：本地 wrangler dev 报 Address already in use？ 端口被占用：npx wrangler dev --port 8788 换端口，或杀掉旧进程。

Q5：wrangler deploy 报 DO 类已存在 / migration 冲突？ 见 8.4 迁移章节。切勿删除 wrangler.toml 中已有的 [[migrations]] 条目。

Q6：两个客户端都能连上，但互相看不到对方（只看得到 easytier-cf-relay）？ 检查是否误配置了 ROOM_HEADER/ROOM_QUERY——两个客户端进了不同 DO 房间。 同房间要求相同的 URL/Header。

Q7：想统计流量？ 配置 METRICS_PATH + METRICS_TOKEN 后访问统计端点， counters.bytesIn/bytesOut/forwards 即为控制面+数据面的转发统计；或用 Web 管理端总览页。

Q8：同名网络被恶意抢占（digest mismatch）怎么办？ 已配置 NETWORK_SECRETS 的网络不受影响（服务端以正确密钥摘要为准，注册表自愈）。 未配置的网络被抢占时，用管理端删除该分组即可解除注册，随后正常客户端可重新接入。 v1.6.0 起，此类握手被拒会写入 squat-suspect 审计事件（含攻击源 IP， 按网络名+IP 10 分钟去重）——「记录查询 → 摘要注册」页可见抢占者并可拉黑其 IP； 总览页「摘要抢占嫌疑」计数持续偏高即说明有人在尝试堵门。加固建议：公开部署 强烈建议配置 NETWORK_SECRETS（服务端密钥校验，抢占直接失效）。

Q9：如何复跑安全测试？

npx wrangler dev --env security --port 8788   # 使用 .dev.vars.security 中的测试 token
node test/security_test.mjs                    # 45 项黑盒安全测试
node test/audit_e2e_test.mjs                   # 34 项 KV 审计（记录/黑名单/边缘拦截）动态测试

Q10：踢出/删除的节点或网络重连不上？ 这是黑名单在生效：踢出节点 / 删除分组 / 删除摘要注册 / 断开连接会把操作对象 （PeerId / 网络名 / IP）加入对应类别黑名单并拦截后续接入。 到管理端「黑名单」页移除对应条目（解除封锁）即可重新接入。 注意两点：

• 断开连接拉黑的是客户端 IP——若多个节点共用同一出口 IP，会一并被拦， 需要时先移除该 IP 条目；
• 配置了 AUDIT_KV 时，IP 拦截发生在 Worker 入口边缘层（KV 直读）。 解除封锁后 KV 传播完成前（通常数秒，最长约 1 分钟）边缘层可能仍拒绝该 IP， 稍候即可。

Q11：管理端记录为什么删不掉 / 关不掉？"查看"事件为什么不见了？ 管理端审计（登录 IP/时间、操作）是硬设置（wrangler.toml ADMIN_AUDIT）， 管理页不可关闭、admin 类记录不可删除（防审计自擦除）。 六类数据记录则可在「记录设置」页单独开关并设置上限。 v1.3.0 起管理端"查看"事件不再记录（管理页自动刷新会持续刷屏且徒增写入）； 黑名单拒绝事件同样不再写入「节点在线」记录（被拉黑客户端会不断重连，逐条记录 会刷爆列表），拒绝次数改看总览页「黑名单拦截」计数。

Q12：被拉黑的客户端一直重连，会不会刷爆免费额度？ 每次重连尝试本身占用 1 次 Worker 请求（客户端行为，服务端无法避免），但 v1.3.0 起：拒绝发生在 Worker 入口边缘层（读 KV 的 bl:socket 一条键）， 不再唤醒 Durable Object——不消耗 DO 请求与时长计费，也不产生任何审计写入 （否则重连风暴每秒都会产生记录与 KV 镜像写入）。v1.4.0 起该 KV 读带 isolate 缓存（IP_BLOCK_CACHE_MS，默认 30s）：重连风暴时 KV 读从每次连接 1 次降为每 30s 至多 1 次，只延后拦截、绝不漏放（DO 层权威兜底）。 若确有恶意 IP 长期轰炸，可在 Cloudflare 控制台配置 WAF/IP Access Rules 在更外层拦截。

本手册对应实现版本：easytier-cf-relay/1.4.0（协议对齐 easytier-core 2.6.x）。技术实现细节见《技术文档》。