# INP2P 任务拆分

## 项目概述

自研 P2P 组网系统，两个二进制：`inp2ps`（信令服务器）+ `inp2pc`（客户端）。
UDP 打洞优先，分层中继，超级辅助节点。

项目位置：`/root/.openclaw/workspace/inp2p/`

---

## 一、核心层（我负责）

**目标**：两个二进制能跑起来、能连上、能打洞、能建隧道、能中继。

### M1: 信令连接（预计 400 行）✅ 完成
- [x] 协议定义 `pkg/protocol/` — 消息格式、编解码、类型枚举
- [x] 信令连接 `pkg/signal/` — WSS 封装、handler 注册、同步请求/响应
- [x] 认证 `pkg/auth/` — CRC64 token 生成、TOTP 生成/验证、一次性中继令牌
- [x] 配置 `pkg/config/` — Server/Client 配置结构体、默认值、环境变量
- [x] **inp2ps 信令主循环** `internal/server/server.go`
  - [x] WSS 接受连接 → Login 验证 → 注册节点
  - [x] 心跳管理 → 超时离线清理
  - [x] ReportBasic 处理 **（必须回响应，OpenP2P 踩过的坑）**
  - [x] 节点上线广播
  - [x] 连接协调 `internal/server/coordinator.go`（收到 A 的 ConnectReq → 同时推送给 A 和 B punch 参数）
- [x] **inp2pc 信令主循环** `internal/client/client.go`
  - [x] WSS 连接 → Login → ReportBasic → 心跳
  - [x] 断线重连（5s 退避）
  - [x] 收到 PushConnectReq 后触发打洞
  - [x] 收到 PushNodeOnline 后重试 apps

### M2: NAT 探测（预计 200 行）✅ 完成
- [x] UDP STUN 客户端/服务端 `pkg/nat/`
- [x] TCP STUN 回退
- [x] **集成到 inp2ps main**：启动 4 个 STUN listener（UDP×2 + TCP×2）
- [x] **集成到 inp2pc main**：登录前先探测，结果带入 LoginReq
- [ ] 定期重新探测（每 5 分钟），NATType 变化时通知 server

### M3: 打洞（预计 300 行）✅ 完成
- [x] UDP punch 基础实现 `pkg/punch/`
- [x] TCP punch 基础实现
- [x] 优先级链（direct → UDP → TCP）
- [x] **双端同步打洞协调** `internal/server/coordinator.go`
  - [x] server 收到 A 的 ConnectReq
  - [x] 同时推送 PunchStart 给 A 和 B（带对方的 IP:Port + NAT 类型）
  - [x] 双方同时调 `punch.Connect()`
  - [x] 任一方成功后报告 PunchResult
- [ ] Symmetric NAT 端口预测（可选优化）
- [ ] 打洞结果上报 + 统计

### M4: 隧道 + 多路复用（预计 500 行）✅ 完成
- [x] 隧道框架 `pkg/tunnel/` — 端口转发、统计、生命周期
- [x] **流多路复用协议** `pkg/mux/`
  - [x] 帧格式：`StreamID(4B) + Flags(1B) + Len(2B) + Data`
  - [x] SYN/FIN/DATA/PING/PONG/RST 控制帧
  - [x] Session（多路复用会话）+ Stream（虚拟连接，实现 net.Conn）
  - [x] Ring buffer 接收缓冲
  - [x] 7 个单元测试 + 1 个性能基准测试 全部通过
- [x] TCP 端口转发实现（listener → mux stream → peer demux → dst connect）
  - [x] 端到端测试通过（echo server + tunnel + 验证数据一致性）
  - [x] 5 并发连接测试通过
- [ ] UDP 端口转发实现
- [x] 连接池/复用（同 peer 多 app 共享一条 tunnel）

### M5: 中继（预计 400 行）✅ 完成
- [x] 中继管理器 `pkg/relay/` — 完整实现（~320 行）
- [x] **中继节点选择策略**（server 端 `server.GetRelayNodes()`）
  - [x] 同用户 `--relay` 节点优先
  - [x] 全局 `--super` 节点次优
  - [x] server 自身中继兜底
- [x] **中继握手协议**（长度前缀 JSON）
  - [x] A → relay: TCP 连接 + RelayHandshake{sessionID, role="from", token, node}
  - [x] B → relay: TCP 连接 + RelayHandshake{sessionID, role="to", token, node}
  - [x] relay: TOTP 验证 → 配对等待（30s 超时）→ 双向桥接
  - [x] 结果回传 relayResult{error, detail}
- [x] **中继认证**
  - [x] 同用户：TOTP(token, now)
  - [x] 跨用户超级节点：server 签发 `RelayToken`（HMAC-SHA256 签名，含 TTL）
- [x] **客户端工具函数** `ConnectToRelay()` — 封装完整握手+等待配对
- [x] **测试覆盖**（3/3 通过）
  - [x] TestRelayBridge — A↔B 双向数据验证
  - [x] TestRelayLargeData — 1MB 精确传输
  - [x] TestRelayAuthDenied — 错误 TOTP 被正确拒绝
- [ ] 中继带宽统计 + 负载均衡

### M6: inp2ps / inp2pc main 入口（预计 200 行）✅ 完成
- [x] `cmd/inp2ps/main.go` — flag 解析、启动 STUN + WSS + API + 优雅退出
- [x] `cmd/inp2pc/main.go` — flag 解析、config.json 读写、优雅退出
- [x] 端到端验证：server + 2 client 同时运行，health API 显示 nodes=2

---

## 二、次要层（可由他人完成）

### S1: 配置持久化
- `inp2pc` 的 `config.json` 读写（登录后 server 回的 token/node 写回文件）
- 支持 `-newconfig` 覆盖文件配置
- 热重载（收到 PushEditApp 后更新本地 config）

