diff --git a/warpgate-prd-v3.md b/warpgate-prd-v3.md index 61e9d95..65381be 100644 --- a/warpgate-prd-v3.md +++ b/warpgate-prd-v3.md @@ -200,13 +200,46 @@ TM 回写策略： **TIMEMACHINE_PATH 与 NAS_REMOTE_PATH 的关系**：两者是 NAS 上的不同目录，互不关联。NAS_REMOTE_PATH 是用户的照片/文件目录（如 `/volume1/photos`），TIMEMACHINE_PATH 是 TM 备份专用目录（如 `/volume1/timemachine`）。TM 回写通过独立的 SFTP 连接直接传输到 TIMEMACHINE_PATH，不经过 rclone VFS。 -#### 4.11 缓存预热（Warm-up） +#### 4.11 配网模式 + 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 地址（高级用户） + +#### 4.12 缓存预热（Warm-up） - 命令行手动预热指定目录 - 按时间范围预热（如"最近 7 天新增的文件"） - 定时预热任务（如每天凌晨自动拉取最新数据） - 预热进度显示 -#### 4.12 管理工具（CLI） +#### 4.13 管理工具（CLI） - `warpgate status` — 查看服务状态、缓存命中率、回写队列、冲突文件数 - `warpgate cache-list` — 列出缓存中的文件 - `warpgate cache-clean` — 清理缓存 @@ -217,28 +250,30 @@ TM 回写策略： - `warpgate verify` — 双卡校验 - `warpgate log` — 查看实时日志 - `warpgate speed-test` — 链路速度测试 +- `warpgate setup-wifi` — 手动进入配网模式 +- `warpgate clone-mac ` — 克隆指定设备的 MAC 地址 -#### 4.13 带宽管理 +#### 4.14 带宽管理 - 支持上传/下载分别限速 - 运行时动态调整限速（不重启服务） - 回写带宽不影响读取体验 -#### 4.14 连接容错 +#### 4.15 连接容错 - Tailscale 断连时自动重试 - 已缓存的文件在离线时仍可正常读取 - 写回队列在恢复连接后自动续传 - 连接超时参数可配置 -#### 4.15 写冲突通知 +#### 4.16 写冲突通知 - 冲突发生时通知用户（CLI 提示 / 日志 / 可选 Webhook） - 冲突文件清单管理 - 手动解决冲突工具 ### P2（后续迭代） -#### 4.16 WiFi AP 现场共享 +#### 4.17 WiFi AP 现场共享 -盒子内置 WiFi 模块开启热点，现场团队设备连上即可通过 SMB/WebDAV 访问缓存目录。 +盒子内置 WiFi 模块开启持久热点，现场团队设备连上即可通过 SMB/WebDAV 访问缓存目录。与 4.11 配网模式的区别：配网 AP 是临时的（完成配网后关闭），本功能是持久的团队共享热点。 - 支持 AP 模式，复用已有的 SMB/WebDAV 多协议服务 - AP 网络与 Tailscale/WAN 网络隔离（安全考虑） @@ -246,24 +281,24 @@ TM 回写策略： - **硬件要求**：需要两个独立网络接口——WiFi 模块用于 AP 热点，有线/USB 4G 网卡用于 WAN/Tailscale 连接。一体机硬件设计需预留双网卡 - 典型场景：婚礼现场摄影师导入 SD 卡后，助理 iPad 连上 WiFi 即可浏览选片 -#### 4.17 Web 管理界面 +#### 4.18 Web 管理界面 - 缓存状态仪表盘（大小、命中率、回写队列、冲突文件、带宽趋势图） - 缓存文件浏览器（查看/手动清除/手动预热） - 配置修改界面（参数调整无需编辑配置文件） - 冲突文件可视化处理 - 实时日志查看器 -#### 4.18 NAS 侧 Agent 推送（可选增强） +#### 4.19 NAS 侧 Agent 推送（可选增强） - 在 NAS 上运行轻量 Agent（Docker 容器），监听文件变化主动推送给 Proxy - 实现秒级远程变更感知（替代分钟级轮询） - 不依赖品牌 API，基于 inotify 通用方案 -#### 4.19 多 NAS / 多目录支持 +#### 4.20 多 NAS / 多目录支持 - 同时连接多个远程 NAS（如家里 + 工作室） - 每个 NAS 独立共享名，独立缓存策略 - 每个共享可配置不同的缓存大小和保留时间 -#### 4.20 智能缓存策略 +#### 4.21 智能缓存策略 - 根据文件类型自动调整策略： - `.lrcat` / `.xmp`（Lightroom catalog/sidecar）→ 高优先级回写，短写回延迟 - `.CR3` / `.ARW` / `.NEF`（RAW 照片）→ 大块预读，长缓存保留 @@ -271,12 +306,12 @@ TM 回写策略： - `.psd` / `.ai`（设计文件）→ 完整缓存，避免分块导致的兼容问题 - 基于访问频率自动调整缓存优先级（热数据不被淘汰） -#### 4.21 Docker 镜像 +#### 4.22 Docker 镜像 - 一行命令启动：`docker run -v /mnt/ssd:/cache warpgate` - docker-compose 配置 - 支持环境变量或挂载配置文件 -#### 4.22 通知机制 +#### 4.23 通知机制 - 回写失败告警（Webhook / Telegram / 邮件） - 缓存空间不足告警 - NAS 离线告警 @@ -1237,6 +1272,16 @@ for dir in watched_directories: | `INGEST_PRIORITY` | 导入文件的回写优先级 | `high` | 高于普通编辑文件 | | `INGEST_IO_CLASS` | 导入时的 I/O 调度优先级 | `best-effort:4` | 使用 ionice 设置，避免导入阻塞缓存读取 | +### 配网模式配置 + +| 参数 | 说明 | 默认值 | 建议值 | +|------|------|--------|--------| +| `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 配置 | 参数 | 说明 | 默认值 | 建议值 | @@ -1333,7 +1378,7 @@ for dir in watched_directories: | SD 卡槽 | SD / microSD，覆盖大多数相机 | | CFexpress 槽（可选） | CFexpress Type-B，高端相机用户 | | USB-A/C 口 | 至少 2 个，用于外接读卡器（XQD 等）或移动硬盘 | -| WiFi 模块 | 支持 AP 模式，建议 WiFi 6 | +| WiFi 模块 | 支持 **AP+STA 并发模式**（配网必须），建议 WiFi 6 | | 物理按钮 | 触发 SD 卡导入 / 确认操作 | | LED 状态指示 | 导入进度 / 完成 / 错误 / 回写状态 | | 内置电池 | 支持断电保护 + 便携使用 | @@ -1386,6 +1431,7 @@ mount -o compress=zstd /dev/ssd_partition /mnt/ssd/warpgate | 缓存空间耗尽 | 中 | dirty 文件（导入+TM）撑满 SSD | 导入前空间预检；TM 硬配额；缓存空间告警（7.3.1） | | 中转服务带宽成本 | 中 | DERP 中继带宽随用户增长上升 | 大部分连接走 P2P 直连；按流量分级限速/计费；初期节点少按需扩容 | | 云备份存储成本 | 低 | 用户数据增长导致存储费用上升 | 接低价对象存储（B2/R2）；按量计费传导成本；增量备份减少传输量 | +| 酒店 Captive Portal | 中 | Headless 设备无法完成网页认证，旅途场景不可用 | 配网 AP + Portal 代理（4.11）；fallback：USB tethering / 手机热点 / MAC 克隆 | --- @@ -1394,7 +1440,7 @@ mount -o compress=zstd /dev/ssd_partition /mnt/ssd/warpgate | 阶段 | 内容 | 重点 | |------|------|------| | **v1.0 — MVP** | 配置文件 + 部署脚本 + CLI 管理 + 基础一致性 + Time Machine 支持 | SMB + 读写缓存 + 三时间戳 + 精简 metadata（两表）+ 分层轮询 + TM 备份目标（几乎零 Samba 配置成本） | -| **v1.5 — 硬件原型** | SD 卡导入 + 自动归档 + 双卡校验 + LED/按钮交互 + 缓存预热 + 带宽管理 + 连接容错 + 写冲突通知 | 外拍现场核心场景 + P1 功能补全，验证硬件形态 | +| **v1.5 — 硬件原型** | SD 卡导入 + 自动归档 + 双卡校验 + **配网模式 + Captive Portal 代理** + LED/按钮交互 + 缓存预热 + 带宽管理 + 连接容错 + 写冲突通知 | 外拍现场核心场景 + P1 功能补全，验证硬件形态 | | **v2.0 — 组网服务** | 内置 Headscale + 高速 DERP 节点 + WiFi AP 共享 | 开箱即连 + 现场团队协作 | | **v2.5 — 容灾 + 附加** | 云端异地备份 + Docker 镜像 + 多协议（NFS/WebDAV）+ NAS 侧 Agent 推送 | 数据安全闭环 + 降低部署门槛 | | **v3.0 — 硬件产品** | 定制硬件（SSD + 电池 + SD 槽 + WiFi），工业设计，开箱即用 | 产品化，面向非技术用户 | @@ -1510,7 +1556,7 @@ mount -o compress=zstd /dev/ssd_partition /mnt/ssd/warpgate | 程序员场景（Git 缓存、Docker 镜像等） | 痛点不够强，已有成熟方案（Git 天然分布式、Codespaces 等） | | 公网文件分享链接 | 法律风险 + 需求不明确 | | 多设备 SaaS 管理面板 | 需求不明确，过早 | -| Docker 开放运行环境 | 产品定位发散（注：这里指的是允许用户在盒子上运行任意 Docker 容器，而非 4.21 的"将本产品打包为 Docker 镜像部署"） | +| Docker 开放运行环境 | 产品定位发散（注：这里指的是允许用户在盒子上运行任意 Docker 容器，而非 4.22 的"将本产品打包为 Docker 镜像部署"） | --- @@ -1535,3 +1581,5 @@ mount -o compress=zstd /dev/ssd_partition /mnt/ssd/warpgate | **DERP** | Tailscale 的中继服务器（Designated Encrypted Relay for Packets），在无法直连时中转流量 | | **Ingest / 导入** | SD 卡文件导入到缓存并自动归档到 NAS 的过程 | | **WAL** | SQLite 的写前日志模式（Write-Ahead Logging），允许并发读写 | +| **Captive Portal** | 强制门户认证，酒店/机场等 WiFi 连接后重定向到网页要求登录的机制 | +| **AP+STA 并发** | WiFi 模块同时作为热点（AP）和连接外部网络（STA）的工作模式 |