Hatchdoor

Hatchdoor

自托管 Obsidian 库：为你提供 Web UI，为 AI Agent 提供 MCP。 无需 Obsidian，也无需插件。

Hatchdoor 直接从磁盘读取你的库，任何包含 Markdown 笔记的文件夹也都适用。无需 Local REST API 插件，也无需让桌面应用一直运行。你可以在快速的 Web UI 中浏览、搜索和编辑笔记，还可以让 Claude、Claude Code、Codex、Cursor 或 Hermes 等 Model Context Protocol（MCP）客户端连接同一个库，让 Agent 能够读取、搜索（关键词和语义）、创建、编辑、移动和链接笔记。一个服务可以管理任意数量的库；每次写入都会通过 UI 使用的同一套原子库操作完成，并提供乐观并发控制和可选的自动 git 提交与推送。Web UI 和你的 Agent 是通往同一个库的两个入口。

你的 Markdown 文件始终是事实来源。Hatchdoor 会构建一个可随时丢弃的 SQLite 读取模型，用于快速浏览、链接、反向链接、关键词搜索、语义搜索、图谱数据和元数据。如果缓存被删除，Hatchdoor 会根据库重新构建。

Hatchdoor 借助 AI 编码 Agent 构建而成，主要使用 Claude Code 和 Codex，并由人工密切审查，同时配有测试和文档化的安全模型。

▶  试用在线演示，这是一个只读的公开库；也可以阅读用户文档，了解设置和使用指南。

目录

• 你将获得什么
• 截图
• 适用人群
• Hatchdoor 对比
• 接下来计划
• 使用 Docker 快速开始
• 数据与安全模型
• 配置
• MCP Agent 访问
• 版本管理与 Git 同步
• 不使用 Docker 运行
• 故障排除
• 安全说明
• 开发
• 项目文档
• 许可证

## 你将获得什么

• 用于浏览文件夹和 Markdown 笔记的 Web 界面。
• 原生多知识库：一个实例可提供多个知识库，每个知识库都有自己的源、Git 同步和 Agent 范围。
• 简洁的笔记 URL：/v/<vault-id>/n/<slug>。
• 支持 Obsidian 风格的 wikilink（如 [[Note]]、[[Folder/Note]] 和 [[Note|Alias]]），也支持指向 .md 文件的 Markdown 链接；重命名和移动后，两类链接都会自动更新。新链接遵循各知识库自己的链接风格。
• 已保存的查询：使用 Obsidian Bases 语法的围栏代码块 base，可实时显示符合条件的笔记表格，供用户和 Agent 使用。
• 支持 GitHub 风格 Markdown、数学公式、Mermaid 图表、frontmatter、图片、附件和失效链接样式的 Markdown 渲染。
• 关键词搜索和语义搜索。
• 最近笔记、反向链接、出站链接、统计信息和图谱视图。
• 当知识库挂载点可写时，可在浏览器中使用实时编辑器：打开笔记即可开始输入，只在当前行显示 Markdown 语法标记，并自动保存修改。其工作方式与 Obsidian 的 Live Preview 相同。
• 附件上传、本地资源托管，以及对链接的 PDF 知识库资源进行内嵌预览。
• 一流的 MCP 服务，让 AI Agent 能够以与界面相同的安全保障读取、搜索、创建、编辑和链接笔记；还能通过一次检查操作重命名或删除整个知识库中的标签，并通过短时有效的下载和上传链接传输任意大小的附件。
• 为适应上下文窗口而设计的 Agent 读取功能：精简的搜索结果、长笔记的大纲和指定章节，以及统计每次出现情况的精确字符串搜索。
• 全新安装时提供设置清单，引导用户从空实例开始，直到 Agent 能够搜索笔记，并用文件夹选择器取代容器路径。
• 内置于应用的手册：在你进行操作时可随时查看帮助；Agent 可通过 read_docs 和 search_docs 使用相同的页面；每个实例也都在 /docs/ 提供纯 Markdown 文档。
• 可选为 Hatchdoor 写入自动执行 Git 提交和推送；每次提交都会注明更改来源（Web 界面、指定名称的 Agent 或外部编辑），同步冲突则通过恢复分支在 Git 托管平台上解决。
• 为常见读取路径提供 PWA 资源和 Service Worker 缓存。
• 采用 Distroless、无根容器镜像（不含 shell，以 nonroot 身份运行），可通过 Docker 或 Podman 部署。

截图

知识图谱：笔记、链接和标签	语义搜索 + 关键词搜索
深色模式	自适应布局，可安装（PWA）

适用对象