### S2: SDWAN 虚拟组网
- TUN 虚拟网卡创建
- 虚拟 IP 分配（server 侧管理子网）
- 组网路由表管理
- 中心模式 vs 全互联模式

### S3: 日志系统
- 分级日志（DEBUG/INFO/WARN/ERROR）
- 日志轮转（按大小）
- 日志目录 `log/`

### S4: 系统集成
- Systemd service 文件生成
- 开机自启
- Daemon 模式（`-d` fork 子进程）
- 自动更新（可选）

### S5: 安全加固
- TLS 证书自动生成（自签名）
- 连接限速
- 单 IP 最大连接数限制
- Brute-force 保护

---

## 三、前端 + Web API（可由他人完成）

### F1: REST API（inp2ps 内嵌 Gin）
- `POST /api/v1/login` — JWT 签发
- `GET /api/v1/devices` — 设备列表（名称、IP、NAT 类型、在线状态、版本）
- `GET /api/v1/devices/:node` — 设备详情
- `POST /api/v1/devices/:node/app` — 创建隧道
- `DELETE /api/v1/devices/:node/app/:name` — 删除隧道
- `PUT /api/v1/devices/:node/app/:name` — 编辑隧道（启停）
- `GET /api/v1/dashboard` — 概览统计
- `GET /api/v1/connections` — 活跃连接列表（打洞/中继/RTT）
- `GET /api/v1/relays` — 中继节点状态
- `POST /api/v1/sdwan/edit` — SDWAN 配置
- `GET /api/v1/sdwans` — SDWAN 列表
- `GET /api/v1/health` — 健康检查

### F2: Web 控制台 UI
- 设备列表页（在线/离线、NAT 类型标签、版本）
- 隧道管理（创建/编辑/删除/启停）
- 连接状态页（实时连接方式、RTT、流量）
- 中继节点页（负载、带宽、会话数）
- SDWAN 组网页
- Dashboard 概览
- 用户管理（admin/operator RBAC）

### F3: 客户端安装脚本
- `GET /api/v1/client/bootstrap` — 返回安装参数
- 一键安装脚本（curl | bash）
- 多架构支持（amd64/arm64）

---

## 依赖关系

```
M1 (信令) ← 无依赖，最先完成
M2 (NAT)  ← 依赖 M1
M3 (打洞) ← 依赖 M1 + M2
M4 (隧道) ← 依赖 M3
M5 (中继) ← 依赖 M1 + M4
M6 (main) ← 依赖 M1~M5

S1~S5 ← 依赖 M6 完成后可并行
F1    ← 依赖 M1（设备数据来自 server 内存）
F2    ← 依赖 F1
F3    ← 依赖 M6
```

## 当前状态

```
pkg/
├── protocol/  ✅ 完成（消息格式、NAT 枚举、所有结构体）
├── config/    ✅ 完成（Server/Client 配置、环境变量、校验、STUN 端口）
├── auth/      ✅ 完成（CRC64 token、TOTP、一次性中继令牌）
├── nat/       ✅ 完成（UDP/TCP STUN 客户端 + 服务端，集成验证通过）
├── signal/    ✅ 完成（WSS 封装、handler、同步请求/响应）
├── punch/     ✅ 完成（UDP/TCP punch + direct + 优先级链）
├── mux/       ✅ 完成（流多路复用，7 测试 + 1 benchmark 全部通过）
├── tunnel/    ✅ 完成（基于 mux 的端口转发，端到端测试通过）
└── relay/     ✅ 完成（中继握手、TOTP 认证、双向桥接、3 测试通过）

internal/
├── server/    ✅ 完成（登录、心跳、report、relay 选择、节点管理、打洞协调）
│   ├── server.go       — WSS 主循环、handler 注册
│   └── coordinator.go  — 打洞协调、EditApp/DeleteApp 推送
└── client/    ✅ 完成（连接、登录、打洞、中继回退、app 管理、断线重连）

cmd/
├── inp2ps/    ✅ 完成（flag、STUN、WSS、API、graceful shutdown）
└── inp2pc/    ✅ 完成（flag、config.json、relay、graceful shutdown）

编译状态: ✅ go build ./... 通过
测试状态: ✅ go test ./... 全部通过
  - internal/client: 1 test (8.3s) — 完整 NAT+WSS+Login+Report 链路
  - internal/server: 2 tests (0.8s) — Login + 双客户端 + Relay 发现
  - pkg/mux: 7 tests + 1 bench (0.2s) — 并发/大载荷/FIN/session
  - pkg/tunnel: 3 tests (0.16s) — 端到端转发/5 并发/统计

  - pkg/relay: 3 tests (0.3s) — 双向桥接/1MB 中继/认证拒绝

二进制: bin/inp2ps (6.0MB) + bin/inp2pc (5.6MB) (静态编译, strip)
```

## 接口约定（核心层 ↔ 前端/次要层）

### server.Server 暴露的方法（供 F1 REST API 调用）
```go
srv.GetNode(name string) *NodeInfo          // 查单个设备
srv.GetOnlineNodes() []*NodeInfo            // 在线设备列表
srv.GetRelayNodes(user string) []*NodeInfo  // 中继节点列表
srv.PushConnect(from, to, app)              // 触发打洞
// NodeInfo 字段: Name, PublicIP, NATType, Version, OS, LanIP, 
//   RelayEnabled, SuperRelay, ShareBandwidth, LoginTime, LastHeartbeat, Apps
```

### client.Client 暴露的方法（供 S1 配置持久化调用）
```go
client.Run() error    // 主循环（阻塞）
client.Stop()         // 优雅退出
// 配置通过 config.ClientConfig 传入
```