在 Arch Linux 上安装与迁移 Karakeep：AUR 包、systemd 服务编排与 Hoarder 数据迁移指南-编程实验室

在 Arch Linux 上安装与迁移 Karakeep：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）是一个可自托管的"收藏一切"应用，支持收藏链接、笔记与图片，并基于 AI 自动打标签、提供全文搜索。本文以官方文档 03-archlinux.md 为核心，完整讲解在 Arch Linux 上通过 AUR 安装 Karakeep、配置/etc/karakeep/karakeep.env、启用 systemd 服务单元，以及从旧版 Hoarder 无损迁移数据的全过程，并结合仓库源码（packages/shared/config.ts、apps/workers/index.ts 等）说明每个关键配置项背后的实现逻辑。

注意：AUR 中的karakeep包由社区维护，并非 Karakeep 官方维护，安装前请自行评估包的可信度与维护活跃度。

一、通过 AUR 安装 Karakeep

Arch Linux 用户可以使用 AUR 助手（例如paru）安装 Karakeep：

paru -S karakeep

安装完成后，包管理器会自动完成用户创建、目录初始化与 systemd 单元文件（karakeep.target及其下属服务）的部署。

可选依赖安装

按需安装以下可选依赖，用于扩展 Karakeep 的功能：

# karakeep-cli: karakeep 命令行工具 paru -S karakeep-cli # ollama: 本地 AI 推理，用于自动打标签 sudo pacman -S ollama # yt-dlp: 下载视频（配合 CRAWLER_VIDEO_DOWNLOAD 使用） sudo pacman -S yt-dlp

其中：

ollama提供本地推理能力。自动打标签功能要求配置OPENAI_API_KEY或OLLAMA_BASE_URL二者之一；使用 Ollama 时需要在 packages/shared/config.ts 中对应设置OLLAMA_BASE_URL（如http://127.0.0.1:11434），并提前下载所需的模型（可在 Ollama 模型库中挑选，例如llama3系列；图片推理模型需支持视觉 API，如llava）。不配置任何推理提供方时，自动打标签会被跳过（inference.isConfigured判定逻辑见 packages/shared/config.ts）。
yt-dlp用于视频下载。需要在环境变量中开启CRAWLER_VIDEO_DOWNLOAD=true（默认false），还可通过CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE（默认 50，单位 MB，-1表示不限制）与CRAWLER_VIDEO_DOWNLOAD_TIMEOUT_SEC（默认 600 秒）控制下载行为。
也可以使用 OpenAI 替代 Ollama 作为推理后端，此时只需配置OPENAI_API_KEY，无需本地模型。

二、基础配置：编辑 /etc/karakeep/karakeep.env

Karakeep 主要通过环境变量进行配置，所有受支持的环境变量统一在 packages/shared/config.ts 中定义与校验（该文件基于 Zod schema 解析process.env，并完成默认值填充与运行时约束检查）。安装包通常会在/etc/karakeep/karakeep.env预置部分变量，文档中未预置的变量需要你自行补充。

必备变量

以下变量是让实例正常运行并保持数据持久化的核心：

变量名	是否必需	默认值	说明
`PORT`	否	`3000`	Web 服务监听端口。
`DATA_DIR`	是	未设置	持久化数据目录，SQLite 数据库存放于此；未单独设置`ASSETS_DIR`时，爬取资源也默认存放于`${DATA_DIR}/assets`（见 packages/shared/config.ts）。
`ASSETS_DIR`	否	未设置	爬取资源的存放路径，缺省为`${DATA_DIR}/assets`。
`NEXTAUTH_URL`	是	未设置	服务器对外地址；不设置虽然可运行，但注销等场景会重定向到错误地址。
`NEXTAUTH_SECRET`	是	未设置	用于签名 JWT 的随机串，可用`openssl rand -base64 36`生成。

在 packages/shared/config.ts 中可以看到校验规则：NEXTAUTH_SECRET未设置时，签名函数会直接抛出NEXTAUTH_SECRET is not set错误；DATA_DIR的默认值为空字符串，因此生产部署必须显式指定。

搜索相关（Meilisearch）

从该版本起，Karakeep 依赖 Meilisearch 提供全文搜索：

