LocalSend 跨平台局域网文件传输：从网络配置到源码架构的技术指南

本文以 LocalSend 项目的多语言文档 马来语版 README 为骨架，系统讲解这款开源的 AirDrop 替代品如何基于 REST API 与 HTTPS 自签名证书实现无互联网依赖的安全文件共享，并覆盖防火墙端口放行、AP 隔离关闭、便携模式与隐藏启动等关键运维配置、故障排查决策表，以及结合仓库源码（Rust 核心与 Flutter 前端）对端口协议、设置持久化与构建流程的深入剖析。读完后，你将能够独立完成 LocalSend 的网络配置、从源码构建，并理解其底层通信与安全机制。

一、项目定位：不依赖互联网的局域网安全通信

LocalSend 是一款免费开源的跨平台应用，允许用户通过本地网络在附近设备之间安全地共享文件和消息，全程无需互联网连接。其核心设计理念在文档中表述得十分明确：

LocalSend 是一个跨平台应用，使用 REST API 和 HTTPS 加密实现设备间的安全通信。与依赖外部服务器的其他消息应用不同，LocalSend 不需要互联网连接或第三方服务器，使其成为本地通信的可靠解决方案。

从仓库结构可以看出这一理念的落地方式：通信核心被抽取为独立的 Rust 包 packages/core，其中 discovery 模块 负责设备发现，http 模块 承载 REST 服务，multicast 模块 负责广播发现，webrtc 模块 提供 P2P 直连能力。Flutter 层（app/lib）则通过 localsend_isolates 包以 Rust Isolate 方式调用这些核心能力，同时仓库还提供了独立命令行工具 cli/src。

二、防火墙与路由器配置：端口 53317 是唯一的默认端口

文档"Penyediaan"（配置）章节指出：大多数情况下 LocalSend 开箱即用，但如果发送或接收文件失败，通常需要配置防火墙以允许 LocalSend 通过本地网络通信。官方给出的防火墙规则表如下：

流量类型	协议	端口	动作
入站（Incoming）	TCP, UDP	53317	Allow
出站（Outgoing）	TCP, UDP	任意（Mana-mana）	Allow

2.1 端口 53317 在源码中的位置

这个默认端口在仓库中得到了充分印证：

• CLI 工具的默认端口定义为 cli/src/storage/config.rs 中的 DEFAULT_PORT: u16 = 53317，且 config.rs 中的注释 给出了 #port = 53317 的配置示例——CLI 端还支持通过 config.toml 覆盖该端口（见 cli/src/main.rs 中"Port of the HTTP server [default: config.toml, else 53317]"的参数说明）；
• 核心包的 URL 构造测试 packages/core/src/http/client/url.rs 反复验证了 https://192.168.1.1:53317/api/localsend/v2/register 这类 V2 协议端点；
• 设备发现的默认端口同样出现在 packages/core/src/discovery/store.rs 与 packages/core/src/model/discovery.rs 的测试数据中；
• CLI 启动横幅 cli/src/banner.rs 会把本机各网卡的地址渲染成 https://192.168.0.1:53317 形式输出给用户，并正确地为 IPv6 地址加上方括号（[::1]:53317）。

由此可以推断：53317 既是内置 HTTP(S) 服务的监听端口，也是设备发现消息中广播的端口，因此防火墙只需放行这一个端口的 TCP/UDP 入站流量即可覆盖主要场景。

2.2 关闭路由器的 AP 隔离

文档同时强调：必须确保路由器上的 AP 隔离（AP-Isolation）处于关闭状态。它默认通常是关闭的，但部分路由器（尤其是访客/ Guest 网络）会开启该功能。一旦开启，同一局域网内的设备之间无法互相通信，LocalSend 的设备发现与直连传输都会失败——这是"设备不可见"问题的首要排查点，与后文故障排查表中的第一条完全对应。

三、桌面端两个实用模式：便携模式与隐藏启动

文档的"Penyediaan"章节还介绍了两个桌面端的特色配置，两者都有明确的源码实现可查。

3.1 便携模式（Mod Mudah Alih）

（v1.13.0 引入）在与可执行文件相同的目录中创建一个名为 settings.json 的文件。该文件可以为空。应用检测到它之后，会改用该文件存储设置，而不是默认位置。

源码位于 app/lib/util/shared_preferences/shared_preferences_portable.dart。关键实现细节包括：

