20 KiB
本地优先（Local-first）Win 客户端改造方案（不依赖客户端 Docker）
1. 背景与目标
你已明确选择“方案 2”：以 丝滑体验 为第一优先级，把主要交互（新建/删除/打开/编辑/附件管理/文件树）尽可能做成 本地零延迟；在线能力只承担 多设备同步、鉴权、RAG/OCR 结果回传 等“不需要即时展示”的部分。
同时你希望：
- Windows 客户端可打包分发（家人/同事无需安装 Docker）
- 后续可扩展：安卓端可以继续使用网页版（或再做安卓壳/客户端）
- 现有服务端栈（Supabase/LightRAG/Redis/MinerU/OnlyOffice）在需要时仍可使用，但不强制落到每个客户端
2. 现状盘点（基于当前仓库）
- 当前仓库根目录的
pnpm run desktop/pnpm run desktop:hot本质是“一键启动脚本”，会启动：wolai-frontend（Next.js）wolai-backend（FastAPI）services/ingest_service（自动入库/清理/触发）services/rag_gateway（RAG 查询网关）
- 这不是可分发的“桌面客户端”：仍依赖 Node/Python 环境、端口服务、配置文件，且前端资源与 API 仍走 HTTP。
结论：要实现你要的“丝滑 + 易安装”，需要把“桌面壳 + 本地数据层 + 后台任务/同步”做成独立产品形态，而不是继续依赖 Cloudflare 反代公网访问。
3. 推荐总体架构（分层 + 可演进）
3.1 角色划分
A. 桌面客户端（Windows，主力）
- UI：本地窗口（WebView/Electron）加载本地页面（不经公网）
- 本地数据层：本地数据库（建议 SQLite）+ 本地文件目录（附件/导入文件）
- 本地任务队列：后台线程/进程异步执行（避免 UI 卡顿）
- 网络：只做“同步/索引请求/鉴权”，且尽量后台化
B. 家庭/办公室“轻服务端”（可选，但强烈建议）
你目前已有 Docker 相关服务，更适合放到一台“常开机器”（NAS/迷你主机/家用服务器）上，而不是每个客户端：
- Supabase（鉴权/同步/共享数据/存储桶/pgvector）
- Redis（队列/后台任务）
- LightRAG（入库/检索）
- MinerU（OCR）
- OnlyOffice Document Server（如仍需要网页内编辑 Office）
C. 公网访问（可选）
- 安卓端/外网访问时，继续使用网页版（可走 Cloudflare、或 VPN/IPv6）
- 但桌面端的“主要交互体验”不再依赖公网链路
3.2 本地优先的数据归属
核心原则：“能本地完成的操作，绝不阻塞在网络请求上。”
- 文档/思维导图的“当前版本内容”：本地可用（SQLite + 文件）
- 附件文件本体：本地可用（本地目录），需要时再同步/上传
- 远端（Supabase）只承担：
- 多设备同步与共享（最终一致）
- RAG/OCR 的产物存储与检索
- 登录鉴权（如你希望跨设备一致账号体系）
4. 技术路线：桌面壳怎么做（不跑 Docker）
你现在的前端是 Next.js（含 Server Components + API Routes），要做桌面客户端通常有两条路线：
路线 1（推荐落地优先）：桌面壳 + 本地 HTTP（保持现有 Next/FastAPI）
- 桌面壳：Tauri 2 或 Electron（两者都能）
- 客户端启动时：
- 启动本机
wolai-frontend（生产模式）到127.0.0.1:3000 - 启动本机
wolai-backend（或逐步把关键 API 收敛到一个本地服务） - 桌面壳打开
http://127.0.0.1:3000（同源、零公网）
- 启动本机
优点：
- 改造小：最大复用当前 Next/FastAPI
- 体验立刻提升：不再经过 Cloudflare/Tunnel
缺点：
- “安装体积/依赖”需要进一步工程化（见第 8 节分阶段）
路线 2（长期更优雅）：本地壳 + 静态前端 + 本地 API（逐步去 Next Server 依赖）
- 把前端逐步改成更“纯前端”的形态（或迁 Vite/React SPA）
- 本地 API 用一个可打包的二进制提供（Rust/Go）+ SQLite
优点：
- 最终安装最轻、启动更快、可控性最好
缺点：
- 改造量大，不建议作为第一阶段目标
建议决策：先走“路线 1”把体验做顺，再按收益逐步往“路线 2”靠拢。
5. “丝滑”的关键：本地任务队列 + 最终一致同步
5.1 本地操作必须立刻返回
把下列操作改为“本地先完成，后台再同步”：
- 新建/重命名/移动/删除（进入回收站）
- 打开文档（本地读）
- 编辑器保存（本地落盘 + 去抖）
- 附件导入（本地复制到附件目录，立即可用）
5.2 同步模型（建议：Oplog/变更日志）
为避免“每次都全量上传大字段”导致卡顿，建议本地维护一个 oplog：
- 每个操作写入：
op_id、entity_type、entity_id、op_type、payload、created_at、synced_at - 后台同步器按顺序上传到 Supabase（或服务端）
- 冲突策略（第一阶段先简单）：
- 同一文档若出现冲突：保留双方版本（生成“冲突副本”），避免覆盖丢数据
5.3 建议的本地 SQLite 最小表结构（用于落地与排期）
目标：先把“本地秒开 + 不依赖网络”的体验做出来；同步与协作逐步增强。
local_documentsid（uuid）、parent_id、title、content_json（或文件路径）、updated_at、deleted_at
local_media_assetsid、document_id、file_path、mime、sha256、size、created_at、deleted_at
local_mindmapsid、document_id（可选）、data_json、updated_at、deleted_at
local_trash_jobsentity_type、entity_id、purge_after（时间戳）、canceled_at
local_oplogop_id、entity_type、entity_id、op_type、payload_json、created_at、synced_at、retry_count
local_sync_stateremote_cursor（用于增量拉取）、last_pull_at、last_push_at
5.4 与当前 Supabase 表的映射（基于 supabase_local 现有表）
你当前 Supabase（public schema）已经有这些关键表：documents、media_assets、mindmap_meta/mindmap_nodes、rag_index_sources、lightrag_*、document_embeddings 等。
建议映射策略（第一阶段）：
- 本地
local_documents<-> 远端public.documents- 远端作为“同步与共享的汇聚层”，本地为“即时交互层”
- 本地
local_media_assets<-> 远端public.media_assets+storage.objects- 远端文件本体尽量走 Storage（签名 URL/直传），避免经 API 中转
- 思维导图：本地
local_mindmaps<-> 远端mindmap_meta/mindmap_nodes- 目前“思维导图删除后垃圾桶没有出现”，本质是缺少统一的
deleted_at与回收站视图 - 建议把 mindmap 也纳入统一软删体系（与 documents/media_assets 同标准）
- 目前“思维导图删除后垃圾桶没有出现”，本质是缺少统一的
6. 回收站 + 延迟删除（解决误删与垃圾堆积）
你提出的需求非常关键：误删后 Ctrl+Z 可恢复，所以“删文件”不应立即删 OCR/RAG 资源。
建议统一成两段式删除：
-
软删（立刻）：进入回收站
- 本地：移动到
.trash/（或打标deleted_at），UI 可见 - 服务端：对应记录打
deleted_at（不做物理删除）
- 本地：移动到
-
延迟清理（例如 10 分钟后）：后台任务执行硬删除
- 若用户在延迟窗口内恢复：取消清理任务
- 手动“清空垃圾桶”：触发立即清理（仍建议带二次确认）
注意：你现有的报错 rag_index_sources 外键约束，说明服务端“删除顺序/级联规则”需要统一：
- 设计层面建议：对 RAG 相关表引入
ON DELETE CASCADE或“先删子表再删父表”的硬规则 - 实现层面建议：垃圾桶清理走同一个
purge流程，确保顺序一致
基于你当前的约束信息：rag_index_sources_document_id_fkey 的 ON DELETE 是 NO ACTION（也就是不会级联删除），因此“清空垃圾桶”若直接删 documents 就必然触发外键错误。这里推荐两条修复路径（二选一）：
- 保留外键 NO ACTION：清理时严格按顺序删除子表（例如先删
rag_index_sources、再删documents） - 改为 ON DELETE CASCADE：允许删除
documents时自动清理rag_index_sources（更省心，但要确认不会误删共享/审计数据）
7. RAG/OCR（MinerU）在本地优先架构中的位置
你的期望是：客户端体验优先，OCR/RAG 可以后台慢慢做。因此推荐：
- 客户端只负责触发与展示结果（不在客户端跑 Docker）
- OCR/RAG 在“轻服务端”执行（可继续用你现有 Docker/服务）
7.1 触发策略（建议）
当本地文件发生变化（导入/更新）：
- 计算
content_hash（用于去重与增量） - 将任务写入本地队列（或远端队列）
- 后台上传文件到服务端（或 Supabase Storage）
- 服务端按文件类型处理：
- PDF/图片型 PDF：MinerU OCR -> 结构化文本
- docx/pptx/xlsx：提取文本（必要时转 pdf 再 OCR）
- 图片：OCR + 元数据
- 最终写入：标准化 chunk + embedding + 元数据（Supabase/pgvector）
7.2 Embedding 建议（中英混合 + 化学语料，尽量免费）
优先推荐“可自托管/本地跑”的 embedding（服务端跑即可）：
bge-m3：多语种通用表现稳定，适合中英混合multilingual-e5-large（或同系）：检索向 embedding 生态成熟- 你现有
Ollama方案里预拉的qwen3-embedding:8b：可作为可用基线（但模型较大，CPU 可能慢，建议服务端有 GPU 或更强 CPU）
第一阶段建议先选 1 个跑通“自动入库闭环”，再用你提供的化学书籍片段做小规模对比评测（Recall@k + 人工判读）。
7.3 任务编排建议（复用现有 Supabase 表）
你当前 Supabase 已有两张非常适合做“可观测后台任务”的表：
public.rag_index_sources：有status/attempts/last_error/source_updated_at/last_enqueued_at/last_processed_atpublic.background_tasks：有task_type/status/progress/message/updated_at
建议用法：
- 入库入口统一：任何“需要入库/重建索引”的源（documents/media_assets/mindmap/ocr_text）都落一条
rag_index_sources - 执行过程可视化：真正跑 OCR/切块/embedding/入库时，同步写
background_tasks（用于前端显示进度条/日志） - 幂等与去重：
- 用
source_updated_at+content_hash（可在 payload 里存）判断是否需要重跑 - 同一
source_id新任务到来时，若已有RUNNING则只更新last_enqueued_at，避免并发重复跑
- 用
7.4 OCR 决策（PDF 有文本 vs 图片型 PDF）
针对你提供的两类测试 PDF（“已 OCR 过含文本”与“图片型 PDF”），建议服务端在入库前做一个轻量判断：
- 先尝试“抽取文本”（例如每页抽样、统计可抽取字符数）
- 若字符数/覆盖率低于阈值，再走 MinerU OCR
- OCR 产物建议保留：
raw_text（纯文本，用于检索）layout（段落/页码/坐标等，用于引用定位与高亮）
这样可以避免对“本来就有文本层的 PDF”重复 OCR，节省大量时间。
7.5 LightRAG 版本对齐（你提到的 v1.4.9.10）
当前仓库内的 LightRAG 代码与其自带虚拟环境显示版本为 1.4.9.9（LightRAG/lightrag/__init__.py 与 LightRAG/.venv 一致）。
建议策略：
- 先稳：在“本地优先客户端”主线落地前，LightRAG 不做大范围升级，避免把变量叠加到体验问题上
- 再对齐：单独开一个“LightRAG 升级分支计划”（仅改 LightRAG 目录/服务启动脚本/兼容性），升级到你说的
v1.4.9.10后，用你提供的两份测试 PDF 跑一遍入库回归（含 OCR 分支）
8. 分阶段落地路线（建议按收益/难度）
P0（最小可用，立刻变丝滑）
- 明确“桌面端默认走本机”：
127.0.0.1/ 局域网 IP - 桌面端不经过 Cloudflare（Cloudflare 仅保留给“手机/外网”）
- 这一步不解决“安装依赖”，但先把“体验问题”排除在公网链路之外
P1（可分发 Win 客户端：无需 Docker）
目标：家人/同事拿到安装包即可用（最多只安装一次 VC 运行库/WebView2）。
- 引入桌面壳（Tauri 或 Electron）
- 把必要服务以“sidecar”方式随客户端分发并由壳统一拉起/关闭：
- Next 前端（建议 next standalone 输出 + 内置 Node）
- 后端 API（优先收敛成一个本地服务；Python 可先保留，后续再二进制化）
- 本地数据层落地：SQLite + 本地文件目录
P2（减少依赖与体积）
- Python 服务逐步二进制化（PyInstaller/Nuitka 或重写关键路径为 Rust/Go）
- 能迁到本地 API 的 Next
app/api/*逐步迁移，减少 Next server 负担
P3（多端）
- 安卓端继续用网页版（外网可用 VPN/IPv6/Cloudflare 其一）
- 桌面端与网页版共享同一套“同步协议/数据模型”，但桌面端以本地为主
9. 你需要做的关键取舍（我建议的默认值）
- OnlyOffice 的定位
- 如果你追求“打开速度极致”：Windows 客户端对 docx/xlsx/pptx 优先“用本机 Office/OnlyOffice Desktop 打开”，应用内只做预览/管理/版本
- OnlyOffice Document Server 保留给：手机端/外网网页端
- 服务端部署位置
- 若你有一台常开机器：把 Supabase/LightRAG/MinerU/Redis/OnlyOffice 放到 LAN 里，桌面端访问延迟会非常低
- 外网访问建议优先 VPN（你是小范围用户），避免 Cloudflare 造成的不可控绕路
10. 下一步我建议你先确认的 5 个问题（确认后我再给出更“可执行”的工程拆分）
- Windows 客户端你更偏好：
Tauri（小体积）还是Electron（生态成熟）？ - 你是否接受“第一阶段仍需要安装 Node/Python”，还是必须“一键安装无运行时依赖”？
- 你希望本地数据目录放哪：
%USERPROFILE%\\Documents\\MNOTE还是跟仓库同级？ - 多人同时编辑是否重要？（决定是否引入 Yjs 协作服务端/冲突策略）
- 你的“轻服务端”准备放在哪台机器（家用主机/NAS/云服务器）？
11. 你已确认的项目决策（已记录，后续按此推进）
你已明确选择：
- 桌面壳：
Electron - 依赖：可以安装任何东西，但希望“安装后即可启动客户端”（减少手工配置）
- 本地数据：放在安装目录（用户上传文件先落到该目录，再与远程 Supabase 同步）
- 协作：暂不做多人同时编辑
- 轻服务端：当前家用主机（先这样）
11.1 关键风险提醒：Windows 的“安装目录”通常不可写
如果你用的是常见的安装方式（MSI/NSIS 默认装到 C:\\Program Files\\...），Windows 会对普通用户进程启用 UAC/权限限制，安装目录默认不可写，会导致：
- 上传文件/本地数据库写入失败或变成“时好时坏”
- 需要管理员权限运行（体验差、也不安全）
你已进一步明确：标准安装，但安装位置必须可选且尽量不在 C 盘（数据会越来越大）。
这里的关键点不在“C 盘 vs 非 C 盘”，而在“是否安装在受保护目录（如 Program Files）”。即使装到 D:\\Program Files\\...，也可能同样不可写。
为满足“标准安装 + 数据放安装目录 + 不在 C 盘”，我建议按下面规则实现（作为默认方案）：
- 安装路径强约束：安装器允许用户自选安装目录，但禁止选择 C 盘，并且默认推荐路径形如
D:\\Apps\\MNOTE（而不是D:\\Program Files\\...）。 - 数据目录固定在安装目录内：例如
D:\\Apps\\MNOTE\\data（满足“数据跟安装目录走”）。 - 安装时设置 data 目录 ACL：安装器在安装阶段为
data目录授予当前用户（或 Users 组）可写权限，避免运行时写入失败。
如果你希望“强制必须装到非 C 盘”，这是可做的；但如果同事机器没有 D 盘，也需要允许选择 E/F 等其它盘符。
结论：你不需要做“绿色版”，也不需要把数据放到 userData；但必须在安装器层面把“安装目录可写”这件事做成默认成立。
12. Electron 客户端落地方案（不让客户端跑 Docker）
12.1 本地优先的最小形态（推荐作为第一阶段实现）
Electron 只做三件事：
- 提供 UI（窗口内渲染网页）
- 提供本地数据目录与 SQLite（零延迟读写）
- 后台做“同步/上传/触发服务端入库”（不阻塞 UI）
客户端不运行 Docker，也不强制在客户端跑 LightRAG / MinerU / Supabase。
12.2 与现有代码的衔接方式（尽量少改，先跑通）
第一阶段建议继续复用你现有的 HTTP 形态，但把链路从“公网 Cloudflare”改为“本机/局域网”：
- Electron 启动时拉起本机服务（作为 sidecar）：
wolai-frontend：Next production（本机127.0.0.1:3000）wolai-backend：FastAPI（本机127.0.0.1:8000）
- Electron 窗口直接打开
http://127.0.0.1:3000
这样 UI 完全不走公网，页面切换/打开文档会立刻变“本地速度”。
说明：你仓库根目录的
pnpm run desktop目前更像“开发者一键启动”；后续我们会新增专用的“Electron sidecar 启动器”，把端口探测、日志、崩溃重启、退出清理做成稳定产品级行为。
12.3 依赖与打包策略（让“安装后可启动”）
你允许安装任何东西，但希望安装后可启动。我建议用“两阶段”逐步降低门槛：
阶段 1（最快落地）
- 安装前置：Node、Python（以及必要的 VC 运行库、WebView2）
- Electron installer 在首次启动时做自检（缺什么就引导安装）
阶段 2（更像产品）
- 把后端打成单文件/少量文件的可执行程序（PyInstaller/Nuitka）
- 把前端打成 Next standalone（或更进一步变成静态 + 本地 API）
- Electron 安装包内置所有运行时（用户无需额外安装 Node/Python）
13. 轻服务端（家用主机）承担什么
鉴于你暂时不做多人实时协作，且优先“本地丝滑”，建议家用主机只承担：
- Supabase：鉴权 + 多端同步汇聚层 + Storage + pgvector
- ingest_service：监听/轮询需要入库的源（
rag_index_sources），做切块/embedding/入库 - MinerU：OCR 工作负载（图片/图片型 PDF）
- LightRAG：统一入库/检索（或作为 ingest_service 内部依赖）
- Redis：任务队列/限流（可选）
- OnlyOffice Document Server：主要给“网页/手机端”使用；Windows 客户端可优先走本机 Office/OnlyOffice Desktop 提升打开速度
14. 下一步里程碑（可直接开工的任务清单）
M0：确定安装与数据目录规则（必须先定）
- 标准安装（NSIS/MSI），允许用户选择安装路径
- 默认路径推荐
D:\\Apps\\MNOTE - 禁止安装到 C 盘（可配置为硬限制或安装器强提示）
- 数据目录固定为
$INSTDIR\\data并在安装时设置写权限
M1：Electron 外壳 + 本机服务启动（体验立竿见影）
- 新增
electron-app/（主进程 + 渲染进程） - 主进程实现：
- 启动前端（Next production）到
127.0.0.1:3000 - 启动后端（FastAPI）到
127.0.0.1:8000 - 进程托管：崩溃重启、退出清理、日志落盘（UTF-8）
- 启动前端（Next production）到
- 渲染进程直接加载
http://127.0.0.1:3000
M2：本地数据目录与 SQLite（真正 local-first）
- 选定数据根目录（绿色版：
./data；标准版：userData） - 引入 SQLite（文档/附件索引/oplog/回收站任务）
- 把“创建/删除/打开”的关键路径改为本地优先（网络失败也能操作）
M3：同步（最终一致）
- 本地
local_oplog推送到 Supabase - 从 Supabase 拉取增量变更，更新本地 SQLite
- 冲突先采用“生成冲突副本”的保守策略
M4：入库/OCR 后台化（不阻塞 UI）
- 客户端只负责：上传文件 + 写
rag_index_sources（或触发 API） - 家用主机跑 ingest_service/MinerU/LightRAG 完成入库
- 客户端订阅/轮询
background_tasks显示进度（可选）