在云服务主导的时代，files.md 选择了一条逆向路径：用 Go 构建一个本地优先的 Markdown 工作空间，让数据始终停留在用户设备。这个项目历经五年迭代，核心哲学可以概括为 ——"限制催生创造力"，通过刻意削减功能边界，实现真正的数据主权。
本地优先架构的核心设计
files.md 的架构围绕 "数据不离开设备" 这一原则展开。前端采用 PWA 形态，默认使用 OPFS（Origin Private File System）作为文件系统驱动，用户无需安装任何软件，仅需浏览器即可运行。这种设计将应用层与存储层彻底解耦：应用只是 Markdown 文件的 "查看器"，真正的数据以纯文本形式驻留在本地文件夹中。
技术实现上，项目刻意保持极简。前端无构建系统，直接打开 web/index.html 即可运行 —— 开发者希望 "十年后这个文件仍然能正常工作"。后端则是一个单 Go 二进制文件，负责同步服务和 Telegram Bot 功能。整个代码库的设计理念是 "一个人或一个 LLM 能够完全理解"，拒绝过度工程化。
四层隐私边界模型
files.md 提供了四种运行模式，形成清晰的隐私边界光谱：
最大隐私模式（Local-First）：数据完全驻留本地设备，不经过任何网络传输。适用于对隐私要求极高的场景，代价是无法跨设备同步。
云文件夹模式：利用 iCloud、Dropbox 或 Google Drive 等现有云存储进行文件同步。数据会经过第三方云服务，但应用本身不接触数据内容。这是平衡便利与隐私的折中方案。
自托管模式：用户在自己的服务器上运行 Go 二进制文件，通过私有网络实现设备间同步。部署流程极简 ——make init_server 和 make deploy_systemd 两条命令即可完成 systemd 服务配置。
托管模式：使用官方提供的 api.files.md 服务，适合希望立即体验的用户，但数据会经过第三方服务器。
这种分层设计让用户可以根据具体场景选择合适的安全级别，而非被迫接受 "全有或全无" 的隐私方案。
同步机制的技术实现
files.md 的同步策略体现了工程上的务实取舍。系统使用两种时间戳协同工作：mtime（修改时间）用于内容同步，ctime（元数据变更时间）用于追踪重命名和删除操作。
同步粒度达到微秒级，足以应对快速连续的文件操作。为避免并发冲突，系统采用按用户顺序处理更新的策略，配合细粒度锁（针对数据库、日志、用户配置分别加锁）而非全局锁，在保证一致性的同时避免阻塞第三方 API 调用（如 ChatGPT 集成）。
文件系统层面，项目限制为单层目录嵌套，文件名即标题，采用约定优于配置的策略。这种简化不仅降低了心智负担，也避免了跨平台文件名兼容性问题 —— 项目明确禁止在文件名中使用 : ? < > \ * " 等 Windows 不支持的字符。
存储与持久化策略
数据持久化采用纯 Markdown 文件形式，所有内容以人类可读的文本存储。这种设计带来几个关键优势：
可移植性：知识库可以在任何支持 Markdown 的平台上打开，不依赖特定软件。项目甚至提供 tomdlinks 工具将 WikiLinks 转换为标准 Markdown 链接，确保跨平台兼容。
版本控制友好：由于全是文本文件，可以直接使用 Git 进行版本管理。文档建议通过 crontab 配置每日自动 Git 提交，实现轻量级备份。
LLM 友好：项目提供 llms.txt 文件描述知识库结构，可直接粘贴到 Claude.md 或 AGENTS.md 中，让 AI 代理理解文件组织方式。
工程取舍与风险边界
files.md 的演进过程中做出了若干关键取舍。2025 年 9 月，项目移除了 WASM 实现 —— 虽然 WASM 允许复用 Go 代码，但带来了 JS 与 Go 之间的复杂异步调用链，且生成的 inbox.wasm 体积达 8MB，与项目追求的轻量目标相悖。最终相关功能被重写为纯 JavaScript 实现。
同样被移除的还有 WikiLinks 支持，项目坚持使用标准 Markdown 链接语法，确保知识库的长期可访问性。
当前实现的主要限制包括：浏览器存储配额限制 OPFS 的容量上限；跨设备同步需要额外配置；以及文件命名需遵守跨平台兼容规则。
可落地的部署参数
对于希望自托管的用户，关键配置参数如下：
- 部署环境：Debian-based 系统，需预先安装 Go
- 初始化命令：
make init_server host=user@example.com salt=$(head -c 32 /dev/urandom | base64) - 服务管理：systemd 托管，日志查看
sudo journalctl -u filesmd - 备份策略：Git 自动提交配置
0 0 * * * cd /app/storage/<USER_ID> && git add . && git commit -m "$(date +\%d.\%m.\%Y)" - 迁移流程：基于 mtime 的压缩传输，确保时间戳不丢失
files.md 的价值不仅在于提供了一个隐私优先的笔记工具，更在于它展示了如何在现代 Web 技术栈中实现真正的本地优先架构。通过清晰的隐私边界划分、极简的工程实现和对长期可维护性的坚持，这个项目为 "数据主权" 这一理念提供了可落地的技术方案。
参考来源
内容声明：本文无广告投放、无付费植入。
如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。