Obsidian Index Service

Obsidian Index Service

此服务会监控 Obsidian 知识库目录，并将 Markdown 文件的元数据和完整内容编入 SQLite 数据库。我开发它是为了配合我的 mcp-server 项目使用，但后来改用了基于 Obsidian 插件 API 的实现。我仍认为它可以用作通用的笔记索引器或同步工具（请参阅“后续步骤”中的说明），因此将它发布在这里。

功能

它会跟踪 Obsidian 知识库中的文件变更（创建、修改、删除），并将所有内容存储在 SQLite 中，可通过 Docker 卷访问。它会记录：

• 路径：文件路径（唯一标识符）
• 标题：来自文件名
• 父文件夹：相对于知识库根目录的路径
• 标签：来自 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：知识库目录路径
• --db-path：SQLite 数据库路径
• --scan-only：扫描但不监控

使用 Docker

1. 构建并运行：

   docker-compose up -d
   

2. 此操作会挂载你的知识库，并公开 SQLite 数据库。

为其他服务提供只读访问

要让其他服务读取数据库（例如，用于扫描变更）：

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

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

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

工作原理

Obsidian Index Service 按照以下流程运行：

1. 启动（ObsidianIndexService.__init__）

   • 从环境变量或命令行参数加载配置
   • 初始化数据库连接（DatabaseConnection）
   • 设置笔记处理器（NoteProcessor）
   • 建立信号处理器，以便平稳关闭

2. 数据库初始化（DatabaseConnection.__init__）

   • 创建或连接到 SQLite 数据库
   • 将数据库设置为 WAL（预写式日志）模式，以提升并发性能
   • 如果 notes 表不存在，则创建该表，其中包含路径、标题、标签等列

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

项目状态

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

后续步骤（同步工具的潜力）

经过一些调整后，我认为它可以成为同步工具：

• 远程后端：添加对云存储（例如 Dropbox）或服务器的支持。
• 同步逻辑：将本地更改（内容 + 元数据）推送到远程端，拉取远程更新，并处理冲突（例如，以最后写入者为准）。
• 数据库调整：添加 sync_status 和 remote_id 列。
• 文件监视器更新：将更改加入同步队列，而不只是建立索引。
• CLI 选项：添加 --sync，以手动或持续触发同步。
• 错误处理：网络故障时重试，并记录问题。