如果你有一个存放 Markdown 笔记的文件夹，并希望通过私有 Web 界面访问它们，Hatchdoor 就很适合你。

它足够易于入门，可通过 Docker Compose 运行，同时也为需要 Agent 访问、基于 Git 的知识库同步、语义搜索和本地开发的用户提供了高级功能。

Hatchdoor 不是托管式同步服务，不是多用户协作平台，也不能替代 Obsidian。它是你可自托管的伴侣应用，用于管理由你掌控的 Markdown 知识库。

Hatchdoor 的对比

Obsidian 的 MCP 工具领域竞争激烈。坦率地说：如果你一直在 Obsidian 应用中工作，只想要一个尽可能精简的连接桥，那么基于插件的工具就很合适。如果你希望知识库独立于 Obsidian 提供服务——例如部署在家庭实验室设备上，同时供浏览器和 Agent 使用，或管理多个知识库，那么 Hatchdoor 就是为此而打造的。

	Hatchdoor	mcp-obsidian	Local REST API	Basic Memory	OpenKnowledge
产品类型	可自托管的知识库服务：Web 界面 + MCP	连接 REST 插件的 MCP 桥接工具	REST 插件本身	基于本地 Markdown 的 AI 记忆，以 MCP 为先	带并排 AI 功能的所见即所得 Markdown 编辑器
无需安装 Obsidian 即可运行	✅ 从磁盘读取知识库	❌ 需要运行 Obsidian 和插件	❌ 在 Obsidian 内运行	✅	✅ 使用自带编辑器
面向用户的 Web 界面	✅ 可自托管，在线演示	❌	❌	付费云应用	✅ 桌面应用 + 本地 Web 应用
提供多个知识库服务	✅ 单个服务，按知识库同步 Git	❌	❌	✅ 项目	❌ 每个实例对应一个文件夹
Agent 编辑的写入安全性	原子写入、乐观并发控制	通过插件 REST API	—	覆盖保护	—
作为服务部署	✅ Docker/Podman、无 root 运行、令牌身份验证	❌ 依赖桌面应用	❌	❌ 本地进程（云服务需付费）	❌ 本地 CLI 应用

Basic Memory 和 OpenKnowledge 都是优秀的项目，解决的是相关但不同的问题（Agent 记忆、原生支持 AI 的编辑器）。Hatchdoor 仅在一种情况下与它们有所重叠：当你的笔记是希望通过服务提供的知识库时。它是一个始终在线的服务，可同时供浏览器和 Agent 使用。

后续计划

下一个大型功能是多账户管理和权限范围控制。目前，Hatchdoor 假定私有部署中只有一位可信用户，因此任何能访问该实例的人都能看到它提供的所有知识库。计划允许多位用户和 Agent 共用一个实例，各自只能访问获准使用的知识库，并由管理员管理其他事项。这样，家庭或小型团队就能只运行一个 Hatchdoor，而不必每人运行一个。

v2.5.0 已将知识库改为由产品管理的独立、可寻址对象，其中包括对 MCP Agent 的知识库范围控制。尚缺少的是有意推迟的另一半：账户、身份验证，以及由服务端强制执行而非仅由界面暗示的访问边界。目标版本为 v3。

另外还有两项期待实现的功能，目前尚未安排版本：

• Agent 来源追踪与撤销。 哪个 Agent 修改了笔记、修改前后的差异，以及与之对应的提交，并支持一键还原。目前 Git 已能提供所有答案：每次提交都会注明执行修改的 Agent，但查看提交日志并不等同于直接查看 Agent 对笔记做了哪些改动。
• 知识库完整性检查。 对知识库进行范围限定的检查，找出孤立笔记、失效的维基链接，以及声明已消失的层标记。这样，由 Agent 在无人看管的情况下维护的知识库就不会悄然偏离原有结构。

产品路线图列出了完整的工作流及各自的进展。

使用 Docker 快速开始

有终端可用的 AI Agent 吗？例如 Claude Code 或 Codex。把下面这一行交给它，它就会先询问几个问题，然后为你安装 Hatchdoor：

Read https://hatchdoor.battercloud.cc/docs/deploy.md and install Hatchdoor for me.

如需手动安装，请按以下步骤操作。

1. 环境要求

你需要：

• Docker 和 Docker Compose（也支持 Podman 和 podman compose）
• 一个 Markdown 知识库文件夹；如果想从头开始，也可以使用空文件夹

2. 创建配置

复制示例环境文件：

cp .env.example .env

默认设置会将一个空的 vault 文件夹挂载在 Compose 文件旁边。若要使用现有 Vault，请在 .env 中取消注释其主机路径：

HOST_VAULT_PATH=/absolute/path/to/your/markdown-vault

