文件传输核心
职责：文件传输核心 REST API（建连/握手/文件下载元数据）+ WebSocket 信令协议（设备发现/会话建立/中继转发）。
文件传输核心 API + WebSocket 信令（v1.5）
创建: 2026-05-15 | 更新: 2026-08-15
维护: Xianyan 团队
关联: 云端暂存 CloudCache
职责：文件传输核心 REST API（建连/握手/文件下载元数据）+ WebSocket 信令协议（设备发现/会话建立/中继转发）。
1. 协议双轨
| 通道 | 用途 | 协议 |
|---|---|---|
REST HTTPS |
文件下载 / 元数据 / 会话创建 | JSON |
WebSocket WSS |
设备发现 / P2P 协商 / 中继转发 | 二进制/JSON |
2. REST 接口
| 接口 | 方法 | 说明 |
|---|---|---|
/api/file_transfer/session |
POST | 创建传输会话（传入文件元数据） |
/api/file_transfer/session/{id} |
GET | 查会话详情（状态/进度） |
/api/file_transfer/file/{hash} |
GET | 通过哈希下载（CDN 级缓存） |
/api/file_transfer/upload |
POST | 服务端中继上传（≤100MB） |
/api/file_transfer/cancel/{id} |
POST | 取消会话 |
/api/file_transfer/history |
GET | 历史会话 |
会话字段：
{
"id": "uuid",
"from": "device-fingerprint",
"to": "device-fingerprint",
"files": [
{ "name": "...", "size": 1024000, "hash": "sha256", "mime": "..." }
],
"transport": "p2p|relay|cloud",
"status": "pending|connected|transferring|done|failed"
}
3. WebSocket 信令
ws://tools.wktyl.com/ws/file_transfer
type 类型（v1.5 类型归一化，兼容旧 kebab-case）：
| type | 方向 | 含义 |
|---|---|---|
device_online |
双向 | 设备上线广播 |
device_offline |
双向 | 设备下线 |
invite |
主动 | 邀请对方 |
accept |
应答 | 接受邀请 |
reject |
应答 | 拒绝 |
transfer_request |
主动 | 发起传输（含文件元数据） |
transfer_accept |
应答 | 接收方确认 |
transfer_chunk |
中继 | 数据块（仅 relay 模式） |
transfer_complete |
双向 | 完成通知 |
delivery_ack |
应答 | 投递确认（v1.5.0 修复：不再丢失） |
relay_forward |
服务端 | 通用转发（带 to 的未注册类型，按 deviceId→fingerprint 路由） |
4. 传输流程
mermaid
sequenceDiagram
participant A as 设备 A
participant S as Server (WSS)
participant B as 设备 B
A->>S: ws.send {type:"device_online", device_id, fingerprint}
B->>S: 同上
A->>S: ws.send {type:"invite", to:b_fingerprint, session_meta}
S->>B: ws.forward
B->>S: ws.send {type:"accept", to:a_fingerprint}
A->>S: ws.send {type:"transfer_request", files:[...]}
B->>S: ws.send {type:"transfer_accept"}
A->>A: 尝试 P2P（NAT 穿透）
alt P2P 失败
A->>S: ws.send {type:"transfer_chunk"}
S->>B: relay 转发
end
B->>S: ws.send {type:"delivery_ack", chunk_id}
A->>S: ws.send {type:"transfer_complete"}
5. 设计要点
- 三层 fallback：P2P（最高速）→ Cloud Relay（中速）→ Server Upload（兜底）
- delivery_ack 必须确认：v1.5.0 修复后所有中继消息强制 ack
- session 一次性：每个会话对应一组文件，会话结束即销毁
- 类型归一化：v1.5 启用，旧
text-message等 kebab-case 自动转 camelCase