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