PRD v4: revert to rclone VFS read-write proxy architecture

Drop the read-only cache + SD Uploader design in favor of rclone VFS native read-write caching. Key changes: - SMB shares are now read-write, writes go to SSD and async write-back to NAS - Remove SD card import/upload, metadata DB, self-built polling - Simplify remote change detection to rclone --dir-cache-time - Add dirty file management, write-back config, and related risks Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-17 18:56:12 +08:00 · 2026-02-17 18:56:12 +08:00 · 8f00f86eb4
commit 8f00f86eb4
parent 3caddc6370
2 changed files with 836 additions and 1207 deletions
--- a/warpgate-prd-v3.md
+++ b/warpgate-prd-v3.md
--- a/warpgate-prd-v4.md
+++ b/warpgate-prd-v4.md
@ -0,0 +1,836 @@
+# Warpgate — Make your NAS feel local — 产品方案与需求描述（v4）
+
+---
+
+## 一、产品定位
+
+**一句话描述**：摄影师的随身存储中枢——SSD 读写缓存加速访问，全程高速组网，云端容灾兜底。
+
+**核心价值**：
+
+1. **远程访问加速**：用户在外通过 Tailscale 等组网工具访问家中 NAS 时，受限于公网带宽，SMB 协议体验极差（卡顿、超时、缩略图加载慢）。本产品在客户端侧部署一层 SSD 读写缓存，对上层应用（Lightroom、Finder、Explorer 等）完全透明，读写都走本地 SSD，读取按需拉取并缓存，写入异步回写 NAS。
+2. **数据安全兜底**：可选的云端异地容灾，为用户的数据提供多层保护。
+
+**产品形态**：
+- **软件方案**（MVP）：配置文件 + 一键部署脚本，部署在任意 Linux 主机上（Docker 镜像在 v2.5 提供）
+- **硬件一体机**（目标形态）：定制盒子，内置 SSD + 电池 + WiFi，开箱即用（SD 卡槽、物理按钮、LED 状态指示等硬件在 SD 卡导入功能启用后加入）
+
+**市场机会**：
+- Gnarbox（曾最受欢迎的摄影师外拍备份设备）已停产，市场空缺明显
+- UnifyDrive UT2（$599）硬件形态相似但软件体验差、电池仅 1 小时
+- ClouZen TAINER 功能单一，只能备份不能联网同步
+- **没有产品把「本地高速读写」和「远程 NAS 透明代理」打通成无缝体验**
+
+---
+
+## 二、目标用户
+
+| 用户画像 | 典型场景 | 痛点 |
+|----------|----------|------|
+| 摄影师 | 出差/外拍，酒店回看、粗修当天照片（Lightroom） | RAW 文件 25-60MB，SMB 远程逐张打开极慢，预览生成卡死 |
+| 视频创作者 | 远程剪辑，浏览素材库、拖拽代理文件 | 视频文件更大，顺序播放需持续带宽 |
+| 设计师 | 出差访问公司 NAS 上的 PSD/AI 源文件 | 大文件 + 多图层，打开一个文件几分钟 |
+| 远程办公族 | 日常办公文档、项目资料存 NAS | 小文件多，SMB 目录浏览延迟高，体验卡顿 |
+| NAS 重度用户 | 旅行途中访问个人数据 | 没有公网 IP 或带宽不足，现有方案都不理想 |
+
+**核心用户优先级**：摄影师（Lightroom + 远程访问）> 远程办公 > 视频创作者
+
+---
+
+## 三、系统架构
+
+### 3.1 整体架构
+
+```mermaid
+graph LR
+    subgraph clients ["客户端设备"]
+        LR["Lightroom<br/>macOS"]
+        Linux["Linux<br/>客户端"]
+        iPad["iPad<br/>移动端"]
+    end
+
+    subgraph proxy ["Linux Proxy（局域网·高速）"]
+        Samba["Samba Server"]
+        NFS_S["NFS Server"]
+        WebDAV_S["WebDAV Server"]
+        VFS["rclone VFS mount<br/>(读写缓存)"]
+        SSD["SSD 缓存"]
+        Samba --> VFS
+        NFS_S --> VFS
+        WebDAV_S --> VFS
+        VFS --> SSD
+    end
+
+    subgraph remote ["远程（公网 / Tailscale·低速）"]
+        TS["Tailscale /<br/>WireGuard"]
+        NAS["任意品牌 NAS<br/>(SFTP)"]
+        TS --- NAS
+    end
+
+    LR -- "SMB" --> Samba
+    Linux -- "NFS" --> NFS_S
+    iPad -- "WebDAV" --> WebDAV_S
+    VFS -- "SFTP (读写)" --> TS
+```
+
+### 3.2 协议选择说明
+
+| 段 | 协议 | 原因 |
+|----|------|------|
+| 客户端 → Proxy（主） | SMB | 对 Lightroom/macOS/Windows 原生兼容，应用无感 |
+| 客户端 → Proxy（辅） | NFS | Linux 客户端性能更好，内核级支持 |
+| 客户端 → Proxy（辅） | WebDAV | 移动端 App 支持广泛 |
+| Proxy → NAS | SFTP | 高延迟链路下比 SMB 稳定得多，任意品牌 NAS 均支持，无需额外套件。需要读写权限 |
+
+### 3.3 多协议对外服务（设计讨论）
+
+**问题**：客户端 → Warpgate 之间只支持 SMB 是否足够？
+
+**讨论**：不同客户端设备对协议的偏好不同。macOS + Lightroom 最适合 SMB，但 Linux 客户端用 NFS 性能更好（内核级支持，且 Linux 侧还能再叠一层 FS-Cache），iPad/移动端 App 则普遍支持 WebDAV。
+
+**设计决策**：所有对外协议服务共享同一个 rclone FUSE 挂载点。缓存层只有一份，不会因为多协议而重复缓存。rclone VFS 统一处理读写，本地写入异步回写 NAS。
+
+```mermaid
+graph LR
+    SMB["SMB Server"] --> Mount["/mnt/nas-photos<br/>(rclone 读写 FUSE 挂载)"]
+    NFS["NFS Server"] --> Mount
+    WebDAV["WebDAV"] --> Mount
+    Mount --> SSD["SSD 缓存<br/>(rclone 内部管理)"]
+```
+
+---
+
+## 四、核心功能
+
+### P0（MVP 必须）
+
+#### 4.1 透明多协议代理
+- 对外暴露标准 SMB 共享，客户端连接方式与直连 NAS 完全一致
+- 支持 SMB2/SMB3 协议
+- 同时支持 NFS 导出（Linux 客户端）和 WebDAV 服务（移动端）
+- 支持 macOS（Finder/Lightroom）、Windows（Explorer）、Linux、移动端客户端
+- 文件读取、写入、目录浏览、文件属性（时间戳/权限）均正常工作
+- 所有协议共享同一个 rclone 缓存层，不重复存储
+- **读写支持**：本地写入缓存到 SSD，rclone 异步回写到 NAS。Lightroom 等应用读取 RAW 文件时直接命中缓存；需要写入时（如保存 XMP sidecar），写入先落到 SSD 再由 rclone 异步回写
+
+#### 4.2 读缓存（Read-through Cache）
+- 文件首次被访问时，从远程 NAS 拉取并存入本地 SSD 缓存
+- 后续访问同一文件直接从本地 SSD 返回
+- 支持分块读取（chunked read）：大文件不需要整个下载完才能开始读取
+- 支持预读（read-ahead）：顺序读取场景下提前拉取后续数据
+- 目录列表缓存：目录结构缓存一段时间，避免频繁远程查询
+
+#### 4.3 缓存一致性
+- rclone VFS 原生管理脏文件回写，LRU 淘汰时自动跳过脏文件（未回写的文件受保护）
+- 单向写约束下（出门期间 NAS 端不动），无冲突
+- rclone 通过 `--dir-cache-time` 控制目录缓存过期，过期后自动从远程重新读取
+- 远程文件被修改 → dir-cache-time 过期后 rclone 自动拉取最新版本
+- 远程文件被删除 → dir-cache-time 过期后 rclone 缓存刷新，文件自动消失
+
+#### 4.5 远程变更检测
+- rclone 通过 `--dir-cache-time` 自动刷新目录缓存，过期后从远程重新读取
+- 不依赖任何 NAS 品牌特有 API，纯 SFTP 协议实现
+- 可选 NAS Agent 推送加速（P2）
+
+#### 4.6 缓存空间管理
+- 设置缓存总大小上限
+- 超出上限时按 LRU（最久未访问）策略自动淘汰
+- rclone 自动管理 LRU 淘汰，脏文件（未回写）受保护不被淘汰
+- 可设置缓存盘最低保留空间，防止磁盘写满
+- 可设置缓存最大保留时间
+- 注意：离线大量写入时缓存可能被脏文件占满，需确保 `--vfs-cache-max-size` 留够空间
+
+#### 4.7 一键部署
+- 提供完整的配置文件 + 部署脚本
+- 自动安装依赖（rclone、Samba、NFS、fuse）
+- 自动配置 systemd 服务，开机自启
+- 自动配置日志轮转
+- 缓存盘文件系统建议 btrfs/ZFS（CoW + journal 保护一致性）
+
+### P1（重要但非 MVP）
+
+#### 4.8 配网模式 + Captive Portal 代理（Setup AP）
+
+盒子是 Headless 设备（无屏幕），而绝大多数酒店/机场 WiFi 需要网页认证（Captive Portal）。没有这个功能，旅途场景直接不可用。
+
+**核心流程**：
+
+```
+① 盒子开机，检测到未配置 WiFi 或无法联网
+   → 自动进入「配网模式」，WiFi 模块启动临时 AP（SSID: Warpgate-Setup）
+
+② 用户手机连接 Warpgate-Setup 热点
+   → 自动弹出配网页面（或手动访问 http://192.168.4.1）
+
+③ 配网页面显示周围可用 WiFi 列表，用户选择酒店 WiFi
+
+④ 盒子连接酒店 WiFi（WiFi 模块切换为 AP+STA 并发模式）
+   → 检测到 Captive Portal 重定向
+
+⑤ 盒子将 Captive Portal 认证页面代理到配网页面
+   → 用户在手机上完成酒店 WiFi 的网页认证（输入房号/姓名等）
+
+⑥ 认证通过，盒子获得互联网访问，Tailscale 自动连接
+   → 配网模式关闭，临时 AP 关闭（或保持为管理入口）
+```
+
+**硬件要求**：WiFi 模块必须支持 **AP+STA 并发模式**（同时作为热点和连接外部 WiFi），这是配网模式的前提。大多数支持 AP 模式的 WiFi 芯片均支持此功能。
+
+**Fallback 方案**（不需要额外开发，文档中列出即可）：
+- **USB 网络共享**：手机 USB 连接盒子，共享手机网络（tethering），绕过酒店 WiFi
+- **手机热点**：盒子直连手机 4G/5G 热点
+- **有线以太网**：部分酒店有网口，直插通常无需认证
+- **MAC 克隆**：`warpgate clone-mac <MAC>` 克隆已认证设备的 MAC 地址（高级用户）
+
+#### 4.9 缓存预热（Warm-up）
+- 命令行手动预热指定目录
+- 按时间范围预热（如"最近 7 天新增的文件"）
+- 定时预热任务（如每天凌晨自动拉取最新数据）
+- 预热进度显示
+
+#### 4.10 管理工具（CLI）
+- `warpgate status` — 查看服务状态、缓存使用量、回写队列、当前带宽限速
+- `warpgate cache-list` — 列出缓存中的文件
+- `warpgate cache-clean` — 清理缓存
+- `warpgate warmup` — 手动预热
+- `warpgate bwlimit` — 动态调整带宽限制
+- `warpgate log` — 查看实时日志
+- `warpgate speed-test` — 链路速度测试
+- `warpgate setup-wifi` — 手动进入配网模式
+- `warpgate clone-mac <MAC>` — 克隆指定设备的 MAC 地址
+
+#### 4.11 带宽管理
+- 支持回写限速（写入回传 NAS）/下载限速（缓存拉取）分别控制
+- 运行时动态调整限速（不重启服务）
+- 回写带宽不影响读取体验
+- **自适应限速（Adaptive Throttle）**：基于吞吐量观测自动降速，避免回写占满链路
+  - 监控回写吞吐量的滑动窗口（如最近 30s 平均值），当吞吐持续下降超过阈值时判定链路拥塞
+  - 拥塞时自动降速，释放带宽给读取和其他流量
+  - 每隔一段时间小幅探测提速
+  - throttle 状态通过 `warpgate status` 实时可见
+  - 用户可通过 `BW_ADAPTIVE` 配置关闭自适应限速
+  - 自适应限速**仅控制回写上传**，不影响缓存读取拉取
+
+#### 4.12 连接容错
+- Tailscale 断连时自动重试
+- 已缓存的文件在离线时仍可正常读取
+- rclone 回写队列在恢复连接后自动续传
+- 连接超时参数可配置
+
+### P2（后续迭代）
+
+#### 4.13 WiFi AP 现场共享
+
+盒子内置 WiFi 模块开启持久热点，现场团队设备连上即可通过 SMB/WebDAV 访问缓存目录。与 4.8 配网模式的区别：配网 AP 是临时的（完成配网后关闭），本功能是持久的团队共享热点。
+
+- 支持 AP 模式，复用已有的 SMB/WebDAV 多协议服务
+- AP 网络与 Tailscale/WAN 网络隔离（安全考虑）
+- AP 模式下仍可同时通过有线/4G 连接 Tailscale 做后台回写
+- **硬件要求**：需要两个独立网络接口——WiFi 模块用于 AP 热点，有线/USB 4G 网卡用于 WAN/Tailscale 连接。一体机硬件设计需预留双网卡
+- 典型场景：现场团队设备连上 WiFi 即可浏览共享文件
+
+#### 4.14 Web 管理界面
+- 缓存状态仪表盘（大小、命中率、回写队列、带宽趋势图）
+- 缓存文件浏览器（查看/手动清除/手动预热）
+- 配置修改界面（参数调整无需编辑配置文件）
+- 实时日志查看器
+
+#### 4.15 NAS 侧 Agent 推送（可选增强）
+- 在 NAS 上运行轻量 Agent（Docker 容器），监听文件变化主动推送给 Proxy
+- 实现秒级远程变更感知（替代分钟级 dir-cache-time）
+- 不依赖品牌 API，基于 inotify 通用方案
+
+#### 4.16 多 NAS / 多目录支持
+- 同时连接多个远程 NAS（如家里 + 工作室）
+- 每个 NAS 独立共享名，独立缓存策略
+- 每个共享可配置不同的缓存大小和保留时间
+
+#### 4.17 智能缓存策略
+- 根据文件类型自动调整策略：
+  - `.lrcat` / `.xmp`（Lightroom catalog/sidecar）→ 高缓存优先级
+  - `.CR3` / `.ARW` / `.NEF`（RAW 照片）→ 大块预读，长缓存保留
+  - `.mp4` / `.mov`（视频）→ 顺序预读优化
+  - `.psd` / `.ai`（设计文件）→ 完整缓存，避免分块导致的兼容问题
+- 基于访问频率自动调整缓存优先级（热数据不被淘汰）
+
+#### 4.18 Docker 镜像
+- 一行命令启动：`docker run -v /mnt/ssd:/cache warpgate`
+- docker-compose 配置
+- 支持环境变量或挂载配置文件
+
+#### 4.19 通知机制
+- 缓存空间不足告警（Webhook / Telegram / 邮件）
+- NAS 离线告警
+- 回写失败告警
+
+---
+
+## 五、数据一致性模型
+
+### 5.1 设计目标
+
+采用**读写透明代理**模型。rclone VFS 统一管理缓存和回写。具体承诺：
+
+1. 本地写入持久化在 SSD → rclone 异步回写 NAS → 回写完成数据安全
+2. 远程 NAS 上的变更会在 `--dir-cache-time` 过期后被自动感知
+3. 已缓存的文件在离线时仍可正常访问
+4. **关键约束**：单向写（出门期间 NAS 端不动），此约束下无冲突
+
+### 5.2 设计讨论与决策过程
+
+#### 问题 A：为什么 rclone VFS 就够了？
+
+**讨论**：早期设计曾考虑 OverlayFS + sync daemon 方案，也曾退化到只读缓存 + SD Uploader 方案。最终回到 rclone VFS 读写缓存：
+
+- rclone VFS `--vfs-cache-mode full` 本身就是完整的读写缓存代理——读按需拉取，写本地暂存后异步回写
+- 在单向写约束下（出门期间 NAS 端不动），不存在写冲突
+- 不需要额外的 sync daemon、OverlayFS、SD Uploader 或 metadata DB
+- 架构大幅简化：一个 rclone 进程 + Samba/NFS 对外服务即可
+
+**核心原则**："回写队列清空 = 数据安全"
+
+**约束条件**：
+- 单向写：出门期间 NAS 端不动
+- 正常 unmount：确保关机前回写完成
+- 缓存空间留够：为脏文件预留足够 SSD 空间
+
+> **MVP 部署建议**：**建议**缓存盘使用 btrfs 或 ZFS 文件系统（CoW + checksum 保护断电一致性）。部署脚本应检测并警告非 CoW 文件系统。
+
+#### 问题 B：回写中断怎么办？
+
+**讨论**：本地写入后、回写完成前，可能发生断电或断网。
+
+**决策**：
+- 断网：rclone 暂停回写，网络恢复后自动继续。脏文件安全保存在 SSD 上。
+- 异常断电：rclone 重启后扫描缓存目录，继续回写未完成的脏文件。但如果断电发生在 SSD 写入过程中（文件只写了一半），可能导致数据丢失。建议使用 UPS/电池保护 + btrfs/ZFS 文件系统。
+
+### 5.3 一致性模型（读写透明代理）
+
+```
+读取路径：应用 → Samba/NFS → rclone FUSE → SSD 缓存 ← SFTP 从 NAS 按需拉取
+写入路径：应用 → Samba/NFS → rclone FUSE → SSD 缓存(dirty) → rclone 异步回写 NAS
+```
+
+**读写缓存**：
+- rclone 以 `--vfs-cache-mode full` 挂载，Samba/NFS 共享支持读写
+- rclone 内部管理 dirty/clean 状态，外部无需干预
+- LRU 淘汰时自动跳过脏文件
+- `--vfs-write-back` 控制回写延迟（默认 5s）
+- 回写完成后文件状态从 dirty 变为 clean，可正常被 LRU 淘汰
+
+**缓存淘汰**：rclone 由 `--vfs-cache-max-size` 和 `--vfs-cache-max-age` 控制 LRU 淘汰，脏文件受保护不被淘汰。
+
+### 5.4 读取时的缓存验证
+
+缓存验证逻辑：
+
+| 远程状态 | 缓存行为 |
+|---|---|
+| 远程没变 | ✅ 直接用缓存 |
+| 远程被修改 | 🔄 dir-cache-time 过期后 rclone 自动感知 → 下次访问时拉新版本 |
+| 远程被删除 | 🗑️ dir-cache-time 过期后 rclone 刷新 → 文件消失 |
+
+**注意**：读取热路径上**不查远程**（不产生网络请求），直接返回缓存。远程变更由 rclone `--dir-cache-time` 过期机制自动发现。
+
+### 5.5 关键场景走查
+
+#### 场景 1：Cache 关机几天，NAS 上文件被修改
+
+```mermaid
+flowchart TD
+    D1["Day 1: Cache 缓存 photo.cr3 (clean)"] --> Off["Day 1: Cache 关机"]
+    Off --> D3["Day 3: NAS 上 photo.cr3 被修改"]
+    D3 --> D5["Day 5: Cache 开机<br/>rclone 启动"]
+    D5 --> Expire["dir-cache-time 过期<br/>rclone 自动刷新目录缓存"]
+    Expire --> Access["用户访问时 rclone 自动拉新版本"]
+    Access --> Result["✅ 用户读到 NAS 最新版本"]
+```
+
+#### 场景 2：NAS 删了文件
+
+```mermaid
+flowchart TD
+    D1["Day 1: Cache 缓存 photo.cr3 (clean)"]
+    D1 --> D3["Day 3: NAS 上删除 photo.cr3"]
+    D3 --> Expire["dir-cache-time 过期<br/>rclone 刷新目录缓存"]
+    Expire --> Gone["rclone 发现远程文件不存在"]
+    Gone --> Result["✅ 本地缓存与远程保持一致"]
+```
+
+#### 场景 3：本地写入文件
+
+```mermaid
+flowchart TD
+    Write["用户通过 Samba 写入文件"] --> Cache["rclone 写入 SSD 缓存<br/>标记为 dirty"]
+    Cache --> Delay["--vfs-write-back 延迟<br/>（默认 5s）"]
+    Delay --> Upload["rclone 通过 SFTP<br/>异步回写到 NAS"]
+    Upload --> Clean["回写完成<br/>dirty → clean"]
+    Clean --> Result["✅ 文件安全到达 NAS"]
+```
+
+#### 场景 4：离线写入
+
+```mermaid
+flowchart TD
+    Offline["远程不可达"] --> Write["用户写入文件到 Samba"]
+    Write --> Cache["rclone 写入 SSD 缓存<br/>标记为 dirty"]
+    Cache --> Queue["rclone 发现网络不可达<br/>回写暂停"]
+    Queue --> Recover["网络恢复"]
+    Recover --> Upload["rclone 自动续传<br/>回写脏文件到 NAS"]
+    Upload --> Result["✅ 无需人工干预"]
+```
+
+---
+
+## 六、远程变更检测机制
+
+### 6.1 设计约束
+
+**不依赖任何 NAS 品牌特有 API**。产品需要支持群晖、QNAP、威联通、TrueNAS 等任意品牌 NAS，因此只能基于标准 SFTP 协议实现。
+
+### 6.2 SFTP 协议的能力边界（设计讨论）
+
+**问题**：远程 NAS 上数据更新了，Cache 怎么知道？能否实时感知？
+
+**讨论**：SFTP 协议本身**没有任何通知/推送/订阅机制**。它是无状态的文件传输协议，不支持 inotify、webhook、filesystem watch 等概念。每次想知道远程状态，必须主动发请求查询。
+
+**考虑过的方案**：
+
+| 方案 | 原理 | 实时性 | 品牌依赖 | 取舍 |
+|------|------|--------|----------|------|
+| SFTP 全量轮询 | 递归 ls 对比 mtime | 分钟级 | 无 | 文件多时开销大 |
+| SFTP 分层轮询 | 先查目录 mtime，变了再查文件 | 分钟级 | 无 | 高效，但增加系统复杂性 |
+| rclone dir-cache-time | rclone 内置目录缓存过期机制 | 可配 | 无 | 零额外代码，推荐 |
+| 群晖 FileStation API | 调 DSM Web API | 秒级 | 仅群晖 | ❌ 不通用 |
+| NAS 侧 Agent 推送 | inotifywait → HTTP 通知 | 秒级 | 无 | 需要 NAS 装软件 |
+
+**最终决策**：
+
+- **P0（MVP）**：rclone 通过 `--dir-cache-time` 控制目录缓存过期时间，过期后自动从远程重新读取。对大多数单用户场景足够。
+- **P2（后续）**：可选的 NAS 侧 Agent 推送，作为增强项给需要秒级同步的用户
+
+### 6.3 后续增强：NAS 侧 Agent 推送（P2）
+
+对于需要秒级同步的用户，可选在 NAS 上部署轻量 Agent（Docker 容器），通过 inotify 监听变化并推送：
+
+```mermaid
+flowchart LR
+    subgraph NAS ["群晖 NAS"]
+        Agent["inotifywait 监听文件变化<br/>(Docker 容器)"]
+    end
+
+    subgraph Proxy ["Linux Proxy"]
+        HTTP["HTTP 接收端<br/>触发 vfs/forget 刷新"]
+    end
+
+    Agent -- "轻量 HTTP POST<br/>(via Tailscale)" --> HTTP
+```
+
+此方案作为 dir-cache-time 的增强，不是替代。即使 Agent 不可用，dir-cache-time 机制仍然工作。
+
+---
+
+## 七、缓存行为详细描述
+
+### 7.1 读取流程
+
+```mermaid
+flowchart TD
+    App["应用请求读取文件"] --> Samba["① Samba/NFS"]
+    Samba --> FUSE["② rclone FUSE 挂载"]
+    FUSE -->|"缓存命中"| Return["直接返回缓存<br/>（SSD 速度）"]
+    FUSE -->|"缓存未命中"| Remote["③ rclone 从远程 NAS 拉取"]
+    FUSE -->|"缓存已过期"| Refresh["④ rclone 检查远程 mtime<br/>变了则重新拉取"]
+
+    Remote --> Chunk["⑤ 按 chunk 分块下载"]
+    Chunk --> Cache["⑥ 缓存到 SSD"]
+    Cache --> ReturnData["⑦ 返回数据给应用"]
+    Refresh --> ReturnData
+```
+
+**设计要点**：
+
+- 读取热路径上**不查远程**（不产生网络请求），直接返回缓存，保证响应速度
+- 目录缓存通过 rclone `--dir-cache-time` 控制过期刷新
+
+### 7.2 写入流程
+
+```mermaid
+flowchart TD
+    App["应用写入文件"] --> Samba["① Samba"]
+    Samba --> FUSE["② rclone FUSE 挂载"]
+    FUSE --> SSD["③ 写入 SSD 缓存<br/>标记为 dirty"]
+    SSD --> Delay["④ --vfs-write-back 延迟"]
+    Delay --> Upload["⑤ rclone 通过 SFTP<br/>回写到 NAS"]
+
+    Upload -->|"回写成功"| Clean["⑥ dirty → clean"]
+    Upload -->|"网络不可达"| Queue["⑥ 暂停回写<br/>网络恢复后自动续传"]
+    Queue --> Upload
+```
+
+### 7.3 缓存淘汰策略
+
+rclone 管理 LRU 淘汰，脏文件受保护不被淘汰：
+
+- `--vfs-cache-max-size`：缓存总大小上限，超出时按 LRU 淘汰
+- `--vfs-cache-max-age`：缓存最大保留时间
+- rclone 自行管理淘汰，无需外部干预
+- 脏文件（未回写到 NAS）不会被淘汰，确保写入数据安全
+
+**脏文件空间说明**：离线大量写入时，脏文件会持续累积在 SSD 上。当脏文件 + clean 缓存接近 `--vfs-cache-max-size` 上限时，rclone 只能淘汰 clean 文件。如果 clean 文件已全部淘汰而脏文件仍在增长，新写入可能失败。应确保 `--vfs-cache-max-size` 为离线写入预留足够空间。
+
+### 7.4 离线行为
+
+| 场景 | 行为 |
+|------|------|
+| 远程不可达，读取已缓存文件 | 正常返回，无影响 |
+| 远程不可达，读取未缓存文件 | 超时报错（可配置超时时间） |
+| 远程不可达，本地写入 | 正常写入到缓存，标记为 dirty，恢复连接后自动回写 |
+| 远程不可达，后台目录缓存刷新 | 静默跳过，下次重试 |
+| 恢复连接后 | rclone 回写队列自动续传 + 目录缓存按 dir-cache-time 正常过期刷新 |
+
+---
+
+## 八、配置参数清单
+
+### 连接配置
+
+| 参数 | 说明 | 默认值 | 建议值 |
+|------|------|--------|--------|
+| `NAS_HOST` | 远程 NAS 的 Tailscale IP | - | `100.x.x.x` |
+| `NAS_USER` | SFTP 用户名 | - | - |
+| `NAS_PASS` / `NAS_KEY_FILE` | 认证信息 | - | 建议密钥 |
+| `NAS_REMOTE_PATH` | NAS 上的目标路径 | - | `/volume1/photos` |
+| `SFTP_PORT` | SFTP 端口 | `22` | `22` |
+| `SFTP_CONNECTIONS` | SFTP 连接复用数 | `8` | `4-16` |
+
+### 缓存配置
+
+| 参数 | 说明 | 默认值 | 建议值 |
+|------|------|--------|--------|
+| `CACHE_DIR` | 缓存存储路径 | - | SSD 路径，建议 btrfs/ZFS |
+| `CACHE_MAX_SIZE` | 缓存大小上限 | `200G` | SSD 容量的 70-80% |
+| `CACHE_MAX_AGE` | 缓存最大保留时间 | `720h`（30天） | 按使用习惯 |
+| `CACHE_MIN_FREE` | 缓存盘最低可用空间 | `10G` | `10-20G` |
+
+### 读取优化
+
+| 参数 | 说明 | 默认值 | 场景建议 |
+|------|------|--------|----------|
+| `READ_CHUNK_SIZE` | 分块读取大小 | `256M` | RAW 照片: `256M`，视频: `512M`，文档: `64M` |
+| `READ_CHUNK_LIMIT` | chunk 自动增长上限 | `1G` | - |
+| `READ_AHEAD` | 预读缓冲区 | `512M` | 视频场景可加到 `1G` |
+| `BUFFER_SIZE` | 内存缓冲区 | `256M` | - |
+
+### 带宽配置
+
+| 参数 | 说明 | 默认值 | 场景建议 |
+|------|------|--------|----------|
+| `BW_LIMIT_UP` | 回写限速上限 | `0`（不限） | 酒店 WiFi 建议 `10-20M` |
+| `BW_LIMIT_DOWN` | 缓存拉取下载限速 | `0`（不限） | 一般不限 |
+| `BW_ADAPTIVE` | 自适应回写限速开关 | `yes` | `yes`=根据吞吐量自动降速，`no`=纯手动 |
+
+### 回写配置
+
+| 参数 | 说明 | 默认值 | 建议值 |
+|------|------|--------|--------|
+| `VFS_WRITE_BACK` | 回写延迟（rclone `--vfs-write-back`） | `5s` | 低延迟链路可设更短 |
+| `TRANSFERS` | rclone 并发传输数（`--transfers`） | `4` | 带宽小就设 `2` |
+
+### 目录缓存
+
+| 参数 | 说明 | 默认值 | 场景建议 |
+|------|------|--------|----------|
+| `DIR_CACHE_TIME` | 目录列表缓存时间（rclone `--dir-cache-time`） | `1h` | 个人: `1-2h`，协作: `5-15m` |
+
+### 多协议配置
+
+| 参数 | 说明 | 默认值 | 建议值 |
+|------|------|--------|--------|
+| `ENABLE_SMB` | 启用 SMB 共享 | `yes` | `yes` |
+| `ENABLE_NFS` | 启用 NFS 导出 | `no` | 有 Linux 客户端时开启 |
+| `ENABLE_WEBDAV` | 启用 WebDAV 服务 | `no` | 有移动端需求时开启 |
+| `NFS_ALLOWED_NETWORK` | NFS 允许访问的网段 | `192.168.0.0/24` | 按实际局域网设置 |
+| `WEBDAV_PORT` | WebDAV 监听端口 | `8080` | - |
+
+### 配网模式配置
+
+| 参数 | 说明 | 默认值 | 建议值 |
+|------|------|--------|--------|
+| `SETUP_AP_SSID` | 配网热点名称 | `Warpgate-Setup` | - |
+| `SETUP_AP_PASSWORD` | 配网热点密码（空=开放） | 空 | 首次配网建议开放，降低门槛 |
+| `SETUP_AP_AUTO` | 无网络时自动进入配网模式 | `yes` | `yes` |
+| `SETUP_AP_TIMEOUT` | 配网完成后临时 AP 保持时间 | `5m` | 认证成功后自动关闭 |
+| `SETUP_PORTAL_LISTEN` | 配网 Web 服务监听地址 | `192.168.4.1:80` | - |
+
+### WiFi AP 配置
+
+| 参数 | 说明 | 默认值 | 建议值 |
+|------|------|--------|--------|
+| `AP_ENABLED` | 启用 WiFi 热点 | `no` | 现场共享时开启 |
+| `AP_SSID` | 热点名称 | `Warpgate` | - |
+| `AP_PASSWORD` | 热点密码 | 随机生成 | 首次配置时设定 |
+| `AP_ISOLATION` | AP 网络与 WAN 隔离 | `yes` | `yes` |
+| `AP_MAX_CLIENTS` | 最大连接数 | `8` | - |
+
+---
+
+## 九、场景预设（模板）
+
+为降低用户配置门槛，提供开箱即用的预设模板。
+
+### 摄影师模式
+
+```
+重点优化：大文件读取性能、RAW 浏览流畅
+- CACHE_MAX_SIZE=500G
+- READ_CHUNK_SIZE=256M
+- READ_AHEAD=512M
+- DIR_CACHE_TIME=2h      ← 目录结构不常变
+- VFS_WRITE_BACK=5s
+- TRANSFERS=4
+- ENABLE_SMB=yes
+- ENABLE_NFS=no
+- ENABLE_WEBDAV=no
+```
+
+### 视频剪辑模式
+
+```
+重点优化：顺序读取性能、大文件预读
+- CACHE_MAX_SIZE=1T
+- READ_CHUNK_SIZE=512M
+- READ_AHEAD=1G          ← 大预读保证播放流畅
+- DIR_CACHE_TIME=1h
+- VFS_WRITE_BACK=5s
+- TRANSFERS=2             ← 减少并发，保带宽给播放
+- ENABLE_SMB=yes
+- ENABLE_NFS=no
+- ENABLE_WEBDAV=no
+```
+
+### 文档办公模式
+
+```
+重点优化：小文件快速响应、频繁感知远程变更
+- CACHE_MAX_SIZE=50G
+- READ_CHUNK_SIZE=64M
+- READ_AHEAD=128M
+- DIR_CACHE_TIME=30m     ← 协作场景需要较快看到新文件
+- VFS_WRITE_BACK=5s
+- TRANSFERS=4
+- ENABLE_SMB=yes
+- ENABLE_NFS=no
+- ENABLE_WEBDAV=yes      ← 移动端也能访问
+```
+
+---
+
+## 十、部署要求
+
+### 硬件要求（通用 Linux 主机部署）
+
+| 组件 | 最低配置 | 推荐配置 |
+|------|----------|----------|
+| CPU | ARMv8 / x86_64 任意 | N100 或同级 |
+| 内存 | 1 GB | 2-4 GB |
+| 缓存盘 | 任意 SSD | NVMe SSD |
+| 缓存容量 | 32 GB | 常用数据量的 30%+ |
+| 网口 | 100M | 千兆（2.5G 更好） |
+| 断电保护 | - | 内置电池或外接 UPS |
+
+### 硬件要求（一体机目标形态）
+
+通用要求之外，一体机额外需要：
+
+| 组件 | 说明 |
+|------|------|
+| USB-A/C 口 | 至少 2 个，用于外接存储设备 |
+| WiFi 模块 | 支持 **AP+STA 并发模式**（配网必须），建议 WiFi 6 |
+| 内置电池 | 支持断电保护 + 便携使用 |
+| SD 卡槽（SD 功能启用后需要） | SD / microSD，覆盖大多数相机 |
+| CFexpress 槽（SD 功能启用后可选） | CFexpress Type-B，高端相机用户 |
+| 物理按钮（SD 功能启用后需要） | 触发 SD 卡导入 / 确认操作 |
+| LED 状态指示（SD 功能启用后需要） | 导入进度 / 完成 / 错误 / 上传状态 |
+
+**缓存盘文件系统建议**：btrfs 或 ZFS。利用 CoW（Copy-on-Write）和 journal 机制，即使意外断电也能保证文件系统级别的一致性。
+
+```bash
+# btrfs 格式化示例
+mkfs.btrfs /dev/ssd_partition
+mount -o compress=zstd /dev/ssd_partition /mnt/ssd/warpgate
+```
+
+### 软件要求
+
+| 组件 | 版本 |
+|------|------|
+| OS | Ubuntu 22.04+ / Debian 12+ / 任意 Linux |
+| rclone | 1.65+（关键参数：`--vfs-cache-mode full --vfs-write-back {VFS_WRITE_BACK} --vfs-cache-max-size {CACHE_MAX_SIZE} --cache-dir {CACHE_DIR}/rclone-cache --rc`）。`--rc` 启用 RC API，供外部调用 `vfs/forget` 刷新目录缓存 |
+| Samba | 4.x |
+| NFS server | nfs-kernel-server（如启用 NFS） |
+| FUSE | 3.x |
+| Tailscale / ZeroTier | 已配置并可连通 NAS |
+
+### NAS 侧要求
+
+| 项目 | 要求 |
+|------|------|
+| SFTP 服务 | 开启（群晖：控制面板 → 文件服务 → FTP → 勾选 SFTP） |
+| 用户权限 | SFTP 用户对目标目录有读写权限 |
+| Tailscale | 已安装并登录同一网络 |
+| 品牌 | **无限制**，任何支持 SFTP 的 NAS 均可（群晖/QNAP/威联通/TrueNAS/DIY 等） |
+
+---
+
+## 十一、风险与局限
+
+| 风险 | 等级 | 说明 | 缓解措施 |
+|------|------|------|----------|
+| 首次访问慢 | 固有 | 未缓存文件必须走远程 | 预热功能；分块下载优化 |
+| 缓存一致性延迟 | 低 | 远程变更在 dir-cache-time 内不可见 | 合理设置 dir-cache-time；后续可选 Agent 推送 |
+| Tailscale 断连 | 中 | 远程不可达时新文件无法获取 | 已缓存文件仍可用；回写队列自动排队；恢复后自动续传 |
+| 回写中断 | 中 | 异常断电时未回写的脏文件可能丢失 | UPS/电池保护 + btrfs/ZFS 文件系统保护一致性 |
+| 脏文件占满缓存 | 中 | 离线大量写入时缓存空间不足 | 确保 `--vfs-cache-max-size` 留够空间；监控脏文件占比 |
+| NAS 端并发修改 | 低 | 单向写约束外有人修改 NAS 导致冲突 | 文档明确说明单向写约束；出门前确认 NAS 端无其他修改 |
+| 中转服务带宽成本 | 中 | DERP 中继带宽随用户增长上升 | 大部分连接走 P2P 直连；按流量分级限速/计费；初期节点少按需扩容 |
+| 云备份存储成本 | 低 | 用户数据增长导致存储费用上升 | 接低价对象存储（B2/R2）；按量计费传导成本；增量备份减少传输量 |
+| 酒店 Captive Portal | 中 | Headless 设备无法完成网页认证，旅途场景不可用 | 配网 AP + Portal 代理（4.8）；fallback：USB tethering / 手机热点 / MAC 克隆 |
+
+---
+
+## 十二、后续演进方向
+
+| 阶段 | 内容 | 重点 |
+|------|------|------|
+| **v1.0 — MVP** | 配置文件 + 部署脚本 + CLI 管理 | SMB 读写共享 + rclone VFS 读写缓存 + 配网模式 + CLI + 缓存预热 + 带宽管理 |
+| **v1.5 — 硬件原型 + P1 功能** | SD 卡导入 + 双卡校验 + LED/按钮交互 + 硬件原型 | SD 功能开发，硬件原型 |
+| **v2.0 — 组网服务** | 内置 Headscale + 高速 DERP 节点 + WiFi AP 共享 | 开箱即连 + 现场团队协作 |
+| **v2.5 — 容灾 + 附加** | 云端异地备份 + Docker 镜像 + 多协议（NFS/WebDAV）+ NAS 侧 Agent 推送 | 数据安全闭环 + 降低部署门槛 |
+| **v3.0 — 硬件产品** | 定制硬件（SSD + 电池 + SD 槽 + WiFi），工业设计，开箱即用 | 产品化，面向非技术用户 |
+
+---
+
+## 十三、付费服务
+
+### 13.1 Headscale + 高速 DERP 中转
+
+**问题**：Tailscale 官方 DERP 是共享资源，跨运营商/跨国时带宽受限。用户自建 DERP 需要有 VPS + 运维能力，门槛高。
+
+**方案**：
+
+```mermaid
+flowchart BT
+    subgraph infra ["运营基础设施"]
+        HS["Headscale<br/>控制面板<br/>(用户管理)"]
+        DERP1["DERP 节点<br/>国内 BGP<br/>(低延迟)"]
+        DERP2["DERP 节点<br/>香港/日本<br/>(跨境加速)"]
+    end
+
+    Box["盒子<br/>开箱即连<br/>(内置配置)"] --> HS
+    Box --> DERP1
+    NAS_C["NAS 端<br/>自动连接<br/>(安装脚本)"] --> DERP1
+    NAS_C --> DERP2
+    Travel["出差设备<br/>自动连接<br/>(通过盒子中继)"] --> DERP2
+```
+
+**用户体验**：
+
+1. 买盒子 → 开机 → 扫码绑定账号
+2. NAS 端运行一行安装脚本，加入用户的 Tailnet
+3. 完成。盒子带到任何地方，自动通过最优 DERP 节点连回家
+4. 无需了解 Headscale、DERP、WireGuard 等概念
+
+**迁移路径**（避免 vendor lock-in）：
+- 盒子底层使用标准 WireGuard 协议，用户可随时切换到自建 Headscale 或官方 Tailscale
+- 提供配置导出工具：一键导出 WireGuard 配置、节点列表、DERP 自定义映射
+- 如用户不再使用我们的 Headscale 服务，盒子仍可正常工作（手动配置 Tailscale/WireGuard）
+
+**定价思路**：
+
+| 套餐 | 内容 | 参考价 |
+|------|------|--------|
+| 免费 | Headscale 控制面板 + 1 个基础 DERP 节点（限速） | ¥0 |
+| 基础版 | + 多节点智能选路 + 不限速 | ¥15-30/月 |
+| 专业版 | + 优先带宽 + 跨境加速节点 + SLA 保证 | ¥50-100/月 |
+
+**成本控制**：
+
+- DERP 中继只在无法打洞直连时使用，大部分 Tailscale 连接是 P2P 直连，中继流量占比通常不高
+- 可按实际中继流量动态限速/计费，避免被少数大流量用户拖垮
+- 初期节点少（1-2 个），按用户增长逐步扩容
+
+### 13.2 异地容灾备份
+
+**问题**：NAS 在家里是单点故障——硬盘坏、被盗、火灾、水灾都可能导致数据永久丢失。
+
+**方案**：
+
+```mermaid
+flowchart TD
+    SSD["盒子 SSD 缓存<br/>（热数据子集）"]
+    SSD -->|"空闲时段<br/>加密增量备份"| Cloud
+
+    subgraph Cloud ["云存储服务"]
+        UX["用户视角: 一键开通，按月付费"]
+        Backend["后端: B2 / R2 / MinIO<br/>(~$5/TB/月)"]
+        Encrypt["数据加密: 用户本地生成密钥<br/>运营方看不到明文"]
+        KeyBackup["密钥备份: 首次设置强制引导<br/>（密钥文件 / 助记词 / 密码管理器）"]
+        Sync["增量同步: 只传变化部分"]
+        Restore["恢复: 新盒子 → 输入密钥 → 自动拉取"]
+    end
+```
+
+**与现有架构的关系**：
+
+- 从缓存/NAS 异步上传到云端
+- 可以做成两级：
+  - **热备份**：盒子 SSD 上缓存过的文件自动备份（几乎零额外成本）
+  - **全量备份**：通过以下任一路径从 NAS 全量增量备份到云端：
+    - **方案 1（推荐）**：盒子在家局域网时自动执行（高速，零公网带宽消耗）
+    - **方案 2**：盒子在外通过 Tailscale 远程执行（速度受限于公网带宽，但保证便携场景也能跑备份）
+    - **方案 3（远期）**：在 NAS 侧部署独立的备份 agent（Docker 容器），NAS 直接备份到云端，不依赖盒子在线
+  - 便携性说明：盒子的核心场景是带出去用。全量备份不要求盒子必须在家——方案 2 保证在外时也能慢速备份，方案 3 完全解耦盒子和全量备份
+
+**定价思路**：
+
+| 套餐 | 内容 | 参考价 |
+|------|------|--------|
+| 免费 | 热数据备份（仅缓存过的文件），上限 50GB | ¥0 |
+| 基础版 | 全量备份，500GB | ¥15/月 |
+| 专业版 | 全量备份，5TB | ¥50/月 |
+| 按量 | 超出部分 | ¥10/TB/月 |
+
+---
+
+## 十四、明确不做的方向
+
+| 方向 | 原因 |
+|------|------|
+| 缩略图/预览生成、Web 相册 | 破坏「透明代理」核心定位，产品本质是协议透传不是数据加工 |
+| AI 选片 | 非核心，远期可选 |
+| 程序员场景（Git 缓存、Docker 镜像等） | 痛点不够强，已有成熟方案（Git 天然分布式、Codespaces 等） |
+| 公网文件分享链接 | 法律风险 + 需求不明确 |
+| 多设备 SaaS 管理面板 | 需求不明确，过早 |
+| Docker 开放运行环境 | 产品定位发散（注：这里指的是允许用户在盒子上运行任意 Docker 容器，而非 4.18 的"将本产品打包为 Docker 镜像部署"） |
+
+---
+
+## 十五、术语表
+
+| 术语 | 说明 |
+|------|------|
+| **Warpgate / 盒子** | 本产品——部署在用户身边的 SSD 缓存代理设备 |
+| **NAS** | 用户家中的网络存储设备（Network Attached Storage） |
+| **VFS** | rclone 的虚拟文件系统层（Virtual File System），将远程存储挂载为本地目录 |
+| **FUSE** | 用户空间文件系统（Filesystem in Userspace），Linux 内核机制，允许 rclone 在不修改内核的情况下提供文件系统挂载 |
+| **FUSE 挂载点** | rclone 通过 FUSE 暴露的本地目录（如 `/mnt/nas-photos`），Samba/NFS 直接服务于此目录 |
+| **dirty file / 脏文件** | 已写入本地 SSD 缓存但尚未回写到远程 NAS 的文件 |
+| **write-back / 回写** | rclone 将本地修改异步上传到远程 NAS 的过程 |
+| **LRU** | 最近最少使用（Least Recently Used），缓存淘汰算法 |
+| **SFTP** | SSH 文件传输协议，本产品与 NAS 通信的主要协议 |
+| **Tailscale** | 基于 WireGuard 的组网工具，用于建立盒子与 NAS 之间的安全隧道 |
+| **Headscale** | Tailscale 控制面板的开源自建实现 |
+| **DERP** | Tailscale 的中继服务器（Designated Encrypted Relay for Packets），在无法直连时中转流量 |
+| **Captive Portal** | 强制门户认证，酒店/机场等 WiFi 连接后重定向到网页要求登录的机制 |
+| **AP+STA 并发** | WiFi 模块同时作为热点（AP）和连接外部网络（STA）的工作模式 |