• SharedPreferencesPortable 继承自 SharedPreferencesFile，以 beautify: true 写入可读的 JSON；
• _resolveExecutable() 解析 Platform.resolvedExecutable 定位可执行文件目录。值得注意的边界处理：在某些虚拟磁盘（如 ImDisk RAM 盘）上读取该值会抛 TypeError，导致应用启动前崩溃，因此代码捕获异常并回退到当前工作目录（Directory.current.path），源码注释中引用了该缺陷背景；
• buildSettingsPath() 被标记为 @visibleForTesting，将"可执行文件目录 + settings.json"的拼接逻辑独立出来便于单测，对应测试见 test/unit/util/native 目录。

这一设计使 LocalSend 桌面版可以完全运行在 U 盘里：设置随文件走，不污染系统用户目录。Windows 下对应的默认设置路径则是 %APPDATA%\LocalSend\settings.json（见 app/lib/provider/persistence_provider.dart）。

3.2 以隐藏方式启动（仅托盘运行）

（v1.15.0 更新）要启动应用并隐藏主窗口（仅驻留系统托盘），使用 --hidden 命令行标志，例如：localsend_app.exe --hidden。 在 v1.14.0 及更早版本中，当 autostart 标志被设置且"隐藏"设置项开启时，应用才会隐藏启动。

托盘相关能力由 app/lib/util/native/tray_helper.dart 与 托盘监视器 支撑；自动启动则由 app/lib/util/native/autostart_helper.dart 处理。v1.15.0 的改动把"隐藏启动"从依赖自启动上下文中解耦为显式的 CLI 标志，使行为更可预测。

四、工作原理：REST API + 即时生成的自签名 TLS

文档"Bagaimana ia Berfungsi"（工作原理）章节的核心表述是：

LocalSend 使用一种安全的通信协议，设备之间通过 REST API 互相通信。所有数据都通过 HTTPS 安全传输，TLS/SSL 证书在每台设备上即时生成，从而确保最大程度的安全性。

这与仓库实现高度一致：

• 证书即时生成：packages/core/src/crypto/cert.rs 实现了设备本地生成自签名证书的逻辑，配合 nonce.rs、token.rs 提供握手所需的随机数与令牌机制；
• REST 端点：客户端 URL 测试 packages/core/src/http/client/url.rs 显示了 V2 协议的典型端点 /api/localsend/v2/register 与 /api/localsend/v2/info；服务端实现位于 packages/core/src/http/server 目录；
• 设备发现：基于多播/广播，packages/core/src/multicast/socket.rs 负责底层套接字，发现状态保存在 packages/core/src/discovery/store.rs；
• P2P 通道：当需要绕过路由层（如 NAT 后互访）时，packages/core/src/webrtc/webrtc.rs 提供 WebRTC 数据通道，signaling.rs 处理信令交换。

协议细节官方维护在独立的 protocol 仓库中（文档"Bagaimana ia Berfungsi"一节指向该外部文档，此处不展开外链）。测试层面，packages/core/tests 目录包含 v2_tls_pinning.rs、accept_resilience.rs、event_backpressure.rs 等集成测试，可分别验证 TLS 证书固定、连接接收的健壮性与事件背压处理，是理解协议边界条件的最佳入口。

五、从源码构建：Flutter + Rust 双栈工作流

文档"Cara Mula"（快速开始）章节给出了完整的源码构建步骤，这里完整继承并结合仓库补充要点：

1. 安装 Flutter——直接使用官方安装方式，或推荐通过 fvm 管理（版本见 .fvmrc）；
2. 安装 Rust 工具链；
3. 克隆 LocalSend 仓库；
4. 执行 cd app 进入应用目录；
5. 执行 flutter pub get 下载依赖；
6. 执行 flutter run 启动应用。

关于 Flutter 版本的注意事项（原文档以 NOTE 形式强调，必须保留）：LocalSend 目前要求特定版本的 Flutter（由 .fvmrc 声明，当前仓库锁定的版本为 3.41.9）。由于所需版本与系统全局安装的 Flutter 版本可能不一致，容易出现构建问题；为使开发环境保持一致，LocalSend 使用 fvm 管理项目级 Flutter 版本——安装 fvm 之后，请运行 fvm flutter 而非直接使用 flutter。

Rust 侧工具链由仓库根的 rust-toolchain.toml 约束；Cargo 工作区包含 packages/core、packages/localsend_isolates/rust 与 cli 三个成员。Rust 二进制通过 rust_builder 中的 CargoKit 工具链集成到各平台构建（Android/iOS/macOS/Windows/Linux 均有对应集成目录）。

各平台的打包发布脚本集中在 support/scripts 目录，例如 compile_windows_msix_store.ps1、compile_mac_dmg.sh、compile_android_appbundle.ps1 等，可作为各平台构建产物的参考。

六、参与贡献：翻译与问题修复