这些设置的含义：

• HOST_VAULT_PATH 是主机上的 Markdown Vault。
• HOST_CACHE_PATH、HOST_STATE_PATH 和 HOST_MODELS_PATH 是可选的 主机端路径，分别用于存放生成的缓存、权威 Vault 注册表 和下载的模型；Compose 默认将它们设在项目目录旁边。

首次启动受管理的 Vault 之前，请创建默认的权威状态目录，并赋予镜像的数字 nonroot 用户访问权限。否则，Docker 可能会以 root 身份创建缺失的绑定挂载源，导致注册表无法写入：

mkdir -p data/state
chmod 700 data/state
sudo chown 65532:65532 data/state

对于无 root 的 Podman，请使用 podman unshare chown 65532:65532 data/state，而不要使用 sudo chown。自定义 HOST_STATE_PATH 时，也请应用相同的所有权规则。

不要将普通设置值添加到 .env：未设置的值可以在设置中实时更改。有关始终仅通过环境变量设置的少数部署值，请参阅配置。

3. 启动 Hatchdoor

docker compose up -d

Docker Compose 会将 Hatchdoor 绑定到非回环容器接口，因此首次运行时若没有 Web 令牌，服务会安全停止并打印一个新的、可恢复的令牌。使用以下命令获取令牌：

docker compose logs hatchdoor

将打印出的 HATCHDOOR_WEB_BEARER_TOKEN=... 赋值语句复制到 .env 中，然后再次运行 docker compose up -d。Hatchdoor 不会存储该令牌；请使用此次拒绝启动时提供的令牌，或生成新的长随机令牌。服务运行后，打开 http://localhost:42824，并在浏览器提示中输入令牌。

4. 选择搜索模型

Hatchdoor 镜像不包含模型权重。首次启动时，在下载任何内容之前，Hatchdoor 会要求你选择一个模型：Gemma（支持多种语言，推荐使用，但需要接受其条款）或 Nomic Embed Text v1.5 （仅支持英语，无需接受条款）。无论选择哪种，模型及其条款接受凭据都会保存在 HOST_MODELS_PATH 中，并在重启后保留；Hatchdoor 绝不会将 Vault 内容发送到任何地方。设置完成前，Vault 功能不可用。

全新安装中没有 Vault。模型就绪后，Hatchdoor 会打开设置 Hatchdoor清单：将笔记文件夹添加为 Vault、连接 Agent，并尝试搜索。顶栏中的 ? 按钮会打开帮助页面，即当前运行版本的使用手册。

5. 容器镜像和路径

镜像发布在 Docker Hub：

battermanz/hatchdoor:latest          # also version tags, e.g. 2.9.0
battermanz/hatchdoor:podman-latest   # for Podman users (podman-<version> too)

运行时镜像采用 distroless 且无 root 的设计。它基于 gcr.io/distroless/cc-debian13:nonroot 构建，不包含 shell 或软件包管理器，并以无特权的 nonroot 用户运行。Hatchdoor 也可以在 Podman 下原样运行（包括无 root 模式）；将 docker / docker compose 替换为 podman / podman compose，并且将镜像标签替换为 podman-latest（或 podman-<version>）——上面的 latest 标签仅适用于 Docker。

Docker Compose 挂载：

容器路径	用途
/data/vault	Markdown Vault，真实数据源
/data/cache	生成的 SQLite 缓存
/data/state	权威 Vault 标识和源定义
/models	下载的搜索模型和本地 Gemma 条款接受凭据

数据与安全模型

Hatchdoor 的设计遵循一条简单原则：你的 Markdown 知识库才是真实数据源。

• Markdown 文件存放在每个知识库各自的文件夹中，具体位置记录在知识库注册表中。VAULT_PATH 并不是该位置：它是 Hatchdoor 可以访问的文件夹，其中的任何内容都不会自动成为知识库，必须先添加。全新安装不会包含任何知识库。
• 知识库身份和源定义存放在 /data/state/vaults.json 中。知识库的 Git HTTPS 凭据也存储在其中，因此该文件在 Unix 上会以 0600 权限创建，并应纳入按机密数据处理的备份。API 绝不会返回该凭据：知识库只会报告 credential_configured；若编辑时要保留已存储的机密，则通过 https_credentials: {"action": "keep"} 表示，而不是重新发送机密。
• SQLite 是可重新生成的缓存。
• SQLite 缓存应存放在知识库之外。
• Hatchdoor 会扫描知识库下的 .md 文件，同时排除内置和已配置的杂项路径（包括 .hatchdoor-trash）。
• 删除操作会将笔记及其各自文件夹中保存的资源移至 .hatchdoor-trash。
• 归档操作会将笔记移至 HATCHDOOR_ARCHIVE_PREFIX 下。
• 只有在知识库可写时，才能使用浏览器写入操作。
• MCP 默认处于禁用状态。
• 启用 MCP 时，必须为其单独配置 bearer token。
• 版本控制默认关闭；启用后，可以保留本地 Git 历史记录，也可以安全地与现有远程仓库同步。

