Quivr 本地部署实战指南：Docker Compose + Supabase 快速搭建 RAG 第二大脑

本篇基于 Quivr 仓库根目录的 README.md 展开，完整覆盖从环境准备、60 秒安装、环境变量配置，到服务启动与登录验证的全部步骤，并结合 docker-compose.yml、.env.example、backend/supabase/config.toml 等仓库内真实配置，解析 Quivr 部署栈中各服务（前端、后端 API、Redis、Celery Worker/Beat/Flower）的角色、端口与协作关系。读完后，你可以在本地（Ubuntu 22+）用 Docker 一键拉起整套 Quivr，并用开发模式热重载迭代后端代码。

一、Quivr 是什么：定位与核心特性

Quivr 自称"Your Second Brain, Empowered by Generative AI"——一个用生成式 AI 驱动的个人助理/第二大脑，作者将其比喻为"加了 AI 加速的 Obsidian"。它属于"Opiniated RAG"（有主见的 RAG）：让你专注于产品本身，而非自己从零拼凑 RAG 管线。README 中声明的核心特性如下，后续部署验证都会对应到这些能力上：

• 快速高效：设计上以速度和效率为核心，快速访问你的数据；
• 安全：数据归用户控制，始终如此；
• 系统兼容：Ubuntu 22 或更新版本；
• 文件兼容：支持 Text、Markdown、PDF、PowerPoint、Excel、CSV、Word、Audio、Video；
• 开源免费：Apache 2.0 License（见 LICENSE）；
• 公开/私有：大脑（Brain）可以通过公开链接分享给用户，也可以保持私有；
• 市场（Marketplace）：可分享自己的 Brain，也可以复用他人的 Brain；
• 离线模式：Quivr 可离线运行，随时随地访问数据。

从仓库结构看，这套能力由三大块组成：frontend/（Next.js 前端）、backend/（FastAPI 后端 + Celery 异步任务 + Supabase 数据库/认证）以及 cms/、docs/ 等内容模块，通过根目录的 Docker Compose 文件编排为完整栈。

二、部署架构总览：一次 docker compose up 到底起了什么

在按步骤安装之前，先理解 docker-compose.yml 定义的服务拓扑，有助于排查"端口不通""服务未就绪"等问题。生产编排包含以下服务：

服务	容器名	职责	关键端口
frontend	web	Next.js 前端应用，构建时注入 NEXT_PUBLIC_BACKEND_URL、NEXT_PUBLIC_SUPABASE_URL 等环境变量	3000
backend-core	backend-core	FastAPI 主 API，由 uvicorn 运行 quivr_api.main:app，带 /healthz 健康检查	5050
redis	redis	Celery 消息队列/Broker	6379
worker	worker	Celery worker，执行 celery -A quivr_api.celery_worker worker -l info	—
beat	beat	Celery beat 定时任务调度	—
flower	flower	Celery 任务监控面板	5555
notifier	notifier	运行 celery_monitor.py 的通知进程	—

几个值得注意的实现细节：

• 健康检查：backend-core 通过 curl http://localhost:5050/healthz 做健康探测，说明后端 API 在 5050 端口暴露了 /healthz 端点；
• 依赖顺序：frontend 依赖 backend-core，notifier 依赖 redis 与 worker，flower 依赖 redis、worker、beat——即异步任务体系（Redis → Worker → Flower 监控）先于依赖方启动；
• 主机回环：各后端服务都配置了 extra_hosts: host.docker.internal:host-gateway，这是为了让容器内进程能访问宿主机上运行的 Supabase 本地实例（见下文数据库部分），与 .env.example 中 SUPABASE_URL=http://host.docker.internal:54321 等写法相呼应；
• 路由注册：后端入口 backend/api/quivr_api/main.py 中，FastAPI 应用依次挂载了 brain、chat、crawl、assistant、sync、upload、user、api_key、subscription、prompt、knowledge、model 等路由，覆盖了"大脑管理、对话、网页爬取、云盘同步、订阅"等核心功能模块，这也解释了 README 中 Brain、Marketplace 等特性背后的 API 来源。

三、环境准备（Prerequisites）

按照 README 的 Prerequisites 要求，本地机器需要：

• Docker
• Docker Compose
• Supabase CLI（README 的 Step 0 要求，用于在本地拉起 Postgres、认证、存储等组件）

supabase -v # 验证 Supabase CLI 安装成功

操作系统要求为 Ubuntu 22 或更新版本（README Key Features 中的 "OS Compatible" 声明）。

四、60 秒安装：完整步骤

以下是 README "60 seconds Installation" 章节的完整流程，每步都保留原始命令并补充仓库内可验证的细节。

Step 1：克隆仓库

git clone https://gitcode.com/GitHub_Trending/qui/quivr.git && cd quivr

Step 2：复制 .env.example

cp .env.example .env

.env 文件是整个 Quivr 栈的唯一配置源——docker-compose.yml 中 backend-core、worker、beat、flower、notifier 服务全部通过 env_file: .env 读取它，前端则通过 build args 注入 NEXT_PUBLIC_* 变量。

Step 3：编辑 .env，填入 OPENAI_API_KEY

vim .env # 或使用 emacs、vscode、nano

README 强调：你只需要更新 .env 中的 OPENAI_API_KEY 变量（先到 OpenAI 平台创建账号并获取 API Key）。对照 .env.example 的完整变量表，可以清楚各变量的用途与默认值：

