Karakeep（原 Hoarder）Monorepo 目录结构深度解析：从 apps、packages 到 tooling 的模块化架构指南

Karakeep原 HoarderMonorepo 目录结构深度解析从 apps、packages 到 tooling 的模块化架构指南【免费下载链接】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本文以 version-v0.28.0 开发文档之目录结构篇 为骨架结合当前仓库的实际源码与配置系统讲解 Karakeep即 Hoarder一个可自托管的收藏一切应用链接、笔记、图片并支持 AI 自动打标签与全文检索的 Monorepo 目录组织方式。读完本文你将能够准确回答某个功能应该去哪个目录找代码新增一个应用或共享包需要动哪些配置文件数据库迁移与业务路由分别在哪里管理等问题为二次开发、定位问题与贡献代码建立清晰的地图。一、Monorepo 总体布局pnpm workspace 与 Turbo 驱动的模块化仓库整个仓库采用 pnpm workspace 管理的 TypeScript Monorepo顶层目录分为三类apps可独立运行的应用、packages被各应用共享的库/包与tooling工程化配置此外还有docs、docker、charts、kubernetes等配套目录。工作区成员在 pnpm-workspace.yaml 中声明packages: - packages/* - apps/* - tooling/* - tools/* - docs该文件还统一固定了关键依赖版本overrides中如react: 19.2.3、vite: 7.0.6并声明了patchedDependencies——仓库根目录的 patches 目录存放了对react-native、playwright-extra、react-tweet等第三方包的本地补丁。任务编排则由根目录的 turbo.json 负责配合 start-dev.sh 一键启动开发环境。版本说明v0.28.0 文档描述的目录结构与当前仓库存在少量演进如新增apps/cli、apps/mcp、packages/api等tooling/eslint已演变为tooling/oxlint下文会逐节标注以便按版本对照查阅。二、Apps五个核心应用及其技术栈v0.28.0 文档给出的 Apps 目录表如下这也是理解本仓库的起点DirectoryDescriptionapps/webThe main web appapps/workersThe background workers logicapps/mobileThe react native based mobile appapps/browser-extensionThe browser extensionapps/landingThe landing page of karakeep.app1.apps/webNext.js 主 Web 应用这是用户接触最多的主应用承担仪表盘、阅读器、设置、管理后台等全部界面。从 apps/web/package.json 可以看到其核心技术栈框架Next.js 16.3.3 React 19.2.3见 package.json存储better-sqlite3drizzle-orm见 package.json数据直接落在 SQLite接口层trpc/client与trpc/server见 package.json业务调用走 tRPC 而非手写 REST鉴权next-auth含 drizzle adapterUIRadix UI 组件族、shadcn、Lexical 编辑器、react-markdown、shiki 代码高亮等。源码结构上页面位于 apps/web/appNext.js App Router含dashboard、reader、settings、admin、signin等路由目录可复用组件位于 apps/web/components国际化文案位于 apps/web/lib/i18n含多语言 JSON服务端鉴权逻辑位于 apps/web/server/auth.ts。值得留意的是仓库已引入apps/cli命令行工具apps/cli/src/commands与apps/mcpMCP 服务器apps/mcp/src两个较新的应用它们不在 v0.28.0 的目录表中属于后续迭代的产物。2.apps/workers后台任务 Workerapps/workers承载所有后台逻辑是收藏—打标—可搜索流水线的执行引擎。架构文档见 docs/docs/08-development/04-architecture.md说明其消费基于 SQLite 的任务队列主要处理三类任务爬取Crawling使用 worker 容器内的无头 Chrome 抓取链接内容AI 打标OpenAI调用 OpenAI 类接口为内容推断标签索引Indexing将内容写入 Meilisearch加速搜索时的检索。从 apps/workers 的目录结构可以看到每个 Worker 的独立入口crawlerWorker.ts、embeddingsWorker.ts、feedWorker.ts、importWorker.ts、ruleEngineWorker.ts、searchWorker.ts、videoWorker.ts、webhookWorker.ts、backupWorker.ts、adminMaintenanceWorker.ts、assetPreprocessingWorker.ts等爬取相关的核心逻辑集中在 apps/workers/workers/crawler。其依赖清单apps/workers/package.json也印证了职责边界playwrightplaywright-extra无头浏览器抓取、metascraper全家桶提取标题/作者/日期/图片等元数据、mozilla/readability正文提取、tesseract.jsOCR、pdf2json/pdfjs-distPDF 解析、rss-parserRSS 抓取、liteque队列实现、hono对外 HTTP 服务与 Prometheus 指标。3.apps/mobileReact Native 移动端移动端基于 ExpoSDK 56与 React Native 0.85.3见 apps/mobile/package.json并使用 NativeWind 做样式方案。源码在 apps/mobile路由页面位于 apps/mobile/app含 dashboard、signin、sharing 等业务组件按components/bookmarks、components/highlights、components/lists、components/settings、components/reader等模块组织离线缓存逻辑在 apps/mobile/lib/offlineCache.ts 与 apps/mobile/lib/offlineLibrary.ts。注意它通过karakeep/trpc直连服务端 tRPC 接口与 Web 端共用同一套业务层。4.apps/browser-extension浏览器扩展浏览器扩展基于 Vite CRXJS 构建apps/browser-extension/package.json使用single-file-core实现页面整体快照存档。主要源码包括后台脚本 apps/browser-extension/src/background、内容脚本 apps/browser-extension/src/content-scripts、以及保存页/选项页/登录页等 UI 组件SavePage.tsx、OptionsPage.tsx、SignInPage.tsx等见 apps/browser-extension/src。扩展与移动端、Web 端一样复用karakeep/trpc与karakeep/shared-react。5.apps/landing官网落地页落地页使用 Astro 6 构建apps/landing/package.json页面位于 apps/landing/src/pages主页组件在 apps/landing/src/Homepage.tsx定价、隐私、条款等独立成页Pricing.tsx、Privacy.tsx、Terms.tsx。三、Shared Packages共享包与业务逻辑中枢v0.28.0 文档的 Shared Packages 表DirectoryDescriptionpackages/dbThe database schema and migrationspackages/trpcWhere most of the business logic lies built as TRPC routespackages/sharedSome shared code between the different apps (e.g. loggers, configs, assetdb)1.packages/db数据库 Schema 与迁移数据库层使用 Drizzle ORM 管理 SQLite。核心文件包括packages/db/schema.ts全部表结构定义书签、标签、列表、高亮、用户、API Key、规则等packages/db/drizzle已生成的迁移 SQL0000_luxuriant_johnny_blaze.sql至0025_aspiring_skaar.sql共 26 个迁移与 meta 目录 中的迁移快照packages/db/migrate.ts迁移执行入口。日常开发通过 packages/db/package.json 中的脚本操作pnpm --filter karakeep/db generate基于 schema 生成新迁移、migrate执行迁移、studio打开 Drizzle Studio 可视化查看数据。表结构变更流程可进一步参考 docs/docs/08-development/03-database.md。2.packages/trpc业务逻辑中枢正如文档所说大部分业务逻辑以 tRPC 路由的形式集中在这里。路由目录 packages/trpc/routers 按领域划分例如bookmarks.ts书签 CRUD 与搜索、tags.ts、lists.ts、highlights.ts、assets.tsfeeds.tsRSS 源、rules.ts自动化规则、webhooks.ts、backups.ts、importSessions.tsusers.ts、admin.ts、invites.ts、subscriptions.ts、apiKeys.ts、publicBookmarks.ts公开分享、config.ts配置读取。每个路由几乎都配套同名*.test.ts如bookmarks.test.ts、rules.test.ts可作为理解接口行为的活文档。路由聚合入口为 packages/trpc/routers/_app.ts上层由 packages/trpc/index.ts 导出供 Web、移动端、扩展端共同调用——这正是三个客户端复用同一套业务层的关键。更细的模块化实现可参阅 docs/docs/08-development/04-architecture.md。3.packages/shared跨端共享代码packages/shared 存放不依赖具体运行时的纯逻辑如文档所述包括 logger、configs 与 assetdb实际还包含searchQueryParser.ts搜索查询语言解析配测试、inference.tsAI 推理相关、signedTokens.ts签名令牌、readOnlyMode.ts只读模式、storageQuota.ts存储配额、vectorStore.ts、concurrency.ts等。凡是Web 与 Worker 都要用、且不涉及平台 API的逻辑都倾向于放在这里。4. 版本演进补充v0.28.0 之后的共享包当前仓库的 packages 目录比 v0.28.0 文档多了多个共享包按职责补充如下DirectoryDescriptionpackages/shared-server服务端专用共享服务如队列queues.ts、资产存储assetdb.ts、插件plugins.ts、事件日志、链路追踪见 packages/shared-server/srcpackages/plugins可插拔服务实现含文件系统/S3 资产存储assetstore-filesystem、assetstore-s3、内存/Redis 限流、Meilisearch 搜索与向量存储、LiteQue/Restate 队列packages/apiREST/HTTP 适配层packages/api/routes为 tRPC 之外的外部调用提供 OpenAPI 风格接口packages/shared-react跨端共享的 React 组件与 hookspackages/shared-react/components、hookspackages/open-apiOpenAPI 规范生成packages/open-api/lib输出karakeep-openapi-spec.jsonpackages/sdk面向外部开发者的 SDKpackages/sdk/srcpackages/benchmarks基准测试工具packages/benchmarks/srcpackages/e2e_testsPlaywright 端到端测试packages/e2e_tests/tests提示如果你的分支基于 v0.28.0则只存在db、trpc、shared三个共享包对照最新代码时请以上表为准。四、Toolings共享工程化配置v0.28.0 文档的 Toolings 表DirectoryDescriptiontooling/typescriptThe shared tsconfigstooling/eslintESlint configstooling/prettierPrettier configstooling/tailwindShared tailwind configs各配置包均以workspace:*形式被各应用引用例如apps/web的 devDependencies 中的karakeep/tsconfig与karakeep/tailwind-config从而保证全仓风格一致tooling/typescript共享 tsconfig 基底包括 tooling/typescript/base.json通用严格配置与 tooling/typescript/node.jsonNode 环境变体各应用在此基础上做少量覆盖tooling/tailwind共享 Tailwind 主题配置tooling/tailwind/base.ts 定义基础 tokenweb.ts 与 native.ts 分别面向 Web 与 React NativeNativeWind输出tooling/prettier统一格式化配置tooling/prettier/index.jstooling/eslint→ 当前为tooling/oxlint这是与 v0.28.0 文档差异最大的一处。当前仓库已无独立tooling/eslint目录取而代之的是 tooling/oxlint含oxlint-base.json、oxlint-react.json、oxlint-nextjs.json各应用的 lint/format 脚本也统一为oxlint与oxfmt可参见 apps/web/package.json。另有tooling/github存放 CI 工作流配置。五、文档、部署与周边目录除上述三大类外仓库根目录还包含支撑项目运转的周边目录docsDocusaurus 文档站含当前版本文档docs/docs开发指南见 08-development 目录与versioned_docsv0.28.0v0.33.0 各版本快照本文件即 v0.28.0 开发文档 对应的版本化副本以及 api 子目录 中的 OpenAPI 接口文档MDXdocker 与 docker-compose.yml容器化部署含带 Chrome 的 worker 镜像 docker/chromecharts、kubernetesKubernetes/Helm 部署清单snapshots演示数据快照JSON 与 tar.gzskills 与 AGENTS.md、CLAUDE.md面向 AI Agent 的开发指引根级 package.json 与 start-dev.sh工作区脚本与开发启动入口。六、基于目录结构的开发速查结合上文日常开发可以按入口在哪—逻辑在哪—数据在哪三步定位找页面/UI去 apps/web/app 与 apps/web/components移动端则去 apps/mobile/app 与 apps/mobile/components找业务逻辑去 packages/trpc/routers 按领域找对应路由配套测试同目录找数据模型去 packages/db/schema.ts 与 packages/db/drizzle 查看表结构与迁移找后台任务去 apps/workers/workers 按 Worker 类型定位改共享逻辑先判断是否跨端复用——是则放入 packages/shared仅服务端用则考虑 packages/shared-server。开发环境搭建请遵循 docs/docs/08-development/01-setup.md 与根目录 start-dev.sh 的说明各应用的具体命令dev、build、test、typecheck、lint均可在对应package.json的scripts字段中查询。七、小结Karakeep 的目录结构遵循典型的 Monorepo 分层原则apps负责表现层与运行入口packages沉淀业务逻辑与领域模型tooling统一工程规范。理解这张地图既能让你在庞大的代码库中快速定位目标文件也能让你在新增功能时判断代码该落在哪一层——这也是阅读源码、参与贡献的第一步。【免费下载链接】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），仅供参考