Obsidian 索引服务

此服务监控 Obsidian vault 目录，并将 Markdown 文件（元数据 和 完整内容）索引到 SQLite 数据库中。我最初构建它是为了与我的 mcp-server 项目一起使用，但后来切换到了使用 Obsidian 插件 API 的实现。我仍然认为它可以用作一个不可知的笔记索引器或同步工具（请参阅“未来步骤”下的说明），所以我把它放在这里。

功能

它跟踪 Obsidian vault 中的文件更改（创建、修改、删除），并将所有内容存储在 SQLite 中，可通过 Docker 卷访问。它捕获：

• 路径 (Path)：文件路径（唯一标识符）
• 标题 (Title)：来自文件名
• 父文件夹 (Parent Folders)：相对于 vault 根目录
• 标签 (Tags)：来自 YAML frontmatter
• 创建日期 (Created Date)：文件系统时间戳
• 修改日期 (Modified Date)：文件系统时间戳
• 内容 (Content)：笔记的完整文本
• 状态 (Status)：处理结果（成功/错误）
• 错误消息 (Error Message)：如果处理失败，则提供详细信息

设置和使用

前提条件

• Python 3.12 或更高版本
• Docker 和 Docker Compose（用于容器化使用）
• uv（可选，但推荐）

安装

1. 克隆仓库：

    git clone https://github.com/pmmvr/obsidian-index-service.git
    cd obsidian-index-service
   

2. 设置虚拟环境：

   • 使用 uv（推荐）：

     uv venv
     source .venv/bin/activate # Linux/macOS
     .venv\Scripts\activate # Windows
     

   • 使用 python（标准）：

     python -m venv .venv
     source .venv/bin/activate  # Linux/macOS
     .venv\Scripts\activate     # Windows
     

3. 安装依赖项：

   • 使用 uv（推荐）：

     uv sync  # 从 uv.lock 安装
     uv pip install pytest pytest-bdd pytest-mock  # 用于测试
     

   • 使用 pip：

     pip install -e .
     pip install pytest pytest-bdd pytest-mock  # 用于测试
     

本地运行

设置环境变量：

export OBSIDIAN_VAULT_PATH=/path/to/vault
export DB_PATH=/path/to/notes.sqlite

运行它：

python main.py

使用 uv：

uv run python main.py

对于一次性扫描：

python main.py --scan-only

或者使用 uv：

uv run python main.py --scan-only

命令行选项

• --vault-path：vault 目录的路径
• --db-path：SQLite 数据库的路径
• --scan-only：仅扫描而不监视

使用 Docker

1. 构建并运行：

   docker-compose up -d
   

2. 它挂载您的 vault 并公开 SQLite 数据库。

其他服务的只读访问

要让另一个服务读取数据库（例如，用于扫描更改）：

1. 在您的 docker-compose.yml 中使用与 obsidian-index-service 相同的卷：

   services:
     your-service:
       image: your-image
       volumes:
         - ${DB_VOLUME_PATH:-./data}:/data:ro  # 只读挂载
   

2. Obsidian Index Service 写入 /data/notes.sqlite（以读写方式挂载），而其他服务（例如 mcp-server）读取它。SQLite 的 WAL 模式处理并发访问。

工作原理

Obsidian 索引服务通过以下过程运行：

1. 启动 (ObsidianIndexService.__init__)

   • 从环境变量或命令行参数加载配置
   • 初始化数据库连接 (DatabaseConnection)
   • 设置笔记处理器 (NoteProcessor)
   • 建立信号处理程序以实现优雅关闭

2. 数据库初始化 (DatabaseConnection.__init__)

   • 创建/连接到 SQLite 数据库
   • 将数据库设置为 WAL（Write-Ahead Logging）模式，以获得更好的并发性
   • 如果 'notes' 表不存在，则创建该表，其中包含 path、title、tags 等列。

3. 初始 Vault 扫描 (NoteProcessor.scan_vault)

   • 在 vault 目录中查找所有 Markdown 文件 (*.md, *.markdown)
   • 对于每个文件，提取元数据
   • 将所有提取的元数据添加到数据库 (NoteOperations.insert_note)

4. 持续监控 (FileWatcher.watch)

   • 监视 vault 目录中的文件系统事件
   • 处理不同类型的事件：
     • 文件创建：索引新文件
     • 文件修改：更新已更改文件的索引
     • 文件删除：从索引中删除条目
     • 文件移动/重命名：更新路径信息

5. 文件处理 (NoteProcessor.process_note)

   • 从 Markdown 文件中提取元数据
   • 包括路径、标题、父文件夹、标签、创建/修改日期
   • 使用此信息更新数据库 (NoteOperations.upsert_note)

6. 优雅关闭 (ObsidianIndexService.shutdown)

   • 在接收到终止信号时，正确关闭文件监视器和数据库连接

该服务在后台运行，持续使 SQLite 数据库与 Obsidian vault 同步。然后，其他应用程序可以使用此数据库来访问笔记元数据，而无需直接解析 Markdown 文件。

开发

运行测试：

pytest

项目状态

• 已完成 (Done)：核心索引（元数据 + 内容）、Docker 设置、文件监视、数据库 CRUD。
• 下一步 (Next)：计划了一个 API，但改为使用插件方法。

未来步骤（同步工具潜力）

经过一些修改，我认为它可以作为一个同步工具：

• 远程后端 (Remote Backend)：添加对云存储（例如 Dropbox）或服务器的支持。
• 同步逻辑 (Sync Logic)：将本地更改（内容 + 元数据）推送到远程，拉取远程更新，处理冲突（例如，最后写入者获胜）。
• 数据库调整 (Database Tweaks)：添加 sync_status 和 remote_id 列。
• 文件监视器更新 (File Watcher Updates)：将更改排队以进行同步，而不仅仅是索引。
• CLI 选项 (CLI Option)：添加 --sync 以手动或持续触发它。
• 错误处理 (Error Handling)：在网络失败时重试，记录问题。