Quivr：开源的持续内容收集、检索与主题预警引擎｜部署与使用全指南

项目仓库： https://github.com/QuivrHQ/quivr（现迁移至 The-Vibe-Company/quivr）

开源协议：MIT · 交付形态：单一 Go 二进制 quivr（api / worker / migrate / mcp 等子命令）+ Docker Compose · 主要语言：Go / TypeScript（演示前端）· 部署方式：make dev 一键起栈或官方发布镜像单机部署 · 默认端口：演示 Web 应用 5183，API 端口见 make env 输出 · 官方文档：docs.quivr.thevibecompany.co

1 项目简介

Quivr 2 是 The Vibe Company 团队重写的开源"持续内容引擎"。你把新闻、邮件、帖子、PDF 等文档发给它，或让它按计划从 RSS、Microsoft 365 邮箱、X 列表自动采集；Quivr 保留每个文档的版本，几秒内即可被关键词与语义检索命中，并按你保存的"主题预警规则"（例如 "harbour strike" AND (ferry OR port)）推送新命中的文档。它对外是一个纯 HTTP API 服务（/v0），本身不带用户界面；官方提供一个演示 Web 应用 quivr-search 用于本地体验。

版本迁移说明（务必先读）：仓库 README 明确标注 "Quivr 2"，自 2.0.0 起 HTTP API（/v0）在 2.x 系列内保持兼容，升级保留数据；项目主体由原 QuivrHQ 团队迁移到 The Vibe Company 公司名下维护。本文命令均按当前 main 分支 README 整理；早期"Quivr 第二大脑 Web 应用"形态已不再是主线。

1.1 核心信息一览

1.2 适用场景

• 持续监控某一主题（行业、竞品、地缘事件），把 RSS、邮箱、社媒列表喂进来，新文档命中规则时自动预警。
• 把文档（PDF、新闻、邮件、帖子）统一存成可检索、可追溯版本的"第二大脑"，检索结果能精确指到段落、文档与版本。
• 在自己的应用里通过 HTTP API 调用 Quivr 做语义搜索与引用，不需要自己维护向量库与切分流水线。
• 让 AI Agent 通过 quivr mcp（Model Context Protocol）搜索 Quivr 并引用出处。
• 用插件替换文件解析、来源采集、嵌入模型、排序、预警规则等任意环节。

1.3 能力边界（官方口径）

• Quivr 2 本身没有用户界面；官方演示应用 quivr-search 只是基于公开 API 的样例，生产使用需自建前端或直接对接 API。
• 文档在确认入库后，切分、嵌入、排序、预警判断等都由 worker 在后台异步处理；宕机只会延迟处理，不会丢失已确认入库的文档。
• 搜索索引可随时从存储重建，存储是唯一事实来源。
• 插件（文件格式、来源、嵌入模型、排序、预警规则）都是独立 HTTP 小服务，可用任意语言替换；不是内嵌 SDK 调用。
• 官方要求 Linux x86_64 或 Apple Silicon Mac、Docker Compose v2、对应版本 Go、Python 3.12 + venv、jq；首次启动下载约 1 GB。

2 功能特性

2.1 内容采集

• 单条 / 批量入库：通过 HTTP API 提交文档，PDF 等格式由插件解析。
• 定时来源：RSS、Microsoft 365 邮箱、X 列表由 source 插件按计划拉取。
• 版本保留：一次修订会生成新版本，旧版本仍可检索；撤回的文档立即从搜索中移除，并通知已命中的预警。

2.2 检索

• 关键词检索：基于 PostgreSQL 全文检索。
• 语义检索：通过嵌入模型插件把文档切块向量化。
• 混合检索与排序：排序逻辑由插件提供，可自定义。
• 可追溯引用：每个结果指向具体段落、文档与版本，便于在应用里做引用。

2.3 主题预警

• 保存一条预警规则，可写布尔表达式（"harbour strike" AND (ferry OR port)）或自然语言描述。
• 每篇新文档入库后，worker 判断是否命中；命中记录原因。
• 应用通过 API 拉取命中记录，或接收签名 webhook。

2.4 插件与 MCP

• 插件协议为 HTTP，官方提供 Go 与 Python SDK（sdks/）。
• 官方内置插件覆盖：预警、来源、PDF、入库、检索等。
• quivr mcp 子命令把 Quivr 暴露为 MCP 工具，AI Agent 可直接搜索并引用段落。

3 官方界面预览

Quivr 2 本身没有用户界面；官方演示应用 quivr-search 仅在执行 make demo 时启动，访问 http://127.0.0.1:5183。本文不另行配图，避免使用第三方截图；界面以官方仓库 quivr-search/ 目录最新版本为准。

4 官方跳转链接汇总

• 仓库地址：https://github.com/QuivrHQ/quivr（现迁移至 The-Vibe-Company/quivr）
• 官方文档首页：https://docs.quivr.thevibecompany.co
• Quickstart：https://docs.quivr.thevibecompany.co/quickstart
• 单机部署：https://docs.quivr.thevibecompany.co/run-quivr/single-machine
• 运维总览：https://docs.quivr.thevibecompany.co/run-quivr/overview
• 插件开发：https://docs.quivr.thevibecompany.co/plugins/overview
• API 参考：https://docs.quivr.thevibecompany.co/api-reference/overview
• 兼容版本说明：https://docs.quivr.thevibecompany.co/reference/compatibility
• 已知限制：https://docs.quivr.thevibecompany.co/reference/known-limits
• 开发方：https://www.thevibecompany.co

5 前置要求与服务器配置

5.1 软件前提