6.1 翻译工作

文档说明 LocalSend 使用 Weblate 平台管理翻译，同时支持直接 fork 仓库手动提交。翻译文件位于 app/assets/i18n 目录，编辑 _missing_translations_<locale>.json 或 strings_<locale>.i18n.json 即可新增或更新词条。该目录当前包含 ar、de、fr、ja、pt-BR、zh-CN、zh-TW 等数十种语言的完整词条文件，以及对应的 _missing_translations_*.json 待译清单和 _unused_translations.json 冗余清单，翻译完成后的代码生成物为 app/lib/gen 目录 下的 strings_*.g.dart 系列文件。

原文档特别提醒：以 @ 前缀标记的字段不属于翻译对象——它们在应用中不会被使用，仅作为给译者提供文件信息或上下文的说明性文本。

6.2 缺陷修复与功能改进

• 修复缺陷（Bug）：发现问题后，直接提交附带清晰问题描述与修复说明的 Pull Request；
• 功能改进（Improvements）：请先提 Issue 讨论改进的必要性，再着手实现。

完整的协作规范见 CONTRIBUTING.md（含分发渠道等章节），项目行为约定另见 AGENTS.md。

七、故障排查：按"发送端 / 接收端"二维定位

文档"Menyelesaikan Masalah"（故障排查）章节提供了一张按平台维度切分的排查表，完整继承如下：

问题	平台（发送端）	平台（接收端）	解决方案
设备不可见	任意	任意	确保已关闭路由器上的 AP 隔离。若其开启，设备间的连接将被禁止。
设备不可见	任意	Windows	将网络配置为"专用（peribadi）"网络。Windows 在网络被配置为公用时限制更严格。
设备不可见	macOS、iOS	任意	可在系统设置的"隐私"中切换"本地网络（Rangkaian Tempatan）"权限。
速度过慢	任意	任意	改用 5 GHz 频段；在两台设备上同时关闭加密。
速度过慢	任意	Android	已知问题（指向 flutter-cavalry/saf_stream 上游 issue #4）。

排查优先级建议：先排除 AP 隔离（网络层）→ 再确认接收端系统级网络策略（Windows 网络类型、Apple 的本地网络权限）→ 最后才考虑性能调优（5 GHz、关闭加密）。其中"速度过慢"一行提到的 Android 接收端问题是上游 saf_stream 插件的已知缺陷，属于平台层限制而非 LocalSend 本身的 Bug。

八、分发渠道与平台兼容性

8.1 下载渠道矩阵

文档建议：由于应用没有自动更新机制，推荐从应用商店或包管理器获取应用。各平台渠道如下：

Windows	macOS	Linux	Android	iOS	Fire OS
Winget / Scoop / Chocolatey / EXE 安装包 / 便携 ZIP	App Store / Homebrew / DMG 安装器	Flathub / Nixpkgs / Snap / AUR / TAR / DEB / AppImage	Play Store / F-Droid / APK	App Store	Amazon

（各渠道的原始链接指向外部商店，此处以名称代指；"最新构建"类条目对应 releases 页面的最新发行版。）关于分发渠道的详细说明见 CONTRIBUTING.md 的 distribution 章节。

8.2 平台兼容性

平台	最低版本	备注
Android	5.0	-
iOS	12.0	-
macOS	11 Big Sur	旧系统可借助 OpenCore Legacy Patcher 2.0.2 运行（见 issue #1005 的讨论）
Windows	10	最后支持 Windows 7 的版本是 v1.15.4，未来可能恢复对 Windows 7 的支持
Linux	N.A.	-

九、小结

LocalSend 的技术价值可以浓缩为三点：

1. 零依赖架构：REST API + 设备本地即时生成的自签名 TLS 证书，全程不经过任何第三方服务器，packages/core 的 Rust 实现保证了跨平台行为一致；
2. 单一端口的简洁网络模型：默认端口 53317（TCP/UDP）覆盖服务与发现，防火墙配置一张表说清，cli/src/storage/config.rs 与 packages/core/src/http/client/url.rs 的源码和测试可交叉验证；
3. 贴近实操的工程细节：便携模式（可执行文件旁放置 settings.json，实现见 shared_preferences_portable.dart）、--hidden 托盘启动、fvm 锁定的 Flutter 版本（.fvmrc，当前为 3.41.9）与按发送/接收端切分的故障排查表，使部署与排障都有据可依。

结合 support/readme/README_MS.md 的完整叙述与上述源码路径，无论是网络管理员放行端口、开发者从源码构建，还是排查"设备不可见/速度慢"的具体场景，都能在仓库内找到对应的实现证据与验证用例。