Deodat-Lawson/LaunchStack · 上手攻略

仓库：Deodat-Lawson/LaunchStack
链接：https://github.com/Deodat-Lawson/LaunchStack
分类：AI 应用引擎 · RAG · 知识管理
作者：Tom
更新：2026-08-23

这是什么

LaunchStack 是一个TypeScript AI 原生应用引擎，内置文档摄取、OCR、RAG、知识图谱、LLM 抽象、后台任务等模块，配有一个 Next.js 参考应用演示完整接线方式。

核心定位是：让开发者把 AI 能力嵌入自己的应用时，不必从零组装 LangChain + PostgreSQL + 向量数据库 + 任务队列，而是直接用 LaunchStack 的引擎包，接上自己的前端和端口实现。

⚠️ 引擎包（@launchstack/core 等）尚未发布到 npm，首次 release 后才能通过 npm 安装。当前必须 clone 仓库运行。

解决什么问题

构建 AI 应用时常见的组装难题：

LangChain 上手容易、收尾难：灵活的代价是脆弱，定制化程度高时不如直接写
RAG 系统各模块拼接：PDF OCR → 向量嵌入 → 检索 → 生成，每个环节都有坑
后台任务编排：文档摄取是异步的，没有好用的持久化任务队列就变成定时轮询
多模型接入：上线后想换 LLM provider，改代码的痛苦经历

LaunchStack 的engine 做了这几件事的统一抽象：db（PostgreSQL + pgvector）、llm、embeddings、ocr、rag、graph、guardrails、ingestion、jobs、storage——通过端口（port）模式让 host app 提供真实实现，engine 本身不直接依赖框架。

快速安装

前置要求

Node.js ≥ 20
pnpm 10.15.1（项目锁定版本）
PostgreSQL（需开启 pgvector 扩展）
Docker Compose（用于本地容器化运行，或自行准备 Postgres + S3 兼容存储）

方式一：Docker 快速启动（推荐）

git clone https://github.com/Deodat-Lawson/LaunchStack.git
cd LaunchStack
cp .env.example .env
# 编辑 .env，填入 DATABASE_URL 和 CLERK_SECRET_KEY

make up-prod   # 轻量栈，后台运行（约 400MB RAM）
make up-ocr    # 加上 Docling OCR，支持 Office 文档（约 1.2GB RAM）
make logs      # 跟踪日志
make down      # 停止（数据卷保留）
make down-clean # 停止并清除数据卷（全新数据库）

Windows（无 make）：

docker compose --env-file .env up --build -d
# 或带 OCR
docker compose --env-file .env --profile ocr up --build -d

方式二：本地开发（无 Docker）

# 1. 安装依赖
pnpm install

# 2. 配置环境变量
cp .env.example .env
# 填入 DATABASE_URL（需 pgvector）和 CLERK_SECRET_KEY

# 3. 数据库迁移
pnpm --filter @launchstack/web db:migrate
# 4. 可选：填充种子数据（一间公司/用户/文档）
pnpm --filter @launchstack/core db:seed

# 5. 启动服务
pnpm --filter @launchstack/web dev      # Next.js → http://localhost:3000
pnpm --filter @launchstack/worker dev   # 持久 worker → http://localhost:8020
pnpm --filter @launchstack/web inngest:dev  # 可选：Inngest dev UI → http://localhost:8288

⚠️ web dev 单独跑可以接受上传但不会处理文档；worker 必须同时运行，文档摄取任务才会真正执行。

核心用法

创建 Engine 实例

import { readFileSync } from "node:fs";
import { createEngine } from "@launchstack/core";
import { createChatModelsConfig } from "@launchstack/core/llm";
import { configureOcr } from "@launchstack/core/ocr/config";
import { configureSecretBox } from "@launchstack/core/crypto";

const engine = createEngine({
  db: { url: process.env.DATABASE_URL! },
  llm: {
    chat: createChatModelsConfig({
      yaml: readFileSync("apps/web/config/chat-models.yaml", "utf8"),
      endpoint: {
        baseUrl: process.env.CHAT_BASE_URL!,
        apiKey: process.env.CHAT_API_KEY,
      },
    }),
    openai: { apiKey: process.env.OPENAI_API_KEY! },
  },
  embeddings: { indexName: "legacy-openai-1536" },
  ocr: { defaultProvider: "NATIVE_PDF" },
  providers: {},
  storage: myStoragePort,       // 你实现 StoragePort（S3 或本地）
  jobs: { dispatcher: myDispatcher },  // 你实现 JobDispatcherPort
});

const { db } = engine;
await engine.close();  // 优雅关闭

配置聊天模型（chat-models.yaml）

LaunchStack 通过 YAML 配置多模型路由，不依赖特定 provider：

version: 1
models:
  primary:
    id: gemini-2.5-flash
    preset: google  # 使用内置 preset

支持的 chat provider： - Google Gemini（默认，不设置 CHAT_BASE_URL 时） - OpenRouter、vLLM、llama.cpp、LM Studio、Ollama /v1 端点 - 任何实现 OpenAI chat-completions 协议的端点

配置示例（Gemini）：

# .env
GOOGLE_AI_API_KEY=你的密钥
# 不设置 CHAT_BASE_URL，chat 默认走 Gemini