从 2.4.x 或更早版本升级的单知识库部署，无法直接升级到此版本：请先升级到 2.5.0 至 2.7.x 版本，该过程会将知识库移入注册表。对于此类安装，Hatchdoor 会拒绝启动，而不是以空状态打开。请参阅旧版单知识库升级指南。

Hatchdoor 绝不会在知识库文件夹中写入示例笔记。空文件夹会作为空知识库打开，直到你向其中添加 Markdown 文件。

要获得写入权限，浏览器写入、MCP 写入、附件上传和 Git 同步都要求容器的非 root 运行用户能够写入知识库挂载、缓存目录和状态目录。只要缓存目录和状态目录保持可写，即使知识库以只读方式挂载，也能进行只读浏览。如果写入功能意外被禁用，请检查这些挂载的权限。

Hatchdoor 不要求使用任何特定的知识库布局——PARA、Zettelkasten、Andrej Karpathy 的 LLM wiki 模式，或以上方式均不使用，都可以正常工作。用户文档对这些方式进行了比较；如何在 Hatchdoor 中运行 LLM wiki则介绍了基于分层的设置方法（将原始来源放在单独的 .hatchdoor-layer 中，并将精选 wiki 作为默认展示层）。

配置

将 .env.example 复制为 .env。其中的值全部已注释：Docker Compose 和 Hatchdoor 会提供常规默认值，而 Settings 负责管理实时服务配置。在 .env 中为服务级 Settings 键设置非空值，即表示有意进行环境固定：该值会在此进程中 优先于已保存的 Settings 值，并且在移除固定值并重启容器之前，Settings 中会显示为 在 .env 中设置。Vault 定义通过 Settings、HTTP API 或 MCP 按 Vault 管理，而非通过 .env 管理。

部署前有两个值得了解的默认设置：

• 如果 HOST=0.0.0.0 或绑定到其他非回环地址，且未设置 HATCHDOOR_WEB_BEARER_TOKEN，Hatchdoor 会拒绝启动。拒绝启动时，它会打印一个新 token 以及需要添加的 .env 行；这就是解决方法，并非程序错误。
• HATCHDOOR_DEMO_MODE=true 会运行一个只读、无需身份验证的实例，供公众浏览。它本身没有速率限制（搜索会为每个 查询生成嵌入，笔记下载会将附件打包到内存中），因此在公开访问之前，请在前面部署一个 限速反向代理。

有一项可选设置是有意未列入 .env.example 的： HATCHDOOR_USAGE_REPORT_ENABLED。这是遥测功能，默认关闭；只有在 Settings 的 使用情况报告中启用，或在 .env 中将其设为 true，才会开启。开启后，Hatchdoor 每天会向维护者发送一份小型报告，说明安装的配置情况，不包含任何笔记内容，以便确定要测试哪些平台，以及用户依赖 Hatchdoor 的哪些部分。使用情况报告 参考 列出了所有字段。

每个部署变量、每个可通过 Settings 实时编辑的值、分层和排除规则，以及搜索索引和缓存的工作方式，都在 Settings 和环境变量 参考 和分层 系统中有完整说明。

MCP Agent 访问

内嵌的 MCP 端点默认处于禁用状态，地址为 http://127.0.0.1:42824/mcp。 它使用独立于 Web token 的专用 bearer token；即使是只读访问也必须提供，因为 /mcp 会绕过 Web 身份验证层。在 Settings → Agent 访问（MCP） 中启用该端点并生成 token；写入访问权限 需单独启用，且只有在你信任 Agent 会如何使用该权限后才启用。更改会立即应用于新的 MCP 请求，无需重启。

完整的客户端设置说明（Claude Code、Codex、OpenClaw、Hermes）、每次工具调用都必须遵守的 Vault 作用域 约定，以及附件上传路径，见 连接你的 Agent 和 MCP 工具 参考。

版本管理与 Git 同步

版本管理按 Vault 配置，而非按服务配置：在该 Vault 的 Settings 页面中选择 No Git、Local history、Pull-only 或 Two-way。合并冲突始终会保留，以便人工解决；Hatchdoor 绝不会强制检出并覆盖 尚未提交的手动 Vault 编辑。

