一个文件夹搭建个人笔记系统：数据自持、本地在线共用同一份Markdown

很多人折腾笔记软件，最后都会卡在同一道选择题上：本地应用数据在自己手里，但换设备、远程访问都麻烦；在线服务随时能记，但导出、迁移、控制权都打折。我现在的做法不太一样——整套笔记系统被我拆成了一个文件夹，本地打开就是笔记库，放到服务器上就变成可在线访问的系统。这个方案没有多复杂，但用久了才会意识到，它解决的不只是“记不记得住”的问题，而是“这份笔记到底属于谁”的问题。

真正让这个方案成立的，不是某个软件，而是把笔记从私有格式里解放出来。当笔记变成一组普通文件后，本地工具、在线服务、同步脚本、备份任务，都可以围绕同一个数据源运转。这几节会先讲清楚为什么数据形态才是核心，再给一套最小可用的搭建路径，最后聊清楚边界和最容易踩的坑。

1. 个人笔记系统的真正矛盾：不是工具不好，而是数据形态不合适

1.1 本地优先和在线优先都在让你做选择题

把市面上的笔记工具粗略分成两类，一类是本地优先，一类是在线优先，你会发现它们都有很明显的取舍。

本地优先的软件通常启动快、支持离线、数据存在自己机器上，隐私感强。但“本地”经常等于“本地私有数据库”。很多工具的笔记内容要么被打进一个库文件，要么分散在应用自己定义的目录里。你用了三个月之后想换工具，导出、转换、清洗每一步都可能丢格式、丢附件、丢内嵌链接。更常见的情况是，导出的 Markdown 里带了一堆该软件独有的特殊标记，换一个工具根本读不顺。

在线优先的软件体验确实顺滑：多端同步、实时保存、打开浏览器就能写。问题是数据在别人的服务器上，免费额度、平台条款、运营方向都可能变。等到某一天平台宣布调整存储策略、下线某个功能或者更新了收费模式，你才突然意识到，自己积累了两三年的知识库并不真正属于自己。

这个选择题看起来是在问“本地还是在线”，实际是在问“数据和应用绑不绑”。过去大家以为换工具就能解决，其实换工具只是从一个私有格式跳到另一个私有格式，问题始终没有消失。

1.2 “一个文件夹”的本质：让数据回到普通文件

把笔记系统做成一个文件夹，技术含义很简单：数据层不再依赖某个特定软件来解码。笔记主体是 Markdown 或纯文本，附件是图片、PDF、音频等标准格式，目录结构是用户可以读懂的约定。也就是说，任何能读取文件夹里文件的程序，都可以成为笔记软件。

这带来了几个直接好处：

• 数据可阅读：就算没有任何笔记软件，用系统自带的记事本也能看到内容。
• 数据可迁移：复制文件夹就是完整的迁移。
• 数据可组合：同一个文件夹能被桌面编辑器读取，能被 Git 做版本管理，能被同步工具传到另一台机器，也能被服务器上的 Web 应用挂载。
• 数据可替代：你今天用某个工具打开它，明天可以换成另一个也支持 Markdown 文件夹的工具，数据不受影响。

所以我说，“一个文件夹”不是部署形态上的取巧，而是把数据边界从应用手里拿了回来。所有上层设计都应该围绕这个边界展开：数据是唯一的事实来源，应用只是读取器。

2. 先理解运行逻辑：数据边界和应用分离

2.1 数据边界：文件夹作为单一事实来源

“单一事实来源”意思是：整个系统里只有一份权威笔记数据，路径固定、结构约定清楚，其他所有端都围绕它工作。本地编辑时直接读写这个文件夹，在线部署时，服务端要么挂载这个文件夹，要么从它构建出可访问页面。最忌讳的是“本地一套、在线一套”，两头都写，最后不知道哪份是最新的。

我建议按这个结构初始化目录：

text复制notes/
├── 00-inbox/
│   └── 2025-05-01-capture.md
├── 01-projects/
├── 02-areas/
├── 03-archive/
├── assets/
└── README.md

这个结构只是一个起点，不是标准答案。有几点原则可以参考：

• 文件名尽量等于标题，加上日期前缀可以让浏览列表时自动按时间排序。
• inbox 专门放临时念头，整理前不要管分类。
• 附件统一放 assets，避免散落到各个目录后找不到引用关系。
• archive 放已经结束的项目或旧内容，不要让主目录堆满历史包袱。

实际落地时，大多数人会高估分类的重要性，低估检索的重要性。文件夹层级越深，维护成本越高，越容易变成负资产。先用“收件箱 + 归档”两层结构跑起来，积累以后再调整，远比一开始就规划 20 个分类目录更可持续。

2.2 本地与在线为什么能共用同一套数据

因为数据是普通文件，访问层可以有多个：

