CorpusGate

一个由 MarkItDown 和 MCP 驱动的 LLM 就绪私有文档网关。

转换、索引并检索私有文档，供 AI 工具使用，无需将文档内容发送给第三方服务。

CorpusGate 是一个通用、自托管的文档 MCP 服务器，适用于需要在自有基础设施上受控地让 AI 工具访问文档的个人和团队。MarkItDown 将受支持的文件转换为可复用的 Markdown。网关随后对该 Markdown 进行分块和索引，MCP 只在服务端强制的预算内返回相关的、带来源归属的文本块。

自托管使源文档、生成的 Markdown、查询、元数据和索引都保持在运维者的控制之下。Token 的减少来自有界的检索和文本块选择——而非仅仅来自 MarkItDown。本项目不是聊天机器人、LLM 答案生成器、合同分析产品、SaaS 平台，也不是面向用户的文档面板。

功能特性

• 通过 Microsoft MarkItDown 转换 PDF、DOCX、PPTX、XLSX、TXT、Markdown 和 HTML。

• 持久化 Markdown 缓存、感知 Token 且保留标题的文本块，以及 SHA-256 去重。

• 轻量默认安装中的 SQLite FTS5/BM25 词法搜索。

• 可选的、仅需 CPU 的多语言语义搜索，以及使用本地嵌入的 RRF 混合检索。

• 有界 MCP 响应，包含来源/位置元数据、游标、去重和相邻块限制。

• REST API 密钥和 MCP Bearer 认证、安全的 UUID 存储、路径/符号链接保护、速率限制，以及结构化且内容安全的日志。

• 针对 AMD64/ARM64、Oracle Cloud、Tailscale 或 Caddy HTTPS 加固的 Docker Compose 部署。

• 初始化辅助脚本、可运维的 doctor/scan/reindex/backup 命令、带版本的 SQLite 架构和 CI。

Related MCP server: rag-retriever-mcp

工作原理

REST upload or read-only inbox scan
        │
        ├─ type, signature, size, path, and free-space validation
        ├─ UUID storage + SHA-256 ── unchanged? ── reuse cached/indexed record
        │
        └─ MarkItDown ──> persistent Markdown ──> token-aware chunks
                                                   │
                              ┌────────────────────┴────────────────────┐
                              │                                         │
                    SQLite FTS5 / BM25                      optional local embeddings
                              │                                  + private Qdrant
                              └────────────────────┬────────────────────┘
                                                   │
                               ranking → dedup → token/char budget → MCP

代码将解析器、存储、仓库、分块、嵌入、向量存储和检索的契约都封装在接口之后，而不会把单服务器产品变成分布式系统。文档始终是主要数据源；Markdown 和向量索引都可以重建。

支持的格式

加密、损坏、纯扫描图像或转换器不支持的文件会安全失败，而不会影响其他文档。

快速开始

要求：带 Compose v2 的 Docker Engine，以及 OpenSSL。主机上不需要安装 Python。

git clone https://github.com/mustafa0zdemir/corpusgate.git
cd corpusgate
./corpusgate init
./corpusgate up
curl --fail http://127.0.0.1:8000/health
./corpusgate doctor

./corpusgate init 会创建 persistent/inbox 数据目录，仅在 .env 不存在时复制 .env.example，生成两个独立的随机 REST/MCP 凭据且不回显，检查 Docker/Compose 和所选端口，并校验 Compose。它绝不会覆盖已有的 .env。

等效的手动流程是：将 .env.example 复制为 .env，用两个不同的 openssl rand -hex 32 值替换两个凭据占位符，创建 documents/，然后运行 docker compose up -d。切勿把 .env 提交到版本库。

初始化之后，可选的语义/混合检索也只需要一步操作：

./corpusgate init --semantic
./corpusgate up --semantic

首次以语义模式启动时，会先把下载到持久缓存中的模型缓存下来，然后在内部 Docker 网络中与 Qdrant 一起离线启动服务。之后的启动会复用模型与向量卷。词法安装不会部署或运行任何语义组件。

添加文档

最简单的运维工作流使用主机上只读的 inbox 目录：

