Files.md 详细部署与使用教程

Files.md 是一款极简、本地优先的笔记与知识管理应用，专为以 Markdown (.md) 文件为核心的工作流设计。它强调数据所有权、离线可用和低认知负荷，整个应用的核心就是你的本地文件夹中的纯文本文件。

本文将介绍该项目的几种主要使用方式，从最便捷的云端体验开始，到完全自托管的服务器部署。

一、核心概念与准备工作

在使用前，请先理解 Files.md 的几个核心设计理念：

本地优先 (Local-first)：你的所有数据（笔记、日记、任务等）都以 .md 文件形式存在，默认只保存在你的设备上，不经过任何服务器。
极致简单：它不是一个需要复杂构建的 IDE 或 Electron 应用，核心就是一个在浏览器中打开的 index.html 文件。
文件即数据：目录结构就是你的知识分类。例如，brain/ 文件夹放笔记，journal/ 文件夹放日记，Chat.md 文件是快速输入的中转站。

准备工作：

一个现代浏览器：推荐 Chromium 内核的浏览器（如 Chrome、Edge、Brave），因为它们对 File System API 支持最好，这是应用读写本地文件夹的关键。
一个用于存放数据的文件夹：在你的电脑上新建一个空文件夹，它将作为你的知识库根目录。

二、方式一：使用在线版或安装为 PWA (最快捷)

这是最快捷、零门槛的方式，适合初次体验。

访问网站：在浏览器中打开 app.files.md。
打开本地文件夹：页面会提示你“打开一个本地文件夹”。点击按钮，选择你在准备工作中创建的那个空文件夹。请放心，应用只会读取和写入这个文件夹，不会访问其他位置。
授予权限：浏览器会询问是否允许该站点访问此文件夹，选择“允许”或“选择文件夹”。
开始使用：你现在就可以创建 .md 文件，或通过聊天框 (Cmd+Enter) 快速记录想法了。所有更改都会直接保存到你选中的本地文件夹中。

进阶：安装为 PWA（渐进式 Web 应用）
为了获得类似原生应用的体验，可以在浏览器地址栏右侧点击“安装”图标（通常是一个向下箭头或“+”号），将 Files.md 安装到你的桌面或开始菜单，方便离线使用。

三、方式二：使用云文件夹同步 (无服务器，多设备)

如果你不想自己维护服务器，但希望在多台电脑间同步数据，可以利用现有的云盘服务。

设置云端同步文件夹：在你的电脑上，使用 iCloud Drive、Dropbox 或 Google Drive 等客户端，创建一个专门用于同步的文件夹，并确保它已同步到云端。
使用 Files.md 打开该文件夹：按照“方式一”，在每台设备上通过 app.files.md 打开同一个云端文件夹。
数据同步：你的数据会通过云盘服务在设备间同步。你在电脑 A 上写的笔记，在电脑 B 上打开同一个云端文件夹后就能看到。

四、方式三：部署自己的同步服务器 (完全自托管)

这是实现完全自托管、数据不经过任何第三方的方案。你需要部署一个用 Go 语言编写的轻量级服务器。

部署步骤

第一步：获取服务器程序

从源码编译 (推荐)：
1. 确保服务器已安装 Go 语言环境 (1.21 版本以上)。
2. 克隆仓库并编译：
  1
  2
  3
  git clone https://github.com/zakirullin/files.md.git
  cd files.md
  go build -o filesmd-server ./cmd/server
3. 这将生成一个名为 filesmd-server 的可执行文件 (Windows 下为 filesmd-server.exe)。
或直接下载：你也可以关注项目的 GitHub Releases 页面，看是否提供预编译的二进制文件。

第二步：运行服务器
在终端中，直接运行编译好的二进制文件即可。它默认监听 8080 端口。

1	./filesmd-server

你可以通过 --port 参数自定义端口，例如 ./filesmd-server --port 9090。

第三步：配置客户端连接

在浏览器中打开 app.files.md。
点击界面中的“设置”或“同步”选项，找到服务器地址配置项。
填入你部署的服务器地址和端口，例如 http://你的服务器IP:8080。
应用将尝试连接。首次连接可能需要你通过浏览器或配置文件完成简单的设备配对和身份验证（具体流程参考后续的官方文档）。

第四步：使用 Docker 部署 (备选)
项目根目录提供了 compose.yaml (Docker Compose) 文件，可以更方便地使用 Docker 运行。

1 2	# 在项目目录下运行 docker-compose up -d

之后客户端同样配置连接到此 Docker 容器的地址和端口即可。

五、使用技巧与核心功能

无论你选择哪种方式，Files.md 的核心交互都围绕“聊天框”和“文件”展开。

记录一切 (聊天框)Cmd+Enter：这是应用的默认入口。按下快捷键，会弹出一个输入框。你可以像发消息一样快速输入任何内容（笔记、任务、想法），按下回车，它就会被保存到根目录的 Chat.md 文件中。这一设计是为了让你在阅读或思考时不被中断。
整理与链接：
- 以后你可以打开 Chat.md，将内容块剪切并移动到对应主题的 .md 文件中（如 brain/ 文件夹）。
- 输入 [ 可以快速搜索并插入指向其他笔记的链接 [链接文字](目标文件路径.md)，构建你的知识网络。
特殊用途文件：
- 日记：输入内容后，在聊天框中输入 jj 或点击“To Journal”，内容会自动存入 journal/YYYY.MM Month.md 文件。
- 任务：输入任务内容后，输入 later 或点击“To Later”，将其存入 Later.md 作为待办清单。
探索更多：项目还提供了 Telegram 聊天机器人 接口，方便你通过手机即时记录；以及用于处理时间戳、添加反向链接等的实用命令行脚本（位于 cmd/ 目录），具体用法可查阅项目文档。

六、进阶与故障排除

数据完全本地化：无需任何服务器，直接打开 web/index.html 文件即可使用 (需通过本地服务器，或现代浏览器的文件访问)。
性能：项目作者明确表示，由于现代操作系统和硬件的速度，使用文件系统作为数据库在性能上完全可行。
备份：你的所有数据就是那个文件夹。请确保定期备份该文件夹即可。
遇到问题：
- 确认你的浏览器：对 File System API 支持不完善的浏览器（如 Firefox、Safari 旧版）可能导致无法打开文件夹，请使用基于 Chromium 的浏览器。
- 查阅文档：项目在 docs/ 目录下有更详细的部署、聊天机器人和同步流程说明。
- 提交 Issue：可以在 GitHub Issues 页面反馈问题。

Files.md 的精髓在于“少即是多”。它不试图用复杂的功能和模板来替你做思考，而是提供一个极简、开放、私密的空间，让你自由地记录、连接和思考。

Files.md 详细部署与使用教程

一、 核心概念与准备工作

二、 方式一：使用在线版或安装为 PWA (最快捷)

三、 方式二：使用云文件夹同步 (无服务器，多设备)

四、 方式三：部署自己的同步服务器 (完全自托管)