LocalSend 波斯语文档解析：跨平台文件传输应用的架构原理、安装配置与源码构建指南

本文以仓库中的波斯语 README（support/readme/README_FA.md）为核心骨架，系统梳理 LocalSend 这款开源跨平台 AirDrop 替代方案的技术定位、安装与网络配置要点、可移植/隐藏启动等特殊运行模式，以及如何从源码编译、参与翻译贡献的完整流程。读完后，你既能按文档完成 LocalSend 的部署与排障，也能从源码层面理解其“REST API + HTTPS + 自签名证书”的局域网传输协议设计。

一、项目定位：不依赖互联网的局域网文件共享

LocalSend 是一款免费、开源的多平台应用，允许用户通过本地网络将文件和消息安全地共享给附近的设备，无需互联网连接，也无需任何第三方服务器。

原文档“درباره”（关于）一节明确指出其技术本质：LocalSend 通过 REST API 配合 HTTPS 加密实现设备间的加密通信。与依赖外部中转服务器的传统传输应用不同，它只在局域网内工作，因此被定位为“快速且可靠的本地通信方案”。这一描述与主 README 完全一致，也与仓库中 Rust 核心包 packages/core 的实现相互印证：发现、HTTP 服务端、客户端、证书管理均围绕本地网络场景实现。

仓库提供了多语言 README（包括波斯语在内的 18 种语言，见 support/readme 目录），本文基于其中的波斯语版本展开，技术事实以仓库实际内容为准。

二、工作原理：REST API + HTTPS + 设备自签名证书

原文档“نحوه عملکرد”（工作原理）一节说明：LocalSend 使用一种安全的通信协议，设备之间通过 REST API 交互，所有数据经 HTTPS 加密传输，且 TLS/SSL 证书由每台设备自动生成。

这部分可以用仓库源码进一步佐证：

• 设备身份生成：packages/core/src/crypto/cert.rs 中的 SelfSignedCert 定义了设备身份的四要素：PKCS#8 编码的私钥、SPKI 编码的公钥、PEM 自签名证书，以及证书的 SHA-256 指纹。generate_self_signed() 生成 RSA-2048 密钥对和自签名证书（CN=LocalSend User），并特意注明：对端设备仅凭证书指纹相互识别，因此证书名称不承载信息；有效期取 rcgen 默认值（1975 年至 4096 年），证书实际上永不过期、也无需因时间原因轮换。
• 默认端口 53317：packages/core/src/multicast/mod.rs 中 DEFAULT_PORT: u16 = 53317，注释明确说明“默认多播端口与默认 HTTP 服务端端口相同”；Dart 侧的 packages/localsend_isolates/lib/constants.dart 中同样有 const defaultPort = 53317;。这与下节防火墙规则表中的 53317 端口完全对应。
• 设备发现机制：同一文件开头注释说明，设备通过向组播组 224.0.0.0/24（具体为 224.0.0.167）发送 MulticastMessageV2 广播自身；“UDP 只负责广播，回答是通过 HTTP register 请求发往广播方”。这一“UDP 广播 + HTTPS 应答”的双通道设计，正是原文档所述“安全协议”的具体形态。

原文档还指向独立的协议文档仓库（localsend/protocol）。从仓库结构看，本地侧的协议常量（版本字符串、设备类型、指纹字段）集中在 packages/core/src/model/discovery.rs 与 packages/core/src/http/dto_v2.rs 中。

三、下载渠道与平台兼容性矩阵

原文档“دانلود”（下载）一节建议优先通过应用商店或包管理器安装，因为应用本身不会自动更新，并给出了完整的渠道矩阵：

平台	推荐/可用渠道
Windows	Winget、Scoop、Chocolatey、EXE 安装包、便携 ZIP
macOS	App Store、Homebrew、DMG 安装包
Linux	Flathub、Nixpkgs、Snap、AUR、TAR / DEB / AppImage 通用包
Android	Play Store、F-Droid、APK 直装、Amazon（Fire OS）

兼容性矩阵（原文档“سازگاری”小节，需完整保留）：

平台	最低版本	备注
Android	5.0	-
iOS	12.0	-
macOS	11 Big Sur	旧机型需借助 OpenCore Legacy Patcher 2.0.2+（原文档引用了 issue #1005）
Windows	10	支持 Windows 7 的最后版本是 1.15.4，未来可能恢复支持
Linux	N.A.	-

仓库中的打包脚本（support/scripts 目录下的 compile_mac_dmg.sh、compile_windows_msix_signed.ps1、compile_linux_appimage.sh 等）与上表渠道一一对应，可作为各平台分发包产出的来源依据。

四、安装后网络配置：防火墙端口规则与 AP Isolation

原文档“نصب”（安装）小节指出：大多数情况下 LocalSend 应开箱即用，但若收发文件失败，可能需要调整防火墙设置，规则如下：

流量类型	协议	端口	动作
入站	TCP, UDP	53317	允许
出站	TCP, UDP	任意	允许

这条规则与源码严格对应：入站 53317 同时承载 HTTP 服务端（HTTPS）与 UDP 多播发现，两个监听都复用同一端口（见 packages/core/src/multicast/mod.rs 的注释）；出站放行则是为了设备发现成功后，主动向对端发起 HTTPS register 请求。

原文档还特别提醒：确认路由器的 AP Isolation（AP 隔离）处于关闭状态。该选项默认关闭，但部分路由器（尤其是访客网络）会将其开启——一旦开启，同网段设备间通信被直接禁止。

