P2P 直传

P2P 直传是本 fork 在上游基础上增加的核心特性：文件不经过服务器，发布者与下载者的浏览器之间通过 WebRTC 直连传输。发布零等待，服务器零负担。

工作原理

传统模式下，文件必须先完整上传到服务器，才能生成提取码分享。P2P 直传改变了这一点：

传统模式：  发布者 ──上传──► 服务器存储 ──下载──► 下载者
P2P 直传：  发布者 ◄────WebRTC 直连────► 下载者
                     （服务器只负责信令握手）

• 信令握手（交换连接信息）经由服务器，流量极小；
• 文件数据在两端浏览器之间点对点传输，全程加密（DTLS），并附带完整性校验；
• 服务器不存储、不转发任何文件内容。

发布：勾选「P2P 直传」

1. 在首页选择「文件分享」，添加文件；
2. 「P2P 直传」开关默认开启，保持勾选；
3. 点击上传——文件不传输，立即出码；
4. 把提取码发给对方。

发布后页面会显示在线状态与「已完成传输」计数。请保持页面打开，直到对方取件完成——发布者关闭页面后，该分享即失效，下载者会看到明确提示。

P2P 分享的过期方式

P2P 分享不支持「按取件次数」过期（数据一旦交给对方无法收回），仅支持按天 / 小时 / 分钟 / 永久。分享的实际存活期 = 发布者页面存活期与所设过期时间的较早者。

取件：直连下载

1. 在首页输入提取码；
2. 页面识别到 P2P 分享后进入直连取件面板，点击「直连取件」；
3. 浏览器建立直连后开始传输，进度实时显示；
4. 传输完成后自动校验完整性，然后保存文件。

保存方式取决于站点协议：

站点	保存方式	大小上限
HTTPS	流式直落磁盘（File System Access API）	无软件上限，只受磁盘空间约束
HTTP	内存中转后保存	超过 1GB 自动分卷（.001 / .002 …），按页面提示用命令合并

建议 HTTPS 部署

生产环境强烈建议配置 HTTPS：下载端走流式落盘，任意大小文件都无需分卷合并，体验最完整。

大小与配额

• 单文件大小不设限（p2pMaxSize=0）：P2P 文件不落服务端磁盘，大小只受两端设备约束；
• 不占存储配额：P2P 分享不计入 storageLimit，也不占用下载次数；
• 后台无空记录：P2P 分享不会出现在管理面板的文件管理列表中。

连接性（NAT 穿透）

WebRTC 直连需要 NAT 穿透，服务端为此内置了 STUN 服务：

• 自建 STUN：容器监听 3478/udp，部署时建议放行该端口；
• 公共兜底：额外配置了公共 STUN 服务器，自建端口不可达时仍可打洞；
• CGNAT 过滤：自动过滤 100.64.0.0/10 等 CGNAT 虚网地址段的候选地址，避免流量被 VPN/虚拟网卡隧道绕道中继导致限速。

大多数家庭宽带与移动网络场景下可以成功直连。如果两端都在严格的 NAT 之后（企业网络、部分对称 NAT），直连会失败并明确提示——此时请改用普通上传模式（文件经服务器中转）。

关于服务器中转兜底

设计方案中包含「流式中转」兜底模式（直连失败时由服务器转发、不落盘），该模式数据面尚未启用。当前版本直连失败即明确报错，不会静默降级。

管理端配置

管理员可在系统设置中调整以下 P2P 相关项（均有合理默认值，通常无需改动）：

配置项	默认值	说明
enableP2P	1	总开关，关闭后隐藏 P2P 功能
p2pDefaultChecked	1	上传页 P2P 开关是否默认勾选
p2pMaxSize	0	单文件大小上限（字节），0 = 不限制
p2pMaxPeers	3	单个分享同时服务的下载者数量上限
p2pHeartbeatTimeout	30	发布者心跳超时（秒），超时判定离线
p2pStunEnabled	1	是否启用内置 STUN 服务
p2pStunPort	3478	内置 STUN 监听端口（UDP）
p2pStunUrls	空	自定义 STUN 列表，留空 = 跟随站点访问入口自动派生
p2pRelayEnabled	1	中转模式开关（数据面尚未实现，仅预留）

常见问题

发布者关掉页面，对方还能取件吗？ 不能。P2P 数据源就是发布者的浏览器，页面关闭即分享失效。需要「发完就走」的场景请用普通上传模式。

下载卡在连接中 / 提示直连失败？ 两端 NAT 穿透失败。确认服务端 3478/udp 已放行；若仍失败，改用普通上传模式。

传输速度不理想？ 确认两端设备没有开启虚拟组网软件（如会分配 100.64.0.0/10 CGNAT 地址的工具）——本版本已自动过滤此类地址，但极端情况下仍可能被运营商 QoS 限速。直连速度取决于两端上行带宽。

大文件下载提示分卷保存？ 说明站点是 HTTP（非安全上下文），浏览器不允许流式落盘。按页面提示合并分卷即可；或为站点配置 HTTPS 一劳永逸。

设计细节

完整的技术设计（状态机、信令协议、安全设计、分阶段实施记录）见 p2p-design.md。