LocalSend 局域网文件分享实战网络配置、工作原理、源码构建与故障排查指南【免费下载链接】localsendAn open-source cross-platform alternative to AirDrop项目地址: https://gitcode.com/GitHub_Trending/lo/localsend本文基于 LocalSend 项目的菲律宾语Tagalog官方 READMEsupport/readme/README_PH.md整理扩充覆盖其局域网安全分享的完整使用路径防火墙与路由器配置、HTTPS 自签证书的工作原理含源码级验证、Portable Mode 与--hidden启动参数、从源码编译的步骤以及官方故障排查表帮助你把一个“开箱即用”的本地 AirDrop 替代品真正部署到生产环境。LocalSend 是什么无互联网依赖的安全本地分享LocalSend 是一款免费、开源的跨平台应用允许你在本地网络内的设备之间安全地分享文件与消息不需要互联网连接也不依赖任何第三方服务器。其核心设计是设备之间通过REST API通信所有数据经由HTTPS 加密传输每个设备本地自行生成TLS/SSL 证书不经过任何外部 CA 或中转服务器。这与依赖外部消息服务器的方案有本质区别数据始终留在你的局域网内隐私与速度都由本地网络条件决定。分发渠道与系统兼容性官方建议从应用商店或包管理器下载应用因为 LocalSend没有自动更新功能。各平台可选的分发渠道详见 README.md 的 Download 一节平台分发渠道WindowsWinget、Scoop、Chocolatey、EXE 安装包、便携 ZIPReleases 页macOSApp Store、Homebrew、DMG 安装包LinuxFlathub、Nixpkgs、Snap、AUR、DEB、AppImage、TARAndroidPlay Store、F-Droid、APKReleases 页iOSApp StoreFire OSAmazon 应用商店其中 Windows 二进制文件经过代码签名签名策略可参阅 CODE_SIGNING.md各分发包的打包细节见 CONTRIBUTING.md 的 Distribution 章节。最低版本兼容性继承自 support/readme/README_PH.md 的 Pagkakatugma 表平台最低版本备注Android5.0—iOS12.0—macOS11 Big Sur老机型可借助 OpenCore Legacy Patcher 2.0.2 运行Windows10最后一个支持 Windows 7 的版本是 v1.15.4LinuxN.A.Gnome 依赖xdg-desktop-portal与xdg-desktop-portal-gtkKDE 依赖xdg-desktop-portal与xdg-desktop-portal-kde网络配置防火墙端口与 AP 隔离在大多数场景下 LocalSend 开箱即用。但如果发送或接收文件失败通常需要两类网络配置。防火墙规则流量类型协议端口动作入站IncomingTCP、UDP53317允许出站OutgoingTCP、UDP任意允许端口 53317 并非任意值——从源码可以确认它是全项目统一的默认端口核心库 packages/core/src/multicast/mod.rs 中定义DEFAULT_PORT: u16 53317注释明确写着“与默认 HTTP 服务器端口相同”命令行工具的 cli/src/storage/config.rs 同样以DEFAULT_PORT: u16 53317作为config.toml缺省值。也就是说UDP 组播发现与 TCP HTTPS 服务复用同一个 53317 端口防火墙只需放行这一个端口即可覆盖发现与传输两条链路。路由器 AP 隔离务必确认路由器的AP 隔离AP Isolation已关闭。它默认通常是关闭的但部分路由器——尤其是访客网络guest network——会默认开启。AP 隔离开启后同一 Wi-Fi 下的设备彼此无法直连通信LocalSend 的组播发现与点对点传输都会失败。工作原理源码剖析从组播发现到 HTTPS 传输官方 README 对原理的表述是“LocalSend 使用安全的通信协议让设备通过 REST API 相互通信所有数据经 HTTPS 安全发送TLS/SSL 证书在每台设备上即时生成”。结合当前仓库源码这套机制的具体实现如下1. 组播发现UDP, 53317发现模块 packages/core/src/multicast/mod.rs 定义了IPv4 组播组224.0.0.167DEFAULT_MULTICAST_GROUP。选择224.0.0.0/24网段是有原因的源码注释指出在某些 Android 设备上只有该网段的 IP 能接收 UDP 组播消息IPv6 组播组ff12::fd3a:e420DEFAULT_MULTICAST_GROUP_V6这是 LocalSend 在协议 v2.2 之上自行扩展的 IPv6 发现能力IPv4 仍是基线设备加入网络后会发送“通告”announce且为避免单条数据报丢失、以及刚上线的设备尚未就绪通告会按 100ms / 500s 2000ms 的延迟序列重复三次ANNOUNCE_DELAYSUDP 只用于“广播自己存在”实际握手是收到通告的一方主动向宣告方发起 HTTP register 请求——这与防火墙规则表中的出站放行相呼应。2. 自签证书与设备指纹证书生成实现在 packages/core/src/crypto/cert.rs。从源码注释可以看到关键设计每台设备生成RSA-2048密钥对与自签名证书CNLocalSend User无 SAN设备之间仅凭证书的 SHA-256 指纹相互识别因此证书名不携带任何信息证书有效期沿用 rcgen 默认区间1975–4096 年实际上永不过期也无需因时间原因轮换。这套“本地生成证书 指纹互认”的设计正是 README 所说“generated on the fly on each device, ensuring maximum security”的工程落地没有任何中心化信任源安全边界完全由设备自身密钥对保证。3. HTTPS 服务与传输HTTPS 侧由 packages/core/src/http/server/ 下的服务端实现承载含 v2/v3 协议版本、web 下载页等而 packages/core/src/http/client/url.rs 的测试用例如https://192.168.1.1:53317/api/localsend/v2/register展示了注册请求的最终 URL 形态。项目整体的模块依赖关系可用 support/docs/dependency-hierarchy.d2 描述的层次图来理解。协议细节的权威文档在独立的 LocalSend Protocol 仓库中README 外链此处不展开。实用特性Portable Mode 与隐藏启动支持文档 的 Setup 一节给出了两个桌面端实用特性二者均可在源码中验证。Portable Modev1.13.0 引入在可执行文件同一目录下创建一个名为settings.json的文件可以为空文件应用就会改用该文件存储设置而不是默认位置。源码依据app/lib/util/shared_preferences/shared_preferences_portable.dart 注释即写明“使用可执行文件旁的 settings.json 文件”对照 app/lib/provider/persistence_provider.dart默认的 Windows 存储位置是%APPDATA%\LocalSend\settings.json。Portable Mode 的价值在于设置随可执行文件一起放在 U 盘里即可携带无需在系统配置目录留下痕迹。隐藏启动--hiddenv1.15.0 更新以localsend_app.exe --hidden启动应用只驻留在系统托盘、不显示主窗口。注意版本行为差异v1.14.0 及更早版本是“设置了 autostart 且隐藏设置开启”时才隐藏启动v1.15.0 起改为直接监听--hidden命令行参数该变更亦记录在 app/assets/CHANGELOG.md。实现上app/lib/util/native/autostart_helper.dart 定义了startHiddenFlag --hidden而 Linux 原生侧 app/linux/my_application.cc 会逐一检查入口参数中是否包含--hidden来决定是否最小化到托盘。从源码编译运行Getting Started官方给出的编译步骤继承自 support/readme/README_PH.md 的 Pagsisimula 章节安装 Flutter——直接安装或使用 [fvm] 管理版本所需版本见仓库根的 .fvmrc克隆 LocalSend 仓库如需克隆可使用git clone https://gitcode.com/GitHub_Trending/lo/localsendcd app进入应用目录flutter pub get下载依赖flutter run启动应用。注意原文档 NOTE 原文翻译LocalSend 当前要求较旧的 Flutter 版本在 .fvmrc 中指定当前值为3.41.9系统级安装的 Flutter 版本若不匹配可能导致构建问题。为保持开发一致性项目使用fvm管理 Flutter 版本——安装fvm后用fvm flutter替代flutter命令。补充说明当前仓库中 Flutter 应用app/通过 Rust 核心库packages/core/、packages/localsend_isolates/完成发现与传输Rust 工具链版本由根目录 rust-toolchain.toml 锁定工作区定义见 Cargo.toml。菲律宾语 README 未单独列出安装 Rust 的步骤而英文版 README.md 的 Getting Started 中包含该步骤完整编译时请以英文版为准。贡献指南翻译与 Bug 修复翻译推荐方式使用 Weblate 协作翻译平台管理翻译平台地址见 README.md 外链替代方式fork 仓库后手动添加翻译。翻译文件位于 app/assets/i18n/编辑_missing_translations_locale.json或strings_locale.i18n.json即可新增/更新词条生成的 Dart 字符串类在 app/lib/gen/ 下如strings_*.g.dart。重要提示原文档原文翻译带前缀的字段不需要翻译。它们不被应用在任何地方使用只是关于文件本身的说明文本或为译者提供上下文。Bug 修复与改进Bug 修复发现 bug 后创建包含清晰问题描述与修复方案的 pull request改进建议先创建 issue 讨论改进的必要性再动手实现。更多细节见 CONTRIBUTING.md。故障排查表官方继承自 support/readme/README_PH.md 的 Pag-troubleshoot 表五条官方排查项问题发送端平台接收端平台解决方案设备不可见任意任意确认路由器 AP 隔离已关闭开启时设备间连接会被禁止设备不可见任意Windows将网络配置为“专用private”网络Windows 对公网public网络的限制更严格设备不可见macOS / iOS任意尝试在系统设置的“隐私”中切换“本地网络Local Network”权限速度过慢任意任意改用 5GHz 频段并在两台设备上均关闭加密速度过慢任意Android已知问题根因在 Flutter Android 侧的saf_stream插件issue 见原文档外链从源码结构看“设备不可见”类问题基本都对应发现链路的某一环路由器 AP 隔离会阻断组播224.0.0.167或点对点 TCP 连接Windows 公网模式与 macOS/iOS 的本地网络权限则会限制系统的网络发现能力。发现与传输复用 53317 端口的单端口设计使得“只开 TCP 忘了 UDP”这类配置错误会成为典型故障点——建议按前文的防火墙规则表同时放行 TCP 与 UDP。小结LocalSend 菲律宾语 README 的核心价值在于给出了一个可落地的部署清单以 53317 单端口放行 TCP/UDP、关闭 AP 隔离为网络基线以 Portable Mode可执行文件旁建settings.json和--hidden托盘启动为桌面端实用特性以 fvm 锁定 Flutter 版本保证源码可编译。再结合 packages/core/ 中组播发现与 RSA-2048 自签证书的源码实现这套“组播广播 HTTP 注册 证书指纹互认 HTTPS 传输”的链路就完全可验证、可复现了。【免费下载链接】localsendAn open-source cross-platform alternative to AirDrop项目地址: https://gitcode.com/GitHub_Trending/lo/localsend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LocalSend 局域网文件分享实战：网络配置、工作原理、源码构建与故障排查指南
LocalSend 局域网文件分享实战网络配置、工作原理、源码构建与故障排查指南【免费下载链接】localsendAn open-source cross-platform alternative to AirDrop项目地址: https://gitcode.com/GitHub_Trending/lo/localsend本文基于 LocalSend 项目的菲律宾语Tagalog官方 READMEsupport/readme/README_PH.md整理扩充覆盖其局域网安全分享的完整使用路径防火墙与路由器配置、HTTPS 自签证书的工作原理含源码级验证、Portable Mode 与--hidden启动参数、从源码编译的步骤以及官方故障排查表帮助你把一个“开箱即用”的本地 AirDrop 替代品真正部署到生产环境。LocalSend 是什么无互联网依赖的安全本地分享LocalSend 是一款免费、开源的跨平台应用允许你在本地网络内的设备之间安全地分享文件与消息不需要互联网连接也不依赖任何第三方服务器。其核心设计是设备之间通过REST API通信所有数据经由HTTPS 加密传输每个设备本地自行生成TLS/SSL 证书不经过任何外部 CA 或中转服务器。这与依赖外部消息服务器的方案有本质区别数据始终留在你的局域网内隐私与速度都由本地网络条件决定。分发渠道与系统兼容性官方建议从应用商店或包管理器下载应用因为 LocalSend没有自动更新功能。各平台可选的分发渠道详见 README.md 的 Download 一节平台分发渠道WindowsWinget、Scoop、Chocolatey、EXE 安装包、便携 ZIPReleases 页macOSApp Store、Homebrew、DMG 安装包LinuxFlathub、Nixpkgs、Snap、AUR、DEB、AppImage、TARAndroidPlay Store、F-Droid、APKReleases 页iOSApp StoreFire OSAmazon 应用商店其中 Windows 二进制文件经过代码签名签名策略可参阅 CODE_SIGNING.md各分发包的打包细节见 CONTRIBUTING.md 的 Distribution 章节。最低版本兼容性继承自 support/readme/README_PH.md 的 Pagkakatugma 表平台最低版本备注Android5.0—iOS12.0—macOS11 Big Sur老机型可借助 OpenCore Legacy Patcher 2.0.2 运行Windows10最后一个支持 Windows 7 的版本是 v1.15.4LinuxN.A.Gnome 依赖xdg-desktop-portal与xdg-desktop-portal-gtkKDE 依赖xdg-desktop-portal与xdg-desktop-portal-kde网络配置防火墙端口与 AP 隔离在大多数场景下 LocalSend 开箱即用。但如果发送或接收文件失败通常需要两类网络配置。防火墙规则流量类型协议端口动作入站IncomingTCP、UDP53317允许出站OutgoingTCP、UDP任意允许端口 53317 并非任意值——从源码可以确认它是全项目统一的默认端口核心库 packages/core/src/multicast/mod.rs 中定义DEFAULT_PORT: u16 53317注释明确写着“与默认 HTTP 服务器端口相同”命令行工具的 cli/src/storage/config.rs 同样以DEFAULT_PORT: u16 53317作为config.toml缺省值。也就是说UDP 组播发现与 TCP HTTPS 服务复用同一个 53317 端口防火墙只需放行这一个端口即可覆盖发现与传输两条链路。路由器 AP 隔离务必确认路由器的AP 隔离AP Isolation已关闭。它默认通常是关闭的但部分路由器——尤其是访客网络guest network——会默认开启。AP 隔离开启后同一 Wi-Fi 下的设备彼此无法直连通信LocalSend 的组播发现与点对点传输都会失败。工作原理源码剖析从组播发现到 HTTPS 传输官方 README 对原理的表述是“LocalSend 使用安全的通信协议让设备通过 REST API 相互通信所有数据经 HTTPS 安全发送TLS/SSL 证书在每台设备上即时生成”。结合当前仓库源码这套机制的具体实现如下1. 组播发现UDP, 53317发现模块 packages/core/src/multicast/mod.rs 定义了IPv4 组播组224.0.0.167DEFAULT_MULTICAST_GROUP。选择224.0.0.0/24网段是有原因的源码注释指出在某些 Android 设备上只有该网段的 IP 能接收 UDP 组播消息IPv6 组播组ff12::fd3a:e420DEFAULT_MULTICAST_GROUP_V6这是 LocalSend 在协议 v2.2 之上自行扩展的 IPv6 发现能力IPv4 仍是基线设备加入网络后会发送“通告”announce且为避免单条数据报丢失、以及刚上线的设备尚未就绪通告会按 100ms / 500s 2000ms 的延迟序列重复三次ANNOUNCE_DELAYSUDP 只用于“广播自己存在”实际握手是收到通告的一方主动向宣告方发起 HTTP register 请求——这与防火墙规则表中的出站放行相呼应。2. 自签证书与设备指纹证书生成实现在 packages/core/src/crypto/cert.rs。从源码注释可以看到关键设计每台设备生成RSA-2048密钥对与自签名证书CNLocalSend User无 SAN设备之间仅凭证书的 SHA-256 指纹相互识别因此证书名不携带任何信息证书有效期沿用 rcgen 默认区间1975–4096 年实际上永不过期也无需因时间原因轮换。这套“本地生成证书 指纹互认”的设计正是 README 所说“generated on the fly on each device, ensuring maximum security”的工程落地没有任何中心化信任源安全边界完全由设备自身密钥对保证。3. HTTPS 服务与传输HTTPS 侧由 packages/core/src/http/server/ 下的服务端实现承载含 v2/v3 协议版本、web 下载页等而 packages/core/src/http/client/url.rs 的测试用例如https://192.168.1.1:53317/api/localsend/v2/register展示了注册请求的最终 URL 形态。项目整体的模块依赖关系可用 support/docs/dependency-hierarchy.d2 描述的层次图来理解。协议细节的权威文档在独立的 LocalSend Protocol 仓库中README 外链此处不展开。实用特性Portable Mode 与隐藏启动支持文档 的 Setup 一节给出了两个桌面端实用特性二者均可在源码中验证。Portable Modev1.13.0 引入在可执行文件同一目录下创建一个名为settings.json的文件可以为空文件应用就会改用该文件存储设置而不是默认位置。源码依据app/lib/util/shared_preferences/shared_preferences_portable.dart 注释即写明“使用可执行文件旁的 settings.json 文件”对照 app/lib/provider/persistence_provider.dart默认的 Windows 存储位置是%APPDATA%\LocalSend\settings.json。Portable Mode 的价值在于设置随可执行文件一起放在 U 盘里即可携带无需在系统配置目录留下痕迹。隐藏启动--hiddenv1.15.0 更新以localsend_app.exe --hidden启动应用只驻留在系统托盘、不显示主窗口。注意版本行为差异v1.14.0 及更早版本是“设置了 autostart 且隐藏设置开启”时才隐藏启动v1.15.0 起改为直接监听--hidden命令行参数该变更亦记录在 app/assets/CHANGELOG.md。实现上app/lib/util/native/autostart_helper.dart 定义了startHiddenFlag --hidden而 Linux 原生侧 app/linux/my_application.cc 会逐一检查入口参数中是否包含--hidden来决定是否最小化到托盘。从源码编译运行Getting Started官方给出的编译步骤继承自 support/readme/README_PH.md 的 Pagsisimula 章节安装 Flutter——直接安装或使用 [fvm] 管理版本所需版本见仓库根的 .fvmrc克隆 LocalSend 仓库如需克隆可使用git clone https://gitcode.com/GitHub_Trending/lo/localsendcd app进入应用目录flutter pub get下载依赖flutter run启动应用。注意原文档 NOTE 原文翻译LocalSend 当前要求较旧的 Flutter 版本在 .fvmrc 中指定当前值为3.41.9系统级安装的 Flutter 版本若不匹配可能导致构建问题。为保持开发一致性项目使用fvm管理 Flutter 版本——安装fvm后用fvm flutter替代flutter命令。补充说明当前仓库中 Flutter 应用app/通过 Rust 核心库packages/core/、packages/localsend_isolates/完成发现与传输Rust 工具链版本由根目录 rust-toolchain.toml 锁定工作区定义见 Cargo.toml。菲律宾语 README 未单独列出安装 Rust 的步骤而英文版 README.md 的 Getting Started 中包含该步骤完整编译时请以英文版为准。贡献指南翻译与 Bug 修复翻译推荐方式使用 Weblate 协作翻译平台管理翻译平台地址见 README.md 外链替代方式fork 仓库后手动添加翻译。翻译文件位于 app/assets/i18n/编辑_missing_translations_locale.json或strings_locale.i18n.json即可新增/更新词条生成的 Dart 字符串类在 app/lib/gen/ 下如strings_*.g.dart。重要提示原文档原文翻译带前缀的字段不需要翻译。它们不被应用在任何地方使用只是关于文件本身的说明文本或为译者提供上下文。Bug 修复与改进Bug 修复发现 bug 后创建包含清晰问题描述与修复方案的 pull request改进建议先创建 issue 讨论改进的必要性再动手实现。更多细节见 CONTRIBUTING.md。故障排查表官方继承自 support/readme/README_PH.md 的 Pag-troubleshoot 表五条官方排查项问题发送端平台接收端平台解决方案设备不可见任意任意确认路由器 AP 隔离已关闭开启时设备间连接会被禁止设备不可见任意Windows将网络配置为“专用private”网络Windows 对公网public网络的限制更严格设备不可见macOS / iOS任意尝试在系统设置的“隐私”中切换“本地网络Local Network”权限速度过慢任意任意改用 5GHz 频段并在两台设备上均关闭加密速度过慢任意Android已知问题根因在 Flutter Android 侧的saf_stream插件issue 见原文档外链从源码结构看“设备不可见”类问题基本都对应发现链路的某一环路由器 AP 隔离会阻断组播224.0.0.167或点对点 TCP 连接Windows 公网模式与 macOS/iOS 的本地网络权限则会限制系统的网络发现能力。发现与传输复用 53317 端口的单端口设计使得“只开 TCP 忘了 UDP”这类配置错误会成为典型故障点——建议按前文的防火墙规则表同时放行 TCP 与 UDP。小结LocalSend 菲律宾语 README 的核心价值在于给出了一个可落地的部署清单以 53317 单端口放行 TCP/UDP、关闭 AP 隔离为网络基线以 Portable Mode可执行文件旁建settings.json和--hidden托盘启动为桌面端实用特性以 fvm 锁定 Flutter 版本保证源码可编译。再结合 packages/core/ 中组播发现与 RSA-2048 自签证书的源码实现这套“组播广播 HTTP 注册 证书指纹互认 HTTPS 传输”的链路就完全可验证、可复现了。【免费下载链接】localsendAn open-source cross-platform alternative to AirDrop项目地址: https://gitcode.com/GitHub_Trending/lo/localsend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考