English | 繁體中文
Lynavo Drive
一款高效能、從行動端（iOS / Android）至桌面端（macOS / Windows）的區域網路 (LAN) 增量同步媒體工具。
產品預覽 •
主要功能 •
開源邊界 •
開發者快速開始 •
參與貢獻 •
社群與社群媒體
---
## 專案狀態
Lynavo Drive 已完成主要功能，並開放社群從原始碼建置與參與貢獻。本儲存庫只提供一套公開的本機原始碼建置與套件驗證流程；不發布官方簽署的安裝程式、行動應用程式商店版本、自動更新或託管服務。
| 使用範圍 | 目前的開源版本支援範圍 |
| ----------- | -------------------------------------------------- |
| 💻 桌面端 | macOS 與 Windows 應用程式執行環境 |
| 📱 行動端 | iOS 與 Android 應用程式執行環境 |
| 🐧 Linux | 僅供本機原始碼建置與套件驗證 |
| 🌐 網路 | 同一區域網路中的前景同步 |
| 📦 發布方式 | 社群原始碼建置，以及在本機產生的套件／二進位執行檔 |
## 📸 產品預覽
## ✨ 主要功能
- **自動增量媒體同步**：掃描手機相簿，自動將尚未同步的照片與影片加入佇列，不需手動選取檔案。
- **本機探索與配對**：透過 mDNS 尋找同一區域網路內的桌面端，再使用 QR code 或 6 位數配對碼完成配對。
- **可續傳的序列傳輸**：每支手機一次上傳一個檔案，前景區域網路重新連線後會繼續處理未完成的佇列項目。
- **唯讀佇列與歷史紀錄**：顯示傳輸進度、已完成檔案與完成日期統計，不提供刪除、跳過或重新排序控制。
- **共用檔案存取**：讓行動端瀏覽及下載桌面端本機共用資料夾公開的檔案；此功能與自動媒體上傳是不同的路徑。
- **本機診斷**：不依賴託管診斷服務，也能匯出桌面端與行動端診斷資料。
## 🛡️ 開源邊界
> [!IMPORTANT]
> **區域網路開源核心**
>
> - 前景自動同步不需要登入或帳戶服務。
> - 上傳內容只來自行動端相簿掃描與本機待處理佇列，不提供手動檔案選取的替代流程。
> - 佇列維持唯讀，每支手機一次只會上傳一個檔案。
> - 缺少非開源模組或帳戶服務狀態，不會阻止前景區域網路配對與同步。
> [!WARNING]
> **此儲存庫不包含的功能**
>
> - 遠端存取、雲端轉送、通道憑證、官方帳戶及靜默背景續傳均不可用，且維持停用。
> - 不提供官方簽署、公證、行動應用程式商店發布、套件上傳及自動更新基礎設施。
> - 原始碼套件不重新散布 Windows 版 Apple Bonjour。若本機已有或另行設定 Bonjour 執行環境便會使用，否則改用相容於 zeroconf 的備援方案。
> - Linux 僅供本機建置與套件驗證，不是目前支援的桌面端使用平台。
## 🚀 開發者快速開始
這是提供給貢獻者的開發流程，不是一般使用者安裝程式。本機套件建置與各平台驗證方式請參閱[發布手冊](./docs/release/release-playbook.md)。
💻 安裝與啟動指令
```bash
# 1. 啟用儲存庫指定的 pnpm 版本並安裝相依套件
corepack enable
pnpm install --frozen-lockfile
# 2. 建置共用套件
pnpm --filter @lynavo-drive/contracts build
pnpm --filter @lynavo-drive/design-tokens build
# 3. 啟動桌面端開發模式
pnpm dev:desktop
```
Electron 視窗會自動開啟，桌面端應用程式會啟動側車服務 (Sidecar)。
若要執行行動端，請保持桌面端運作，並開啟另一個終端機：
📱 行動端開發指令
```bash
# 啟動 Metro
pnpm dev:mobile
# 接著在另一個終端機啟動其中一個平台
pnpm --filter @lynavo-drive/mobile ios
# 或
pnpm dev:mobile:android
```
仍需準備各平台開發工具：iOS 需要 macOS、Xcode 與 CocoaPods；Android 需要 Android Studio 及 Android SDK／NDK。
配對應用程式：
1. 將手機與桌面端連接到同一個區域網路。
2. 開啟桌面端 Lynavo Drive，設定或查看 6 位數配對碼。
3. 在行動端探索桌面裝置，再掃描其 QR code 或輸入配對碼。
4. 使用開源版本進行區域網路自動同步時，請將行動應用程式保持在前景。
## ❓ 常見問題與疑難排解
🔍 檢視疑難排解指南與常見問題
### 📡 1. 行動端應用程式找不到我的桌面裝置（mDNS 裝置探索失敗）
- **檢查網路**：確保行動端和桌面端皆處於同一個區域網路 (LAN)。
- **Windows 防火牆**：驗證 Windows Defender 防火牆是否允許連接埠 `39593` (TCP/LMUP 檔案傳輸) 和 `39594` (HTTP API) 的連入流量。
- **Bonjour 執行環境**：開源建置版本不重新散布 Apple Bonjour。請確認 Windows 已安裝 Bonjour，否則使用相容於 zeroconf 的備援方案。
### ☁️ 2. 為什麼我的一些 iCloud 照片卡住 / 無法傳輸？
- 標記為 `iCloud` 的照片在傳輸前，必須先從 Apple Photos 雲端儲存庫中匯出。
- 在 `cloud_downloading` 或 `preparing` 狀態下，手機正在將高解析度的原始內容下載至本機儲存空間。下載完成後會自動開始傳輸。
### 📸 3. 我可以手動選擇要同步哪些照片 / 影片嗎？
- 不行。自動上傳由行動端相簿掃描及嚴格唯讀的待處理佇列驅動，開源流程不提供核取方塊選取功能。
### 💤 4. 當桌面端進入睡眠狀態或連線中斷時會發生什麼事？
- 區域網路傳輸會中斷。當行動應用程式位於前景時，桌面端喚醒並恢復區域網路連線後，會繼續處理未完成的佇列。
- 開源執行環境不提供靜默背景續傳。
- 在桌面端應用程式設定中啟用「同步時防止電腦進入睡眠」，以確保傳輸不中斷。
## 🏗️ 架構概覽
```mermaid
flowchart TD
subgraph Mobile["📱 行動端 (iOS / Android)"]
RN["React Native UI"]
subgraph SE["原生同步引擎"]
iOS["iOS (Swift)"]
Android["Android (Kotlin)"]
end
end
subgraph Desktop["💻 桌面端 (macOS / Windows)"]
Renderer["React 18 渲染器"]
Preload["預載橋接 (Preload Bridge)"]
Main["Electron 主程序"]
subgraph Sidecar["Go 側車服務 (Sidecar)"]
HTTP["HTTP API 與 WebSocket (連接埠 39594)"]
LMUP["LMUP 接收器 (連接埠 39593)"]
DB[("SQLite 資料庫")]
FS["檔案系統共用目錄"]
end
end
%% Communication Links
RN <--> SE
Renderer <--> Preload
Preload <--> Main
Main <--> HTTP
%% Network Sync Channels
SE -- "mDNS 探索 / 配對" --> HTTP
SE -- "在線狀態與元資料 (HTTP/WS)" --> HTTP
SE -- "增量媒體同步 (LMUP/TCP)" --> LMUP
classDef mobile fill:#fff0f5,stroke:#db7093,stroke-width:1px;
classDef desktop fill:#f0f8ff,stroke:#4682b4,stroke-width:1px;
classDef sidecar fill:#f5fffa,stroke:#2e8b57,stroke-width:1px;
class Mobile,RN,SE,iOS,Android mobile;
class Desktop,Renderer,Preload,Main desktop;
class Sidecar,HTTP,LMUP,DB,FS sidecar;
```
## 🔧 技術基礎設施
### 🛠️ 技術架構
| 層級 | 技術 |
| --------------------- | ---------------------------------------------------------- |
| 📦 Monorepo | pnpm 10 + turborepo 2.8 |
| 💻 桌面端 | Electron 41 + electron-vite 5 + electron-builder 26 |
| 🎨 桌面端 UI | React 18.3 + zustand 5 + Tailwind CSS v4 |
| 📱 行動端 | React Native 0.84.1 + React 19 (iOS / Android) |
| 🍎 iOS 原生 | Swift `SyncEngine` + BGTask + PhotoKit + Network.framework |
| 🤖 Android 原生 | Kotlin 橋接 + NativeSyncEngine / MediaStore / NsdManager |
| ⚡ 側車服務 (Sidecar) | Go 1.25.6 + SQLite + WebSocket |
| 🔗 共用套件 | `@lynavo-drive/contracts` + `@lynavo-drive/design-tokens` |
| 🧪 測試 | vitest 4.1 + jest + `go test` |
### ⚙️ 系統需求
- **macOS 或 Windows**（桌面端目前支援 macOS / Windows；Linux 僅用於本機建置 / 套件驗證；iOS 建置仍需要 macOS + Xcode）
- **Node.js** >= 22.12.0
- **pnpm** >= 10
- **Go** >= 1.25.6 (側車服務 (Sidecar) 開發與測試)
📱 檢視行動端與平台特定 SDK 需求
- **Xcode + CocoaPods**（iOS 建置和裝置偵錯，僅限 macOS）
- **Android Studio + Android SDK / NDK**（Android 建置和偵錯）
### 💻 常用指令
🛠️ 檢視開發者指令參考
```bash
# Desktop
pnpm dev:desktop
pnpm build:desktop
pnpm package:desktop # macOS local DMG
pnpm package:desktop:win # Windows NSIS + zip (default desktop Windows package, no release profile)
# Mobile
pnpm dev:mobile
pnpm build:mobile
pnpm dev:mobile:android
pnpm build:mobile:android # Android Debug build (assembleDebug)
# Sidecar
pnpm dev:sidecar
pnpm build:sidecar
pnpm test:sidecar
# Full repository validation
pnpm build
pnpm test
pnpm typecheck
pnpm format:check
pnpm check
```
### 📦 開源版本建置與套件驗證
此開源儲存庫保留本機原始碼建置與套件驗證流程，以及在 GitHub 上執行、無需儲存庫秘密金鑰 (Secret-free) 的未簽署建置與套件驗證。託管的建置輸出僅為驗證產物，並非官方簽署的發布版本。Linux 僅用於本機驗證，並非支援的桌面端使用者平台。
🔬 檢視驗證與建置管道
```bash
# Inspect the local build / package commands that would run
pnpm release --profile review --targets ios,android,mac,win,linux --dry-run
# Local iOS / Android Debug / Desktop build verification
pnpm build:mobile
pnpm build:mobile:ios:release
pnpm build:mobile:android
pnpm package:desktop
# Android Release source-build verification
pnpm release --profile review --targets android --dry-run
pnpm release --profile review --targets android
# Local desktop platform package
pnpm package:desktop
# Linux package verification (Linux host, one arch per run)
pnpm --filter @lynavo-drive/desktop package:linux -- --arch=x64
pnpm --filter @lynavo-drive/desktop package:linux -- --arch=arm64
```
`release` 設定檔只會注入 `LYNAVO_RELEASE_CHANNEL` 與本機建置設定，並只選擇本機建置／套件指令。
GitHub 裝載的工作流程 (Workflows) 可能在無儲存庫秘密金鑰的情況下，使用公開的原始碼調用這些指令。第三方或外部建置服務、程式碼簽署、公證、商店上傳、自動更新以及私有發布基礎設施皆在此開源基準之外。
`OSS Draft Release` 工作流程接受符合 `vX.Y.Z` 的穩定標籤 (Tags)，從該標籤提交重建完整的驗證組套，並建立或更新 GitHub 草稿版本 (Draft Release)。手動派發僅限建置。發布的檔案為未簽署的開源建置驗證輸出，並包含 SHA-256 校驗和；有關確切的資產清單、警示和維護者程序，請參閱[發布手冊](./docs/release/release-playbook.md)。
### 📁 專案結構
📂 檢視目錄結構圖
```text
lynavo-drive/
├── apps/
│ ├── desktop/ # Electron desktop app
│ │ └── src/
│ │ ├── main/ # Main process (window, IPC, sidecar lifecycle)
│ │ ├── preload/ # Preload bridge
│ │ └── renderer/ # React 18 UI
│ └── mobile/ # React Native iOS/Android app + native sync
│ ├── ios/ # Xcode project and Swift native modules
│ ├── android/ # Android project, Kotlin bridge, native sync
│ ├── src/ # RN screens and hooks
│ └── __tests__/ # RN tests
├── packages/
│ ├── contracts/ # Shared DTOs / constants / events / error codes
│ └── design-tokens/ # Shared design tokens
├── services/
│ └── sidecar-go/ # Go sidecar (TCP/HTTP/SQLite/mDNS)
└── docs/
├── architecture/ # Architecture, state machine, data model
├── operations/ # Troubleshooting, diagnostics, sidecar runbook
├── product/ # Product constraints, OSS boundaries, non-goals
├── release/ # OSS build and package verification playbook
└── testing/ # OSS verification matrix
```
## 🎯 開發基準線
- 共用型別、常數、事件名稱和連接埠定義皆來自於 `@lynavo-drive/contracts`。
- 渲染器 (Renderer) 不直接存取側車服務 (Sidecar)、檔案系統或 SQLite；所有存取皆透過預載橋接 (preload bridge) / 主行程 (main process) 進行。
- 佇列保持唯讀狀態。使用者介面 (UI) 無法刪除、重新排序或跳過項目。
- 指定的手機一次只能上傳一個檔案。
- 訪客 / 本機前景區域網路 (LAN) 同步採 fail-open；遠端存取和背景持續運作則採 fail-closed。
## 📄 文件參考
- ⚙️ 開發限制與營運規則：[`AGENTS.md`](./AGENTS.md)
- 📘 系統概覽：[`docs/architecture/system-overview.md`](./docs/architecture/system-overview.md)
- 🔄 同步狀態機：[`docs/architecture/sync-state-machine.md`](./docs/architecture/sync-state-machine.md)
- 📊 資料模型與統計語義：[`docs/architecture/data-model.md`](./docs/architecture/data-model.md)
- 🔧 疑難排解指南：[`docs/operations/troubleshooting.md`](./docs/operations/troubleshooting.md)
- 📱 行動端診斷套件：[`docs/operations/mobile-diagnostics.md`](./docs/operations/mobile-diagnostics.md)
- ⚡ 側車服務 (Sidecar) 運作手冊：[`docs/operations/sidecar-runbook.md`](./docs/operations/sidecar-runbook.md)
- 🛡️ 產品限制、開源邊界與非目標：[`docs/product/constraints.md`](./docs/product/constraints.md)
- 📦 開源版本建置驗證手冊：[`docs/release/release-playbook.md`](./docs/release/release-playbook.md)
- 🔬 開源驗證矩陣：[`docs/testing/oss-verification-matrix.md`](./docs/testing/oss-verification-matrix.md)
- 🔒 安全性政策：[`SECURITY.md`](./SECURITY.md)
- 🕵️ 隱私權聲明：[`PRIVACY.md`](./PRIVACY.md)
- 🤝 貢獻指南：[`CONTRIBUTING.md`](./CONTRIBUTING.md)
- 📜 行為準則：[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)
- 📄 第三方聲明：[`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md)
## 💡 參與貢獻
歡迎社群參與貢獻。若要開始：
1. **Fork 本儲存庫**：建立個人 Fork 並複製到本機。
2. **設定開發工作區**：依照[開發者快速開始](#-開發者快速開始)，安裝預計修改平台所需的開發工具。
3. **驗證變更**：先執行聚焦測試，再於提交 pull request 前執行適用的儲存庫檢查：
⚙️ 驗證指令
```bash
pnpm test
pnpm typecheck
pnpm format:check
pnpm gate:release
```
詳細的程式撰寫規範、專案結構與開發流程，請參閱[貢獻指南](./CONTRIBUTING.md)及[行為準則](./CODE_OF_CONDUCT.md)。
- [瀏覽現有 issue](https://github.com/lynavo/lynavo-drive/issues)
- [回報錯誤](https://github.com/lynavo/lynavo-drive/issues/new?labels=bug)
- [提出功能建議](https://github.com/lynavo/lynavo-drive/issues/new?labels=enhancement)
- [私下回報安全漏洞](https://github.com/lynavo/lynavo-drive/security/advisories/new)，請勿在公開 issue 張貼可被利用的漏洞細節。
## 🌐 社群與社群媒體
透過以下管道追蹤專案消息與最新動態：
- [](https://x.com/founder_im63606) — [@Lynavo](https://x.com/founder_im63606)
- [](https://mastodon.social/@ViviDrop) — [@Lynavo](https://mastodon.social/@ViviDrop)
- [](https://bsky.app/profile/vividrop.bsky.social) — [@Lynavo](https://bsky.app/profile/vividrop.bsky.social)
- [](https://www.linkedin.com/in/lynavo-lynavo-1273322b6/) — [Lynavo](https://www.linkedin.com/in/lynavo-lynavo-1273322b6/)
- [](https://www.youtube.com/channel/UCMcYmWmPMzQ5N8bHFffnldQ) — [YouTube 頻道](https://www.youtube.com/channel/UCMcYmWmPMzQ5N8bHFffnldQ)
## ⚖️ 授權條款
本專案採用 GNU Affero General Public License v3.0。請參閱 [`LICENSE`](./LICENSE)。