cp examples/documents/* documents/
./corpusgate scan
./corpusgate list-documents

扫描会跳过隐藏/系统/临时文件、不支持的格式、目录和符号链接。输入文件仍保留在 documents/ 中；私有 UUID 副本存放在持久化的源卷中。 如需从词法到语义/混合再到 MCP 的完整演示，请使用合成演示。

对于可以由单个文件调用且不需要把文件字节放进模型上下文的单文件工作流，可将本地文件直接流式上传到正在运行的 REST API（需要 curl）：

./corpusgate upload /absolute/path/to/document.pdf

该命令会从 CORPUSGATE_CLIENT_API_KEY、CORPUSGATE_API_KEY 或本地 .env 读取 REST 密钥，不会打印密钥，拒绝重定向和非安全的远程 HTTP，并且只返回 API 的上传元数据。远程私有服务器请传入 --url https://YOUR-NODE.YOUR-TAILNET.ts.net。

REST 上传可供程序使用：

export CORPUSGATE_CLIENT_API_KEY='value-from-your-env'
curl --fail -X POST http://127.0.0.1:8000/api/v1/documents \
  -H "X-API-Key: ${CORPUSGATE_CLIENT_API_KEY}" \
  -F 'file=@examples/documents/private-network-guide.md'

REST 还在 /api/v1/documents 下提供分页元数据、Markdown、文本块、词法搜索和删除。交互式 OpenAPI 文档位于 /docs；受保护的操作仍需要 X-API-Key。

连接 MCP 客户端

远程端点为 https://YOUR_PRIVATE_OR_PUBLIC_HOST/mcp，每个 MCP 请求都需要：

Authorization: Bearer YOUR_MCP_TOKEN

推荐使用 Tailscale Serve 作为私有路由。Caddy HTTPS 是面向公众的公开方案；两种情况下网关端口都只绑定到主机回环地址。有关已验证的字段映射、Inspector 命令、Tailscale/HTTPS 示例和故障排查，请参阅 MCP 连接指南。不要复制未来过时的客户端专属 JSON 包装，也不要把令牌提交到源码控制。

MCP 工具

检索项d均包含 document_id、document_name、chunk_id、heading、position、相关性/排序字段、有界的 content、content_length 和检索模式元数据。空搜索返回空的 items 列表、已应用预算、指标，并且没有游标。无效模式、筛选器、文档 ID 或超限值会产生受控的工具错误。上传和删除仍仅限会话内容。

推荐流程：

AI tool → search_document(query, top_k=3, max_tokens=600)
        → ranked chunks + source positions + actual retrieval mode
        → optional bounded get_document_section

词法、语义和混合检索

• lexical 是生产默认值：SQLite FTS5 搭配带标题权重的 BM25，无需其他服务即可保留精确的标识符和短语。

• semantic 使用可配置的多语言 CPU 模型在本地对查询/文本块进行嵌入，并将向量存储在私有 Qdrant 中。

• hybrid 通过 Reciprocal Rank Fusion 合并独立的词法排名和语义排名；重复的文本块只返回一次，精确的词法匹配不会被舍弃。

• 当请求 semantic 或 hybrid，但可选本地模型、向量存储或索引不可用且启用了回退时，会报告 lexical_fallback。

默认模型是 Apache-2.0 许可证的 sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2， 这是一个 384 维多语言模型，在 CPU 上通过 FastEmbed/ONNX 运行。关于模型替换、离线传输、重建索引规则、测量结果和 Oracle 内存指导，请参阅语义搜索指南。

Token 优化

MarkItDown 让各种文件都能一致地被解析，但它本身并不自动减少 Token。网关通过以下方式减少返回的上下文：缓存一次转换、对文本块排序、去除重复、强制执行 top_k、max_chars 和估算的 max_tokens、限制相邻块，以及对长结果集分页。它从不暴露默认的 MCP 工具来一次性返回完整文档或原始文件。

Token 计数是本地确定性的估计，并非某个供应商计费的 tokenizer。可重复的合成测量及其确切覆盖范围见 检索评测报告；并不声明普适的节省百分比。

安全与隐私

• 无遥测、无文档文本、无查询文本、无云端嵌入 API，也不要求任何 LLM 提供商。

• 源文件使用 UUID 路径；对文件名穿越、绝对路径、符号链接逃逸、隐藏/临时文件、MIME/签名不匹配、解压文件包、上传大小和磁盘空间不足都进行校验。

• REST 使用 API 密钥；远程 MCP 使用环境变量或 Docker Secret 中常量时间比较的 Bearer 令牌。多个当前/历史令牌支持轮换。

• 结构化日志只包含允许的操作记录，绝不包含文档内容、凭据、完整查询或客户端可见的堆栈。

• 网关容器以非 root 运行、无 capabilities、启用 no-new-privileges、根文件系统只读，并具备显式的可写卷/tmpfs 资源和日志限制。

• 基本 Compose 只发布 127.0.0.1:8000；Qdrant 仅供内部使用。公开部署需要 Caddy TLS，并继续保留 Bearer 认证/速率/响应限制。

存储的数据包括私有 UUID 源副本、生成的 Markdown、SQLite 元数据/文本块/FTS、可选的本地向量/模型缓存、备份和操作者配置。要删除数据，请先通过 REST 删除文档；只有在显式的备份和完全停产之后，再删除持久卷。请参见 SECURITY.md 报告私有漏洞。

Oracle Cloud 部署

推荐的 Oracle Ubuntu 部署将应用和绑定到 loopback，并通过 Tailscale Serve 提供仅限 tailnet 的 HTTPS。对于需要域名的场景，文档中说明了 Caddy public 配置文件。Oracle 安全列表/NSG 绝不能开放 TCP 8000 或 Qdrant 6333。

虚拟机准备、AMD64/Ampere ARM64 说明、Docker 安装、文件系统的属主、机密、防火墙、Tailscale/Caddy、日志、更新、备份、恢复和故障排查等，见 Oracle 部署指南。

配置

所有应用环境变量的默认值、需求、范围、示例和安全影响，均列于配置契约和 .env.example 中。启动时会拒绝缺失/过短的凭据、无效的端口/路径、不可能的分块/预算关系、不支持的检索模式，以及无效的语义向量存储配置，并且不会回显秘密值。

运维命令：

./corpusgate version
./corpusgate status
./corpusgate doctor
./corpusgate mcp-smoke
./corpusgate upload /absolute/path/to/document.pdf
./corpusgate scan
./corpusgate reindex
./corpusgate reindex --semantic
./corpusgate list-documents --limit 20 --offset 0

备份与恢复

./corpusgate backup
./corpusgate restore /backups/corpusgate-backup-TIMESTAMP.tar.gz --confirm-restore

恢复操作会替换当前的持久化数据，因此需要显式确认标志，并且生产环境中必须已停止写入方。备份包括私有源数据存储、Markdown 缓存、通过事务方式复制的 SQLite 数据库、清单文件以及不含密钥的配置示例。请将 .env 和令牌文件放入单独的加密密钥备份中。向量数据可从分块重建。

更新与回滚

了解当前版本，然后进行备份，选择经过评审的标签/镜像，运行带版本号的幂等迁移，重启服务，检查 ready/MCP 就绪状态，并在验证完成前保留备份。由较新版本不兼容应用创建的 SQLite 数据库会被拒绝，而不会遭到静默修改。

准确的命令和安全回滚/恢复路径见 update and rollback。正常的更新过程中绝不运行 docker compose down -v。

仓库中还包含一个手动、需审批才可执行的 GHCR 工作流。稳定标签、移动的 minor 标签以及 latest 标签行为在容器发布策略中定义;本次冲刺尚未发布任何镜像。

Troubleshooting

• ./corpusgate doctor:校验配置、存储权限、SQLite/schema、磁盘、可选的模型/向量 状态、服务就绪度和版本，并且不泄露密钥。

• 401：请使用 REST 的 X-API-Key 或 MCP 的 Authorization: Bearer，不要使用另一类凭据。

• 主机被拒绝：将确切的 Tailscale/域名主机添加到 CORPUSGATE_ALLOWED_HOSTS 并重新创建网关。

• 507：释放磁盘空间，或重新检查预留磁盘阈值后再重试摄入。

• lexical_fallback：检查模型缓存和 Qdrant 健康状态；词法检索仍然可用。

• 转换失败：确认支持的文件扩展名、MIME/签名、UTF-8/Office 压缩包完整性、大小、加密情况， 以及 PDF 中是否包含文本。

• 日志：./corpusgate logs --tail=100；分享前请清理敏感输出。

在打开 issue 前，请阅读 SUPPORT.md 和部署环境对应的故障排查指南。

兼容性

未经测试的平台不会标注为受支持。发布前请阅读发布检查清单。

局限性

• 单节点 SQLite 不是高可用数据库，也不支持多写入方。

• 0.1.0 中上传清理为同步进行；大文档可能需要更长的客户端/代理 超时时间。

• 不支持 OCR、云存储适配器、用户账户、UI、行为生成、检索重排、 详情，也没有 SaaS 控制平面。

• 近似令牌预算可能与特定 LLM 分词器有所差异。

• 语义模型下载需要临时出站访问，除非离线离线传输。

路线图

• 对单节点用户不强制 Redis，同时引入后台转换任务。

• 将可选的 PostgreSQL/pgvector 和对象存储适配器放入现有接口之后。

• 支持提取更多的转换器元数据，并提供操作者可控制的 OCR 适配器。

• 提供签名发布、SBOM/来源证明，并扩展跨架构和升级测试。

贡献指南

请阅读 CONTRIBUTING.md，遵守 CODE_OF_CONDUCT.md，在共享代码时添加测试，并且只使用合成的、不涉及敏感信息的测试数据。所有安全报告必须通过 SECURITY.md 中说明的私有途径提交，绝不能公开并创建 issue。

许可证

CorpusGate 以现有的 MIT License 许可证发布。第三方 无关库以及可选的嵌入模型保留其自己的许可证。