01
Share to X
Share to LinkedInKeepFlash 架构概览
本文档面向开发者，介绍 KeepFlash 代码库的整体结构。
技术栈
- Next.js App Router，搭配 React 19 服务端和客户端组件
- PostgreSQL，通过 Prisma ORM 管理关系数据（笔记、标签、空间、用户）
- Meilisearch，用于笔记的全文和语义搜索
- better-auth，认证系统（邮箱密码、魔法链接、OAuth）
- Creem，默认支付提供商（可选 Stripe / Paddle 适配器）
- Cloudflare Workers，定时后台任务
- BlockNote，块式笔记编辑器
关键目录
| 路径 | 用途 |
|---|---|
app/[locale]/ | 公开和认证后的路由 |
app/api/ | REST 和流式 API 端点 |
components/landing/ | 首页区块组件 |
components/notes/ | 笔记列表、详情和编辑器 UI |
db/prisma/schema.prisma | 数据库 Schema |
db/services/ | 数据库访问层 |
lib/actions/ | 客户端组件使用的 Server Actions |
lib/ai/ | AI 提供商封装、用量账本、流式传输 |
lib/search/ | Meilisearch 客户端和索引同步 |
lib/marketing/ | 首页内容构建器 |
messages/ | i18n 翻译文件（en、zh） |
workers/keepflash-cron/ | 定时任务 Cloudflare Worker |
数据流：保存一条笔记
- 用户通过浏览器插件、粘贴或上传来保存内容。
app/api/notes/中的 API 路由创建Note记录和关联的Block记录。- 将后台分析任务加入队列。
- Cloudflare Worker（
keepflash-cron）轮询并触发分析端点。 - 执行分析：AI 打标签、生成嵌入向量、更新 Meilisearch 索引、评估 Auto Wiki。
搜索架构
KeepFlash 使用 Meilisearch 支持两种搜索模式：
- 全文搜索：对笔记标题、正文和元数据进行关键词匹配
- 语义搜索：基于嵌入向量的相似度匹配（Plus/Pro 套餐）
嵌入向量异步生成，通过 lib/embedding-scheduler.ts 调度。
AI 处理
AI 功能使用 lib/ai/providers/ 中的提供商。app/api/ai/chat/stream/ 中的对话端点使用两阶段 LangGraph 流水线：
- 规划模型（不向用户计费）处理工具调用
- 用户选择的模型生成最终回答
- 只根据最终模型的实际 token 用量扣除积分
Auto Wiki
Auto Wiki 通过 Cron Worker 作为异步任务运行。当某个主题下积累了足够多的相关笔记时，lib/knowledge/ 会评估是否应该创建或更新 Topic Page。每个套餐的上限通过 config/wiki-page-limits.ts 执行。