294 lines
12 KiB
Markdown
294 lines
12 KiB
Markdown
# MNote control-plane Turso / libSQL 运行手册
|
||
|
||
> 状态：首轮 Rust control-plane cutover 手册。
|
||
> 范围：只覆盖 MNote Rust control-plane；本地 `.md`、附件、mindmap、OnlyOffice 文件仍是 local-first 文件真相，不迁入 Turso。
|
||
|
||
## 后端选择
|
||
|
||
```bash
|
||
# 默认本地 libSQL 运行时（无云依赖）
|
||
export MNOTE_CONTROL_PLANE_BACKEND=libsql-local
|
||
export MNOTE_TURSO_LOCAL_PATH=/mnt/Data1T/Mnote_data/control-plane/control-plane-libsql.db
|
||
|
||
# 真实 Turso remote
|
||
export MNOTE_CONTROL_PLANE_BACKEND=turso-remote
|
||
export MNOTE_TURSO_DATABASE_URL=libsql://...
|
||
export MNOTE_TURSO_AUTH_TOKEN=...
|
||
|
||
# Turso local replica
|
||
export MNOTE_CONTROL_PLANE_BACKEND=turso-local-replica
|
||
export MNOTE_TURSO_LOCAL_REPLICA_PATH=/mnt/Data1T/Mnote_data/control-plane/control-plane-replica.db
|
||
export MNOTE_TURSO_DATABASE_URL=libsql://...
|
||
export MNOTE_TURSO_AUTH_TOKEN=...
|
||
|
||
# libSQL synced database
|
||
export MNOTE_CONTROL_PLANE_BACKEND=turso-synced
|
||
export MNOTE_TURSO_SYNCED_PATH=/mnt/Data1T/Mnote_data/control-plane/control-plane-synced.db
|
||
export MNOTE_TURSO_DATABASE_URL=libsql://...
|
||
export MNOTE_TURSO_AUTH_TOKEN=...
|
||
```
|
||
|
||
|
||
# Sync interval for turso-local-replica / turso-synced
|
||
export MNOTE_TURSO_SYNC_INTERVAL_MS=5000
|
||
## 当前决策边界
|
||
|
||
2026-07-03 已配置真实 Turso dev DB/token，但当前不把 Turso Cloud 作为 MNote 本地功能测试的前置条件，也不把它当成本地文件网盘。
|
||
|
||
- 本地 `.md`、附件、mindmap、OnlyOffice 文件仍是 local-first 文件真相，不迁入 Turso。
|
||
- Turso 只承接 Rust control-plane 元数据：auth、session、workspace、grant、AI policy/runtime、audit/outbox 等。
|
||
- `dev-hot`、`mnote-web-hot`、prod runtime 默认使用 `libsql-local`；`sqlite` 不再是 mnote-web 运行时后端。
|
||
- `turso-remote` / `turso-local-replica` / `turso-synced` 只作为 dev DB dry-run、迁移演练、回滚演练和后续受保护 smoke。
|
||
- remote 成为长期候选默认前，必须先完成 Argon2id password hash migration、remote smoke、rollback export 和 token 轮换策略。
|
||
|
||
## 本机私有 Turso env
|
||
|
||
真实 URL/token 不写入仓库。当前本机私有配置文件：
|
||
|
||
```bash
|
||
/mnt/Data1T/Mnote_data/control-plane/turso.env
|
||
```
|
||
|
||
要求：
|
||
|
||
- 文件权限必须是 `0600`。
|
||
- 只在本机 shell 中 `source`，不要复制到设计文档、日志、issue、截图或 commit。
|
||
- repo 内不得出现 JWT 明文、`MNOTE_TURSO_AUTH_TOKEN=<jwt>` 或带 token 的 libSQL URL。
|
||
- `tmp/turso.md` 仅作为本机临时凭据来源，已被 `tmp/` ignore，不纳入版本管理。
|
||
|
||
加载方式：
|
||
|
||
```bash
|
||
set -a
|
||
source /mnt/Data1T/Mnote_data/control-plane/turso.env
|
||
set +a
|
||
```
|
||
|
||
确认不打印 token：
|
||
|
||
```bash
|
||
printf 'backend=%s\n' "$MNOTE_CONTROL_PLANE_BACKEND"
|
||
printf 'url_host=%s\n' "$(printf '%s' "$MNOTE_TURSO_DATABASE_URL" | sed -E 's#^libsql://([^/]+).*#\1#')"
|
||
test -n "$MNOTE_TURSO_AUTH_TOKEN" && echo 'token_present=yes'
|
||
```
|
||
|
||
## 初始化
|
||
|
||
```bash
|
||
cargo run --manifest-path rust/Cargo.toml -p control-plane --bin control-plane-admin -- \
|
||
init \
|
||
--backend "$MNOTE_CONTROL_PLANE_BACKEND"
|
||
```
|
||
|
||
默认会创建测试账号：
|
||
|
||
- 邮箱：`mnote.e2e@example.com`
|
||
- 用户名：`mnote-e2e`
|
||
- 默认 workspace、directory grant、AI policy、UI preference、audit/outbox 初始化记录
|
||
|
||
可先 dry-run：
|
||
|
||
```bash
|
||
cargo run --manifest-path rust/Cargo.toml -p control-plane --bin control-plane-admin -- \
|
||
init \
|
||
--backend "$MNOTE_CONTROL_PLANE_BACKEND" \
|
||
--dry-run
|
||
```
|
||
|
||
## SQLite 到 libSQL / Turso 迁移
|
||
|
||
```bash
|
||
cargo run --manifest-path rust/Cargo.toml -p control-plane --bin control-plane-admin -- \
|
||
migrate-sqlite-to-target \
|
||
--source /mnt/Data1T/Mnote_data/control-plane/control-plane.db \
|
||
--backend "$MNOTE_CONTROL_PLANE_BACKEND" \
|
||
--dry-run
|
||
|
||
cargo run --manifest-path rust/Cargo.toml -p control-plane --bin control-plane-admin -- \
|
||
migrate-sqlite-to-target \
|
||
--source /mnt/Data1T/Mnote_data/control-plane/control-plane.db \
|
||
--backend "$MNOTE_CONTROL_PLANE_BACKEND" \
|
||
--reset-target
|
||
```
|
||
|
||
## 导出到 SQLite 备份
|
||
|
||
SQLite 仅作为 control-plane-admin 迁移 / 导出格式和测试隔离实现，不再作为 mnote-web runtime fallback。需要离线备份时执行：
|
||
|
||
```bash
|
||
cargo run --manifest-path rust/Cargo.toml -p control-plane --bin control-plane-admin -- \
|
||
export-target-to-sqlite \
|
||
--backend "$MNOTE_CONTROL_PLANE_BACKEND" \
|
||
--output /mnt/Data1T/Mnote_data/control-plane/control-plane.backup.sqlite \
|
||
--backup-existing
|
||
```
|
||
|
||
备份文件仅用于审计、对照和后续手工恢复，不作为 `npm run dev:hot` / `npm run dev:hot` 启动后端。
|
||
|
||
## 验证命令
|
||
|
||
```bash
|
||
cargo check --manifest-path rust/Cargo.toml -p mnote-web
|
||
cargo test --manifest-path rust/Cargo.toml -p control-plane
|
||
cargo test --manifest-path rust/Cargo.toml -p control-plane --features turso-unit-tests -- --test-threads=1
|
||
cargo test --manifest-path rust/Cargo.toml -p mnote-web app_state_initializes_control_plane_store_for_tests
|
||
cargo test --manifest-path rust/Cargo.toml -p mnote-web dev_seed -- --test-threads=1
|
||
cargo test --manifest-path rust/Cargo.toml -p mnote-web local_folder_watcher -- --test-threads=1
|
||
node --test scripts/mnote-web-hot.test.js
|
||
node scripts/task-dev-hot-plan-test.js
|
||
node scripts/task-control-plane-admin-libsql-roundtrip-smoke.js
|
||
codegraph sync .
|
||
```
|
||
|
||
脚本审计：
|
||
|
||
```bash
|
||
rg -n "sqlite3|better-sqlite3|node:sqlite|MNOTE_CONTROL_PLANE_DB_PATH|control-plane\\.(sqlite|db)" scripts rust/crates \
|
||
-g '!target' -g '!node_modules' -g '!recycle'
|
||
```
|
||
|
||
允许命中范围：
|
||
|
||
- `control-plane-admin` CLI
|
||
- `control-plane-admin` 的 SQLite 迁移 / 导出参数
|
||
- `scripts/lib/control-plane-test-env.js` 的显式测试后端参数
|
||
- `mnote-web-hot` / `dev-hot` / `prod-build-start` 对 `sqlite` runtime 的拒绝逻辑
|
||
- legacy `evidence.sqlite` / local search 测试边界
|
||
|
||
不允许命中范围：
|
||
|
||
- smoke 脚本直接调用 `sqlite3` CLI 写 control-plane DB
|
||
- Node 脚本用 SQLite 库写生产 control-plane DB
|
||
|
||
## 故障边界
|
||
|
||
- 缺 URL/token：应返回 `InvalidInput` 或启动时报清晰错误，不允许 panic。
|
||
- 本地 libSQL path 不可写：应返回 storage error，不允许 panic。
|
||
- remote 网络不可达、5xx、限流、replica 同步失败：属于后续云端同步/备份链路验收，必须在真实 Turso dev DB 配好后补注入测试。
|
||
- 真实 remote / replica / synced 未验证前，本地功能测试优先使用 `libsql-local`；不再回落到 SQLite runtime。
|
||
|
||
## Turso dev DB 后续云端验证项
|
||
|
||
remote / local-replica / synced 更接近云端同步、备份和多设备准备层；它们不影响当前 local-first 本地功能测试。真实 Turso 验证需要：
|
||
|
||
```bash
|
||
export MNOTE_TURSO_DATABASE_URL=libsql://...
|
||
export MNOTE_TURSO_AUTH_TOKEN=...
|
||
```
|
||
|
||
然后执行：
|
||
|
||
```bash
|
||
set -a
|
||
source /mnt/Data1T/Mnote_data/control-plane/turso.env
|
||
set +a
|
||
|
||
MNOTE_CONTROL_PLANE_BACKEND=turso-remote \
|
||
cargo run --manifest-path rust/Cargo.toml -p control-plane --bin control-plane-admin -- init --backend turso-remote
|
||
|
||
MNOTE_CONTROL_PLANE_BACKEND=turso-remote \
|
||
cargo run --manifest-path rust/Cargo.toml -p control-plane --bin control-plane-admin -- \
|
||
migrate-sqlite-to-target \
|
||
--source /mnt/Data1T/Mnote_data/control-plane/control-plane.db \
|
||
--backend turso-remote \
|
||
--dry-run
|
||
```
|
||
|
||
当前已完成的非破坏性 remote dry-run：
|
||
|
||
```bash
|
||
set -a
|
||
source /mnt/Data1T/Mnote_data/control-plane/turso.env
|
||
set +a
|
||
|
||
cargo run --manifest-path rust/Cargo.toml -q -p control-plane --bin control-plane-admin -- \
|
||
init --backend turso-remote --dry-run
|
||
|
||
cargo run --manifest-path rust/Cargo.toml -q -p control-plane --bin control-plane-admin -- \
|
||
migrate-sqlite-to-target \
|
||
--source /mnt/Data1T/Mnote_data/control-plane/control-plane.db \
|
||
--backend turso-remote \
|
||
--dry-run
|
||
```
|
||
|
||
2026-07-03 结果：
|
||
|
||
- `init --backend turso-remote --dry-run` 返回 `ok=true`。
|
||
- `migrate-sqlite-to-target --backend turso-remote --dry-run` 返回 `ok=true`，并成功读取本地 SQLite 源库表计数，`targetBackend=TursoRemote`。
|
||
- 这只证明 URL/token 和 admin CLI 配置可用，不代表 remote 已成为默认后端。
|
||
|
||
通过后再进入 remote / replica 默认切换；不要把 OpenHub SQLite 和 Rust control-plane 首轮本地 cutover 绑死。
|
||
|
||
## 后续优化 checklist
|
||
|
||
- [x] 增加 `MNOTE_TURSO_SYNC_INTERVAL_MS`，让 remote replica / synced 同步间隔可配置。
|
||
- [ ] remote replica 启动后做 explicit initial sync，并验证 `read_your_writes` 行为。
|
||
- [ ] 新增 control-plane health endpoint，仅暴露 backend/mode/schema/sync 状态，不暴露 token。
|
||
- [ ] Argon2id password migration 完成前，不把 remote Turso 作为长期默认。
|
||
- [ ] secret-gated `turso-dev` store contract smoke：init、migration、session、grant、audit/outbox、export rollback。
|
||
- [ ] browser QA 覆盖 `turso-remote` 和 `turso-local-replica`，但失败不阻塞本地 `libsql-local` smoke。
|
||
|
||
## P0 / P1 / P2 状态
|
||
|
||
当前已完成的是 local cutover 和安全基线，不是所有 Turso 优势都已经落地：
|
||
|
||
- P0 已完成：唯一写入口、脚本直写清退、`libsql-local` store、migration、admin roundtrip、browser QA、local 多线程并发防损坏测试、remote dry-run 凭据验证、`MNOTE_TURSO_SYNC_INTERVAL_MS`。
|
||
- P0 未完成：explicit initial sync、control-plane health endpoint、Argon2id password migration。
|
||
- P1 未完成：读写并发性能优化。当前 `TursoControlPlaneStore` 仍是单 `Mutex<TursoConnection>`，读写都串行；这是故意保守的安全基线，不是最终性能设计。
|
||
- P2/P3 暂缓：CDC、Tantivy FTS、vector/hybrid search、Browser WASM/OPFS、OpenHub SQLite 迁移。
|
||
|
||
## 读写并发设计
|
||
|
||
当前实现优先保证一致性和可回滚：
|
||
|
||
- 单进程内通过 `Mutex<TursoConnection>` 串行化 control-plane 操作。
|
||
- 脚本和 smoke 不再直接写生产 control-plane DB，降低多进程直写损坏风险。
|
||
- local 多线程测试已覆盖 session、sidebar shortcut、AI runtime event、audit/outbox 并发写。
|
||
|
||
后续性能优化需要单独实施：
|
||
|
||
- 写入路径保持单写者或独占写锁；多表写入必须显式事务。
|
||
- 读路径可以评估 read connection pool 或 `RwLock`，但必须先按 store 方法分类只读/写入，并跑压力测试。
|
||
- remote replica 只适合本地读副本；写仍转发 remote primary，不把 embedded replica 当成高并发本地写主路径。
|
||
- 在同步 trait 未改 async 前，不扩大 `block_in_place` 使用面。
|
||
|
||
## CDC / Tantivy 评估
|
||
|
||
CDC 当前不进入默认路线：
|
||
|
||
- Turso CDC 通过 `PRAGMA capture_data_changes_conn(...)` 把变更写入 CDC 表，按连接开启，尊重事务边界。
|
||
- CDC 可以用于后续审计归档、外部消息桥接、实时分析或同步 spike。
|
||
- MNote control-plane 当前已有 `audit_log` 和 `outbox_events`，这些记录业务语义，比通用表级 CDC 更适合当前主链。
|
||
- CDC 可能捕获敏感字段，启用前必须定义脱敏、保留期、权限和导出边界。
|
||
|
||
Tantivy FTS 当前不进入 control-plane：
|
||
|
||
- Turso FTS 是 `CREATE INDEX ... USING fts` + `fts_match` / `fts_score` / `fts_highlight`，不是 SQLite FTS5 的无成本替换。
|
||
- 当前 control-plane 只存轻量元数据，全文搜索收益有限。
|
||
- 页面正文、知识库和 RAG 仍走 local-first 文件 / OpenHub / LightRAG，不迁入 Turso control-plane。
|
||
- 后续如需搜索页面标题、路径、AI 会话标题或轻量摘要，可单独做 P2/P3 spike。
|
||
|
||
Browser WASM / OPFS 当前不进入主线：
|
||
|
||
- 它适合纯浏览器 / PWA 离线 SQL 存储，但当前 MNote 主路径是本地文件夹 + Rust mnote-web + watcher。
|
||
- 浏览器 OPFS 不能替代本地 `.md`、附件、mindmap、OnlyOffice 文件真相，否则会制造第三份正文真相。
|
||
- 浏览器内数据库也不能作为 auth、grant、AI policy 的权限真源；这些仍必须由 Rust control-plane 校验。
|
||
- 后续可作为 P3 spike：只存可重建 cache、草稿、最近访问索引或纯 Web 离线收集箱，不存不可恢复正文唯一副本和长期 secret。
|
||
|
||
## 密钥泄露检查
|
||
|
||
```bash
|
||
rg -n "eyJhbGciOi|MNOTE_TURSO_AUTH_TOKEN=.*ey|authToken=.*ey|mnote-liaibo\.aws-ap-northeast-1\.turso\.io" . \
|
||
-g '!target/**' \
|
||
-g '!node_modules/**' \
|
||
-g '!recycle/**' \
|
||
-g '!*.db' \
|
||
-g '!*.sqlite' \
|
||
-g '!*.sqlite3' \
|
||
-g '!*.png' \
|
||
-g '!*.jpg' \
|
||
-g '!*.jpeg'
|
||
```
|
||
|
||
允许结果：无输出；或者只命中文档中不含 token 的 host 示例。任何 JWT 明文命中都必须立即移出仓库路径并轮换 token。
|