变量名	是否必需	默认值	说明
`MEILI_ADDR`	否	未设置	Meilisearch 地址（如`http://127.0.0.1:7700`）。未设置时搜索功能被禁用。
`MEILI_MASTER_KEY`	仅生产环境且启用搜索时	未设置	Meilisearch 主密钥，可用`openssl rand -base64 36 \\| tr -dc 'A-Za-z0-9'`生成。

服务与 Worker 相关

变量名	是否必需	默认值	说明
`WORKERS_PORT`	否	`0`（随机端口）	Worker 导出 Prometheus 指标`/metrics`的端口。
`WORKERS_HOST`	否	`127.0.0.1`	监听`WORKERS_PORT`的主机地址。
`WORKERS_ENABLED_WORKERS`	否	未设置	逗号分隔的 Worker 白名单，设置后仅运行这些 Worker。v0.30.0 版本有效值：`crawler,inference,search,adminMaintenance,video,feed,assetPreprocessing,webhook,ruleEngine`（当前主分支还加入了`backup`，完整列表见 apps/workers/index.ts 中的`workerBuilders`）。
`WORKERS_DISABLED_WORKERS`	否	未设置	逗号分隔的 Worker 黑名单，优先级高于`WORKERS_ENABLED_WORKERS`。

Worker 启停逻辑位于 apps/workers/index.ts：白名单非空时，不在名单中的 Worker 一律不启动；黑名单命中则直接跳过。

自动打标签相关（结合 Ollama 场景）

变量名	是否必需	默认值	说明
`OLLAMA_BASE_URL`	否	未设置	Ollama API 地址，用于本地推理。
`OLLAMA_KEEP_ALIVE`	否	未设置	模型在内存中的驻留时长，例如`5m`表示 5 分钟，`-1m`表示常驻，`0`表示用完立即卸载。
`INFERENCE_TEXT_MODEL`	否	`gpt-5.6-luna`（v0.30.0 为`gpt-4.1-mini`）	文本推理模型；使用 Ollama 时必须改为你下载的本地模型名。
`INFERENCE_IMAGE_MODEL`	否	`gpt-4o-mini`	图片推理模型；使用 Ollama 时需选择支持视觉的模型（如`llava`）。
`INFERENCE_ENABLE_AUTO_TAGGING`	否	`true`	是否启用自动打标签。
`INFERENCE_CONTEXT_LENGTH`	否	`2048`	传给推理模型的 token 上限，越大标签质量越好但推理成本（OpenAI 计费 / Ollama 资源）越高。
`INFERENCE_JOB_TIMEOUT_SEC`	否	`30`	推理任务超时时间；无强力 GPU 运行 Ollama 时建议调大。
`INFERENCE_FETCH_TIMEOUT_SEC`	否	`300`	（仅 Ollama）请求 Ollama 服务器的超时时间。
`INFERENCE_LANG`	否	`english`	生成标签的语言。

其他常用变量

变量名	默认值	说明
`LOG_LEVEL`	`debug`	日志级别（遵循 winston 级别定义），生产环境建议`notice`或`warning`。
`MAX_ASSET_SIZE_MB`	`50`	允许上传的最大资源大小（MB）。
`DISABLE_SIGNUPS`	`false`	设为`true`时禁止新用户注册。
`DB_WAL_MODE`	`false`	为 SQLite 启用 WAL 模式，可显著提升数据库性能；除非数据库位于网络挂载盘，否则建议开启。
`DISABLE_NEW_RELEASE_CHECK`	`false`	设为`true`时禁用管理面板中的新版本检查。

完整的变量清单（含资产存储 S3、OAuth、OCR、Webhook、SMTP、代理、OpenTelemetry 监控等）请参阅环境变量配置文档。例如启用视频下载与整页截图等爬取行为时，可参考其中的 Crawler Configs 章节。

配置示例

一份面向 Arch Linux 本机部署的最小化示例（按需增删）：

# /etc/karakeep/karakeep.env DATA_DIR=/var/lib/karakeep NEXTAUTH_URL=http://localhost:3000 NEXTAUTH_SECRET=<openssl rand -base64 36 生成的值> MEILI_ADDR=http://127.0.0.1:7700 MEILI_MASTER_KEY=<为 Meilisearch 生成的主密钥> LOG_LEVEL=notice DB_WAL_MODE=true # 本地推理（自动打标签） OLLAMA_BASE_URL=http://127.0.0.1:11434 INFERENCE_TEXT_MODEL=llama3 INFERENCE_IMAGE_MODEL=llava INFERENCE_LANG=english # 可选：视频下载 CRAWLER_VIDEO_DOWNLOAD=true