变量	默认值/示例	说明
OPENAI_API_KEY	CHANGE_ME	必填（或按注释填入假 Key 跳过 OpenAI 集成）
OLLAMA_API_BASE_URL	注释状态	取消注释即可启用本地 Ollama（默认地址 http://host.docker.internal:11434），实现"离线模式"与任意 LLM 支持
NEXT_PUBLIC_ENV	local	前端运行环境标识
NEXT_PUBLIC_BACKEND_URL	http://localhost:5050	前端调用后端 API 的地址
NEXT_PUBLIC_SUPABASE_URL	http://localhost:54321	前端调用 Supabase API（PostgREST）的地址
NEXT_PUBLIC_SUPABASE_ANON_KEY	已内置 demo key	Supabase anon 密钥
NEXT_PUBLIC_AUTH_MODES	password	登录方式，本地默认密码登录
SUPABASE_URL / PG_DATABASE_URL	host.docker.internal:54321/54322	后端访问 Supabase API 与 Postgres 的地址
CELERY_BROKER_URL	redis://redis:6379/0	Celery Broker，指向 compose 中的 redis 服务
CRAWL_DEPTH	1	网页爬取深度
PREMIUM_MAX_BRAIN_NUMBER / PREMIUM_DAILY_CHAT_CREDIT	30 / 100	高级配额：Brain 数量、每日对话额度
BRAVE_SEARCH_API_KEY	CHANGE_ME	Brave 搜索集成 Key
GOOGLE_CLIENT_ID 等	your-client-id	Google Drive / SharePoint 云盘同步所需凭据

其中，docs/install.mdx 还补充了一个 README 未展开的技巧：如果不想用 OpenAI 而想用本地 Ollama 路线，可以取消 .env 中 OLLAMA_API_BASE_URL 的注释，并运行 ollama run llama2 启动本地模型。

Step 4：启动项目

第一步，进入 backend 目录启动本地 Supabase：

cd backend && supabase start

这一步由 backend/supabase/config.toml 驱动，会拉起整套本地基础设施，关键端口为：

• 54321：Supabase API（PostgREST）——[api] port = 54321；
• 54322：本地 PostgreSQL 数据库（[db] port = 54322，Postgres 15）；
• 54323：Supabase Studio 管理界面（[studio] port = 54323）；
• 54324：Inbucket 邮件测试服务器（本地开发时不真正发邮件，而是拦截展示）；
• Auth 配置中 site_url = "http://localhost:3000"，enable_signup = true，即默认开启注册、跳转白名单指向前端 3000 端口。

然后回到仓库根目录，拉取镜像并启动编排栈：

cd ../
docker compose pull
docker compose up

README 给出两条针对性提示：

• macOS 用户：进入 Docker Desktop > Settings > General，确认 "file sharing implementation" 设置为 VirtioFS；
• 开发者：使用开发模式启动 docker compose -f docker-compose.dev.yml up --build。

Step 5：登录应用

启动成功后，三个入口即可访问（与 compose 文件中的端口映射一致）：

• 应用登录页：http://localhost:3000/login，使用 [e-mail] / admin 登录；
• 后端 API 文档（FastAPI 自动生成的 Swagger）：http://localhost:5050/docs；
• Supabase Studio：http://localhost:54323。

关于默认账号的事实依据：[e-mail] 这个账号是由 Supabase 种子数据预置的，可以在 backend/supabase/seed.sql 中检索到该邮箱的注册/登录审计记录，说明它随 supabase start 的本地种子数据一起被灌入，而非运行期动态创建。

五、开发模式：热重载与调试

docker-compose.dev.yml 与生产编排的差异，正是开发者迭代的重点：

• backend-core 使用 Dockerfile.dev 构建并带 --reload 参数（代码变更自动重启 uvicorn），同时额外暴露 5678 调试端口（debug port）；
• worker、beat、flower、notifier 均将 ./backend/ 挂载为 /code/ 卷（volumes: - ./backend/:/code/），因此后端 Python 代码的修改无需重新构建镜像即可生效——生产编排中 backend-core 同样有此挂载；
• 开发编排不包含 frontend 服务，前端需单独在 frontend/ 目录下构建运行。

仓库根目录的 Makefile 提供了对应的快捷命令：

make dev        # 等价于 docker compose -f docker-compose.dev.yml up --build（带 BuildKit）
make test      # pytest backend/
make front     # cd frontend && yarn build && yarn start

六、更新 Quivr

README 的 "Updating Quivr" 章节只有两步，核心是代码与数据库迁移同步：

# Step 1: 拉取最新代码
git pull

# Step 2: 应用数据库迁移
supabase migration up

supabase migration up 会执行 backend/supabase/migrations/ 目录下按时间戳命名的全部增量 SQL（从 20240103173626_init.sql 初始化到后续数十个迁移文件），保证本地 schema 与仓库最新状态一致。因此升级流程中"拉代码 + 跑迁移"缺一不可。

七、贡献与许可

• 参与贡献：README 建议通过 Open Issues / Open Pull Requests 参与，并标注了 Frontend/Backend/Good First Issues 分类入口；仓库同时提供 renovate.json（依赖自动更新）与 release-please-config.json（自动化发版）等工程化配置。
• 许可证：本项目采用 Apache 2.0 License，详见 LICENSE，可免费使用。

小结

Quivr 的本地部署路径非常清晰：Supabase CLI 提供数据库/认证/存储底座（54321/54322/54323），docker compose up 拉起前端（3000）、FastAPI 后端（5050）、Redis（6379）与 Celery 全家桶（Worker/Beat/Flower 5555），唯一必填项是 .env 中的 OPENAI_API_KEY（或改为 Ollama 走本地模型）。理解 docker-compose.yml 的服务依赖与健康检查、.env.example 的变量语义、backend/supabase/config.toml 的端口规划后，无论是排障、二次开发（docker-compose.dev.yml 热重载）还是升级（supabase migration up），都有据可依。