• 桌面端打开同一个文件夹，用于日常阅读和编辑。
• 构建工具读取该文件夹，生成静态站点，上传到服务器。
• 服务器上的容器应用把宿主机目录映射成数据目录，在线访问时读写同一个文件夹。
• 移动端通过文件同步客户端把文件夹拉到本机，用支持 Markdown 的编辑器修改后，再同步回去。

所以本地和在线不再是两套系统，而是同一份数据的不同入口。对比常见的三种形态，差异很清楚：

这个表只是一个粗略特征，不是绝对结论。但它能解释一个关键现象：当你把数据从应用私有格式里拿出来，放到一个普通文件夹里，工具选择就变成了纯粹的性能和体验问题，不再涉及数据所有权问题。

3. 最小可行搭建：把一个文件夹变成笔记系统

3.1 初始化目录和版本控制

先用命令行创建一个目录骨架。以下命令在常见的 Linux 或 macOS 终端里可以直接用：

bash复制mkdir -p notes/{00-inbox,01-projects,02-areas,03-archive,assets}
cd notes
git init
echo "# Notes" > README.md

Git 不是这套方案的必需件，但强烈建议加上，因为文本笔记非常适合版本管理。你可以每天写完后提交一次，未来就能看到某段内容是什么时候被改的，改了什么。这个能力是多数商业笔记软件不会给你的。

如果是在 Windows 上，用鼠标新建文件夹也可以，只是后续版本管理命令要在 Git Bash 或 PowerShell 里运行。

3.2 本地编辑：选一个读文件夹、写 Markdown 的工具

不需要先选工具再建目录，顺序反过来更顺：先有文件夹，再选一个能“把文件夹当作库”的工具。以 Obsidian 为代表的本地优先工具就是这种思路，它把一个文件夹当作知识库。关键是记住一点：无论你用的是哪个编辑器，它都只是前端。你可以用插件、模板、双链，但不要依赖太多私有语法。

在我自己的实践里，会非常克制地使用插件和模板。很多花样写进文件以后，将来换工具就会变成乱码或特殊标记。让 Markdown 保持标准，才是长期可迁移的关键。比如下面这种内容就是标准 Markdown：

markdown复制# 2025-05-01 项目会议记录

- 确认了文件夹方案作为数据边界
- 下一步：搭建在线访问入口

这种文件在任何支持 Markdown 的工具里都能正常显示和编辑。

3.3 在线访问的方向一：静态站点发布

如果目标是“在任何设备上都能看笔记，但主要在本地写”，静态发布是最轻量、最不容易出问题的方案。

基本流程是：

1. 在 notes 目录里维护 Markdown 文件。
2. 用静态站点生成器读取这些 Markdown，生成纯 HTML。
3. 把生成产物传到服务器或对象存储，用 Nginx 托管。

以常见的 VitePress 为例，目录结构大致是这样：

text复制notes/
├── docs/          # 你的 Markdown 笔记
├── package.json   # 构建配置，示例结构
└── dist/          # 构建输出的静态文件

具体命令要以所用工具的文档为准，大致是：

bash复制npm install
npm run docs:build
rsync -avz dist/ user@server:/var/www/notes/

静态发布几乎不需要维护，也没有被攻击的入口，因为它只是一堆 HTML 文件。缺点是服务器端不能编辑笔记，只能展示。这正好匹配“主要本地写作，外网查看”的使用模式。

3.4 在线访问的方向二：容器化自托管笔记服务

如果希望在浏览器里也能编辑、也能新增笔记，可以用容器方式部署一个自托管笔记应用。具体选哪个开源项目，看你的偏好和活跃度。这里只讨论最关键的机制：把同一个文件夹挂载进容器。

一个简化的 docker-compose 结构长这样：

yaml复制services:
  notes:
    image: your-note-app:latest   # 示例镜像名，请替换为实际选择的开源项目
    container_name: notes
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./notes-data:/app/data

几乎所有容器化笔记应用都有三个需要注意的细节：

• 宿主机上的数据目录要提前创建，且路径要对，否则容器会把空目录当成数据源。
• 容器内部路径必须和应用配置一致。不同项目默认的数据目录不一样，有的叫 /app/data，有的叫 /data，还有的叫 /var/lib/notes。以该项目的文档为准。
• 不要用匿名卷存笔记数据。匿名卷在容器重建后特别容易变成孤儿数据，想找回来很麻烦。

3.5 本地和服务器之间的同步策略

在线访问确定之后，还要决定“谁可以写这份数据”。常见的做法有几种：

如果走静态发布路线，同步本质是“本地到服务器”的单向推送，本地就是权威，服务器只有构建产物。如果走容器自托管路线，就要明确服务器上的应用可不可以修改数据。可以修改，就存在双向同步的冲突风险；不可以修改，就把在线端定位成只读。

