Karakeep 源码地图monorepo 目录结构与模块职责全解析v0.30.0【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder本文基于 Karakeep原 Hoarderv0.30.0 版本文档docs/versioned_docs/version-v0.30.0/08-development/02-directories.md展开结合当前仓库源码逐一拆解apps、packages、tooling三大目录的作用边界、依赖关系与运行时角色。读完本文你将能像翻地图一样快速定位「某个功能写在哪个目录、由哪个包提供能力」并理解 pnpm Turborepo 单仓库monorepo下的构建、迁移与开发工作流为后续参与开发或阅读源码打下基础。Karakeep 是一个可自托管的收藏一切应用链接、笔记与图片具备 AI 自动打标与全文搜索能力。整个项目采用 pnpm workspace Turborepo 组织的单仓库结构根目录的 pnpm-workspace.yaml 声明了packages/*、apps/*、tooling/*、tools/*、docs等成员根 package.json 则通过pnpm --filter暴露pnpm web、pnpm workers、pnpm db:migrate、pnpm ios、pnpm android等一键脚本。官方文档将源码划分为三大板块Apps应用、Shared Packages共享包与Toolings工程化工具下文逐一深入。一、Apps五个面向用户的运行单元v0.30.0 文档中的 Apps 目录如下目录说明apps/web主 Web 应用The main web appapps/workers后台 Worker 逻辑The background workers logicapps/mobile基于 React Native 的移动应用apps/browser-extension浏览器扩展apps/landing项目官网落地页1.1 apps/webNext.js 主应用这是用户日常打交道的 Web 前端与 API 宿主。apps/web/package.json 显示它基于 Next.js 16next16.3.3与 React 19并通过karakeep/trpc、karakeep/db、karakeep/shared等 workspace 包串联后端能力。从 apps/web/app 的目录结构可以清晰看出其职责范围路由页面dashboard/书签、列表、标签、高亮、RSS 源、归档、收藏、搜索等管理界面、reader/阅读器、settings/设置、admin/管理后台、signin/signup/invite/verify-email/reset-password等认证流程页面API 层app/api/与server/目录承载服务端逻辑国际化lib/i18n/下维护 34 个语言的翻译 JSON仪表盘组件apps/web/components/dashboard 下 100 余个组件实现书签卡片、拖拽、批量操作、搜索等交互。运行方式见根脚本pnpm web等价于pnpm --filter karakeep/web run dev即next dev默认监听http://localhost:3000。1.2 apps/workers后台任务引擎apps/workers是 Karakeep 的后台大脑。根脚本pnpm workers实际执行pnpm --filter karakeep/workers run start即tsx watch index.ts。apps/workers/index.ts 启动时导入并初始化了LinkCrawlerQueue链接爬取、LowPriorityCrawlerQueue、OpenAIQueueAI 打标、EmbeddingsQueue向量化、AssetPreprocessingQueue资源预处理、BackupQueue备份、FeedQueueRSS 订阅、RuleEngineQueue规则引擎、SearchIndexingQueue搜索索引、VideoWorkerQueue视频处理、WebhookQueueWebhook 回调、AdminMaintenanceQueue管理维护等十余条队列。apps/workers/workers 目录则按领域拆分了具体执行器例如Worker职责从文件名与依赖推断crawlerWorker.ts使用 Playwright 抓取页面并解析可读内容inference/调用 OpenAI 等模型生成自动标签embeddingsWorker.ts生成/同步向量嵌入feedWorker.ts轮询 RSS 源并入库importWorker.ts处理导入会话E2E 导入、备份恢复backupWorker.ts创建/维护备份归档webhookWorker.ts触发用户配置的 WebhookvideoWorker.ts视频链接元数据抓取ruleEngineWorker.ts按用户规则自动整理书签searchWorker.ts将数据写入 Meilisearch 索引此外 apps/workers/server.ts 用 Hono 暴露了/health健康检查与受bearerAuth保护的/metricsPrometheus 指标端点说明 Workers 不仅消费队列还承担可观测性职责。1.3 apps/mobileReact Native 移动端apps/mobile是基于Expo React Native的移动应用apps/mobile/package.json采用 Expo Router 的文件路由apps/mobile/app 下的dashboard/、signin.tsx、sharing.tsx等。它提供开发dev、预览preview、发布release三种变体分别对应不同 bundle ID配置见 apps/mobile/app.config.js 与 apps/mobile/eas.json。移动端与 Web 共享同一套 tRPC 后端因此也依赖karakeep/shared与karakeep/trpc。1.4 apps/browser-extension浏览器扩展apps/browser-extension是基于Vite React的浏览器扩展Manifest V3见 apps/browser-extension/manifest.json。apps/browser-extension/src 下的关键页面包括SavePage.tsx保存弹窗主界面BookmarkSavedPage.tsx/BookmarkDeletedPage.tsx保存/删除结果反馈页CustomHeadersPage.tsx/OptionsPage.tsx自定义请求头与选项设置SignInPage.tsx/NotConfiguredPage.tsx登录与未配置提示content-scripts/与background/注入脚本与后台 Service Worker。开发时执行pnpm dev会启动扩展 dev server默认http://localhost:5174并产出dist目录在chrome://extensions开启开发者模式后Load unpacked加载即可。1.5 apps/landing官网落地页apps/landing基于Astroapps/landing/astro.config.ts提供首页、定价、隐私政策、条款等营销页面apps/landing/src/pages。它与主应用解耦独立构建部署这也是文档将其单独列出的原因。1.6 版本演进提示当前仓库的新增应用值得注意的是当前仓库在 v0.30.0 之后还新增了两个应用它们在本文档中尚未出现但已纳入 workspacepnpm-workspace.yamlapps/cli命令行工具apps/cli/src/commands 下提供auth、bookmarks、tags、lists、highlights、assets、dump、wipe、migrate、skill、admin、whoami等子命令apps/mcpModel Context Protocol 服务器apps/mcp/src将书签、标签、列表、高亮等操作暴露给 AI Agent配套测试见assets.test.ts、bookmarks.test.ts等。阅读源码时请以当前仓库为准v0.30.0 文档可作为该版本的历史快照参考。二、Shared Packages跨应用复用的共享能力v0.30.0 文档中的共享包如下目录说明packages/db数据库 schema 与迁移The database schema and migrationspackages/trpc大部分业务逻辑所在以 tRPC 路由形式组织packages/shared各应用之间的共享代码如 logger、config、assetdb2.1 packages/db数据模型与迁移的唯一事实来源packages/db/package.json 表明它基于better-sqlite3 Drizzle ORM drizzle-kit。packages/db/schema.ts 定义了全部表结构packages/db/drizzle 目录存放 26 份 SQL 迁移文件0000_luxuriant_johnny_blaze.sql起与对应的meta/*.json快照。根目录的三个快捷脚本与之对应pnpm db:generate # pnpm --filter karakeep/db run generatedrizzle-kit generate pnpm db:migrate # pnpm --filter karakeep/db run migratetsx migrate.ts pnpm db:studio # pnpm --filter karakeep/db studiodrizzle-kit studiopackages/db是所有应用与 Worker 访问 SQLite 的统一入口通过karakeep/shared/config读取DATA_DIR定位数据库文件。2.2 packages/trpc业务逻辑的核心枢纽packages/trpc是文档明确指出的大部分业务逻辑所在。其结构印证了这一点packages/trpc/routers36 个路由模块如bookmarks.ts、tags.ts、lists.ts、highlights.ts、assets.ts、feeds.ts、rules.ts、webhooks.ts、subscriptions.ts、apiKeys.ts、users.ts、admin.ts等且每个核心路由都配有同名*.test.ts如bookmarks.test.ts、lists.test.ts是理解业务语义的最佳入口packages/trpc/models按领域拆分的仓储/服务层如bookmarks.ts、feeds.repo.ts、feeds.service.ts、highlights.repo.ts、importSessions.service.ts等体现路由编排 服务封装 仓储访问的分层packages/trpc/lib横切能力包括rateLimit.ts限流、ruleEngine.ts规则引擎、search.ts与searchRanking.ts搜索与排序、attachments.ts、linkPreview.ts、impersonate.ts管理员模拟登录、tracing.ts链路追踪等。karakeep/trpc同时被apps/web与apps/workers依赖见两者的 package.json因此 Web 请求路径与 Worker 队列消费路径共享同一套校验zod schema、业务规则与测试覆盖。2.3 packages/shared纯前端可用的共享工具packages/shared存放不依赖服务端运行时的通用代码文档点名的三样都在源码中得到了印证logger.ts基于 winston 的日志封装config.ts统一的环境变量配置解析所有应用共享同一份配置定义assetdb.ts资源数据库访问封装。此外还包含search.ts与searchQueryParser.ts搜索查询语言解析配套searchQueryParser.test.ts、inference.tsAI 打标客户端封装配套inference.test.ts、prompts.ts/prompts.server.ts提示词模板、signedTokens.ts签名令牌、ratelimiting.ts、queueing.ts、storageQuota.ts、import-export/导入导出格式以及types/19 个类型定义文件与utils/子目录。2.4 版本演进提示当前仓库的共享包扩张v0.30.0 之后共享层显著扩充。当前仓库packages 目录还包含packages/shared-server仅服务端可用的服务如queues.ts队列抽象、assetdb.ts资源存储、plugins.ts插件加载、eventLogger.ts事件日志、tracing.ts其 src 目录清晰体现server-only边界packages/plugins可插拔服务的实现包括assetstore-filesystem本地文件存储、assetstore-s3S3 存储、queue-liteque/queue-restate队列后端、ratelimit-memory/ratelimit-redis限流后端、search-meilisearch与vectorstore-meilisearch搜索/向量存储packages/apiHTTP API 路由供 CLI/第三方使用、packages/sdkTypeScript SDK、packages/open-apiOpenAPI 规范生成、packages/shared-react跨 Web/移动端复用的 React hooks 与组件、packages/e2e_tests端到端测试等。这种演进体现了项目先 monorepo 收敛、再插件化解耦的架构思路packages/trpc负责业务packages/plugins负责可替换的底层实现。三、Toolings统一的工程化基线v0.30.0 文档中的工具目录如下目录说明tooling/typescript共享的 tsconfigtooling/eslintESLint 配置tooling/prettierPrettier 配置tooling/tailwind共享的 Tailwind 配置3.1 tooling/typescript一份基线处处继承tooling/typescript/base.json 定义了全仓默认的编译选项strict严格模式、ES2022目标、moduleResolution: Bundler、isolatedModules、moduleDetection: force、jsx: preserve与增量编译incremental并统一排除node_modules、build、dist、.next、.expo。各应用与包只需extends: karakeep/tsconfig/base.json即可继承如 apps/web/tsconfig.json 所示保证全仓类型检查口径一致配合根脚本pnpm typecheckturbo 并行执行各包tsc --noEmit。3.2 代码检查与格式化文档与仓库的演进差异需要特别说明v0.30.0 文档写作时工具目录为tooling/eslint而当前仓库已迁移为tooling/oxlint见 tooling 目录下的oxlint子目录。tooling/oxlint/oxlint-base.json 启用了typescript、import、unicorn、oxc等插件并以error级别收紧大量规则如no-debugger、no-empty、no-constant-binary-expression等oxlint-react.json与oxlint-nextjs.json则分别面向移动端/Web 应用叠加规则。各包 package.json 中的lint脚本统一为oxlint --ignore-path../../.gitignore .配合根脚本pnpm lint执行全仓检查。格式化层面tooling/prettier 的karakeep/prettier-config依赖ianvs/prettier-plugin-sort-importsimport 排序与prettier-plugin-tailwindcssTailwind class 排序不过当前各包实际通过oxfmt执行格式检查format/format:fix脚本。根 package.json 的preflight脚本把typecheck、lint、format串成一条提交前检查链。3.3 tooling/tailwindWeb 与移动端共享的样式基线tooling/tailwind/base.ts 导出一个darkMode: [class]、基于 CSS 变量hsl(var(--background))等的 Tailwind 主题配置同目录的web.ts与native.ts分别面向 Next.js 与 React NativeNativeWind场景。这样 Web 与移动端可以共用一套色板与间距体系。3.4 工程化编排turbo.jsonturbo.json 是这套 tooling 的调度中枢build任务声明dependsOn: [^build]自底向上构建并缓存.next/**、.expo/**、dist/**等产物dev任务persistent: true且禁用缓存lint/typecheck/test均依赖拓扑顺序^topo保证先编译依赖再检查依赖者。这正是根目录一条命令、全仓并行流水线的实现基础。四、目录结构与运行时架构的对应关系单纯看目录表很难建立整体直觉下图展示了各应用/共享包在运行时如何协作数据流Web 与移动端通过 tRPC 访问packages/trpc路由业务写入经packages/db落到 SQLite后台任务进入队列由apps/workers消费并驱动无头浏览器抓取、调用 AI 打标、同步 Meilisearch 搜索索引对照 docs/docs/08-development/04-architecture.md 的架构文档可以确认各层的运行时角色apps/web既渲染前端也作为 tRPC 服务端进程承载 APIapps/workers独立进程消费队列karakeep/shared-server/queues完成爬取、推理、索引等异步工作packages/db是所有写路径的唯一落库入口搜索与向量通过可插拔的packages/plugins中的search-meilisearch/vectorstore-meilisearch接入存储通过assetstore-filesystem或assetstore-s3抽象配置见karakeep/shared/config。五、基于目录结构的开发工作流理解了目录职责官方文档 开发环境搭建 中的命令就一目了然了# 1. 准备环境Node 24 corepack pnpm nvm install 24 corepack enable pnpm install # 2. 复制环境变量模板并在各应用目录建立软链接 cp .env.sample .env # 3. 初始化数据库packages/db 的迁移脚本 pnpm db:migrate # 4. 分别启动 Web 与 Workers等价于过滤运行对应 workspace 包 pnpm web # - pnpm --filter karakeep/web run devNext.js端口 3000 pnpm workers # - pnpm --filter karakeep/workers run starttsx watch index.ts # 5. 移动端与扩展按需启动 pnpm ios / pnpm android # apps/mobile cd apps/browser-extension pnpm dev # 浏览器扩展产物在 dist/若未启动 MeilisearchMEILI_ADDR未配置Web 应用其余功能仍可使用但搜索不可用若未启动 Workers新收藏的内容不会被爬取、打标或索引数据库文件与资源默认存放在DATA_DIR指定的目录packages/shared/config读取。对于想快速跑通全栈的开发者仓库还提供了 start-dev.sh一键拉起 Meilisearch、headless Chrome、安装依赖并并行启动 Web 与 Workers与 docker/docker-compose.dev.ymlprep服务负责安装依赖与迁移web/workers/meilisearch/chrome四服务编排。六、根目录的其他配套设施除三大板块外仓库根目录还包含与开发、部署密切相关的配套目录可从 docs/docs/08-development/03-database.md 等文档延伸阅读目录作用依据仓库内容docker/Dockerfile 与 docker-compose 部署编排docker/docker-compose.ymlkubernetes/K8s 部署清单web、meilisearch、chrome、PVC 等charts/Helm chart 说明docs/Docusaurus 技术文档站含docs/docs当前版与docs/versioned_docs历史版本快照tools/辅助工具如compare-models模型对比、seed-snapshot种子数据快照snapshots/预置种子数据seed-data-*.json/.tar.gz配合pnpm seed:apply使用patches/pnpmpatchedDependencies补丁React Native、Expo JSI、Playwright Extra 等见 pnpm-workspace.yamlskills/Agent 技能定义skills/SKILL.md七、小结一张表读懂 Karakeep 源码布局综合 v0.30.0 文档与当前仓库源码可得到如下定位口诀找界面→apps/webNext.js、apps/mobileExpo、apps/browser-extensionMV3 扩展找后台任务→apps/workers队列消费者与 Worker找业务规则→packages/trpcrouters → models → lib 三层找数据模型→packages/dbschema.ts drizzle 迁移找通用能力→packages/shared前端可用与packages/shared-server服务端专用找可替换实现→packages/plugins存储、队列、限流、搜索找工程基线→tooling/typescript、tooling/oxlint、tooling/prettier、tooling/tailwind。最后提醒一点v0.30.0 的02-directories.md属于版本化快照当前仓库已在应用层cli、mcp与共享层shared-server、plugins、api、sdk等做了大量扩充且代码检查从 ESLint 切换到了 oxlint。对照阅读时建议以 docs/docs/08-development/02-directories.md当前版目录结构文档与本文的源码证据为准二者结合即可获得最新、最准确的源码地图。【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考