Obsidian索引服务

黑曜石指数服务

此服务监视黑曜石保管库目录并为Markdown文件（元数据）建立索引 和 完整内容——存入SQLite数据库。我建造它是为了与我的 mcp-server 项目，但切换到使用Obsidian插件API的实现。我仍然认为这是一个不可知的注释索引器或同步工具（见“未来步骤”下的注释），所以我把它放在这里。

功能

它跟踪黑曜石保管库中的文件更改（创建、修改、删除），并将所有内容存储在SQLite中，可通过Docker卷访问。它捕捉到：

• 路径：文件路径（唯一标识符）
• 标题：来自文件名
• 父文件夹：相对于vault根
• 标签：来自YAML frontmatter
• 创建日期：文件系统时间戳
• 修改日期：文件系统时间戳
• 内容：说明全文
• 状态：处理结果（成功/错误）
• 错误消息：处理失败的详细信息

设置和使用

先决条件

• 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  # Installs from uv.lock
     uv pip install pytest pytest-bdd pytest-mock  # For tests
     

   • 随着 pip:
     复制

     pip install -e .
     pip install pytest pytest-bdd pytest-mock  # For tests
     

本地运行

设置环境变量：

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. 使用与相同的音量 obsidian-index-service 在你的 docker-compose.yml:
   复制

   services:
     your-service:
       image: your-image
       volumes:
         - ${DB_VOLUME_PATH:-./data}:/data:ro  # Read-only mount
   

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

运作原理

黑曜石索引服务通过以下流程运行：

1. 初创公司 (ObsidianIndexService.__init__)

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

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

   • 创建/连接到SQLite数据库
   • 在WAL（预写日志）模式下设置数据库，以获得更好的并发性
   • 如果不存在带有路径、标题、标签等列的“注释”表，则创建该表。

3. 初始保险库扫描 (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数据库与黑曜石数据库同步。其他应用程序可以使用此数据库访问笔记元数据，而无需直接解析Markdown文件。

发展

运行测试：

pytest

项目状态

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

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

经过一些修改，我可以将其视为一个同步工具：

• 远程后端：添加对云存储（例如Dropbox）或服务器的支持。
• 同步逻辑：将本地更改（内容+元数据）推送到远程，拉取远程更新，处理冲突（例如，上次写入获胜）。
• 数据库调整：添加 sync_status 和 remote_id 柱。
• 文件监视程序更新：队列更改用于同步，而不仅仅是索引。
• CLI选项：添加 --sync 手动或连续触发。
• 错误处理：网络重试失败，记录问题。