尧图网页设计 
Karakeep 仓库目录结构全解析从 Monorepo 分层到各模块职责【免费下载链接】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自托管书签管理应用支持链接、笔记与图片收藏并提供 AI 自动打标与全文检索v0.31.0 官方开发文档中的目录结构说明为骨架结合仓库当前源码逐层拆解apps/、packages/、tooling/等目录的职责边界与依赖关系。读完本文你将能快速定位 Web 主应用、后台 Workers、移动端、浏览器扩展与落地页的代码位置理解数据库 Schema、tRPC 业务逻辑、共享工具包的划分逻辑并掌握在 monorepo 中新增或修改模块时的正确落点。整体布局pnpm Turbo 驱动的 Monorepo 三层结构Karakeep 采用 pnpm workspace 管理的 monorepo 仓库根目录下的 pnpm-workspace.yaml 定义了全部工作区成员packages/*、apps/*、tooling/*、tools/*与docs。其中nodeLinker: hoisted将依赖提升到根node_modules同时通过overrides如将vite锁定为 7.0.6、React 全家桶锁定为 19.2.x保证跨应用依赖版本一致——例如 React Native 对 React 精确版本有运行时断言整个工作区必须使用同一版本。任务编排统一交给 turbo.jsonbuild、lint、typecheck、test等任务按^topo依赖拓扑序执行dev任务声明为persistent且不缓存保证 Web 与 Workers 可以并行常驻运行。根目录 package.json 提供了大量一键脚本例如pnpm web启动 Web 应用等价于pnpm --filter karakeep/web run devpnpm workers启动后台 Workerspnpm db:generate/pnpm db:migrate/pnpm db:studio数据库迁移与可视化pnpm android/pnpm ios构建移动端pnpm lint/pnpm test/pnpm typecheck/pnpm preflight全仓库质量检查。官方开发文档将整个仓库划分为三层Apps可运行的应用、Shared Packages共享包与Toolings工程化配置。下文逐一展开。Apps五个可独立运行的应用目录说明apps/web主 Web 应用Next.js SQLite 存储apps/workers后台 Workers抓取、AI 打标、索引apps/mobile基于 React Native 的移动端应用apps/browser-extension浏览器扩展apps/landing项目官网落地页apps/web承载主要 UI 的 Next.js 应用apps/web/package.json 显示其核心依赖为next16.3.3、react19.2.3、drizzle-orm与better-sqlite3并大量使用radix-ui/*、shadcn/react构建 UI 组件配合i18next实现国际化语言包位于 apps/web/lib/i18n。在源码层面路由由 apps/web/app 下的 Next.js App Router 目录承载包含dashboard/、settings/、reader/、signin/、signup/、admin/等页面组页面级组件进一步拆分到 apps/web/components如dashboard/下约 100 个组件文件、ui/下的基础组件库、settings/下的设置项前端业务逻辑封装在 apps/web/libhooks、store、拖拽、附件、阅读器设置等服务端认证逻辑位于 apps/web/server。apps/workers全部后台任务逻辑apps/workers/package.json 揭示了 Worker 的技术选型playwrightplaywright-extra驱动无头 Chrome 抓取页面mozilla/readability与metascraper系列提取可读内容与元信息tesseract.js做 OCRpdf2json/pdfjs-dist处理 PDFliteque作为 SQLite 队列实现hono提供内部 HTTP 服务。启动脚本start使用tsx watch index.ts。从官方架构文档见 version-v0.31.0 架构说明可知Workers 消费基于 SQLite 的任务队列处理三类任务抓取Crawling使用运行在 Workers 容器内的无头 Chrome 获取链接内容AI 打标OpenAI调用 OpenAI API 为内容推断标签索引Indexing将内容写入 Meilisearch加速搜索检索。对应实现位于 apps/workers/workerscrawlerWorker.ts、embeddingsWorker.ts、searchWorker.ts、videoWorker.ts、importWorker.ts、ruleEngineWorker.ts、webhookWorker.ts等每个 Worker 处理一类领域任务抓取相关的爬虫逻辑再细分到crawler/子目录。apps/mobileReact Native 移动端apps/mobile/package.json 表明其基于expo~56react-native0.85.3使用expo-router做路由、nativewind做样式、tanstack/react-query做服务端状态管理并通过 tRPC 客户端直连后端。源码布局上apps/mobile/app 存放路由页面dashboard、signin、sharing、test-connection 等apps/mobile/components 按业务域拆分bookmarks、highlights、lists、reader、search、settings、sharing、uiapps/mobile/lib 承载客户端配置、离线缓存offlineCache.ts、offlineLibrary.ts、会话、分享、上传等逻辑平台相关插件放在 apps/mobile/plugins如trust-local-certs.js用于信任本地证书以连接自托管实例。apps/browser-extension浏览器扩展apps/browser-extension/package.json 使用vitecrxjs/vite-plugin构建依赖single-file-core实现整页归档保存。其结构包括background/后台脚本、content-scripts/内容脚本、components/弹出页 UI、utils/与SavePage.tsx、OptionsPage.tsx、SignInPage.tsx等页面。开发时运行pnpm dev生成dist目录再在浏览器中以“加载已解压的扩展程序”方式引入。apps/landing官网落地页apps/landing/package.json 显示其基于astro^6构建集成astrojs/react、astrojs/sitemap样式使用 Tailwind。页面源码位于 apps/landing/srcHomepage、Pricing、Privacy、Terms、Navbar 等定价数据与文案分别维护在pricing-data.ts与pricing-markdown.ts。Shared Packages共享代码与业务逻辑目录说明packages/db数据库 Schema 与迁移脚本packages/trpc大部分业务逻辑以 tRPC 路由形式实现packages/shared各应用间的共享代码logger、config、assetdb 等packages/db数据库 Schema 与迁移packages/db/package.json 以better-sqlite3drizzle-orm为核心提供migratetsx migrate.ts、generatedrizzle-kit generate、studiodrizzle-kit studio三个脚本。核心文件包括packages/db/schema.ts全部表结构定义packages/db/drizzle25 个 SQL 迁移文件及meta/下的迁移元数据packages/db/migrate.ts 与 packages/db/index.ts迁移与连接入口。开发流程中修改schema.ts后执行pnpm db:generate生成迁移再通过pnpm db:migrate应用到本地数据库。packages/trpc业务逻辑主战场官方文档明确指出“大部分业务逻辑以 tRPC 路由形式位于此处”。从 packages/trpc/package.json 看它依赖karakeep/db、karakeep/shared、karakeep/shared-server与trpc/server11并集成stripe订阅计费、nodemailer邮件、bcryptjs密码哈希、turndownHTML 转 Markdown、superjson序列化。其内部结构清晰packages/trpc/routers36 个业务路由文件覆盖书签、列表、标签、高亮、用户、管理、订阅等packages/trpc/models数据模型定义packages/trpc/lib路由实现所需的底层库函数。Web、移动端、浏览器扩展均通过 tRPC 客户端调用这些路由因此业务逻辑只需在此实现一次即可被所有前端复用。packages/shared跨应用共享代码packages/shared 存放不依赖特定运行时的通用代码包括config.ts全局配置logger.ts日志工具assetdb.ts附件/资产存储抽象types/19 个类型文件与utils/14 个工具文件search.ts、searchQueryParser.ts搜索与查询语言解析signedTokens.ts签名令牌prompts.ts/prompts.server.tsAI 打标提示词import-export/导入导出格式支持。此外还有若干围绕核心业务包的支撑包packages/apiHTTP 中间件与公开路由、packages/shared-server服务端共享逻辑、packages/shared-react跨端 React hooks 与组件、packages/plugins可插拔的存储/队列/搜索/限流实现、packages/sdk客户端 SDK、packages/open-apiOpenAPI 规范生成、packages/e2e_tests端到端测试。Toolings统一的工程化配置目录说明tooling/typescript共享 tsconfigtooling/eslintESLint 配置tooling/prettierPrettier 配置tooling/tailwind共享 Tailwind 配置说明v0.31.0 文档中的目录表沿用了早期版本的命名而当前仓库的实际实现略有演进——各工具包位于 tooling 下其中 TypeScript 基础配置在 tooling/typescriptbase.json、node.jsonTailwind 配置在 tooling/tailwindbase.ts、web.ts、native.ts、globals.cssPrettier 配置在 tooling/prettier。全仓库的 lint 已统一使用oxlint规则见 tooling/oxlint格式化统一使用oxfmt二者分别替代了传统 ESLint/Prettier 的日常角色各应用与包的package.json中均通过karakeep/tsconfig、karakeep/tailwind-config等 workspace 依赖引用这些共享配置。围绕目录结构的开发实操建议结合官方开发文档version-v0.31.0 开发环境搭建将上述目录知识落到实际开发流程中快速启动根目录运行./start-dev.sh脚本会自动拉起 Meilisearch端口 7700与无头 Chrome端口 9222容器、按需pnpm install并并行启动 Webhttp://localhost:3000与 Workers环境变量将.env.sample复制为.env至少设置DATA_DIR数据库与附件存储目录、NEXTAUTH_SECRET可用openssl rand -base64 36生成、MEILI_ADDR未设置则搜索禁用、OPENAI_API_KEY开启 AI 自动打标并在apps/web、apps/workers、packages/db等目录做好符号链接或各自配置数据库初始化pnpm db:migrate应用迁移修改 packages/db/schema.ts 后用pnpm db:generate生成新迁移业务开发大部分业务改动落在packages/trpc/routers与各应用 UI 目录通用逻辑放入packages/shared跨端 React 逻辑放入packages/shared-react质量门禁提交前可运行pnpm preflighttypecheck lint format或pnpm test这些任务由 Turbo 按依赖拓扑并发执行。小结三层结构的依赖方向Karakeep 的 monorepo 遵循清晰的依赖方向apps/*入口应用依赖packages/*共享包packages/*之间按需互相依赖如trpc→db、shared、shared-servertooling/*仅作为开发期配置被各包引用。理解这一分层后无论是排查 Web 端某个行为、给抓取 Worker 增加解析逻辑还是为移动端新增设置页你都能第一时间定位到正确的源码目录。【免费下载链接】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），仅供参考 Karakeep 仓库目录结构全解析：从 Monorepo 分层到各模块职责
Karakeep 仓库目录结构全解析从 Monorepo 分层到各模块职责【免费下载链接】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自托管书签管理应用支持链接、笔记与图片收藏并提供 AI 自动打标与全文检索v0.31.0 官方开发文档中的目录结构说明为骨架结合仓库当前源码逐层拆解apps/、packages/、tooling/等目录的职责边界与依赖关系。读完本文你将能快速定位 Web 主应用、后台 Workers、移动端、浏览器扩展与落地页的代码位置理解数据库 Schema、tRPC 业务逻辑、共享工具包的划分逻辑并掌握在 monorepo 中新增或修改模块时的正确落点。整体布局pnpm Turbo 驱动的 Monorepo 三层结构Karakeep 采用 pnpm workspace 管理的 monorepo 仓库根目录下的 pnpm-workspace.yaml 定义了全部工作区成员packages/*、apps/*、tooling/*、tools/*与docs。其中nodeLinker: hoisted将依赖提升到根node_modules同时通过overrides如将vite锁定为 7.0.6、React 全家桶锁定为 19.2.x保证跨应用依赖版本一致——例如 React Native 对 React 精确版本有运行时断言整个工作区必须使用同一版本。任务编排统一交给 turbo.jsonbuild、lint、typecheck、test等任务按^topo依赖拓扑序执行dev任务声明为persistent且不缓存保证 Web 与 Workers 可以并行常驻运行。根目录 package.json 提供了大量一键脚本例如pnpm web启动 Web 应用等价于pnpm --filter karakeep/web run devpnpm workers启动后台 Workerspnpm db:generate/pnpm db:migrate/pnpm db:studio数据库迁移与可视化pnpm android/pnpm ios构建移动端pnpm lint/pnpm test/pnpm typecheck/pnpm preflight全仓库质量检查。官方开发文档将整个仓库划分为三层Apps可运行的应用、Shared Packages共享包与Toolings工程化配置。下文逐一展开。Apps五个可独立运行的应用目录说明apps/web主 Web 应用Next.js SQLite 存储apps/workers后台 Workers抓取、AI 打标、索引apps/mobile基于 React Native 的移动端应用apps/browser-extension浏览器扩展apps/landing项目官网落地页apps/web承载主要 UI 的 Next.js 应用apps/web/package.json 显示其核心依赖为next16.3.3、react19.2.3、drizzle-orm与better-sqlite3并大量使用radix-ui/*、shadcn/react构建 UI 组件配合i18next实现国际化语言包位于 apps/web/lib/i18n。在源码层面路由由 apps/web/app 下的 Next.js App Router 目录承载包含dashboard/、settings/、reader/、signin/、signup/、admin/等页面组页面级组件进一步拆分到 apps/web/components如dashboard/下约 100 个组件文件、ui/下的基础组件库、settings/下的设置项前端业务逻辑封装在 apps/web/libhooks、store、拖拽、附件、阅读器设置等服务端认证逻辑位于 apps/web/server。apps/workers全部后台任务逻辑apps/workers/package.json 揭示了 Worker 的技术选型playwrightplaywright-extra驱动无头 Chrome 抓取页面mozilla/readability与metascraper系列提取可读内容与元信息tesseract.js做 OCRpdf2json/pdfjs-dist处理 PDFliteque作为 SQLite 队列实现hono提供内部 HTTP 服务。启动脚本start使用tsx watch index.ts。从官方架构文档见 version-v0.31.0 架构说明可知Workers 消费基于 SQLite 的任务队列处理三类任务抓取Crawling使用运行在 Workers 容器内的无头 Chrome 获取链接内容AI 打标OpenAI调用 OpenAI API 为内容推断标签索引Indexing将内容写入 Meilisearch加速搜索检索。对应实现位于 apps/workers/workerscrawlerWorker.ts、embeddingsWorker.ts、searchWorker.ts、videoWorker.ts、importWorker.ts、ruleEngineWorker.ts、webhookWorker.ts等每个 Worker 处理一类领域任务抓取相关的爬虫逻辑再细分到crawler/子目录。apps/mobileReact Native 移动端apps/mobile/package.json 表明其基于expo~56react-native0.85.3使用expo-router做路由、nativewind做样式、tanstack/react-query做服务端状态管理并通过 tRPC 客户端直连后端。源码布局上apps/mobile/app 存放路由页面dashboard、signin、sharing、test-connection 等apps/mobile/components 按业务域拆分bookmarks、highlights、lists、reader、search、settings、sharing、uiapps/mobile/lib 承载客户端配置、离线缓存offlineCache.ts、offlineLibrary.ts、会话、分享、上传等逻辑平台相关插件放在 apps/mobile/plugins如trust-local-certs.js用于信任本地证书以连接自托管实例。apps/browser-extension浏览器扩展apps/browser-extension/package.json 使用vitecrxjs/vite-plugin构建依赖single-file-core实现整页归档保存。其结构包括background/后台脚本、content-scripts/内容脚本、components/弹出页 UI、utils/与SavePage.tsx、OptionsPage.tsx、SignInPage.tsx等页面。开发时运行pnpm dev生成dist目录再在浏览器中以“加载已解压的扩展程序”方式引入。apps/landing官网落地页apps/landing/package.json 显示其基于astro^6构建集成astrojs/react、astrojs/sitemap样式使用 Tailwind。页面源码位于 apps/landing/srcHomepage、Pricing、Privacy、Terms、Navbar 等定价数据与文案分别维护在pricing-data.ts与pricing-markdown.ts。Shared Packages共享代码与业务逻辑目录说明packages/db数据库 Schema 与迁移脚本packages/trpc大部分业务逻辑以 tRPC 路由形式实现packages/shared各应用间的共享代码logger、config、assetdb 等packages/db数据库 Schema 与迁移packages/db/package.json 以better-sqlite3drizzle-orm为核心提供migratetsx migrate.ts、generatedrizzle-kit generate、studiodrizzle-kit studio三个脚本。核心文件包括packages/db/schema.ts全部表结构定义packages/db/drizzle25 个 SQL 迁移文件及meta/下的迁移元数据packages/db/migrate.ts 与 packages/db/index.ts迁移与连接入口。开发流程中修改schema.ts后执行pnpm db:generate生成迁移再通过pnpm db:migrate应用到本地数据库。packages/trpc业务逻辑主战场官方文档明确指出“大部分业务逻辑以 tRPC 路由形式位于此处”。从 packages/trpc/package.json 看它依赖karakeep/db、karakeep/shared、karakeep/shared-server与trpc/server11并集成stripe订阅计费、nodemailer邮件、bcryptjs密码哈希、turndownHTML 转 Markdown、superjson序列化。其内部结构清晰packages/trpc/routers36 个业务路由文件覆盖书签、列表、标签、高亮、用户、管理、订阅等packages/trpc/models数据模型定义packages/trpc/lib路由实现所需的底层库函数。Web、移动端、浏览器扩展均通过 tRPC 客户端调用这些路由因此业务逻辑只需在此实现一次即可被所有前端复用。packages/shared跨应用共享代码packages/shared 存放不依赖特定运行时的通用代码包括config.ts全局配置logger.ts日志工具assetdb.ts附件/资产存储抽象types/19 个类型文件与utils/14 个工具文件search.ts、searchQueryParser.ts搜索与查询语言解析signedTokens.ts签名令牌prompts.ts/prompts.server.tsAI 打标提示词import-export/导入导出格式支持。此外还有若干围绕核心业务包的支撑包packages/apiHTTP 中间件与公开路由、packages/shared-server服务端共享逻辑、packages/shared-react跨端 React hooks 与组件、packages/plugins可插拔的存储/队列/搜索/限流实现、packages/sdk客户端 SDK、packages/open-apiOpenAPI 规范生成、packages/e2e_tests端到端测试。Toolings统一的工程化配置目录说明tooling/typescript共享 tsconfigtooling/eslintESLint 配置tooling/prettierPrettier 配置tooling/tailwind共享 Tailwind 配置说明v0.31.0 文档中的目录表沿用了早期版本的命名而当前仓库的实际实现略有演进——各工具包位于 tooling 下其中 TypeScript 基础配置在 tooling/typescriptbase.json、node.jsonTailwind 配置在 tooling/tailwindbase.ts、web.ts、native.ts、globals.cssPrettier 配置在 tooling/prettier。全仓库的 lint 已统一使用oxlint规则见 tooling/oxlint格式化统一使用oxfmt二者分别替代了传统 ESLint/Prettier 的日常角色各应用与包的package.json中均通过karakeep/tsconfig、karakeep/tailwind-config等 workspace 依赖引用这些共享配置。围绕目录结构的开发实操建议结合官方开发文档version-v0.31.0 开发环境搭建将上述目录知识落到实际开发流程中快速启动根目录运行./start-dev.sh脚本会自动拉起 Meilisearch端口 7700与无头 Chrome端口 9222容器、按需pnpm install并并行启动 Webhttp://localhost:3000与 Workers环境变量将.env.sample复制为.env至少设置DATA_DIR数据库与附件存储目录、NEXTAUTH_SECRET可用openssl rand -base64 36生成、MEILI_ADDR未设置则搜索禁用、OPENAI_API_KEY开启 AI 自动打标并在apps/web、apps/workers、packages/db等目录做好符号链接或各自配置数据库初始化pnpm db:migrate应用迁移修改 packages/db/schema.ts 后用pnpm db:generate生成新迁移业务开发大部分业务改动落在packages/trpc/routers与各应用 UI 目录通用逻辑放入packages/shared跨端 React 逻辑放入packages/shared-react质量门禁提交前可运行pnpm preflighttypecheck lint format或pnpm test这些任务由 Turbo 按依赖拓扑并发执行。小结三层结构的依赖方向Karakeep 的 monorepo 遵循清晰的依赖方向apps/*入口应用依赖packages/*共享包packages/*之间按需互相依赖如trpc→db、shared、shared-servertooling/*仅作为开发期配置被各包引用。理解这一分层后无论是排查 Web 端某个行为、给抓取 Worker 增加解析逻辑还是为移动端新增设置页你都能第一时间定位到正确的源码目录。【免费下载链接】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），仅供参考