01
Share to X
Share to LinkedInKeepFlash 架构概览
本文档面向开发者，介绍 KeepFlash 代码库的整体结构。
技术栈
- Next.js App Router，搭配 React 19 服务端和客户端组件
- PostgreSQL，通过 Prisma ORM 管理关系数据（笔记、标签、空间、用户）
- Meilisearch，用于笔记的全文和语义搜索
- better-auth，认证系统（邮箱密码、魔法链接、OAuth）
- Creem，默认支付提供商（可选 Stripe / Paddle 适配器）
- 独立 Node.js Worker，执行 PostgreSQL 持久化后台任务
- BlockNote，块式笔记编辑器
关键目录
| 路径 | 用途 |
|---|---|
apps/web/app/[locale]/ | 公开和认证后的路由 |
apps/web/app/api/ | REST 和流式 API 端点 |
apps/web/components/notes/ | 笔记列表、详情和编辑器 UI |
apps/worker/ | 队列轮询、租约续期、健康检查和停机 |
packages/database/prisma/schema.prisma | 数据库 Schema |
packages/jobs/ | 队列协议、调度器、Handler 和 Registry |
apps/web/db/services/ | Web 数据库访问层 |
apps/web/lib/ | Server Actions、AI、搜索与工具 |
apps/web/messages/ | i18n 翻译文件（en、zh） |
数据流：保存一条笔记
- 用户通过浏览器插件、粘贴或上传来保存内容。
apps/web/app/api/notes/中的 API 路由创建Note和Block记录。@keepflash/jobs调度器向 PostgreSQL 写入持久化 pending 任务。apps/worker直接领取任务，持有资源租约并在执行期间持续续租。- 共享 Handler 执行 AI 打标签、向量嵌入、搜索投影或 Auto Wiki，并提交任务结果。
队列仅支持 PostgreSQL。Worker 提供 /health/live 和 /health/ready，生产进程通过根目录的 pm2:worker:start、pm2:worker:reload 和 pm2:worker:logs 命令管理。
搜索架构
KeepFlash 使用 Meilisearch 支持两种搜索模式：
- 全文搜索：对笔记标题、正文和元数据进行关键词匹配
- 语义搜索：基于嵌入向量的相似度匹配（Plus/Pro 套餐）
嵌入向量和搜索投影通过 @keepflash/jobs 调度。
AI 处理
AI 功能使用 lib/ai/providers/ 中的提供商。app/api/ai/chat/stream/ 中的对话端点使用两阶段 LangGraph 流水线：
- 规划模型（不向用户计费）处理工具调用
- 用户选择的模型生成最终回答
- 只根据最终模型的实际 token 用量扣除积分
Auto Wiki
Auto Wiki 由一组持久化 Worker 任务串联执行。共享 Handler 负责主题创建和页面编译，并在创建页面前执行套餐上限。
运维回滚只需重新部署上一个 Worker 构建，不恢复任何旧执行器。