KarakeepHoarder本地开发环境搭建完整指南一键脚本、手动配置与 Docker Compose 全流程【免费下载链接】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 本地开发环境搭建实战指南围绕官方开发文档docs/versioned_docs/version-v0.31.0/08-development/01-setup.md展开覆盖start-dev.sh一键启动、Node 24 corepack pnpm 手动安装、环境变量与数据库初始化、Meilisearch 与无头 Chrome 依赖、Web/Workers/Mobile/浏览器扩展四大应用的启动方式以及基于 Docker Compose 的容器化开发环境。读完本文你将掌握从零启动整套 Karakeep 前后端开发环境所需的全部命令、配置与排错要点。一、开发环境概览一套本地开发环境由哪些进程组成Karakeep原 Hoarder是一个基于 pnpm workspace 的 monorepo根目录的 package.json 定义了 Turbo 任务编排仓库主要包含以下可独立运行的应用apps/webNext.js 前端 Web 应用脚本pnpm web对应pnpm --filter karakeep/web run devapps/workers后台 Worker 应用脚本pnpm workers负责爬取、索引、导入、推理等异步任务apps/mobile基于 Expo 的 iOS / Android 移动端apps/browser-extension基于 Vite CRX 的浏览器扩展packages/db基于 Drizzle ORM 的 SQLite 数据库包提供迁移能力。要让整套环境真正“跑起来”除了上述应用本身还需要两个外部依赖Meilisearch全文搜索与向量检索的提供方和无头 ChromeWorker 爬取网页时的浏览器环境。开发文档明确提醒Web 应用在没有任何依赖的情况下也能基本运行但搜索功能必须依赖 Meilisearch新收藏的书签也只有在 Workers 运行时才会被爬取和索引。二、快速开始一条命令启动整套开发环境开发文档推荐的首选路径是仓库根目录下的./start-dev.sh./start-dev.sh该脚本会自动完成以下工作与 start-dev.sh 源码一一对应启动 Meilisearch通过docker run -d -p 7700:7700 --name karakeep-meilisearch getmeili/meilisearch:v1.41.0启动当前仓库中使用的镜像版本为 v1.41.0v0.31.0 版本文档中写的是 v1.37.0以仓库实际为准启动无头 Chromedocker run -d --init -p 127.0.0.1:9222:9222 --name karakeep-chrome ghcr.io/karakeep-app/karakeep-chrome:release并附带--disable-gpu --disable-dev-shm-usage --hide-scrollbars --disable-blink-featuresAutomationControlled --window-size1440,900等参数安装依赖若根目录不存在node_modules自动执行pnpm install执行数据库迁移运行pnpm run db:migrate并行启动 Web 与 Workers后台执行pnpm web与pnpm workers并等待 Web 应用在 3000 端口就绪使用nc -z localhost 3000最多探测 30 秒。脚本启动后会输出三个可直接访问的服务地址Web 应用http://localhost:3000Meilisearchhttp://localhost:7700Chrome 调试器http://localhost:9222前置条件本机已安装并运行 Docker且已安装 pnpm安装方式见下文手动搭建章节。值得注意的细节脚本会先通过lsof -i :端口检查 7700 与 9222 端口是否已被占用已占用则复用现有容器而非重复启动DATA_DIR会从环境变量或.env文件中读取若不存在会自动创建目录按CtrlC时trap cleanup SIGINT SIGTERM会依次 kill 掉 Web/Workers 进程并docker stop/docker rm清理两个容器。三、手动搭建从零配置开发环境如果希望完全掌控每一步可以走手动搭建路线。Karakeep 的开发环境对 Node 版本有明确要求且依赖 corepack 来管理包管理器版本。3.1 安装 Node.js 24 与启用 corepackKarakeep 要求 Nodev24版本推荐使用 nvm 安装$ nvm install 24安装后验证版本$ node --version v24.14.0项目使用 corepack 锁定包管理器版本——根目录 package.json 中声明了packageManager: pnpm11.2.1。由于 corepack 随 Node 一起分发安装 Node 后通常无需额外操作可先确认其存在$ command -v corepack /home/user/.nvm/versions/node/v24.14.0/bin/corepack若尚未启用执行$ corepack enable容器化开发环境同样遵循这一约定docker/Dockerfile.dev 基于node:24-alpine构建并在镜像内执行corepack enable。3.2 安装依赖pnpm install在仓库根目录执行$ pnpm install一次成功的安装输出大致如下Scope: all 20 workspace projects Lockfile is up to date, resolution step is skipped Packages: 3129 Progress: resolved 0, reused 2699, downloaded 0, added 3129, done devDependencies: karakeep/prettier-config 0.1.0 - tooling/prettier . prepare$ husky └─ Done in 45ms Done in 5.5s从中可以看到仓库共 20 个 workspace 子项目安装过程会触发prepare钩子执行 huskyGit 钩子工具依赖复用率较高reused 2699。安装完成后即可继续后续配置。四、首次配置环境变量与数据库初始化4.1 准备环境变量开发环境的每个应用都需要读取环境变量。最省事的做法是在仓库根目录配置一次.env然后在各应用目录如apps/web、apps/workers以及packages/db下用符号链接指向它。首先从模板复制$ cp .env.sample .env仓库根目录的 .env.sample 内容非常精简仅包含两个占位变量# See https://docs.karakeep.app/configuration for more information DATA_DIRpath NEXTAUTH_SECRETsecret开发文档强调的四个关键变量如下变量作用说明DATA_DIR数据库与资产的存放目录唯一必填项。建议使用绝对路径让所有应用指向同一目录NEXTAUTH_SECRET用于签名 JWT 的随机字符串缺失时登录功能将不可用可用openssl rand -base64 36生成MEILI_ADDRMeilisearch 服务地址未设置时搜索功能会被禁用本地可用http://127.0.0.1:7700OPENAI_API_KEYOpenAI API 密钥仅在开发环境启用 AI 自动打标签auto tag inference时需要从源码层面看所有环境变量的解析集中在 packages/shared/config.ts它用 zod 定义了完整的allEnvschema 并对process.env进行校验。其中有几个与本文直接相关的实现细节DATA_DIR默认值为空字符串ASSETS_DIR未设置时会回退为path.join(DATA_DIR, assets)NEXTAUTH_SECRET通过signingSecret()延迟求值未设置时会直接抛出NEXTAUTH_SECRET is not set异常——这与文档“登录将不可用”的警告在代码层面完全吻合MEILI_ADDR未设置时搜索链路不会初始化索引所有配置最终通过serverConfigSchema.parse(process.env)生成只读的serverConfig并单独挑出clientConfig暴露给前端避免敏感信息泄漏。4.2 初始化数据库环境变量就绪后在仓库根目录执行$ pnpm run db:migrate该命令实际执行pnpm --filter karakeep/db run migrate见 package.json即packages/db中的tsx migrate.ts。packages/db/migrate.ts 的实现很简洁若serverConfig.degradedMode降级模式开启则跳过迁移否则调用 Drizzle 的migrate(db, { migrationsFolder: ./drizzle })。迁移 SQL 文件位于packages/db/drizzle/目录从0000_luxuriant_johnny_blaze.sql到0025_aspiring_skaar.sql均由drizzle-kit generate生成。数据库本身是 SQLitebetter-sqlite3驱动见 packages/db/package.json。五、本地依赖Meilisearch 与 Chrome5.1 Meilisearch全文搜索与向量检索的提供方Meilisearch 是 Karakeep 全文搜索未来还包括 embeddings 向量搜索的提供方。手动启动方式$ docker run -p 7700:7700 getmeili/meilisearch:v1.41.0两个实操要点如需跨重启保留索引数据请挂载持久化卷若需对整个书签集合重新建索引可在 Web 应用的**管理面板admin panel**中触发全量 re-index。在 Docker 开发环境中Meilisearch 以独立 service 运行并设置了MEILI_NO_ANALYTICStrue与MEILI_MASTER_KEY见下文第九章与 docker/docker-compose.dev.yml。5.2 ChromeWorker 爬虫的浏览器环境Worker 应用启动时会自动启动无头 Chrome用于爬取页面开发环境下通常无需手动干预。从配置角度看爬虫连接 Chrome 的方式由BROWSER_WEB_URLHTTP 调试端口如http://chrome:9222或BROWSER_WEBSOCKET_URL等变量控制见 packages/shared/config.ts 中crawler配置段。CRAWLER_HEADLESS_BROWSER默认开启即爬虫默认依赖无头浏览器抓取页面内容。六、启动 Web 应用与 Workers6.1 Web 应用在仓库根目录运行$ pnpm web然后访问 http://localhost:3000 即可。需要特别说明的是依赖关系开发文档中的 NOTE 原文强调Web 应用在没有依赖的情况下也能基本运行。但搜索功能只有在 meilisearch 运行时才可用此外新添加的书签只有在 workers 运行时才会被爬取和索引。换句话说纯看界面可以不启动任何外部服务但要完整体验“保存书签 → 自动爬取 → 全文搜索 → AI 打标签”的闭环Meilisearch、Workers 与 OpenAI 配置缺一不可。6.2 Workers在仓库根目录另开终端运行$ pnpm workersWorkers 承载了 Karakeep 的大量异步能力。从 apps/workers 的源码结构看Worker 类型包括crawler页面爬取、inferenceAI 推理/打标签/摘要、search搜索索引、embeddings向量嵌入、import导入、feedRSS 订阅、webhook、backup、ruleEngine、assetPreprocessing 等分别对应apps/workers/workers/下的各个 Worker 文件。WORKERS_ENABLED_WORKERS/WORKERS_DISABLED_WORKERS环境变量可以按需启停特定 Worker见 packages/shared/config.ts。七、移动端开发iOS Android7.1 前置条件要本地构建并运行移动应用需要iOS 开发macOS 电脑、从 App Store 安装 Xcode、随 Xcode 附带的 iOS SimulatorAndroid 开发安装 Android Studio、配置 Android SDK、准备 Android Emulator 或真机。详细的本地开发环境搭建可参考 Expo 官方文档local app development 指南。7.2 构建并运行进入移动端目录并预构建原生工程$ cd apps/mobile $ pnpm exec expo prebuild --no-installiOS$ pnpm exec expo run:ios应用会被安装并启动到模拟器中。iOS 排错如果遇到类似xcrun: error: SDK iphoneos cannot be located的错误可能是 Xcode 开发者目录未指向正确位置可执行sudo xcode-select -s /Applications/Xcode.app/Contents/DeveloperAndroid$ pnpm exec expo run:android应用会被安装并启动到模拟器/真机上。代码改动会触发热重载hot reload但安装新依赖包后需要重启 expo server才能生效。从当前仓库 apps/mobile/package.json 的脚本来看移动端提供了更细分的运行入口pnpm ios/pnpm androiddevelopment 变体、ios:preview/android:preview独立 bundle ID、无需 devserver 的预览变体、ios:release/android:release接近生产构建的 release 变体并通过APP_VARIANT环境变量控制。日常开发 90% 的情况下使用 development 变体即可如果从旧版本升级后构建失败如 Expo 大版本升级残留了过期的原生构建产物可先执行pnpm run clean:workspaces、pnpm install与pnpm --filter karakeep/mobile clean:prebuild清理后重新构建。八、浏览器扩展开发浏览器扩展的开发步骤如下$ cd apps/browser-extension $ pnpm dev执行后Vite 会生成dist产物目录扩展开发服务器默认运行在 http://localhost:5174。然后打开浏览器扩展管理页Chrome 的chrome://extensions或 Brave 对应页面开启“开发者模式”Developer mode点击“Load unpacked”加载已解压的扩展程序选择apps/browser-extension/dist目录扩展会出现在扩展列表中。开发模式下打开和关闭扩展弹窗即会重新加载代码无需手动刷新整个扩展。从 apps/browser-extension/package.json 可以看到dev脚本直接调用vite构建链路为tsc vite build并依赖crxjs/vite-plugin来生成符合 Chrome Manifest V3 规范的扩展产物。九、基于 Docker Compose 的开发环境如果手动搭建过于繁琐官方文档还提供了一条容器化路径在仓库根目录执行$ docker compose -f docker/docker-compose.dev.yml upv0.31.0 版本文档对这套方案的评价比较谨慎原文称“这套方案对我来说不算特别可靠”但当前仓库中的 docker/docker-compose.dev.yml 已经演进得相当完整共编排了五个服务服务作用prep一次性任务创建DATA_DIR默认为/data、执行pnpm install --frozen-lockfile、执行pnpm run db:migrate为其他服务准备好依赖与数据库web运行pnpm webNext.js dev server映射宿主机 3000 端口开启WATCHPACK_POLLING/CHOKIDAR_USEPOLLING以在 Mac/Windows 文件同步下可靠触发热重载workers运行pnpm workers与本地开发行为一致meilisearch内部服务仅容器网络内可访问宿主机不暴露端口禁用遥测并挂载持久化数据卷chrome供 Workers 使用的可远程调试 Chrome 实例映射到 9222 端口几个关键的编排细节值得开发者注意默认环境变量即使不创建.envcompose 文件也会通过${VAR:-default}语法注入合理默认值——DATA_DIR/data、MEILI_ADDRhttp://meilisearch:7700、NEXTAUTH_URLhttp://localhost:3000、NEXTAUTH_SECRETsuper-secure-nextauth-secret必须覆盖的变量NEXTAUTH_SECRET默认值只用于开发演示正式使用前应至少通过.env覆盖用openssl rand -base64 36生成可选的OPENAI_API_KEY等也建议写进.env数据挂载data:${DATA_DIR:-/data}默认将数据存入 Docker volume如需改用宿主机目录可修改 volume 映射为/path/to/your/directory:/data共享卷所有应用容器把宿主仓库挂载到/app并共享node_modules依赖装在 Linux 容器内与pnpm-storepnpm 缓存两个卷日志与清理docker compose logs -f web workers跟踪日志docker compose down停止全部服务改动 Node 依赖或 Dockerfile 后需加--build重建docker compose down -v可彻底清空数据卷获得全新状态。十、常见问题与排查建议结合开发文档与仓库源码整理开发中最高频的几类问题及对应排查方向登录/认证失效检查NEXTAUTH_SECRET是否设置。源码层面 packages/shared/config.ts 会在其缺失时直接抛错确保所有应用尤其是 Web 与 Workers读取的是同一个.env建议符号链接共享搜索不可用确认MEILI_ADDR已设置且 Meilisearch 在 7700 端口可达docker ps或直接访问 http://localhost:7700本地重启后索引数据丢失可挂载持久化卷并在管理面板触发全量 re-index新收藏书签没有被爬取/索引确认pnpm workers正在运行同时确认 9222 端口的无头 Chrome 可访问BROWSER_WEB_URL指向正确Node 版本不匹配node --version必须是 v24 系列nvm 切换后记得重新corepack enable与pnpm installiOS 构建报xcrun: error: SDK iphoneos cannot be located执行sudo xcode-select -s /Applications/Xcode.app/Contents/Developer修正开发者目录移动端升级后构建失败清理过期原生产物按pnpm run clean:workspaces→pnpm install→pnpm --filter karakeep/mobile clean:prebuild顺序重建端口冲突start-dev.sh对 7700/9222 端口已有占用检测逻辑若手动启动遇到冲突可先停掉占用进程或改用其他端口并同步调整环境变量。结语Karakeep 的开发环境横跨 Web、Workers、移动端与浏览器扩展四个应用形态外加 Meilisearch 与无头 Chrome 两个外部依赖初次搭建容易在环境变量与依赖顺序上踩坑。本文以官方开发文档为骨架结合仓库内 start-dev.sh、.env.sample、package.json、packages/shared/config.ts、docker/docker-compose.dev.yml 等真实源码把“一键脚本、手动搭建、容器化开发”三条路径完整走通。上手时优先尝试./start-dev.sh需要精细化控制时再按手动流程逐步配置完整的变量清单还可参考 docs/docs/03-configuration/01-environment-variables.md目录结构说明见 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），仅供参考 Karakeep（Hoarder）本地开发环境搭建完整指南：一键脚本、手动配置与 Docker Compose 全流程
KarakeepHoarder本地开发环境搭建完整指南一键脚本、手动配置与 Docker Compose 全流程【免费下载链接】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 本地开发环境搭建实战指南围绕官方开发文档docs/versioned_docs/version-v0.31.0/08-development/01-setup.md展开覆盖start-dev.sh一键启动、Node 24 corepack pnpm 手动安装、环境变量与数据库初始化、Meilisearch 与无头 Chrome 依赖、Web/Workers/Mobile/浏览器扩展四大应用的启动方式以及基于 Docker Compose 的容器化开发环境。读完本文你将掌握从零启动整套 Karakeep 前后端开发环境所需的全部命令、配置与排错要点。一、开发环境概览一套本地开发环境由哪些进程组成Karakeep原 Hoarder是一个基于 pnpm workspace 的 monorepo根目录的 package.json 定义了 Turbo 任务编排仓库主要包含以下可独立运行的应用apps/webNext.js 前端 Web 应用脚本pnpm web对应pnpm --filter karakeep/web run devapps/workers后台 Worker 应用脚本pnpm workers负责爬取、索引、导入、推理等异步任务apps/mobile基于 Expo 的 iOS / Android 移动端apps/browser-extension基于 Vite CRX 的浏览器扩展packages/db基于 Drizzle ORM 的 SQLite 数据库包提供迁移能力。要让整套环境真正“跑起来”除了上述应用本身还需要两个外部依赖Meilisearch全文搜索与向量检索的提供方和无头 ChromeWorker 爬取网页时的浏览器环境。开发文档明确提醒Web 应用在没有任何依赖的情况下也能基本运行但搜索功能必须依赖 Meilisearch新收藏的书签也只有在 Workers 运行时才会被爬取和索引。二、快速开始一条命令启动整套开发环境开发文档推荐的首选路径是仓库根目录下的./start-dev.sh./start-dev.sh该脚本会自动完成以下工作与 start-dev.sh 源码一一对应启动 Meilisearch通过docker run -d -p 7700:7700 --name karakeep-meilisearch getmeili/meilisearch:v1.41.0启动当前仓库中使用的镜像版本为 v1.41.0v0.31.0 版本文档中写的是 v1.37.0以仓库实际为准启动无头 Chromedocker run -d --init -p 127.0.0.1:9222:9222 --name karakeep-chrome ghcr.io/karakeep-app/karakeep-chrome:release并附带--disable-gpu --disable-dev-shm-usage --hide-scrollbars --disable-blink-featuresAutomationControlled --window-size1440,900等参数安装依赖若根目录不存在node_modules自动执行pnpm install执行数据库迁移运行pnpm run db:migrate并行启动 Web 与 Workers后台执行pnpm web与pnpm workers并等待 Web 应用在 3000 端口就绪使用nc -z localhost 3000最多探测 30 秒。脚本启动后会输出三个可直接访问的服务地址Web 应用http://localhost:3000Meilisearchhttp://localhost:7700Chrome 调试器http://localhost:9222前置条件本机已安装并运行 Docker且已安装 pnpm安装方式见下文手动搭建章节。值得注意的细节脚本会先通过lsof -i :端口检查 7700 与 9222 端口是否已被占用已占用则复用现有容器而非重复启动DATA_DIR会从环境变量或.env文件中读取若不存在会自动创建目录按CtrlC时trap cleanup SIGINT SIGTERM会依次 kill 掉 Web/Workers 进程并docker stop/docker rm清理两个容器。三、手动搭建从零配置开发环境如果希望完全掌控每一步可以走手动搭建路线。Karakeep 的开发环境对 Node 版本有明确要求且依赖 corepack 来管理包管理器版本。3.1 安装 Node.js 24 与启用 corepackKarakeep 要求 Nodev24版本推荐使用 nvm 安装$ nvm install 24安装后验证版本$ node --version v24.14.0项目使用 corepack 锁定包管理器版本——根目录 package.json 中声明了packageManager: pnpm11.2.1。由于 corepack 随 Node 一起分发安装 Node 后通常无需额外操作可先确认其存在$ command -v corepack /home/user/.nvm/versions/node/v24.14.0/bin/corepack若尚未启用执行$ corepack enable容器化开发环境同样遵循这一约定docker/Dockerfile.dev 基于node:24-alpine构建并在镜像内执行corepack enable。3.2 安装依赖pnpm install在仓库根目录执行$ pnpm install一次成功的安装输出大致如下Scope: all 20 workspace projects Lockfile is up to date, resolution step is skipped Packages: 3129 Progress: resolved 0, reused 2699, downloaded 0, added 3129, done devDependencies: karakeep/prettier-config 0.1.0 - tooling/prettier . prepare$ husky └─ Done in 45ms Done in 5.5s从中可以看到仓库共 20 个 workspace 子项目安装过程会触发prepare钩子执行 huskyGit 钩子工具依赖复用率较高reused 2699。安装完成后即可继续后续配置。四、首次配置环境变量与数据库初始化4.1 准备环境变量开发环境的每个应用都需要读取环境变量。最省事的做法是在仓库根目录配置一次.env然后在各应用目录如apps/web、apps/workers以及packages/db下用符号链接指向它。首先从模板复制$ cp .env.sample .env仓库根目录的 .env.sample 内容非常精简仅包含两个占位变量# See https://docs.karakeep.app/configuration for more information DATA_DIRpath NEXTAUTH_SECRETsecret开发文档强调的四个关键变量如下变量作用说明DATA_DIR数据库与资产的存放目录唯一必填项。建议使用绝对路径让所有应用指向同一目录NEXTAUTH_SECRET用于签名 JWT 的随机字符串缺失时登录功能将不可用可用openssl rand -base64 36生成MEILI_ADDRMeilisearch 服务地址未设置时搜索功能会被禁用本地可用http://127.0.0.1:7700OPENAI_API_KEYOpenAI API 密钥仅在开发环境启用 AI 自动打标签auto tag inference时需要从源码层面看所有环境变量的解析集中在 packages/shared/config.ts它用 zod 定义了完整的allEnvschema 并对process.env进行校验。其中有几个与本文直接相关的实现细节DATA_DIR默认值为空字符串ASSETS_DIR未设置时会回退为path.join(DATA_DIR, assets)NEXTAUTH_SECRET通过signingSecret()延迟求值未设置时会直接抛出NEXTAUTH_SECRET is not set异常——这与文档“登录将不可用”的警告在代码层面完全吻合MEILI_ADDR未设置时搜索链路不会初始化索引所有配置最终通过serverConfigSchema.parse(process.env)生成只读的serverConfig并单独挑出clientConfig暴露给前端避免敏感信息泄漏。4.2 初始化数据库环境变量就绪后在仓库根目录执行$ pnpm run db:migrate该命令实际执行pnpm --filter karakeep/db run migrate见 package.json即packages/db中的tsx migrate.ts。packages/db/migrate.ts 的实现很简洁若serverConfig.degradedMode降级模式开启则跳过迁移否则调用 Drizzle 的migrate(db, { migrationsFolder: ./drizzle })。迁移 SQL 文件位于packages/db/drizzle/目录从0000_luxuriant_johnny_blaze.sql到0025_aspiring_skaar.sql均由drizzle-kit generate生成。数据库本身是 SQLitebetter-sqlite3驱动见 packages/db/package.json。五、本地依赖Meilisearch 与 Chrome5.1 Meilisearch全文搜索与向量检索的提供方Meilisearch 是 Karakeep 全文搜索未来还包括 embeddings 向量搜索的提供方。手动启动方式$ docker run -p 7700:7700 getmeili/meilisearch:v1.41.0两个实操要点如需跨重启保留索引数据请挂载持久化卷若需对整个书签集合重新建索引可在 Web 应用的**管理面板admin panel**中触发全量 re-index。在 Docker 开发环境中Meilisearch 以独立 service 运行并设置了MEILI_NO_ANALYTICStrue与MEILI_MASTER_KEY见下文第九章与 docker/docker-compose.dev.yml。5.2 ChromeWorker 爬虫的浏览器环境Worker 应用启动时会自动启动无头 Chrome用于爬取页面开发环境下通常无需手动干预。从配置角度看爬虫连接 Chrome 的方式由BROWSER_WEB_URLHTTP 调试端口如http://chrome:9222或BROWSER_WEBSOCKET_URL等变量控制见 packages/shared/config.ts 中crawler配置段。CRAWLER_HEADLESS_BROWSER默认开启即爬虫默认依赖无头浏览器抓取页面内容。六、启动 Web 应用与 Workers6.1 Web 应用在仓库根目录运行$ pnpm web然后访问 http://localhost:3000 即可。需要特别说明的是依赖关系开发文档中的 NOTE 原文强调Web 应用在没有依赖的情况下也能基本运行。但搜索功能只有在 meilisearch 运行时才可用此外新添加的书签只有在 workers 运行时才会被爬取和索引。换句话说纯看界面可以不启动任何外部服务但要完整体验“保存书签 → 自动爬取 → 全文搜索 → AI 打标签”的闭环Meilisearch、Workers 与 OpenAI 配置缺一不可。6.2 Workers在仓库根目录另开终端运行$ pnpm workersWorkers 承载了 Karakeep 的大量异步能力。从 apps/workers 的源码结构看Worker 类型包括crawler页面爬取、inferenceAI 推理/打标签/摘要、search搜索索引、embeddings向量嵌入、import导入、feedRSS 订阅、webhook、backup、ruleEngine、assetPreprocessing 等分别对应apps/workers/workers/下的各个 Worker 文件。WORKERS_ENABLED_WORKERS/WORKERS_DISABLED_WORKERS环境变量可以按需启停特定 Worker见 packages/shared/config.ts。七、移动端开发iOS Android7.1 前置条件要本地构建并运行移动应用需要iOS 开发macOS 电脑、从 App Store 安装 Xcode、随 Xcode 附带的 iOS SimulatorAndroid 开发安装 Android Studio、配置 Android SDK、准备 Android Emulator 或真机。详细的本地开发环境搭建可参考 Expo 官方文档local app development 指南。7.2 构建并运行进入移动端目录并预构建原生工程$ cd apps/mobile $ pnpm exec expo prebuild --no-installiOS$ pnpm exec expo run:ios应用会被安装并启动到模拟器中。iOS 排错如果遇到类似xcrun: error: SDK iphoneos cannot be located的错误可能是 Xcode 开发者目录未指向正确位置可执行sudo xcode-select -s /Applications/Xcode.app/Contents/DeveloperAndroid$ pnpm exec expo run:android应用会被安装并启动到模拟器/真机上。代码改动会触发热重载hot reload但安装新依赖包后需要重启 expo server才能生效。从当前仓库 apps/mobile/package.json 的脚本来看移动端提供了更细分的运行入口pnpm ios/pnpm androiddevelopment 变体、ios:preview/android:preview独立 bundle ID、无需 devserver 的预览变体、ios:release/android:release接近生产构建的 release 变体并通过APP_VARIANT环境变量控制。日常开发 90% 的情况下使用 development 变体即可如果从旧版本升级后构建失败如 Expo 大版本升级残留了过期的原生构建产物可先执行pnpm run clean:workspaces、pnpm install与pnpm --filter karakeep/mobile clean:prebuild清理后重新构建。八、浏览器扩展开发浏览器扩展的开发步骤如下$ cd apps/browser-extension $ pnpm dev执行后Vite 会生成dist产物目录扩展开发服务器默认运行在 http://localhost:5174。然后打开浏览器扩展管理页Chrome 的chrome://extensions或 Brave 对应页面开启“开发者模式”Developer mode点击“Load unpacked”加载已解压的扩展程序选择apps/browser-extension/dist目录扩展会出现在扩展列表中。开发模式下打开和关闭扩展弹窗即会重新加载代码无需手动刷新整个扩展。从 apps/browser-extension/package.json 可以看到dev脚本直接调用vite构建链路为tsc vite build并依赖crxjs/vite-plugin来生成符合 Chrome Manifest V3 规范的扩展产物。九、基于 Docker Compose 的开发环境如果手动搭建过于繁琐官方文档还提供了一条容器化路径在仓库根目录执行$ docker compose -f docker/docker-compose.dev.yml upv0.31.0 版本文档对这套方案的评价比较谨慎原文称“这套方案对我来说不算特别可靠”但当前仓库中的 docker/docker-compose.dev.yml 已经演进得相当完整共编排了五个服务服务作用prep一次性任务创建DATA_DIR默认为/data、执行pnpm install --frozen-lockfile、执行pnpm run db:migrate为其他服务准备好依赖与数据库web运行pnpm webNext.js dev server映射宿主机 3000 端口开启WATCHPACK_POLLING/CHOKIDAR_USEPOLLING以在 Mac/Windows 文件同步下可靠触发热重载workers运行pnpm workers与本地开发行为一致meilisearch内部服务仅容器网络内可访问宿主机不暴露端口禁用遥测并挂载持久化数据卷chrome供 Workers 使用的可远程调试 Chrome 实例映射到 9222 端口几个关键的编排细节值得开发者注意默认环境变量即使不创建.envcompose 文件也会通过${VAR:-default}语法注入合理默认值——DATA_DIR/data、MEILI_ADDRhttp://meilisearch:7700、NEXTAUTH_URLhttp://localhost:3000、NEXTAUTH_SECRETsuper-secure-nextauth-secret必须覆盖的变量NEXTAUTH_SECRET默认值只用于开发演示正式使用前应至少通过.env覆盖用openssl rand -base64 36生成可选的OPENAI_API_KEY等也建议写进.env数据挂载data:${DATA_DIR:-/data}默认将数据存入 Docker volume如需改用宿主机目录可修改 volume 映射为/path/to/your/directory:/data共享卷所有应用容器把宿主仓库挂载到/app并共享node_modules依赖装在 Linux 容器内与pnpm-storepnpm 缓存两个卷日志与清理docker compose logs -f web workers跟踪日志docker compose down停止全部服务改动 Node 依赖或 Dockerfile 后需加--build重建docker compose down -v可彻底清空数据卷获得全新状态。十、常见问题与排查建议结合开发文档与仓库源码整理开发中最高频的几类问题及对应排查方向登录/认证失效检查NEXTAUTH_SECRET是否设置。源码层面 packages/shared/config.ts 会在其缺失时直接抛错确保所有应用尤其是 Web 与 Workers读取的是同一个.env建议符号链接共享搜索不可用确认MEILI_ADDR已设置且 Meilisearch 在 7700 端口可达docker ps或直接访问 http://localhost:7700本地重启后索引数据丢失可挂载持久化卷并在管理面板触发全量 re-index新收藏书签没有被爬取/索引确认pnpm workers正在运行同时确认 9222 端口的无头 Chrome 可访问BROWSER_WEB_URL指向正确Node 版本不匹配node --version必须是 v24 系列nvm 切换后记得重新corepack enable与pnpm installiOS 构建报xcrun: error: SDK iphoneos cannot be located执行sudo xcode-select -s /Applications/Xcode.app/Contents/Developer修正开发者目录移动端升级后构建失败清理过期原生产物按pnpm run clean:workspaces→pnpm install→pnpm --filter karakeep/mobile clean:prebuild顺序重建端口冲突start-dev.sh对 7700/9222 端口已有占用检测逻辑若手动启动遇到冲突可先停掉占用进程或改用其他端口并同步调整环境变量。结语Karakeep 的开发环境横跨 Web、Workers、移动端与浏览器扩展四个应用形态外加 Meilisearch 与无头 Chrome 两个外部依赖初次搭建容易在环境变量与依赖顺序上踩坑。本文以官方开发文档为骨架结合仓库内 start-dev.sh、.env.sample、package.json、packages/shared/config.ts、docker/docker-compose.dev.yml 等真实源码把“一键脚本、手动搭建、容器化开发”三条路径完整走通。上手时优先尝试./start-dev.sh需要精细化控制时再按手动流程逐步配置完整的变量清单还可参考 docs/docs/03-configuration/01-environment-variables.md目录结构说明见 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），仅供参考