Karakeep 开发环境搭建指南从一键脚本到 Docker 的完整本地开发工作流【免费下载链接】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自托管书签收藏应用开发环境的完整搭建指南覆盖快速启动脚本、手动配置、环境变量、数据库迁移、Meilisearch 与无头 Chrome 依赖服务以及 Web、Workers、移动端和浏览器插件四类应用的本地运行方式。读完本文你将能在一台机器上独立跑起完整的 Karakeep 开发栈并理解每个启动环节背后的脚本与源码实现。本文内容以仓库中版本化文档 docs/versioned_docs/version-v0.28.0/07-development/01-setup.md 为骨架并结合仓库根目录的 start-dev.sh、package.json、docker/docker-compose.dev.yml 等真实文件进行源码级佐证。开发环境概览需要启动哪些东西Karakeep 是一个 monorepo 项目一次完整的本地开发需要同时运行多个进程它们各司其职Web AppNext.js默认http://localhost:3000用户界面处理登录、书签展示与管理。Workers后台任务进程负责爬取网页、生成全文索引、执行规则引擎、AI 打标等异步任务。Meilisearch端口 7700全文搜索与向量检索的提供者。无头 Chrome端口 9222供 Workers 抓取页面内容使用。仓库根目录的 package.json 中定义了对应脚本web对应pnpm --filter karakeep/web run devworkers对应pnpm --filter karakeep/workers run startdb:migrate对应pnpm --filter karakeep/db run migrate此外还有db:studio、seed:apply、android、ios等便捷命令。Quick Start一条命令启动整个开发栈最快的启动方式是在仓库根目录执行./start-dev.sh从源码看start-dev.sh这个脚本会自动完成以下步骤环境预检检查docker与pnpm是否已安装缺失时直接报错退出。启动 Meilisearch若端口 7700 未被占用执行docker run -d -p 7700:7700 --name karakeep-meilisearch getmeili/meilisearch:v1.41.0。启动无头 Chrome若端口 9222 未被占用执行docker 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。准备数据目录从环境变量或.env读取DATA_DIR不存在则创建。迁移数据库执行pnpm run db:migrate。并行启动后台启动pnpm web与pnpm workers两个进程并最多等待 30 秒探测localhost:3000是否就绪。优雅清理注册SIGINT/SIGTERM陷阱按CtrlC时杀掉 Web 与 Workers 进程并docker stop/rm两个容器。脚本成功运行后会输出三个服务地址Web app: http://localhost:3000 Meilisearch: http://localhost:7700 Chrome debugger: http://localhost:9222前置要求Docker 已安装并运行、pnpm 已安装安装方式见下文手动配置部分。小提示脚本通过port_in_uselsof -i :端口判断端口占用因此如果你已手动跑过 Meilisearch 或 Chrome脚本会自动跳过对应的 Docker 容器启动不会重复创建。Manual Setup手动配置完整开发环境如果你希望完全掌控每一步可以跳过脚本按下面的流程手动搭建。Node.js 与 corepackKarakeep 使用 Node.js 22 进行开发version-v0.28.0 文档以v22.14.0为示例输出。推荐用nvm安装并切换到对应版本nvm install 22 node --version # v22.14.0仓库演进说明当前仓库根目录的 .nvmrc 已更新为24即主分支已向 Node 24 迁移本文基于 v0.28.0 版本化文档按 Node 22 说明实际开发请以你检出的分支/版本的.nvmrc或文档为准。项目还依赖corepack来固定包管理器版本根 package.json 声明了packageManager: pnpm11.2.1。安装 Node 后 corepack 通常已随附验证并启用command -v corepack # 例如 /home/user/.nvm/versions/node/v22.14.0/bin/corepack corepack enable安装依赖在仓库根目录执行pnpm install这是一次典型的 pnpm workspace 安装成功的输出大致如下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安装完成后仓库会通过prepare钩子自动执行huskygit hooks 工具。工作区结构由 pnpm-workspace.yaml 定义包含packages/*、apps/*、tooling/*、tools/*与docs等目录并对react-tweet、react-native、expo-modules-jsi等依赖应用了 patches 目录下的补丁。First Setup环境变量与数据库初始化开发环境需要先准备环境变量。文档推荐的策略是在仓库根目录创建一份.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_ADDR选填Meilisearch 地址不设置则搜索功能被禁用。本地可设为http://127.0.0.1:7700OPENAI_API_KEY选填需要在开发环境启用 AI 自动打标auto tag inference时设置这些变量的底层解析与校验位于 packages/shared/config.tsDATA_DIR默认空字符串并在运行期被使用NEXTAUTH_SECRET在缺失时会直接抛出NEXTAUTH_SECRET is not set错误config.ts 296-299 行BROWSER_WEB_URL则用于告诉 Workers 无头 Chrome 的调试地址。完成.env配置后初始化数据库pnpm run db:migrate该命令最终执行packages/db包内的migrate脚本见 packages/db/package.json。数据库基于 SQLitebetter-sqlite3与 Drizzle ORM迁移逻辑见 packages/db/migrate.ts除非处于degradedMode降级模式会跳过迁移否则将packages/db/drizzle目录下的迁移文件packages/db/drizzle依次应用到数据库。Dependencies两个外部依赖服务Meilisearch全文搜索Meilisearch 是全文搜索未来还包括向量/嵌入搜索的提供者。按文档可以用一条 Docker 命令启动docker run -p 7700:7700 getmeili/meilisearch:v1.13.3如果想在容器重启后保留索引数据可以挂载持久化卷。若索引数据需要重建可在 Web 应用的管理后台Admin Panel中对整个条目集合触发一次全量 re-index。版本说明version-v0.28.0 文档示例为v1.13.3而当前仓库的 start-dev.sh 与 docker/docker-compose.dev.yml 已统一升级到getmeili/meilisearch:v1.41.0两者均可用建议跟随仓库当前版本。Chrome页面抓取Workers 应用在启动时会自动拉起无头 Chrome用于抓取网页无需手动配置。开发时通过BROWSER_WEB_URL默认http://chrome:9222本地为http://127.0.0.1:9222与之通信。启动 Web App在仓库根目录执行pnpm web然后浏览器访问http://localhost:3000。重要提醒原文档明确说明Web 应用在没有任何依赖服务时也能部分工作——但搜索需要 Meilisearch 运行新添加的条目也需要 Workers 运行才会被爬取和索引。启动 Workers在仓库根目录执行pnpm workersWorkers 承担抓取、索引、AI 打标、规则引擎、导入导出等后台任务。只有 Web 与 Workers 同时运行整个保存书签 → 抓取内容 → 生成索引的闭环才完整。Mobile AppiOS 与 Android前置条件要本地构建并运行移动端应用需要iOS 开发macOS 电脑、App Store 安装的 Xcode、随 Xcode 附带的 iOS Simulator。Android 开发安装 Android Studio、配置好 Android SDK、准备 Android Emulator 或真机。移动端基于 Expo/React Native见 apps/mobile/package.json脚本如expo run:ios、expo run:android更多环境细节可参考 Expo 官方的本地应用开发文档。运行应用cd apps/mobile pnpm exec expo prebuild --no-installiOSpnpm exec expo run:ios应用会被安装并启动到模拟器中。iOS 常见问题若出现xcrun: error: SDK iphoneos cannot be located之类的错误通常是 Xcode 开发者目录未指向正确位置执行sudo xcode-select -s /Applications/Xcode.app/Contents/DeveloperAndroid先启动 Android 模拟器或连接真机然后pnpm exec expo run:android应用会被安装并启动到模拟器/设备上。代码修改会触发热重载hot reload但安装新依赖包后需要重启 expo server才能生效。Browser Extension浏览器插件cd apps/browser-extension pnpm dev这会基于 Viteapps/browser-extension/package.json 中dev脚本为vite构建使用crxjs/vite-plugin生成一个dist目录。随后打开 Chrome 的扩展程序管理页开启开发者模式。点击加载已解压的扩展程序选择dist目录。插件会出现在插件列表中。开发模式下打开/关闭插件菜单即可重载代码无需手动刷新扩展。Docker Dev Env一键容器化开发环境如果觉得手动配置繁琐仓库还提供了基于 Docker 的开发环境docker compose -f docker/docker-compose.dev.yml up从 docker/docker-compose.dev.yml 可以看到完整的服务编排共 5 个服务web基于Dockerfile.dev构建挂载仓库到/app暴露 3000 端口默认执行pnpm web通过WATCHPACK_POLLING/CHOKIDAR_USEPOLLING开启文件轮询以支持容器内热更新。workers同样的开发镜像默认执行pnpm workers与 web 共享data卷与node_modules。meilisearchgetmeili/meilisearch:v1.41.0设置MEILI_NO_ANALYTICStrue数据持久化到meilisearch卷。chromeghcr.io/karakeep-app/karakeep-chrome:release仅绑定到127.0.0.1:9222。prep一次性初始化服务负责mkdir -p DATA_DIR pnpm install --frozen-lockfile pnpm run db:migrateweb/workers 通过depends_on等待其成功完成。其中大部分环境变量都有默认值如MEILI_ADDR默认http://meilisearch:7700、NEXTAUTH_SECRET默认super-secure-nextauth-secret可用.env覆盖DATA_DIR默认映射到名为data的 Docker 卷如需自定义目录需修改卷映射而非直接改环境变量。文档原话提醒这套 Docker 开发环境并不是特别可靠wasnt super reliable如果遇到问题建议优先使用前面的一键脚本或手动配置方式。常用开发命令速查整理自根 package.json按需使用命令作用./start-dev.sh一键启动 Meilisearch Chrome 依赖安装 迁移 Web Workerspnpm install安装全部 workspace 依赖pnpm run db:migrate应用数据库迁移pnpm run db:studio打开 Drizzle Studio 可视化数据库pnpm web启动 Web 应用Next.js dev server端口 3000pnpm workers启动后台 Workerspnpm android/pnpm ios启动移动端应用转发到apps/mobile的 Expo 脚本pnpm test/pnpm typecheck/pnpm lint运行测试、类型检查与代码检查pnpm preflight依次执行 typecheck lint format 的完整质量门禁小结Karakeep 的本地开发环境由 Web、Workers、Meilisearch 与无头 Chrome 四个核心部分组成start-dev.sh负责把一切自动化手动流程则需要依次完成 Node 22 corepack 环境、pnpm install、.env环境变量重点是DATA_DIR与NEXTAUTH_SECRET、db:migrate再分别启动 Web 与 Workers。移动端与浏览器插件作为独立的子应用各自通过 Expo 与 Vite 提供热重载开发体验。理解了脚本与配置背后的实现细节端口探测、镜像版本、迁移逻辑、服务编排无论遇到何种环境问题都能快速定位与修复。【免费下载链接】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 开发环境搭建指南：从一键脚本到 Docker 的完整本地开发工作流
Karakeep 开发环境搭建指南从一键脚本到 Docker 的完整本地开发工作流【免费下载链接】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自托管书签收藏应用开发环境的完整搭建指南覆盖快速启动脚本、手动配置、环境变量、数据库迁移、Meilisearch 与无头 Chrome 依赖服务以及 Web、Workers、移动端和浏览器插件四类应用的本地运行方式。读完本文你将能在一台机器上独立跑起完整的 Karakeep 开发栈并理解每个启动环节背后的脚本与源码实现。本文内容以仓库中版本化文档 docs/versioned_docs/version-v0.28.0/07-development/01-setup.md 为骨架并结合仓库根目录的 start-dev.sh、package.json、docker/docker-compose.dev.yml 等真实文件进行源码级佐证。开发环境概览需要启动哪些东西Karakeep 是一个 monorepo 项目一次完整的本地开发需要同时运行多个进程它们各司其职Web AppNext.js默认http://localhost:3000用户界面处理登录、书签展示与管理。Workers后台任务进程负责爬取网页、生成全文索引、执行规则引擎、AI 打标等异步任务。Meilisearch端口 7700全文搜索与向量检索的提供者。无头 Chrome端口 9222供 Workers 抓取页面内容使用。仓库根目录的 package.json 中定义了对应脚本web对应pnpm --filter karakeep/web run devworkers对应pnpm --filter karakeep/workers run startdb:migrate对应pnpm --filter karakeep/db run migrate此外还有db:studio、seed:apply、android、ios等便捷命令。Quick Start一条命令启动整个开发栈最快的启动方式是在仓库根目录执行./start-dev.sh从源码看start-dev.sh这个脚本会自动完成以下步骤环境预检检查docker与pnpm是否已安装缺失时直接报错退出。启动 Meilisearch若端口 7700 未被占用执行docker run -d -p 7700:7700 --name karakeep-meilisearch getmeili/meilisearch:v1.41.0。启动无头 Chrome若端口 9222 未被占用执行docker 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。准备数据目录从环境变量或.env读取DATA_DIR不存在则创建。迁移数据库执行pnpm run db:migrate。并行启动后台启动pnpm web与pnpm workers两个进程并最多等待 30 秒探测localhost:3000是否就绪。优雅清理注册SIGINT/SIGTERM陷阱按CtrlC时杀掉 Web 与 Workers 进程并docker stop/rm两个容器。脚本成功运行后会输出三个服务地址Web app: http://localhost:3000 Meilisearch: http://localhost:7700 Chrome debugger: http://localhost:9222前置要求Docker 已安装并运行、pnpm 已安装安装方式见下文手动配置部分。小提示脚本通过port_in_uselsof -i :端口判断端口占用因此如果你已手动跑过 Meilisearch 或 Chrome脚本会自动跳过对应的 Docker 容器启动不会重复创建。Manual Setup手动配置完整开发环境如果你希望完全掌控每一步可以跳过脚本按下面的流程手动搭建。Node.js 与 corepackKarakeep 使用 Node.js 22 进行开发version-v0.28.0 文档以v22.14.0为示例输出。推荐用nvm安装并切换到对应版本nvm install 22 node --version # v22.14.0仓库演进说明当前仓库根目录的 .nvmrc 已更新为24即主分支已向 Node 24 迁移本文基于 v0.28.0 版本化文档按 Node 22 说明实际开发请以你检出的分支/版本的.nvmrc或文档为准。项目还依赖corepack来固定包管理器版本根 package.json 声明了packageManager: pnpm11.2.1。安装 Node 后 corepack 通常已随附验证并启用command -v corepack # 例如 /home/user/.nvm/versions/node/v22.14.0/bin/corepack corepack enable安装依赖在仓库根目录执行pnpm install这是一次典型的 pnpm workspace 安装成功的输出大致如下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安装完成后仓库会通过prepare钩子自动执行huskygit hooks 工具。工作区结构由 pnpm-workspace.yaml 定义包含packages/*、apps/*、tooling/*、tools/*与docs等目录并对react-tweet、react-native、expo-modules-jsi等依赖应用了 patches 目录下的补丁。First Setup环境变量与数据库初始化开发环境需要先准备环境变量。文档推荐的策略是在仓库根目录创建一份.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_ADDR选填Meilisearch 地址不设置则搜索功能被禁用。本地可设为http://127.0.0.1:7700OPENAI_API_KEY选填需要在开发环境启用 AI 自动打标auto tag inference时设置这些变量的底层解析与校验位于 packages/shared/config.tsDATA_DIR默认空字符串并在运行期被使用NEXTAUTH_SECRET在缺失时会直接抛出NEXTAUTH_SECRET is not set错误config.ts 296-299 行BROWSER_WEB_URL则用于告诉 Workers 无头 Chrome 的调试地址。完成.env配置后初始化数据库pnpm run db:migrate该命令最终执行packages/db包内的migrate脚本见 packages/db/package.json。数据库基于 SQLitebetter-sqlite3与 Drizzle ORM迁移逻辑见 packages/db/migrate.ts除非处于degradedMode降级模式会跳过迁移否则将packages/db/drizzle目录下的迁移文件packages/db/drizzle依次应用到数据库。Dependencies两个外部依赖服务Meilisearch全文搜索Meilisearch 是全文搜索未来还包括向量/嵌入搜索的提供者。按文档可以用一条 Docker 命令启动docker run -p 7700:7700 getmeili/meilisearch:v1.13.3如果想在容器重启后保留索引数据可以挂载持久化卷。若索引数据需要重建可在 Web 应用的管理后台Admin Panel中对整个条目集合触发一次全量 re-index。版本说明version-v0.28.0 文档示例为v1.13.3而当前仓库的 start-dev.sh 与 docker/docker-compose.dev.yml 已统一升级到getmeili/meilisearch:v1.41.0两者均可用建议跟随仓库当前版本。Chrome页面抓取Workers 应用在启动时会自动拉起无头 Chrome用于抓取网页无需手动配置。开发时通过BROWSER_WEB_URL默认http://chrome:9222本地为http://127.0.0.1:9222与之通信。启动 Web App在仓库根目录执行pnpm web然后浏览器访问http://localhost:3000。重要提醒原文档明确说明Web 应用在没有任何依赖服务时也能部分工作——但搜索需要 Meilisearch 运行新添加的条目也需要 Workers 运行才会被爬取和索引。启动 Workers在仓库根目录执行pnpm workersWorkers 承担抓取、索引、AI 打标、规则引擎、导入导出等后台任务。只有 Web 与 Workers 同时运行整个保存书签 → 抓取内容 → 生成索引的闭环才完整。Mobile AppiOS 与 Android前置条件要本地构建并运行移动端应用需要iOS 开发macOS 电脑、App Store 安装的 Xcode、随 Xcode 附带的 iOS Simulator。Android 开发安装 Android Studio、配置好 Android SDK、准备 Android Emulator 或真机。移动端基于 Expo/React Native见 apps/mobile/package.json脚本如expo run:ios、expo run:android更多环境细节可参考 Expo 官方的本地应用开发文档。运行应用cd apps/mobile pnpm exec expo prebuild --no-installiOSpnpm exec expo run:ios应用会被安装并启动到模拟器中。iOS 常见问题若出现xcrun: error: SDK iphoneos cannot be located之类的错误通常是 Xcode 开发者目录未指向正确位置执行sudo xcode-select -s /Applications/Xcode.app/Contents/DeveloperAndroid先启动 Android 模拟器或连接真机然后pnpm exec expo run:android应用会被安装并启动到模拟器/设备上。代码修改会触发热重载hot reload但安装新依赖包后需要重启 expo server才能生效。Browser Extension浏览器插件cd apps/browser-extension pnpm dev这会基于 Viteapps/browser-extension/package.json 中dev脚本为vite构建使用crxjs/vite-plugin生成一个dist目录。随后打开 Chrome 的扩展程序管理页开启开发者模式。点击加载已解压的扩展程序选择dist目录。插件会出现在插件列表中。开发模式下打开/关闭插件菜单即可重载代码无需手动刷新扩展。Docker Dev Env一键容器化开发环境如果觉得手动配置繁琐仓库还提供了基于 Docker 的开发环境docker compose -f docker/docker-compose.dev.yml up从 docker/docker-compose.dev.yml 可以看到完整的服务编排共 5 个服务web基于Dockerfile.dev构建挂载仓库到/app暴露 3000 端口默认执行pnpm web通过WATCHPACK_POLLING/CHOKIDAR_USEPOLLING开启文件轮询以支持容器内热更新。workers同样的开发镜像默认执行pnpm workers与 web 共享data卷与node_modules。meilisearchgetmeili/meilisearch:v1.41.0设置MEILI_NO_ANALYTICStrue数据持久化到meilisearch卷。chromeghcr.io/karakeep-app/karakeep-chrome:release仅绑定到127.0.0.1:9222。prep一次性初始化服务负责mkdir -p DATA_DIR pnpm install --frozen-lockfile pnpm run db:migrateweb/workers 通过depends_on等待其成功完成。其中大部分环境变量都有默认值如MEILI_ADDR默认http://meilisearch:7700、NEXTAUTH_SECRET默认super-secure-nextauth-secret可用.env覆盖DATA_DIR默认映射到名为data的 Docker 卷如需自定义目录需修改卷映射而非直接改环境变量。文档原话提醒这套 Docker 开发环境并不是特别可靠wasnt super reliable如果遇到问题建议优先使用前面的一键脚本或手动配置方式。常用开发命令速查整理自根 package.json按需使用命令作用./start-dev.sh一键启动 Meilisearch Chrome 依赖安装 迁移 Web Workerspnpm install安装全部 workspace 依赖pnpm run db:migrate应用数据库迁移pnpm run db:studio打开 Drizzle Studio 可视化数据库pnpm web启动 Web 应用Next.js dev server端口 3000pnpm workers启动后台 Workerspnpm android/pnpm ios启动移动端应用转发到apps/mobile的 Expo 脚本pnpm test/pnpm typecheck/pnpm lint运行测试、类型检查与代码检查pnpm preflight依次执行 typecheck lint format 的完整质量门禁小结Karakeep 的本地开发环境由 Web、Workers、Meilisearch 与无头 Chrome 四个核心部分组成start-dev.sh负责把一切自动化手动流程则需要依次完成 Node 22 corepack 环境、pnpm install、.env环境变量重点是DATA_DIR与NEXTAUTH_SECRET、db:migrate再分别启动 Web 与 Workers。移动端与浏览器插件作为独立的子应用各自通过 Expo 与 Vite 提供热重载开发体验。理解了脚本与配置背后的实现细节端口探测、镜像版本、迁移逻辑、服务编排无论遇到何种环境问题都能快速定位与修复。【免费下载链接】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），仅供参考