PinSlip - 桌面小便签 - PinSlip 本地数据存储与备份

8. 数据存储

PinSlip 的核心理念：本地优先
这章讲你的便签到底存在哪里、是什么格式、怎么备份、怎么迁移**。

8.1 vault 目录在哪

默认位置

系统	路径
Windows	`C:\Users\<你>\Documents\PinSlip`
macOS	`~/Documents/PinSlip`
Linux	`~/Documents/PinSlip`

怎么改

首次启动时选定
之后在 设置 → 存储位置 → 更改位置 改

切换后会关掉所有便签窗口、重启服务、重新建索引，约几秒。

8.2 目录结构

你选的目录/
├── notes/              # 全部便签（.md，可分子文件夹）
├── inbox/              # 速记便签（扁平）
├── attachments/        # 图片附件（png/jpg/gif/webp）
├── .trash/             # 回收区
└── .pinslip/           # 运行时文件
    ├── settings.json   # 设置文件
    ├── pinslip.db      # 搜索索引数据文件
    ├── groups.json     # 便签组注册表
    ├── git-sync.json   # Git 同步配置（token 在此）
    ├── mcp.json        # MCP 发现文件
    └── .gitignore      # 排除 git-sync.json 等敏感文件

各目录用途

目录	用途
`notes/`	正式便签。可以自由建子文件夹分类。
`inbox/`	速记暂存区。扁平（无子文件夹）。手动移到 `notes/` 即脱离 inbox 身份。
`attachments/`	图片统一存放。白名单格式：png / jpg / gif / webp。
`.trash/`	回收区。删除的文件先到这里。
`.pinslip/`	运行时文件。建议备份时排除（含 token 等敏感信息）。

8.3 文件格式

每张便签是一个 .md 文件，YAML frontmatter + Markdown 正文：

---
tags: [work, ideas]
pin: true
color: yellow
collapsed: false
group: g-abc123
zoom: 1.0
created: 2026-07-30T14:00:00+08:00
updated: 2026-07-31T09:30:00+08:00
source: browser-extension
---

# 任务清单

- [ ] 写日报
- [ ] 给客户回邮件
- [ ] 整理本周 notes

frontmatter 字段

字段	类型	含义
`tags`	`string[]`	标签列表
`pin`	`boolean`	是否置顶
`color`	`string`	颜色（`yellow` / `pink` / `green` / `blue` / `purple` / `orange`）
`collapsed`	`boolean`	是否折叠
`group`	`string`	所属组 ID（无组则不写）
`zoom`	`number`	字号缩放（默认 100% 不写字段）
`source`	`string`	创建来源（`note` / `quick-capture` / `browser-extension` / `mcp`）
`created`	`string`	创建时间（ISO 8601）
`updated`	`string`	更新时间（ISO 8601）

文件命名

标题slug-创建日期yyyymmdd-id.md

例：my-idea-20260731-abcd1234.md
slug 清理非法字符 \/:*?"<>|，按 rune 截断 30 字符
标题变了 → 自动重命名文件
兼容旧的 <id>.md 命名

标题推导

当便签没显式标题时，PinSlip 取正文第一个有效行：

剥掉 markdown 结构标记（# / - / > / - [ ]）
剥掉行内包装（**bold** / __bold__ / ~~strike~~ / *italic* / _italic_ / `code`）
跳过整行链接 / 整行图片
跳过 git conflict markers
按 rune 截断 30 字符

服务端与渲染端算法同步，保证文件名一致。

8.4 图片路径

图片存到 attachments/，便签里写相对路径：

![png](attachments/screenshot.png)

当便签在 notes/ 根目录时，就这样直接写。

嵌套文件夹的相对路径

便签在 notes/work/project/ 时，路径加 ../：

![png](../attachments/screenshot.png)

PinSlip 帮你自动维护这个 ../ 前缀：

移动便签到不同深度的文件夹 → 服务端自动重写附件路径
这样 Obsidian / VS Code 打开同一目录时，图片也能正常显示

8.5 备份

怎么备份

整个 vault 目录直接复制即可。

你的 vault 就是一些 .md 文件 + 一堆图片，不依赖任何专有格式。

备份建议

全量备份：整个 vault 复制到外部硬盘 / 网盘
增量备份：推荐用 Git 同步（见 06-Sync），自动做版本控制
手动备份：CopyOnSave / Time Machine / Windows 文件历史记录

备份时建议排除 `.pinslip/`

含 token（git-sync.json）
含进程信息（mcp.json）
含索引（pinslip.db，启动会自动重建）
排除后重装时重新初始化即可（你不会丢失任何便签内容）

备份时一定要备份的

notes/（全部便签 + 标签 + 颜色 + 置顶）
inbox/（速记）
attachments/（图片）
groups.json（组顺序，可选；丢失只是组顺序变乱，便签还是按 frontmatter 找回）

8.6 迁移

迁移到新电脑

在新电脑装 PinSlip
复制 vault 目录（不含 .pinslip/）到新电脑
启动 PinSlip → 选新位置 → 等索引重建
用 Git 同步的话会更简单：填同一仓库 → 自动 clone 全部便签回来

迁移到不同文件夹

设置 → 存储位置 → 更改位置
选新目录后 PinSlip 会关掉所有便签窗口、重启 Go 服务、重新建索引
旧 vault 不会被自动删除（手动删除即可）

迁移到另一台电脑（用 Git）

详见 06-Sync → 多设备同步。

8.7 隐私

所有便签仅存在本机磁盘
PinSlip 不上传任何便签内容
MCP 服务和 Git 同步开启后才会有外部通信
关闭所有外部功能后，PinSlip 是个完全离线的本地应用

8.8 数据恢复

误删的便签

普通便签 / 组 / 文件夹 → 检查 .trash/
找不到 → 检查你的备份（Git 同步历史 / 备份副本）

索引坏了

删除 <vault>/.pinslip/pinslip.db
重启 PinSlip → 自动全量重建索引（便签内容不受影响）

整个 vault 损坏

从备份恢复整个 vault 目录
或重新从 Git 仓库 clone

8. PinSlip 本地数据存储与备份