• 操作系统：Linux x86_64，或 Apple Silicon（M 系列）macOS。
• Docker + Docker Compose v2。
• Go：版本与仓库 go.mod 中 go 指令一致。
• Python 3.12 与 venv（本地开发脚本依赖）。
• jq（用于读取与过滤环境变量）。

5.2 硬件与磁盘

• 首次启动需要下载约 1 GB 镜像与依赖。
• PostgreSQL 与对象存储随文档量增长，建议预留 SSD；嵌入模型与向量维度由所选嵌入插件决定。
• 生产部署参考官方 单机部署文档，按官方推荐分配 CPU / 内存。

5.3 端口

6 方式一：Docker / Compose 一键部署（推荐）

6.1 克隆并启动开发栈

git clone https://github.com/The-Vibe-Company/quivr.git
cd quivr

# 启动 Quivr 及其依赖（PostgreSQL、对象存储等）
make dev

6.2 在当前 Shell 注入 API 地址与本地密钥

eval "$(make -s env)"

执行后当前 Shell 内会有指向本地 API 的地址与一个本地开发密钥，后续 curl 或 SDK 自动使用。

6.3 启动演示 Web 应用（可选）

make demo
# 访问 http://127.0.0.1:5183

6.4 按 Quickstart 跑通最小闭环

按官方 Quickstart：创建 collection → 提交一篇文章 → 关键词与语义检索 → 保存一条主题预警，约 15 分钟跑通。

远程访问注意事项：默认 127.0.0.1 绑定，仅供本机开发；生产部署请按官方 单机部署文档 配置反向代理、TLS 与密钥。

7 方式二：源码 / 本地开发运行

7.1 仓库结构

cmd/quivr/       单一 quivr 二进制：api、worker、migrate、plugin tools、search、mcp
internal/        引擎，每个领域一个 Go 包
contracts/       HTTP API（OpenAPI）与插件协议契约
sdks/            与 Go 插件 SDK
plugins/         官方内置插件：alerts、sources、PDF、ingestion、retrieval…
client/          由 HTTP 契约生成的 Go 客户端
migrations/      PostgreSQL 迁移
deploy/          Compose、Railway、镜像构建
quivr-search/    基于公开 API 的演示 Web 应用
docs-site/       文档站
docs/            贡献者文档、ADR、日期记录
scripts/         本地栈、检查、度量工具

7.2 常用开发命令

# 本地检查（约 2 分钟，不需要 Docker）
make check

# 在隔离栈上跑端到端流程
make verify

# 执行数据库迁移
quivr migrate

# 启动 API
quivr api

# 启动 worker
quivr worker

# 直接在命令行里搜索
quivr search "your query"

# 启动 MCP 服务
quivr mcp

7.3 服务器部署（从发布镜像）

不克隆源码直接部署的方式见官方 Run Quivr on one machine，使用官方发布镜像与 Compose 文件。

8 配置项说明

Quivr 的配置通过环境变量与启动子命令传入；完整字段以官方 API 参考 与 兼容版本说明 为准。常见入口：

具体字段名与默认值以官方文档为准，本文不臆造环境变量名。

9 常用运维命令

# 查看正在运行的栈
docker compose ps

# 查看 API 与 worker 日志
docker compose logs -f api
docker compose logs -f worker

# 停止本地栈
make dev-stop        # 或 docker compose down

# 拉取最新代码并重启
git pull && make dev

# 执行数据库迁移
quivr migrate

# 在 Shell 中重新注入 API 地址与密钥
eval "$(make -s env)"

# 直接在命令行搜索
quivr search "your query"

备份：PostgreSQL 与对象存储是唯一事实来源，备份策略应覆盖这两者；搜索索引可随时从存储重建。

10 常见故障排查

• make dev 首次启动下载很慢：首次需要约 1 GB 镜像与依赖，建议配置 Docker 镜像加速器；网络问题可在有网机器预拉镜像。
• eval "$(make -s env)" 后 curl 仍连不上 API：确认 make dev 已完全启动，再重新执行 eval；不同 Shell 窗口需要重新注入环境变量。
• 想在生产部署但不想跑 make dev：官方开发栈面向本地调试，生产应使用单机部署文档里的发布镜像与 Compose 配置。
• 插件调用失败：插件是独立 HTTP 服务，确认对应插件进程在运行、端点可达；官方插件在 plugins/ 目录。
• 检索不到刚提交的文档：文档入库后由 worker 异步切分与嵌入，刚提交完立即搜可能尚未索引；稍等或通过日志观察 worker 进度。
• 想升级版本：Quivr 2 在 2.x 内 API 兼容且升级保留数据，升级前阅读兼容版本说明与已知限制。
• AI Agent 接入：使用 quivr mcp 子命令，把 Quivr 暴露为 MCP 工具，Agent 可搜索并引用段落。

11 风险与合规说明

• Quivr 采用 MIT 协议，允许商用与二次开发，但需保留版权与许可声明。
• 文档内容（新闻、邮件、PDF、社媒帖子）的版权、隐私与跨境传输责任由使用者承担；Microsoft 365 邮箱、X 列表等来源接入需符合对应平台条款。
• 主题预警与 webhook 涉及签名校验，生产部署应配置 HTTPS 与独立 API Key，避免泄漏内部文档。
• 项目主体已从 QuivrHQ 迁移到 The Vibe Company；早期 Quivr 1.x 版本与当前 2.x 在 API 与形态上差异较大，迁移前请阅读官方兼容说明。
• 本文所有命令、端口、版本号均来自官方 README 与 docs.quivr.thevibecompany.co；后续演进以官方仓库最新说明为准。