Karakeep 在 Arch Linux 上的安装、systemd 服务编排与 Hoarder 数据迁移指南【免费下载链接】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原 Hoarder在 Arch Linux 发行版上的完整落地流程展开从通过 AUR 安装主程序与可选依赖、在/etc/karakeep/karakeep.env中配置核心环境变量到使用karakeep.target一键拉起 web / workers / browser 三大 systemd 服务最后给出从旧版 Hoarder 平滑迁移数据的具体步骤。读完本文你将能够在 Arch Linux 上独立完成 Karakeep 的部署、调优与升级迁移。一、前置说明AUR 包的维护归属Karakeep 在 Arch Linux 上的安装依赖 AURArch User Repository 中的karakeep软件包。需要特别注意的是该 AUR 包并非由 Karakeep 官方维护而是由社区维护者打包。这意味着包的更新节奏、systemd 单元文件与默认配置路径可能滞后于官方发布版本使用前建议查看 AUR 包页面上的评论与.SRCINFO确认当前打包版本若遇到与官方 Docker 部署行为不一致的情况应以该 AUR 包的实际文件为准。官方文档位于本仓库的 docs/versioned_docs/version-v0.29.0/02-installation/03-archlinux.md本文以该文档为骨架展开。二、安装 Karakeep 主程序推荐使用 AUR 助手paru完成安装当然你也可以使用yay等其他 AUR 助手paru -S karakeep安装完成后包内会提供可执行文件与 web 应用Next.js 构建产物systemd 服务单元karakeep-web.service、karakeep-workers.service、karakeep-browser.service及聚合目标karakeep.target默认配置目录/etc/karakeep/包含karakeep.env模板独立系统用户karakeep与数据目录/var/lib/karakeep。三、安装可选依赖# karakeep-cliKarakeep 命令行工具 paru -S karakeep-cli # ollama本地 AI 推理用于自动打标签automatic tagging sudo pacman -S ollama # yt-dlp用于抓取网页中的视频 sudo pacman -S yt-dlp这三个可选依赖对应三种增强能力karakeep-cli仓库中的 apps/cli/package.json 显示其二进制入口为karakeep提供基于 tRPC 的命令行操作能力添加书签、查询、批量操作等适合脚本化使用。ollama为自动打标签提供本地推理能力。安装后需先下载模型可参考 ollama 官方模型库https://ollama.com/library例如llama3系列文本模型、支持视觉的llava系列图像模型。若不想使用本地推理也可以用 OpenAI 替代见下文“推理配置”。yt-dlp对应CRAWLER_VIDEO_DOWNLOAD配置项启用后抓取页面视频时由 yt-dlp 负责下载CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE默认 50单位 MB控制文件大小上限-1表示不限制。四、核心配置/etc/karakeep/karakeep.envKarakeep 整体通过环境变量驱动配置。AUR 包将环境变量文件放在/etc/karakeep/karakeep.env由 systemd 单元以EnvironmentFile方式加载。重要/etc/karakeep/karakeep.env模板中只预置了少量变量文档中未在模板里预置的变量需要你手动添加。完整的环境变量清单以源码 packages/shared/config.ts 为准该文件用 zod 定义了全部环境变量的 schema、默认值与校验规则官方配置说明见 docs/versioned_docs/version-v0.29.0/03-configuration.md。4.1 必填与高优先级变量变量是否必填默认值说明DATA_DIR是未设置持久化数据目录SQLite 数据库存放于此未设置ASSETS_DIR时资源assets默认存放在${DATA_DIR}/assets。源码中DATA_DIR默认空字符串部署时必须显式指定例如/var/lib/karakeepNEXTAUTH_URL是http://localhost:3000服务对外地址用于登录/登出跳转与回调。源码 config.ts 会去掉末尾斜杠NEXTAUTH_SECRET是生产未设置用于签发 JWT 的随机字符串。源码中该字段为 optional但生产模式下若未设置会直接抛出NEXTAUTH_SECRET is not set见 config.ts。可用openssl rand -base64 36生成MEILI_ADDR否未设置Meilisearch 地址例如http://127.0.0.1:7700。未设置时全文搜索被禁用MEILI_MASTER_KEY仅生产且启用搜索时未设置Meilisearch 主密钥可用openssl rand -base64 36 \| tr -dc A-Za-z0-9生成PORT否3000web 服务监听端口对应karakeep-web.service一个最小可用的/etc/karakeep/karakeep.env示例# 数据目录AUR 包默认约定 DATA_DIR/var/lib/karakeep # 服务对外地址与 JWT 密钥 NEXTAUTH_URLhttp://localhost:3000 NEXTAUTH_SECRET$(openssl rand -base64 36) # Meilisearch由 karakeep.target 一并拉起 MEILI_ADDRhttp://127.0.0.1:7700 MEILI_MASTER_KEY你的随机密钥 # 日志级别生产建议 notice 或 warning默认 debug 过于冗长 LOG_LEVELnotice提示NEXTAUTH_SECRET与MEILI_MASTER_KEY请用实际的随机串替换占位符不要在生产环境沿用示例值。4.2 推理配置自动打标签自动打标签需要配置OpenAIOPENAI_API_KEY或OllamaOLLAMA_BASE_URL二者之一否则自动打标签会被跳过INFERENCE_ENABLE_AUTO_TAGGING默认true但缺少推理后端时不会执行。变量默认值说明OLLAMA_BASE_URL未设置Ollama API 地址如http://127.0.0.1:11434OLLAMA_KEEP_ALIVE未设置模型在内存中的驻留时长如5m5 分钟、-1m无限期驻留、0处理完立即卸载OPENAI_API_KEY未设置OpenAI 密钥也可通过OPENAI_BASE_URL指向兼容 OpenAI 协议的第三方 APIINFERENCE_TEXT_MODELgpt-5.6-lunav0.29.0 为gpt-4.1-mini文本推理模型使用 Ollama 时必须改为本地模型名INFERENCE_IMAGE_MODELgpt-4o-mini图像推理模型Ollama 场景需支持视觉 API如llavaINFERENCE_CONTEXT_LENGTH2048传给推理模型的 token 上限内容超出会被截断。调大可提升打标签质量但会增加推理成本/资源占用INFERENCE_LANGenglish生成标签的语言INFERENCE_JOB_TIMEOUT_SEC30推理任务超时无 GPU 的 Ollama 场景建议调大4.3 抓取Crawler与浏览器配置karakeep-browser.service提供无头浏览器服务crawler worker 通过浏览器执行 JavaScript、截图并提取内容。若既不设置BROWSER_WEB_URL也不设置BROWSER_WEBSOCKET_URLcrawler 会退化为纯 HTTP 请求跳过截图与 JS 执行见 config.ts 与 apps/workers/workers/crawler/browser.ts 中的连接逻辑。变量默认值说明BROWSER_WEB_URL未设置无头浏览器调试地址HTTPcrawler 通过它解析 websocket 地址CRAWLER_NUM_WORKERS1并发抓取任务数默认 1 以控制资源占用CRAWLER_JOB_TIMEOUT_SEC60单个抓取任务超时弱网络/低配设备可调大CRAWLER_STORE_SCREENSHOTtrue是否保存抓取页面的截图CRAWLER_FULL_PAGE_ARCHIVEfalse是否保存整页本地副本开启会显著增加磁盘占用CRAWLER_VIDEO_DOWNLOADfalse是否用 yt-dlp 下载页面视频CRAWLER_ENABLE_ADBLOCKERtrue是否启用广告拦截器4.4 Worker 启停控制WORKERS_ENABLED_WORKERS/WORKERS_DISABLED_WORKERS可以按需裁剪 worker 类型合法值包括crawler、inference、search、adminMaintenance、video、feed、assetPreprocessing、webhook、ruleEngine。WORKERS_DISABLED_WORKERS优先级更高。例如仅保留核心抓取与推理WORKERS_ENABLED_WORKERScrawler,inference,search,feed五、启用服务并访问配置完成后启用聚合目标karakeep.targetsudo systemctl enable --now karakeep.target随后访问http://localhost:3000即可看到登录/注册页面。常用管理命令# 查看各服务状态 systemctl status karakeep-web.service karakeep-workers.service karakeep-browser.service # 查看日志web 服务 journalctl -u karakeep-web.service -f六、服务与端口架构karakeep.target聚合了 3 个服务原文档第 42 行写为karakeep-works.service应为笔误正确的单元名为下述karakeep-workers.service单元职责端口karakeep-web.service提供 Karakeep Web UI 与 APINext.js/tRPC 服务端3000默认由PORT控制karakeep-workers.service后台 worker 集群爬取、推理、搜索索引、规则引擎等无对外端口Prometheus 指标默认随机端口karakeep-browser.service无头浏览器Playwright Chromium供 crawler 执行 JS 与截图9222默认调试端口依赖关系karakeep依赖meilisearchkarakeep-workers.service依赖meilisearch.service。因此启动karakeep.target时会同时拉起 Meilisearch无需单独手动启动。全栈数据流大致为用户在 Web UIkarakeep-web端口 3000提交书签任务进入队列由karakeep-workers.service消费crawler worker 通过karakeep-browser.service端口 9222完成页面渲染、截图与内容提取——browser.ts 中 crawler 依据BROWSER_WEB_URL连接已有浏览器实例若配置了BROWSER_CONNECT_ONDEMANDtrue则按需连接inference worker 调用 Ollama/OpenAI 生成标签搜索结果与向量索引落到 Meilisearch。七、从 Hoarder 迁移到 KarakeepKarakeep 由 Hoarder 更名而来。Arch Linux 的 PKGBUILD 已全面更新将所有hoarder引用替换为karakeep。若希望在升级时保留已有 Hoarder 数据请严格按以下 7 步操作数据目录重命名前务必确认备份或磁盘快照1. 停止旧服务sudo systemctl stop hoarder-web.service hoarder-worker.service hoarder-browser.service sudo systemctl disable --now hoarder.target2. 卸载 Hoarderparu -R hoarder卸载后如需要可手动删除旧的hoarder用户与用户组。3. 重命名旧数据目录sudo mv /var/lib/hoarder /var/lib/karakeep4. 安装 Karakeepparu -S karakeep5. 修复数据目录所有权新包使用独立的karakeep系统用户旧数据目录的属主必须改过来否则 web/workers 服务无法读写数据库sudo chown -R karakeep:karakeep /var/lib/karakeep6. 配置 Karakeep按 docs/versioned_docs/version-v0.29.0/03-configuration.md 编辑/etc/karakeep/karakeep.env模板中未预置的变量需手动补齐。也可以直接将旧的环境变量文件复制过来注意旧文件中的路径/密钥若引用/var/lib/hoarder需同步修改sudo cp -f /etc/hoarder/hoarder.env /etc/karakeep/karakeep.env7. 启动 Karakeepsudo systemctl enable --now karakeep.target迁移完成后再访问http://localhost:3000旧账号与书签数据应原样保留。若迁移后出现异常优先检查第 5 步的所有权修复以及MEILI_MASTER_KEY是否与 Meilisearch 实际配置一致搜索功能依赖 Meilisearch 正常启动。八、注意事项小结AUR 包非官方维护升级前留意包版本与官方 release 的差异环境变量必须自检/etc/karakeep/karakeep.env模板不完整务必参照 packages/shared/config.ts 全量核对特别是NEXTAUTH_SECRET缺失会导致启动失败搜索依赖 Meilisearch未配置MEILI_ADDR时搜索功能不可用自动打标签依赖推理后端OPENAI_API_KEY与OLLAMA_BASE_URL至少要配置其一Ollama 场景还需提前下载模型迁移有先后先停旧服务、再改名数据目录、最后装新包并修复属主顺序不可颠倒。【免费下载链接】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），仅供参考