云端暂存 CloudCache API（v6.45）

创建: 2026-05-15 | 更新: 2026-08-15
基础URL: https://tools.wktyl.com/api/cloud_cache/
维护: Xianyan 团队
关联: 文件传输核心 · 短链服务

职责：云端暂存文件（设备间中转）+ 局域网二维码配对 + 跨网络文件下载。

1. 通用约定

• 公共接口（无需登录），token 用于文件加密
• 文件大小限制：100MB / 默认；企业用户可达 1GB
• 过期时间：24h（默认），可调 1h-7d
• 频率：上传 30/60s，下载不限，二维码生成 60/60s

2. 接口清单

2.1 文件上传 / 下载

• POST /api/cloud_cache/upload — 上传文件，返回 cache_id + download_url
• GET /api/cloud_cache/{cache_id} — 查询元数据
• GET /api/cloud_cache/{cache_id}/download — 下载（可走 P2P 或 CDN）
• DELETE /api/cloud_cache/{cache_id} — 删除（创建者或过期）
• POST /api/cloud_cache/batchDelete — 批量删除

2.2 二维码配对（核心）

• POST /api/cloud_cache/qrcode/generate — 创建设备配对二维码（内含局域网 URL + xianyan:// scheme）
• POST /api/cloud_cache/qrcode/parse — 扫描端解析二维码
• POST /api/cloud_cache/qrcode/confirm — 一键确认（局域网配对）

2.3 局域网增强

• GET /api/cloud_cache/lan/peers?session_id=... — 列出同局域网内可发现的对端设备
• POST /api/cloud_cache/lan/transfer — 通过局域网 IP 直传（不走云端）

2.4 加密

• POST /api/cloud_cache/encrypt — 上传前客户端加密（AES-256）
• GET /api/cloud_cache/decrypt — 下载并解密（客户端持有密钥）

3. 输入字段

{
  "filename": "...",
  "size_bytes": 1024000,
  "mime": "image/png",
  "expire_hours": 24,
  "password": "可选"
}

4. 响应

POST /api/cloud_cache/upload

# 响应
{
  "code": 1,
  "data": {
    "cache_id": "cc_abc123",
    "download_url": "https://cdn.xianyan.cc/cache/cc_abc123",
    "expires_at": 1777243207,
    "sha256": "...",
    "qr_url": "https://tools.wktyl.com/cache/qr/cc_abc123"
  }
}

5. 配对流程

mermaid sequenceDiagram participant A as 设备 A participant S as Server participant B as 设备 B A->>S: POST /qrcode/generate {lan_only: true} S-->>A: {qr_data: "xianyan://transfer?...;LAN:192.168.1.10"} B->>B: 扫码 → 解析 + 局域网发现 B->>S: POST /qrcode/parse (扫码) S->>A: HTTP-PUSH 通知被扫 A->>A: 用户点击"确认" A->>S: POST /qrcode/confirm S-->>B: 配对成功（token） B->>A: LAN 直连 192.168.1.10:8848 传输

6. 设计要点

• 24h 自动过期：避免云端堆积，回收存储
• LAN + QR 组合：v6.45 新增，局域网环境下 P2P 直连，节省云端流量
• 可选 AES-256 客户端加密：密码不在服务端留痕，敏感文件可端到端加密
• 二维码包含 LAN URL：扫码即可发现局域网内设备，无需额外步骤

7. 关联文档

• 文件传输核心（WebSocket）
• 短链服务