建议：先跑通一个方向，再考虑双向。很多人第一步就同时开两个编辑器，结果一个文件被两端反复覆盖，最后连哪份是最新的都分不清。从单主模式开始，至少能让你明确“哪一端是权威”。

4. 部署到在线环境：端口、权限、静态文件和容器

4.1 从本地到服务器的传输路径

静态发布的部署动作，本质上就是把构建产物从本目录传到服务器目录。在 Linux 服务器上，用 rsync 是最顺手的：

bash复制rsync -avz --delete dist/ user@server:/var/www/notes/

几个参数的含义可以简单理解：-a 保留权限和目录结构，-v 显示详情，-z 压缩传输，--delete 删除服务器上多余文件，使服务器目录和本地 dist 保持严格一致。这个命令适合每次发布时执行。

如果是 Windows 环境，用支持 SFTP 的图形客户端上传也可以。关键在于让服务器上的目录是构建产物的准确副本，不要手动一个文件一个文件地拖。

4.2 静态站点的 Nginx 托管

一个最简单的 Nginx 配置片段：

nginx复制server {
    listen 80;
    server_name notes.example.com;
    root /var/www/notes;
    index index.html;
}

只要生成器输出了 index.html，这个配置就能跑起来。如果只有服务器 IP，没有域名，也可以直接用 IP + 端口 访问，但长期使用还是建议配一个域名和 HTTPS 证书。至少内容在传输过程中需要加密。证书获取通常可以通过主流免费 CA 完成，具体以你的域名服务商和服务器环境为准。

4.3 容器化部署时最容易错的几个参数

容器化部署的调试成本比静态发布高，常见问题集中在四个地方：

• volume 路径：宿主机路径和容器路径必须对应。配置写错时，容器往往不会报错，但应用读取到的是空目录。
• 端口映射：8080:80 表示宿主机 8080 转发到容器 80。如果应用实际监听的是 3000，端口映射也要对应改成 8080:3000。
• 防火墙和安全组：容器端口通了，不代表外网能访问。云服务器通常还分服务器防火墙和安全组两层，两层都要放行。
• 文件权限：容器内运行的用户需要对挂载目录有读写权限。否则应用会提示“目录只读”或“无权限写入”。

不要把笔记数据放在容器的匿名卷里，也不要放在只属于容器内部的文件系统中。数据目录必须在宿主机上以文件夹形式存在，否则容器一重建，数据就可能找不回来。

5. 长期使用必须补的三件事：备份、同步、迁移

5.1 备份：服务器不是唯一副本

文件夹方案的天然优势是，备份一个文件夹就是备份全部笔记。但大多数人的问题是“知道要备份，但不会定期做”。所以与其建立一个复杂的备份系统，不如先套用那个老原则：3-2-1 备份。

对于纯文本笔记，整体打包通常只有几十到几百 MB。就算每天自动备份一次，成本也可以忽略。关键是先让备份流程跑起来。哪怕一开始只是在线编辑完手动打包一次，也比从不备份安全得多。

一个简单的打包命令：

bash复制cd ~
tar -czvf notes-backup-$(date +%Y%m%d).tar.gz notes/

然后把打包文件传到另一台机器或对象存储。

5.2 同步模式：单向发布和双向同步

静态发布天然是单向的，本地永远是编辑源头，服务器只是发布产物。这种模式下不需要解决冲突，因为服务器上的内容不重要，重新构建一次就能恢复。

双向同步适合“任何端都可编辑”的场景，但成本体现在冲突管理上。计划任务、实时监控进程、网络断开、手机锁屏、应用强退，任何一个环节出错，都可能让某个文件停留在旧版本。更现实的问题是，如果你在电脑上写了一篇文章，手机端看到的是没改过的版本，你会很难判断到底哪边是最新。

我建议的使用策略是：以本地为主，在线端主要做阅读和临时记录。临时记录统一先进 inbox，回到电脑后再整理。这样双向同步的冲突面会被压到很小。

5.3 迁移与换工具

文件夹方案最舒服的一点是，迁移成本低到几乎可以忽略：把整个目录复制到新机器，用新编辑器打开目录即可。但有一个容易被忽略的点：附件路径。

如果笔记里用相对路径引用 assets/xxx.png，目录整体迁移后依然有效。如果用了绝对路径，比如 C:/Users/xxx/notes/assets/xxx.png，只要换机器、换用户名，路径就失效。所以建议在笔记中始终使用相对路径，避免绝对路径。

另外一个大类别的问题是中文文件名和特殊字符。中文文件名在现代系统里基本没问题，但空格、#、%、& 这些特殊字符容易在 Web 路径或命令行里出问题。能避免就避免，实在要用空格，用连字符替代更省心。

我一般每隔半年会做一次恢复演练：把最近的备份包在另一个目录解压，然后用一个没装任何插件的编辑器打开，看看笔记是否能直接阅读和检索。这个演练看起来多余，但真到需要恢复数据的时候，能救你一次。

