在跨平台文件传输工具领域，LocalSend 以开源、端到端加密且无需互联网中转的特性脱颖而出。其核心创新在于放弃传统云服务中转思路，完全依托局域网实现设备发现与直连传输。理解这一协议的设计逻辑，对于构建类似 P2P 应用或优化局域网通信机制具有重要参考价值。
协议设计哲学：零依赖与容错优先
LocalSend 协议的核心目标极为简洁 —— 建立一套不依赖外部服务器的 REST 通信机制，使任意局域网内的设备能够相互发现并传输文件。然而现实网络环境复杂多变：部分设备不支持多播、部分场景下无法启动 HTTP 服务器、防火墙策略差异显著。为此，协议设计了多重降级方案，确保只要通信双方之一能够暴露服务，便可完成发现与传输。
这种「聪明」的协议设计理念体现在两个层面：发现阶段的 Multicast UDP 主路径与 HTTP 扫描备用路径；传输阶段的 Upload API 与 Download API 双向支持。前者解决设备发现问题，后者解决谁充当服务器的角色分配。这种双向兼容机制大幅提升了协议在复杂网络环境下的存活率。
设备发现：多播广播与双向注册
LocalSend 的设备发现机制借鉴了 mDNS/DNS-SD 的思想，但实现了完全自研的协议栈。默认配置使用 UDP 多播方式：目标地址为 224.0.0.167，端口为 53317。选择这一地址的原因是部分 Android 设备仅接受特定的组播地址，224.0.0.0/24 段兼容性最佳。
设备启动时，首先向多播组发送公告消息。公告载荷包含设备别名、协议版本、设备型号、设备类型、指纹信息、监听端口、协议类型以及下载 API 可用性标志。其中指纹字段尤为关键 —— 在 HTTPS 模式下，指纹为证书的 SHA-256 哈希值；在 HTTP 模式下，则为随机生成的字符串。收到公告的其他设备通过比对指纹，可判断是否为自身（避免自发现），同时将该设备纳入可用对等端列表。
公告消息被设置为可配置：端口、地址均可通过应用设置调整。这种灵活性源于真实网络环境的多样性 —— 企业网络可能限制特定端口或组播地址，允许多配置路径是保障可用性的务实选择。
当设备 A 收到设备 B 的公告后，将触发注册响应流程。响应首先通过 HTTP/TCP 直接发送到对方端口（POST /api/localsend/v2/register），携带自身信息。如果 TCP 请求失败，设备可降级为同样使用 UDP 多播响应。这种双通道响应设计显著提高了发现成功率。
备用发现：全网段 HTTP 扫描
当多播方式不可用时，协议提供 HTTP 扫描作为兜底方案。设备将向本地网段的所有 IP 地址发送注册请求（POST /api/localsend/v2/register），通过 HTTP 响应判断目标是否为 LocalSend 实例。这一方案虽然效率较低（需要遍历 254 个地址），但在多播被阻断的场景下仍能工作。
从工程实践角度，备用发现机制的阈值设置值得关注：主路径（多播）超时通常设置为 3 至 5 秒，失败后切换至 HTTP 扫描；HTTP 扫描可并行发送请求以缩短总耗时，但需注意并发数限制以免触发网络设备告警或被误判为扫描攻击。
文件传输：双向 HTTP API 设计
文件传输采用纯 HTTP 协议实现，区分两种场景：Upload API（默认）与 Download API。两种模式的核心差异在于谁充当 HTTP 服务器 ——Upload 模式下接收方开启服务器，Download 模式下发送方开启服务器。
Upload 流程
发送方首先调用准备接口（POST /api/localsend/v2/prepare-upload），仅传输元数据：文件名称、大小、MIME 类型、SHA256 哈希、可选预览图、修改时间等。接收方据此决定是否接受传输，并返回会话 ID 与各文件的授权令牌。如果接收方设置了 PIN 验证，发送方需在请求参数中附加 PIN 码。
准备阶段可能返回多种 HTTP 状态码：204 表示无需传输（例如文件已存在且完整）；401 表示需要 PIN 或 PIN 错误；403 表示接收方拒绝；409 表示被其他会话阻塞；429 表示请求过于频繁。正确处理这些状态码是构建健壮客户端的关键。
获得令牌后，发送方通过 POST /api/localsend/v2/upload 接口传输实际文件内容。接口支持并行调用 —— 不同文件可以同时上传，充分利用带宽。会话可通过 cancel 接口中止。
Download 流程
当接收方无法启动 HTTP 服务器时，可启用 Download 模式。发送方生成访问 URL，接收方在浏览器中打开该地址，使用未加密的 HTTP 协议下载文件。选择 HTTP 而非 HTTPS 的原因是浏览器对自签名证书的处理限制 —— 这在安全敏感场景下需谨慎评估风险。
Download 模式同样支持准备阶段（prepare-download），接收方可获取文件元数据后再决定是否下载。如果用户刷新页面，发送方需根据会话 ID 验证请求合法性，防止会话劫持。
关键参数与工程化建议
实现或集成 LocalSend 协议时，以下参数值得重点关注。端口配置默认为 53317，建议在冲突检测失败时依次尝试 53318、53319 等递增端口，避免固定端口导致的启动失败。多播地址默认 224.0.0.167，若网络设备不支持可替换为 224.0.0.251（标准 mDNS 地址），但需验证客户端兼容性。
安全层面，协议强制 HTTPS 传输时使用自签名证书，指纹验证可有效防止中间人攻击。但 Download 模式使用明文 HTTP 的设计意味着敏感场景下应避免该模式，或在应用层实现额外加密。指纹字段还承担设备身份持久化功能 —— 更换网络后仍可通过指纹识别曾通信过的设备。
监控指标建议覆盖：发现成功率（多播 vs HTTP 降级比例）、传输完成率、各状态码分布、端到端延迟。异常告警阈值可参考：发现成功率低于 80% 触发排查、传输失败率超过 5% 触发告警。
总结
LocalSend 协议展示了如何在无需中心服务器的前提下，构建可靠的去中心化文件传输系统。其核心思路 —— 多路径发现、双向传输模式、明确的错误处理 —— 对于设计健壮的局域网 P2P 应用具有重要借鉴意义。理解这些设计决策背后的工程考量，能够帮助开发者在类似场景下做出更明智的技术选择。
资料来源：LocalSend 官方协议文档（https://github.com/localsend/protocol）