三、启用 systemd 服务并访问 Web UI

配置完成后，启用服务：

sudo systemctl enable --now karakeep.target

然后访问http://localhost:3000，即可看到登录/注册页面。若修改了PORT或NEXTAUTH_URL，请以实际地址访问。

四、服务与端口编排

karakeep.target是一个 systemd target，聚合了三个服务单元：

karakeep-web.service：提供 Karakeep Web UI 服务，默认监听3000端口。
karakeep-workers.service：提供后台 Worker 服务（爬虫、推理、搜索索引、RSS、Webhook 等），不监听对外端口（其指标端口由WORKERS_PORT控制，默认随机）。
karakeep-browser.service：提供无头浏览器（headless browser）服务，默认监听9222端口，用于爬取网页时的截图与 JavaScript 执行。

从当前版本开始，Karakeep 依赖 Meilisearch 提供全文搜索：karakeep-workers.service依赖meilisearch.service，因此启动karakeep.target时会同时拉起meilisearch.service，无需手动单独启动。

这与官方 Docker 编排中的服务拓扑一致——docker/docker-compose.yml 中同样包含web（暴露3000:3000）、chrome（无头浏览器）与meilisearch三个服务，并设置了MEILI_ADDR: http://meilisearch:7700与BROWSER_WEB_URL: http://chrome:9222。可以推断，Arch 包的服务划分沿用了同一套进程模型：Web 进程、Worker 进程、无头浏览器进程彼此独立，通过环境变量（如BROWSER_WEB_URL）互相协作。

排查问题时，可用以下命令查看各服务状态与日志：

systemctl status karakeep.target systemctl status karakeep-web.service karakeep-workers.service karakeep-browser.service meilisearch.service journalctl -u karakeep-workers.service -f

五、从 Hoarder 迁移到 Karakeep

由于项目已从 Hoarder 更名为 Karakeep，AUR 的 PKGBUILD 已全面将hoarder引用替换为karakeep。若希望在升级过程中保留已有的 Hoarder 数据，请严格按照以下步骤操作：

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. 重命名旧数据目录

sudo mv /var/lib/hoarder /var/lib/karakeep

4. 安装 Karakeep

paru -S karakeep

5. 修正数据目录属主

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

7. 启动 Karakeep

sudo systemctl enable --now karakeep.target

迁移完成后，旧数据的 SQLite 数据库与资产文件已位于新数据目录/var/lib/karakeep下，且属主已修正为karakeep:karakeep，Karakeep 可以直接接管使用。若迁移前旧实例还配置了 Meilisearch 索引数据，建议一并确认新实例的MEILI_ADDR/MEILI_MASTER_KEY指向与索引数据一致，否则需要重建搜索索引。

六、常见问题与排查要点

登录页面打不开：先确认karakeep-web.service已启动且PORT未被占用；检查journalctl -u karakeep-web.service中的报错。
自动打标签不生效：检查是否设置了OPENAI_API_KEY或OLLAMA_BASE_URL（两者都没有时inference.isConfigured为false，推理任务被跳过）；若用 Ollama，确认模型已下载、OLLAMA_BASE_URL可达，且INFERENCE_TEXT_MODEL指向正确的本地模型名。
搜索无结果：确认MEILI_ADDR已正确配置，且meilisearch.service已随karakeep.target一并启动。
视频无法下载：确认已安装yt-dlp并设置CRAWLER_VIDEO_DOWNLOAD=true。
数据目录权限问题：/var/lib/karakeep的属主必须是运行服务的karakeep用户，否则数据库写入会失败。

通过上述安装、配置与迁移流程，你可以在 Arch Linux 上获得一套完整的、可离线推理的自托管收藏系统：Web 界面、后台 Worker 与无头浏览器协同工作，Meilisearch 提供全文检索，Ollama 提供本地 AI 自动打标签。相关源码入口包括环境变量解析与校验、Worker 注册与启停以及 Docker 服务拓扑参考，可供进一步深入阅读。

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