6. 这套方案的边界：适合谁，不适合谁

6.1 适合的场景

• 你希望长期拥有自己的笔记数据，不愿意被任何平台锁定。
• 你的笔记以文字为主，包含普通图片和 PDF 附件，不依赖复杂表格和在线协同编辑。
• 你愿意花一点时间掌握 Git、rsync 或 Docker 中的任意一到两样技能。
• 你主要的工作设备是电脑，手机只是一个阅读和临时记录终端。
• 你需要在一台自己的服务器上暴露在线访问入口，数据不出自己的可控范围。

6.2 不适合的场景

• 多人实时协作编辑同一篇文档，对格式冲突零容忍。文件级同步不适合这种协作强度，它缺少在线文档那种细粒度锁和实时合并能力。
• 你极度依赖移动端原生体验，希望从锁屏、语音、图片批量插入到离线推送都达到主流在线笔记的完成度。文件夹方案能实现一部分，但体验通常不如商业产品。
• 你完全不希望接触文件路径、目录结构、命令行、服务器这些概念。这套方案的前提就是用户能理解“数据在哪个目录”，如果这本身就是负担，方案就不合适。

6.3 什么时候该用回商业在线笔记

如果使用一段时间后，你发现自己花了太多时间维护服务器、处理同步冲突、折腾部署，却没有更多时间写笔记，那就应该停下来想想：文件夹自托管只是手段，笔记系统最终要服务于记录和回顾。如果商业在线笔记的搜索、移动端、同步体验明显更高，而且你并不在意数据所有权问题，那回到商业工具完全合理。

从这个角度说，文件夹方案的适用边界不在于技术难度，而在于你对数据所有权的需求有多强。愿意为它付出一些维护成本的人，才会觉得它值得。

7. 常见问题排查链路：从“看不到笔记”到“不同步”

7.1 线上看不到最新笔记

先看现象：是“页面最新内容没出现”，还是“某篇文章打不开”。然后按链路排查：

1. 确认本地笔记已经保存，文件内容确实是最新。
2. 确认构建产物已经更新，看 dist 里的 HTML 是否包含最新内容。
3. 确认服务器上的文件被替换了，rsync 完成后检查服务器目录的文件时间。
4. 确认 Web 服务没有缓存，强制刷新浏览器，或在 Nginx 里关闭静态缓存。

第 2 步失败，问题在构建命令；第 3 步失败，问题在传输；第 4 步失败，问题在缓存层。

7.2 文件同步冲突

现象是同一篇笔记在两个设备上被改成不同版本，同步后出现冲突副本或内容丢失。

排查顺序：

1. 先明确自己的同步模式是单向还是双向。
2. 查看同步工具的冲突副本文件，通常带冲突前缀或特殊后缀。
3. 手工合并差异，把权威版本放回主目录。
4. 后续避免在未同步状态下于多个端同时编辑同一篇长文。可以约定：手机临时写 inbox，不在手机上大改已有正文。

7.3 容器部署后无法访问

按下面顺序排查，不要一上来就怀疑 Nginx 或域名：

1. docker ps 看容器是否为 running 状态。
2. docker logs 容器名 看启动日志里有没有端口监听失败、路径错误或权限错误。
3. 在服务器本地用 curl http://localhost:8080 测试。能通说明容器正常；不能通说明容器内部或端口映射有问题。
4. 再检查服务器防火墙和安全组是否放行了该端口。
5. 最后查域名解析和 Nginx 配置。如果配置了域名，先 ping 域名看解析是否正常。

先拿 IP+端口验证最基本链路，再判断上层问题，通常比到处翻配置更快。

7.4 中文文件名、特殊字符和相对路径

迁移仓库或从 Windows 传到 Linux 时，文件名编码容易导致链接失效。我通常会做两件事：

• 批量扫描所有 Markdown 文件中的图片和附件引用，检查目标文件是否存在；
• 统一把引用改成相对路径，避免任何绝对路径。

如果发现某些文件因为特殊字符在 Web 服务里访问不到，直接把文件名改成安全的短名称。笔记系统里文件名只是标识，真正的检索靠搜索和标签，不需要在文件名里承载过多信息。

等这套系统真正跑起来，你会发现你不再纠结“该用哪款笔记软件”。你的笔记就是文件夹里的普通文件，软件只是读取器。数据在你手上，备份是文件复制，迁移是目录移动，在线部署只是给同一份数据加了一个访问入口。如果这套思路有可取之处，那就在于它把一个高频但长期的问题，简化成了一套可以替换、可以带走、可以独立判断的流程。建议从今天开始，先创建一个文件夹，把第一条笔记放进去。工具可以慢慢选，部署可以慢慢做，但数据边界先立起来，后面的一切都会顺得多。