五、两个桌面端高级启动模式

5.1 可移植模式（Portable Mode）

原文档说明：该模式自 1.13.0 引入，操作很简单——在可执行文件所在目录创建一个名为 settings.json 的文件（可为空文件），应用便会改用该文件保存设置，而不是默认位置。

源码实现完全印证了这一行为：app/lib/util/shared_preferences/shared_preferences_portable.dart 中 _getSettingsPathFromExecutable() 会解析可执行文件路径并拼接 settings.json；若 Platform.resolvedExecutable 无法解析（例如某些虚拟磁盘），则回退到当前工作目录。测试用例 app/test/unit/util/shared_preferences/shared_preferences_portable_test.dart 验证了两种路径拼接逻辑（可执行文件目录与回退目录各一条）。

5.2 隐藏式启动（--hidden）

原文档说明：该行为在 1.15.0 更新——使用 --hidden 标志即可让应用只驻留在系统托盘（通知区）而不显示主窗口，例如：

localsend_app.exe --hidden

原文档同时交代了版本沿革：1.14.0 及更早版本中，隐藏启动是由“开启了自启动 + 勾选隐藏选项”组合触发的，而不是显式参数。从源码结构看，Linux 端的处理位于 app/linux/my_application.cc——逐条检查 Dart 入口参数中的 --hidden；app/lib/util/native/autostart_helper.dart 中定义了 const startHiddenFlag = '--hidden'; 作为桌面端各平台统一的参数名。

六、从源码构建：Flutter + Rust 双栈工具链

原文档“شروع به کار”（开始使用/构建）小节给出的源码编译步骤：

1. 安装 Flutter（可直接安装，或使用 fvm 管理版本，版本要求见 .fvmrc）；
2. 安装 Rust；
3. 克隆 LocalSend 仓库；
4. cd app 进入应用目录；
5. 执行 flutter pub get 下载依赖；
6. 执行 flutter run 启动应用。

原文档附带的 NOTE 值得特别强调：LocalSend 需要特定版本的 Flutter，可能与你系统上安装的版本不一致，因此推荐用 fvm 管理项目级 Flutter 版本，装好 fvm 后所有命令把 flutter 换成 fvm flutter。 当前仓库中 .fvmrc 指定的版本为 Flutter 3.41.9，rust-toolchain.toml 则固定 Rust 1.97.1（并附加 clippy 组件）。构建前建议先核对这两个文件，避免版本错配导致的构建失败。

应用代码入口为 app/lib/main.dart，Flutter UI 通过 packages/localsend_isolates 包以 Rust 隔离层（flutter_rust_bridge 生成代码见 rust/frb_generated.dart）调用 packages/core 的核心逻辑（协议、发现、传输），这一分层与“Rust 核心 + Flutter 前端”的构建说明一致。

七、参与贡献：翻译与 bug 修复流程

7.1 翻译

原文档“ترجمه”（翻译）小节说明了两条贡献路径，首选 Weblate 平台，其次是直接 fork 仓库手工添加翻译。翻译文件位于 app/assets/i18n 目录，需要编辑的是 _missing_translations_<locale>.json 或 strings_<locale>.i18n.json 文件。波斯语翻译即为其中的 app/assets/i18n/fa.json，配套的缺失词条清单是 app/assets/i18n/_missing_translations_fa.json，编译后的 Dart 代码由 app/lib/gen 下的 strings_fa.g.dart 等生成文件承载。

原文档还有一条关键规则（波斯语原文以粗体标注）：以 @ 开头的字段不应翻译——这些字段不在应用中实际使用，只作为文件说明或为译者提供上下文。

7.2 Bug 修复与改进建议

• Bug 修复：提交包含清晰问题描述与修复说明的 Pull Request；
• 改进建议：先创建 issue 讨论必要性，再动手实现。

更多细节可参考 CONTRIBUTING.md。

八、官方故障排查表（完整继承原文档）

原文档“عیب‌یابی”（排障）一节给出的问题-平台-解决方案对照表，是部署 LocalSend 时最实用的速查资料，完整内容如下：

问题	平台（发送）	平台（接收）	解决方案
设备不可见	任意平台	任意平台	确认路由器已关闭 AP-Isolation；开启时设备间连接会被禁止
设备不可见	任意平台	Windows	将网络类型配置为“专用（Private）”网络；Windows 在“公用（Public）”网络下限制更严
设备不可见	macOS、iOS	任意平台	可尝试修改系统设置“隐私”中的“本地网络（Local Network）”权限
速度太慢	任意平台	任意平台	使用 5GHz Wi-Fi；在两台设备上关闭加密
速度太慢	任意平台	Android	已知问题（原文档引用了 flutter-cavalry/saf_stream 的 issue #4）

九、小结

波斯语 README 虽然是一个翻译版本，但它完整承载了 LocalSend 的工程事实：以 53317 端口上的 UDP 多播发现 + HTTPS REST API 注册为核心的局域网协议、设备级 RSA-2048 自签名证书与指纹识别体系（见 packages/core/src/crypto/cert.rs）、防火墙与 AP Isolation 两类最常见的组网坑点、settings.json 可移植模式与 --hidden 托盘启动两个桌面端特性（分别由 app/lib/util/shared_preferences/shared_preferences_portable.dart 与各平台原生入口实现），以及 Flutter 3.41.9 / Rust 1.97.1 的源码构建基线。以上要点均可在仓库对应路径中直接验证，适合作为部署、排障与二次开发的第一手参考。