配置示例（OpenRouter 或其他 OpenAI 兼容端点）：

CHAT_BASE_URL=https://openrouter.ai/api/v1
CHAT_API_KEY=你的密钥

⚠️ OPENAI_API_KEY / OPENROUTER_API_KEY / OLLAMA_BASE_URL 不能直接配置 chat，必须通过 CHAT_BASE_URL 指定端点（变量名即目标）。Bare OPENAI_API_KEY 不会被用于 chat，这是一个明确的设计决策。

文档摄取（Ingestion）

worker 进程负责异步摄取上传文档： - 支持多种 OCR provider：NATIVE_PDF、Docling（Office 文档）、Azure、Landing.AI、Datalab -摄取结果写入 PostgreSQL + pgvector - 通过 Inngest 支持后台任务（趋势搜索、潜在客户挖掘等）

架构边界（重要）

┌─────────────── apps/web (Next.js host) ───────────────┐
│ env.ts → engine.ts → createEngine(config)             │
│  wires: StoragePort(S3) · JobDispatcherPort(Inngest)  │
│         CreditsPort(DB) · RagPort(hybrid search)     │
└───────────────────────┬────────────────────────────────┘
                        │
┌───────────────────────▼───────────────────────────────┐
│            @launchstack/features/*                     │
│  (adeu · marketing-pipeline · client-prospector ...)  │
│  通过 @launchstack/core/<子路径> 导入，不直接 import app │
└───────────────────────┬────────────────────────────────┘
                        │
┌───────────────────────▼───────────────────────────────┐
│                  @launchstack/core                     │
│  db · llm · embeddings · ocr · rag · graph · ...    │
└──────────────────────────────────────────────────────┘

关键约束： - Core 不读 process.env（no-env 规则由 lint 强制） - Features 不能 import 来自 host app 的代码 - Host 拥有 env、auth、路由，并实现所有端口 - 一个进程只能有一个 engine 实例（依赖 globalThis 存储状态，防 Next.js HMR 重复求值）

自托管默认行为

默认 DEPLOYMENT_MODE 非 cloud（自托管），不发送遥测、不依赖 CDN、不 gated
第一个注册用户自动成为 workspace owner（无需单独 admin 引导）

典型适用场景

构建企业知识库问答：PDF/Office 文档上传 → OCR → 向量检索 → LLM 生成答案
AI 应用快速原型：用 LaunchStack engine + Next.js 参考应用快速跑通全栈
多模型切换：通过 YAML 配置切换 Gemini/OpenRouter/vLLM，代码不动
RAG + 知识图谱联合查询：LaunchStack 支持 graph 模块（Neo4j 端口），可以做混合检索
创业公司文档处理流程：内置 marketing pipeline、legal templates、趋势搜索等业务垂直功能

坑与注意

engine 包尚未发布 npm：必须 clone 仓库运行，还没有语义化版本保障；首次 release 后会有 Changesets 发布流程
make up 前台运行：make up 会占住终端；需要后台运行用 make up-prod 或 make up-ocr
pnpm dev 在根目录会失败：ERR_PNPM_NO_SCRIPT；必须用 --filter 指定包：pnpm --filter @launchstack/web dev
PostgreSQL 必须有 pgvector：stock Postgres 会导致迁移失败；Docker 默认配置已包含扩展
CHAT_BASE_URL 变量名即目标：不是 "OPENAI_API_KEY → chat"，而是 "CHAT_BASE_URL → chat endpoint"；Bare OPENAI_API_KEY 不会配置 chat
Windows 用户需要 make：通过 Chocolatey（choco install make）或 Scoop（scoop install make）安装
db:migrate 两次：先跑 engine migration 再跑 product migration；只跑一个会导致 schema 不完整
Inngest dev server 是可选的：仅用于查看 Inngest 托管后台任务的 UI，摄取任务本身靠 worker 进程运行

与同类对比

方案	语言	数据库	RAG	任务队列	部署方式
LaunchStack	TypeScript	PostgreSQL + pgvector	内置	Inngest	自托管 / Docker
LangChain	Python/TS	多种	自己组装	自己组装	灵活
Flowise	No-code	多种	拖拽	内置	Docker/K8s
Dify	No-code	多种	拖拽	内置	Docker/K8s
LangFlow	Python	多种	拖拽	自己组装	Python

LaunchStack 的差异化在于engine + 端口模式：给了足够的内部模块抽象，但没有做成黑盒 SaaS；适合想深入定制但不想从零搭基础设施的团队。

一句话推荐结论

TypeScript AI 应用引擎的扎实选择——engine 封装了 RAG/OCR/知识图谱/任务队列，搭配 Next.js 参考应用跑通全栈，端口模式让换存储和 LLM provider 不改 engine 本身。（⚠️ engine 包尚未发 npm，生产使用需等首次 release；当前需 clone 仓库依赖 master 分支）

来源：GitHub README (https://github.com/Deodat-Lawson/LaunchStack) · Web 搜索（补充 LaunchStack 关键词 2026）

待验证：Neo4j 端口具体用法、@launchstack/features 各模块完整状态（部分标记 roadmap）、@launchstack/core 首次 npm 发布计划时间。