Karakeep 在 Arch Linux 上的安装部署指南AUR 包安装、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 的安装流程、可选依赖CLI / Ollama / yt-dlp的配置方法、/etc/karakeep/karakeep.env环境变量文件的关键参数以及karakeep.target下各 systemd 服务与默认端口的职责划分并逐步演示如何从旧版 Hoarder 无损迁移数据。读完本文你将能够在 Arch Linux 上独立完成 Karakeep 的安装、配置、开机自启与版本迁移。前置说明AUR 包与官方维护边界Arch Linux 用户可以通过 AURArch User Repository安装 Karakeep。需要特别留意的是AUR 上的karakeep包并非由 Karakeep 官方维护而是由社区贡献者维护包更新节奏、构建方式与官方发布可能存在时间差。安装前建议自行查看 AUR 页面上的包说明与构建脚本确认其与当前版本匹配。除 AUR 之外仓库同时提供了其他裸机安装路径如 Debian/Ubuntu 安装脚本 与 Docker 部署Arch 用户若更倾向容器化也可以参考 Docker 方式。一、安装 Karakeep 本体使用 AUR 助手本文以paru为例yay等助手同理执行安装paru -S karakeep安装完成后Karakeep 的二进制、systemd 单元文件与配置文件模板会被放置到系统对应位置systemd 服务单元见下文「服务与端口」小节。二、可选安装可选依赖Karakeep 的核心功能可以独立运行但部分高级能力依赖额外的外部工具按需安装即可# karakeep-cliKarakeep 命令行工具操作书签、列表、标签支持批量导入导出 paru -S karakeep-cli # ollama本地 LLM 推理服务用于自动打标签AI Tagging sudo pacman -S ollama # yt-dlp用于下载页面中的视频需配合 CRAWLER_VIDEO_DOWNLOAD 配置启用 sudo pacman -S yt-dlp三个可选项的用途说明如下karakeep-cli面向高级用户的命令行客户端可对书签bookmarks、列表lists、标签tags进行增删改查并支持批量导入导出。其完整用法API Key 获取、whoami验证、karakeep auth init交互式初始化等参见 命令行工具文档。ollama本地运行 LLM为自动打标签提供推理能力。官方推荐使用其 OpenAI 兼容端点/v1接入配置方式见 配置不同的 AI 提供商。yt-dlp视频下载能力依赖。在环境变量中设置CRAWLER_VIDEO_DOWNLOADtrue后抓取页面时才会调用 yt-dlp 下载视频。关于 AI 提供商你并非必须使用 Ollama——也可以直接使用 OpenAI。若选择 Ollama需要先自行下载对应的模型文本模型用于打标签如gemma3若需要对图片推理还需视觉模型如llava。未配置任何 AI 提供商时自动打标签功能会被跳过这是由源码中inference.isConfigured的判断逻辑决定的见下文源码分析。环境变量层面如何决定 AI 能力从源码 packages/shared/config.ts 可以看到推理能力是否启用完全由两个变量决定inference: { isConfigured: !!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL, ... }也就是说只要在环境变量中设置了OPENAI_API_KEY或OLLAMA_BASE_URL二者之一自动打标签/摘要即可启用两者都不设置则自动跳过。此外INFERENCE_TEXT_MODEL与INFERENCE_IMAGE_MODEL的默认值分别面向 OpenAI 模型gpt-4.1-mini/gpt-4o-mini使用 Ollama 时必须显式改为本地模型名。三、配置环境变量文件安装完成后需要将环境变量写入/etc/karakeep/karakeep.env配置项以 环境变量配置文档 为准。需要特别强调AUR 包提供的/etc/karakeep/karakeep.env只包含部分基础变量文档中列出但文件里没有的变量必须由你手动补充。必填与高频变量速查变量是否必填默认值说明DATA_DIR是未设置持久化数据目录SQLite 数据库存放于此资产默认也存放于此NEXTAUTH_URL是http://localhost:3000服务对外地址未正确设置会在登出等场景重定向到错误地址NEXTAUTH_SECRET是未设置用于签名 JWT 的随机串可用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 服务监听端口裸机安装可修改LOG_LEVEL否debug日志级别生产环境建议设为notice或warningDB_WAL_MODE否falseSQLite 启用 WAL 模式建议设为true以提升数据库性能网络盘除外ASSETS_DIR否${DATA_DIR}/assets抓取资产的存储路径未设置时默认为数据目录下的assetsMAX_ASSET_SIZE_MB否50允许上传的单个资产最大体积MBOLLAMA_BASE_URL否未设置启用 Ollama 本地推理时填写其 API 地址OPENAI_API_KEY否未设置启用 OpenAI 推理时填写 API Key一份可直接使用的示例以下配置覆盖了最常用的组合——本地 Meilisearch 全文搜索 Ollama 本地推理# 数据目录务必指向持久化磁盘删除内容将丢失全部数据 DATA_DIR/var/lib/karakeep # Web 服务端口 PORT3000 # 认证 NEXTAUTH_URLhttp://localhost:3000 NEXTAUTH_SECRETopenssl rand -base64 36 生成 # 全文搜索Meilisearch MEILI_ADDRhttp://127.0.0.1:7700 MEILI_MASTER_KEYopenssl rand -base64 36 | tr -dc A-Za-z0-9 生成 # 本地 AI 推理二选一Ollama 或 OpenAI OLLAMA_BASE_URLhttp://127.0.0.1:11434 INFERENCE_TEXT_MODELgemma3 INFERENCE_IMAGE_MODELllava # 生产环境建议 LOG_LEVELnotice DB_WAL_MODEtrue配置底层原理env 解析即服务配置从源码实现看Karakeep 的全部服务配置都通过 packages/shared/config.ts 中的 zod schema 从process.env解析而来。这意味着布尔型变量如DB_WAL_MODE、DISABLE_SIGNUPS只接受字面量字符串true/false多数变量都有安全默认值如PORT默认3000、OCR_LANGS默认eng未设置时按默认值运行存在跨变量校验例如EMAIL_VERIFICATION_REQUIREDtrue时若未配置 SMTP 会在启动时直接报错见 config.ts。因此编辑完/etc/karakeep/karakeep.env后必须重启相关服务见下一步配置才会重新加载生效。四、启用服务并完成首次访问执行以下命令启动并设置开机自启sudo systemctl enable --now karakeep.targetkarakeep.target是一个 systemd target目标单元它会聚合启动其依赖的全部服务。启动完成后浏览器访问http://localhost:3000即可看到登录/注册页面完成首个账号创建后即可开始使用。服务与端口职责karakeep.target下包含 3 个服务单元karakeep-web.service提供 Karakeep Web 界面与 API 服务默认监听3000端口karakeep-workers.service后台 Worker 服务爬虫、推理、搜索索引、规则引擎、备份等不对外监听端口karakeep-browser.service无头浏览器服务Headless Browser供爬虫执行 JavaScript、截图等任务默认监听9222端口Chrome DevTools 调试端口。此外Karakeep 现在依赖Meilisearch提供全文搜索karakeep-workers.service声明了对meilisearch.service的依赖因此启动karakeep.target时会同时拉起 Meilisearch。Meilisearch 默认监听7700端口与上文环境变量中的MEILI_ADDR对应。若你不安装/不启动 Meilisearch则搜索功能将完全禁用其余功能不受影响这与 Minimal Install 文档 中的说明一致。Worker 进程的实际构成从源码 apps/workers/index.ts 可以看到karakeep-workers.service内部实际是一个按需启用的 worker 集合包括crawler爬虫、inferenceAI 推理、search搜索索引、adminMaintenance、video视频下载、feedRSS、assetPreprocessing图片/OCR 预处理、webhook、ruleEngine自动化规则、backup备份调度等。默认全部启用若希望裁剪可在环境变量中设置WORKERS_ENABLED_WORKERS白名单逗号分隔或WORKERS_DISABLED_WORKERS黑名单优先级更高。五、从 Hoarder 迁移到 Karakeep升级路径Hoarder 已正式更名为 KarakeepAUR 中的 PKGBUILD 也已全面更新将所有hoarder引用替换为karakeep。如果你此前已经部署了 Hoarder希望在升级时保留既有数据请严格按照以下 7 个步骤操作。通用迁移背景可参考 Hoarder 到 Karakeep 迁移文档其中也覆盖了 Docker 镜像名称从ghcr.io/hoarder-app/hoarder变更为ghcr.io/karakeep-app/karakeep的说明。第 1 步停止旧服务sudo systemctl stop hoarder-web.service hoarder-worker.service hoarder-browser.service sudo systemctl disable --now hoarder.target第 2 步卸载 Hoarder卸载后可按需手动删除旧的hoarder用户与用户组。paru -R hoarder第 3 步重命名旧数据目录数据目录是 SQLite 数据库与资产的所在地重命名而非删除可完整保留数据sudo mv /var/lib/hoarder /var/lib/karakeep第 4 步安装 Karakeepparu -S karakeep第 5 步修正数据目录属主Karakeep 服务以karakeep用户运行必须确保数据目录归属正确否则服务将因无权限读写而启动失败sudo chown -R karakeep:karakeep /var/lib/karakeep第 6 步配置 Karakeep 环境变量参照 环境变量配置文档 编辑/etc/karakeep/karakeep.env文件中未列出的变量需自行补充或者直接复制旧的环境变量文件sudo cp -f /etc/hoarder/hoarder.env /etc/karakeep/karakeep.env直接复制旧 env 文件可以最大程度保留原有配置如DATA_DIR、MEILI_ADDR、推理模型设置等但仍建议对照配置文档核对一遍尤其是DATA_DIR必须指向第 3 步重命名后的/var/lib/karakeep。第 7 步启动 Karakeepsudo systemctl enable --now karakeep.target启动后访问http://localhost:3000使用原有账号登录即可确认书签、列表、标签等数据已完整迁移。六、验证、更新与常见问题验证服务状态systemctl status karakeep.target systemctl status karakeep-web karakeep-workers karakeep-browser meilisearch修改配置后重载编辑/etc/karakeep/karakeep.env后需要重启受影响的服务参考 Debuntu 脚本的做法见 debuntu 文档sudo systemctl restart karakeep-web karakeep-workers更新版本AUR 包通过paru -Syu或paru -S karakeep拉取新版 PKGBUILD 升级升级前建议先通过 Web 界面或备份功能导出数据以防构建脚本变动导致意外。常见问题排查搜索不可用检查MEILI_ADDR与MEILI_MASTER_KEY是否设置、meilisearch.service是否正常运行监听7700端口自动打标签不生效检查OPENAI_API_KEY/OLLAMA_BASE_URL是否配置、INFERENCE_TEXT_MODEL是否为本地模型名并确认 Ollama 模型已ollama pull启动失败/数据丢失风险优先检查/var/lib/karakeep的属主是否为karakeep:karakeep以及.env文件权限是否允许服务用户读取端口冲突3000Web、9222浏览器、7700Meilisearch若被占用可分别通过PORT、浏览器服务配置、Meilisearch 配置调整。总结在 Arch Linux 上部署 Karakeep 是一条与 Docker 路线平行的裸机方案通过paru -S karakeep安装、在/etc/karakeep/karakeep.env中补充完整环境变量、以karakeep.target统一管理 Web / Workers / Browser / Meilisearch 四个服务。理解环境变量与 config.ts 源码中解析逻辑的对应关系是排障和定制部署的关键而从 Hoarder 升级时只要按「停服务 → 卸载 → 重命名数据目录 → 安装 → 修属主 → 配 env → 启动」的顺序执行即可无损保留全部历史数据。【免费下载链接】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),仅供参考