设置方法请参阅如何设置由 Git 支持的 Vault；如果你要升级部署前未使用注册表的单 Vault 版本，请参阅 docs/migrations/legacy-single-vault.md。

不使用 Docker 运行

如果已安装 just，just dev-start 会在以下手动步骤的基础上构建，并跟踪 PID，防止重复服务或过期的构建缓存目录不断累积；just dev-stop 会妥善关闭两者，just --list 则会显示其他命令（dev-status、dev-clean、prod-check）。有关每个配方的作用，请参阅 justfile。构建产物通过主检出目录在关联的工作树之间共享；显式设置 CARGO_TARGET_DIR、CARGO_HOME 和 HATCHDOOR_TMPDIR 可覆盖可移植默认值。

否则，请先构建一次前端：

cd frontend
npm ci
npm run build
cd ..

运行后端：

cargo run

默认情况下，本地源码运行会绑定到 127.0.0.1:42824，且启动时不包含任何 Vault。请在 Settings 中添加一个，或使用 POST /api/v1/vaults 添加。若要使用一组现成的开发 Vault，请改用 just dev-start（参见 AGENTS.md）。

前端开发模式：

# terminal 1
cargo run

# terminal 2
cd frontend
npm run dev

首次运行时选择的模型也适用于本地开发。Hatchdoor 默认将模型存储在 ./models 中，因此无需运行模型预下载命令。

故障排查

Hatchdoor 拒绝在 0.0.0.0 上启动

请设置 HATCHDOOR_WEB_BEARER_TOKEN、绑定到 127.0.0.1，或启用 HATCHDOOR_DEMO_MODE=true 以提供只读公开演示。这是有意为之：绑定到非回环地址可能会将你的 Vault 暴露到网络中。

应用打开后没有 Vault，或你的笔记文件夹不在列表中

全新安装在添加 Vault 之前不会包含任何 Vault：请在设置清单中选择 添加笔记，或选择 Settings → 添加 Vault。如果文件夹列表为空或找不到你的文件夹，几乎总是因为容器挂载了一个空目录。请检查 .env 中的 HOST_VAULT_PATH 是否有拼写错误，以及是否有遗留的 Docker 卷遮蔽了挂载目录。

有关写入权限问题、MCP 401/403、git 同步问题等，请参阅用户文档中的常见问题排查指南。每个 HTTP 端点都有文档说明，请参阅 HTTP API 参考。

安全说明

• 使用较长且随机的 HATCHDOOR_WEB_BEARER_TOKEN。
• 如果未在 Hatchdoor 前面配置 HTTPS，请勿将其公开到互联网。
• HATCHDOOR_DEMO_MODE=true 仅用于只读浏览的公开测试实例。
• 除非需要，否则请禁用 MCP。
• 请谨慎对待 MCP 写入模式：它可以创建、编辑、移动、删除和导入内容。
• 将 SQLite 缓存存放在 Vault 之外。
• 不要将 .env 纳入 git。
• 启动容器前，请检查 Docker 卷路径。

开发

后端检查：

cargo fmt --check
CARGO_BUILD_JOBS=1 cargo clippy --all-targets -- -D warnings
CARGO_BUILD_JOBS=1 cargo test

前端检查：

cd frontend
npm run format:check
npm run typecheck
npm run lint
npm test
npm run build

just release-prepare 和 just release-publish 会创建一个发布版本并发布其 Docker 镜像；请参阅发布操作手册。发布需要维护者的构建机器和凭据，因此贡献者无法创建发布版本。若要在本地构建镜像，请参阅容器构建目标和 Cargo 缓存。

项目文档

• 用户文档：提供 Hatchdoor 的安装、配置和日常使用指南，托管在 Hatchdoor 自身的知识库中。源文件位于 docs/user-vault，每个安装版本都附带适用于该版本的相同页面，可在“帮助”中以及 /docs/ 访问。
• 在线演示：一个公开的只读实例，包含四个示例知识库。
• 更新日志和发布版本：记录每个版本的变更。
• 文档索引：架构、协作、路线图、研究、维护和历史记录。
• 产品路线图：产品整体方向草案，以及由此拆分出的各项工作流。
• 设计系统：前端使用的视觉设计令牌、组件模式、布局规则和交互状态。
• 语义搜索策略：决策记录，说明为何在运行时流程中采用纯语义搜索，而非混合检索或交叉编码器重排序器。

许可证

Hatchdoor 仅依据 GNU Affero 通用公共许可证 v3.0 授权。 请参阅 LICENSE。

第三方材料——打包的图标以及运行时下载的嵌入模型——记录在 THIRD_PARTY_NOTICES 中。