Karakeep 在 Arch Linux 上的安装部署指南：AUR 包安装、systemd 服务管理与 Hoarder 迁移-二趣网

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 用户可以通过 AUR（Arch 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-cli：Karakeep 命令行工具（操作书签、列表、标签，支持批量导入导出） 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_DOWNLOAD=true后，抓取页面时才会调用 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`	否	`3000`	Web 服务监听端口（裸机安装可修改）
`LOG_LEVEL`	否	`debug`	日志级别，生产环境建议设为`notice`或`warning`
`DB_WAL_MODE`	否	`false`	SQLite 启用 WAL 模式，建议设为`true`以提升数据库性能（网络盘除外）
`ASSETS_DIR`	否	`${DATA_DIR}/assets`	抓取资产的存储路径，未设置时默认为数据目录下的`assets`
`MAX_ASSET_SIZE_MB`	否	`50`	允许上传的单个资产最大体积（MB）
`OLLAMA_BASE_URL`	否	未设置	启用 Ollama 本地推理时填写其 API 地址
`OPENAI_API_KEY`	否	未设置	启用 OpenAI 推理时填写 API Key

一份可直接使用的示例

以下配置覆盖了最常用的组合——本地 Meilisearch 全文搜索 + Ollama 本地推理：

# 数据目录（务必指向持久化磁盘，删除内容将丢失全部数据） DATA_DIR=/var/lib/karakeep # Web 服务端口 PORT=3000 # 认证 NEXTAUTH_URL=http://localhost:3000 NEXTAUTH_SECRET=<openssl rand -base64 36 生成> # 全文搜索（Meilisearch） MEILI_ADDR=http://127.0.0.1:7700 MEILI_MASTER_KEY=<openssl rand -base64 36 | tr -dc 'A-Za-z0-9' 生成> # 本地 AI 推理（二选一：Ollama 或 OpenAI） OLLAMA_BASE_URL=http://127.0.0.1:11434 INFERENCE_TEXT_MODEL=gemma3 INFERENCE_IMAGE_MODEL=llava # 生产环境建议 LOG_LEVEL=notice DB_WAL_MODE=true

配置底层原理：env 解析即服务配置

从源码实现看，Karakeep 的全部服务配置都通过 packages/shared/config.ts 中的 zod schema 从process.env解析而来。这意味着：

布尔型变量（如DB_WAL_MODE、DISABLE_SIGNUPS）只接受字面量字符串"true"/"false"；
多数变量都有安全默认值（如PORT默认3000、OCR_LANGS默认eng），未设置时按默认值运行；
存在跨变量校验，例如EMAIL_VERIFICATION_REQUIRED=true时若未配置 SMTP 会在启动时直接报错（见 config.ts）。

因此，编辑完/etc/karakeep/karakeep.env后必须重启相关服务（见下一步），配置才会重新加载生效。

四、启用服务并完成首次访问

执行以下命令启动并设置开机自启：

sudo systemctl enable --now karakeep.target

karakeep.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（爬虫）、inference（AI 推理）、search（搜索索引）、adminMaintenance、video（视频下载）、feed（RSS）、assetPreprocessing（图片/OCR 预处理）、webhook、ruleEngine（自动化规则）、backup（备份调度）等。默认全部启用；若希望裁剪，可在环境变量中设置WORKERS_ENABLED_WORKERS（白名单，逗号分隔）或WORKERS_DISABLED_WORKERS（黑名单，优先级更高）。

五、从 Hoarder 迁移到 Karakeep（升级路径）

Hoarder 已正式更名为 Karakeep，AUR 中的 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 步：安装 Karakeep

paru -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 步：启动 Karakeep

sudo 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文件权限是否允许服务用户读取；
端口冲突：3000（Web）、9222（浏览器）、7700（Meilisearch）若被占用，可分别通过PORT、浏览器服务配置、Meilisearch 配置调整。

总结

在 Arch Linux 上部署 Karakeep 是一条与 Docker 路线平行的裸机方案：通过paru -S karakeep安装、在/etc/karakeep/karakeep.env中补充完整环境变量、以karakeep.target统一管理 Web / Workers / Browser / Meilisearch 四个服务。理解环境变量与 config.ts 源码中解析逻辑的对应关系，是排障和定制部署的关键；而从 Hoarder 升级时，只要按「停服务 → 卸载 → 重命名数据目录 → 安装 → 修属主 → 配 env → 启动」的顺序执行，即可无损保留全部历史数据。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析