warpgate/warpgate-prd-v4.md

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 整体架构

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。

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 上文件被修改

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 删了文件

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：本地写入文件

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：离线写入

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 监听变化并推送：

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 读取流程

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 写入流程

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 机制，即使意外断电也能保证文件系统级别的一致性。

# 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 + 运维能力，门槛高。

方案：

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 在家里是单点故障——硬盘坏、被盗、火灾、水灾都可能导致数据永久丢失。

方案：

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）的工作模式