故障排查¶

汇集使用与开发过程中最常见的问题及排查思路。若未覆盖，欢迎通过 CONTRIBUTING.md 的渠道反馈。

使用类问题¶

客户端连不上服务端？¶

确认服务端已启动：curl http://<host>:8080/healthz 应返回 {"ok":true,...}。
确认「同步设置」里的地址与端口正确（跨设备用机器 IP 或域名，不要用 127.0.0.1）。
跨设备时确认防火墙放行端口。
Web 端跨域问题已由服务端 CORS 解决；若仍失败，检查反代是否透传。

剪藏扩展提示「登录已失效，请重新登录」/ 剪藏返回 401？¶

v0.12.2 起扩展用账号密码登录换取令牌（令牌存 chrome.storage.local，访问令牌 30 分钟、刷新令牌 30 天，过期自动单飞刷新）。出现该提示说明刷新令牌已过期或被吊销（如在其它端执行过「登出全部会话」）——在扩展设置页用账号密码重新登录一次即可。若升级前一直在用手填的长期 Token，本版需重新登录一次（旧令牌自 M10 起已失效）。

剪藏结果没有正文？¶

部分网页（如纯 JS 渲染的单页应用）正文在脚本执行后生成。可改用全页快照模式（浮层模式分段控件切换到「全页快照」），或先选中网页文字再右键剪藏。

剪藏提示「N 张图片未本地化」/ 图片加载不出来？¶

单图下载失败或超出限额的图片会降级保留其绝对外链，因此原站图片失效后这类图片无法显示。限额为单图 10 MiB、每篇 200 张、总时长 30s。可确认服务端能否访问外网、目标图片是否需要登录 / 防盗链；已本地化的图片则不受原站影响（存于附件库、正文以 sui:// 引用）。

两个设备都改了同一篇笔记，会丢内容吗？¶

不会。冲突自动合并，双方内容都会保留（冲突段落带标记分隔）。原理见系统架构 · 同步协议。

登录提示「登录尝试过于频繁，请 N 秒后重试」？¶

v0.12.2 起服务端内置登录失败防护（FR-59）：按「用户名 + 来源」统计连续失败，≥5 次起指数退避（1s → 2s → 4s…上限 30s），≥10 次锁定 15 分钟；锁定期内即使密码正确也会被拒。解锁方式（任一）：等待窗口到期；重启服务端（计数只驻内存，重启即清零）；或用 SUI_LOGIN_GUARD=0 启动以临时关闭防护。阈值可用 SUI_LOGIN_* 环境变量调整（见部署指南 · 登录失败防护）。

离线时某些附件打不开？¶

未缓存到本机的附件离线打不开（卡片显示「未下载」），联网后点击即可下载；离线时新添加的附件仍会挂到笔记上（卡片显示「待上传」），联网后自动补传。

本地磁盘被附件占满？¶

附件不会全部下载到每台设备，只有真正打开过的才缓存，且总量受「缓存上限」约束（默认 512MB，可在同步设置里调整）。超出上限时，最久未打开且没有被任何笔记引用的附件会被自动清理，再次打开会重新下载。详见系统架构 · 附件存储策略。

界面显示某些笔记是「仅本地」/ 换了服务端后数据没上来？¶

「仅本地」= 云端从来没有这个条目（不是「上传失败」，而是服务端根本没有它）。常见成因两种：

这台设备还没连过服务端：先在「同步设置」里连上，再跑一次「全部重新同步」。
换了服务端 / 换了数据目录，或服务端被重建、回滚：客户端会发现「云端已经不是原来那一份」，并弹出标题为「云端数据已更换 / 重建」的三选一对话框（用本地数据补齐到云端 / 以云端为准（不补齐）/ 取消）。在你做出选择之前，它不会上传、也不会清空任何一端的数据；选「以云端为准（不补齐）」时本机独有的数据不会被删除，只会降级为「仅本地」且不再自动上传。

处置步骤：先跑一次「全部重新同步」（桌面端菜单「同步 → 全部重新同步」，或「同步设置」对话框里的同名面板）；仍卡住的条目用它的「立即上传 / 重试」单项处理（只影响这一项），把鼠标停在状态图标上可看到具体失败原因。详见用户指南 §4。

开发类问题¶

`dart test` / `flutter test` 报 `Failed to load dynamic library 'libsqlite3.so'`¶

drift 在原生平台需要 libsqlite3 动态库。WSL / Linux 常见问题是只有 libsqlite3.so.0 而没有 libsqlite3.so 符号链接：

mkdir -p ~/.local/lib
ln -sf /usr/lib/x86_64-linux-gnu/libsqlite3.so.0 ~/.local/lib/libsqlite3.so
export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH

运行测试时确保该 LD_LIBRARY_PATH 生效。

Web 端数据不持久化（刷新即丢）¶

检查 clients/flutter_app/web/ 下是否存在 sqlite3.wasm 与 drift_worker.dart.js。缺失任一资源时，浏览器控制台会出现 drift worker / wasm 相关报错，数据库回退为内存实现。

验证是否落库：DevTools 中执行 indexedDB.databases()，应能看到名为 sui 的库。
重新生成方式见快速开始 §4.4。

`flutter build web` 报 `Dart library 'dart:ffi' is not available on this platform`¶

平台相关能力必须走条件导入（壳文件 + *_io.dart / *_web.dart），不能无条件 import 'dart:io' 或 package:drift/native.dart。检查新增代码是否破坏了这一分层，见系统架构 · 平台分层。

`flutter build linux` 停在 CMake / Ninja 报错¶

脚手架与平台配置已就位，缺的是宿主工具链：

sudo apt install -y clang ninja-build pkg-config libgtk-3-dev

典型报错：CMake was unable to find a build program corresponding to "Ninja" / CMAKE_CXX_COMPILER not set。Windows / macOS / iOS 需在对应宿主系统上构建。

找不到 `go` / `flutter` 命令¶

WSL（或其他环境）中工具链可能不在默认 PATH，需显式指定绝对路径，例如 Go 在 /home/aiuser/go-sdk/go/bin、Flutter 在 /home/aiuser/flutter/bin。

e2e 测试偶发「连接被拒」¶

测试起服务端后若用固定 sleep，机器繁忙时服务端尚未监听会假失败。当前 e2e 已改为轮询 GET /healthz 探活（100ms 一次，上限 20s）。若自建测试出现类似问题，同样改用探活。

修改了 drift schema 但代码没生效¶

drift schema 变更后必须重新生成代码：

cd clients/note_core
dart run build_runner build

桌面端启动后提示「数据目录不可用」？¶

说明引导指针 <应用支持目录>/storage.json 指向的数据目录当前不可访问（外置盘 / 网络盘未挂载、目录被移动或删除、权限不足）。应用会整屏阻断并给三个动作：

重试：挂载磁盘 / 修复权限后重试；
改回默认目录：在默认目录新建空库（不会删除原目录数据，稍后仍可手动指回）；
重新指定其他路径：直接指向数据实际所在目录。

三者都需要重启应用生效。排查时可查看 storage.json 里的 dataDir 是否为你期望的路径；该文件损坏会被视为「无指针」，此时应用会用默认目录并在界面提示数据位置，请勿在原目录之外随意写入数据，以免误判。

更改存储位置后没有生效 / 数据「看起来没变」？¶

迁移完成后必须重启应用才切换到新位置（连接仍指向旧目录直到重启）。若迁移失败，应用会继续使用旧位置并给出原因（权限 / 空间不足 / 校验不一致）；旧目录始终保留，不会被自动删除。