用 Next.js+Postgres+pgvector+Inngest+Gemini 跑通 AI 原生应用的可摄取/OCR/RAG 后台任务全链路

方案简介

LaunchStack 是一个面向 AI 原生应用的 TypeScript 引擎组合方案。它把文档摄取、OCR、RAG、知识图谱、LLM 抽象、后台任务这些常被散落在各处的 AI 能力，按 ports-based（端口式）分层封装到一个引擎里，并配一个 Next.js 参考应用演示如何把这些零件拼起来。

适合的受众：想自托管一套「能传文件、能 OCR、能做 RAG 检索问答」的 AI 工作台，又不愿意被单一 SaaS 锁死的开发者和团队。引擎由 packages/protocol、evidence、application、adapters 与 packages/core 门面组成，参考应用位于 apps/web（Next.js UI + 同步读取）和 apps/worker（耐久工作流协调器），辅以 services/ 下独立的文档转换/转写服务。

部署模型默认自托管：只有设置 DEPLOYMENT_MODE=cloud 才走云模式；自托管默认下不强制启用用量门禁、不加载遥测、不从 CDN 拉资源，且实例以访问主机名标识自身。第一个注册用户直接成为其工作区的 owner 并已验证，无需另设管理员引导。

实施步骤

1. 拉取代码并安装依赖

git clone https://github.com/Deodat-Lawson/LaunchStack.git
cd LaunchStack
pnpm install
cp .env.example .env

2. 配置最小环境变量

在 .env 中至少设置：

• DATABASE_URL：默认 localhost:5433/pdr_ai_v2，与 Compose 发布端口一致；自备 Postgres 时改用 .env.example 中注释掉的 localhost:5432/pdr_ai。
• BETTER_AUTH_SECRET：用 openssl rand -base64 32 生成。
• GOOGLE_AI_API_KEY：未设置 CHAT_BASE_URL 时用于调用 Gemini 的 OpenAI 兼容端点。

注意：apps/web/src/env.ts 缺少 DATABASE_URL 或 BETTER_AUTH_SECRET 时会拒绝启动。空跑的 OPENAI_API_KEY/OPENROUTER_API_KEY/OLLAMA_BASE_URL 不会配置 chat，也不会被转发到 Gemini 默认端点——「key 表示身份，base URL 表示去哪儿」。

3. 启动数据库与完整栈（Docker 推荐路径）

make up-prod     # lite stack, detached (~400MB RAM)
make up-ocr      # adds Docling for Office docs, detached (~1.2GB RAM)
make logs        # follow logs
make down        # stop containers (keeps volumes — DB + S3 data persists)
make down-clean  # stop + wipe volumes (fresh DB on next up)

make up 以前台方式运行，要停服务得另开终端 make down，日常迭代建议用 make up-fast（在主机上先构建 Next.js）或直接用 make up-prod。

Windows 无 make 的替代命令：

docker compose --env-file .env up --build -d                 # lite
docker compose --env-file .env --profile ocr up --build -d   # with Docling
docker compose --env-file .env down --remove-orphans      # stop (keeps volumes)
docker compose --env-file .env down -v --remove-orphans   # stop + wipe volumes

或通过 choco install make / scoop install make 安装 make。

4. 非 Docker 路径：手动迁移与启动

需要先准备一个带 pgvector 的 Postgres：

pnpm --filter @launchstack/web    db:migrate   # apply BOTH migration sets (engine, then product)
pnpm --filter @launchstack/core   db:seed      # optional: one company/user/document
pnpm --filter @launchstack/web    dev          # Next.js on :3000
pnpm --filter @launchstack/worker dev          # the durable worker on :8020 — ingestion runs here, not in web
pnpm --filter @launchstack/web    inngest:dev  # optional: Inngest dev UI on :8288, pointed at the worker's :8020/api/inngest

注意：db:migrate 是 CI、Docker 与生产镜像构建用的同一条命令；从 @launchstack/core 跑只应用 engine 那套 schema，不够一个完整应用使用——完整应用必须从 web 包跑。

使用与配置要点

• 进程角色分工：浏览器访问 http://localhost:3000（Next.js）做上传与查询；摄取/后台任务由 :8020 的 worker 消费，仅跑 web 不跑 worker 时上传的文档会一直留在队列里。Inngest dev UI（:8288，可选）只服务于 Inngest 托管的后台垂直功能（如 trend search、prospector），不参与摄取。
• chat 路由切换：保留默认就走 Gemini 的 OpenAI 兼容端点；切到任意 OpenAI Chat-Completions 厂商只需设 CHAT_BASE_URL + CHAT_API_KEY。AI_BASE_URL/AI_API_KEY 只是规范命名的别名，会以弃用警告方式翻译迁移。
• 部署模式：默认即自托管；设置 DEPLOYMENT_MODE=cloud 才进入云模式。自托管下：用量会被记录但不会做门禁、不加载遥测、不从 CDN 拉资源；实例用所服务的主机名标识自身。
• 首个用户即 owner：自托管实例的第一个注册用户直接成为其所建工作区的 owner 且已验证，无需单独的管理员引导流程。
• 开发期迭代：make up-fast 是最快的迭代回路（先在主机编 Next.js 再挂载）。

注意事项与常见问题

• 根目录不是应用：仓库根是无运行时依赖的 pnpm workspace；在根目录跑 pnpm dev 会得到 ERR_PNPM_NO_SCRIPT，必须用 --filter 选定包。根目录只保留工作区级命令：lint、lint:fix、typecheck、check、format:write、format:check 与 Changesets 脚本。
• chat 变量命名：历史上 OPENAI_API_KEY/OPENROUTER_API_KEY/OLLAMA_BASE_URL 等看起来「应该能用」的变量在当前版本不再被 chat 识别，也不会透传到 Gemini 默认端点；务必通过 CHAT_BASE_URL 切换供应商。
• OCR 资源消耗：lite 栈约 400MB RAM；带 Docling 的 OCR 栈约 1.2GB RAM，按需启用。
• 数据库坑：db:migrate 在缺少 pgvector 的 Postgres 上会以非零退出，迁移既覆盖 engine schema 也覆盖 product schema。
• 引擎包尚未发布 npm：@launchstack/protocol、evidence、application、adapters 与 core 走 Changesets 流程统一发布；目前只能通过运行本仓库消费引擎。
• 营销站点不在自托管里：apps/landing 是 launchstack.app 的独立站点，Docker/Compose 不构建；自托管实例的 / 是登录页，不是产品介绍页。

优缺点

• ✓ 明文分层引擎+参考应用
• ✓ Docker 一键起完整 lite 栈
• ✕ 引擎包尚未发布 npm
• ✕ 首个注册用户即 owner，权限模型极简

出处

本方案挖掘自开源项目 Deodat-Lawson/LaunchStack，方案内容与实施命令均来自其 README 原文。