在 Arch Linux 上安装与迁移 KarakeepAUR 包、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/hoarderKarakeep原 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 安装 KarakeepArch Linux 用户可以使用 AUR 助手例如paru安装 Karakeepparu -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_DOWNLOADtrue默认false还可通过CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE默认 50单位 MB-1表示不限制与CRAWLER_VIDEO_DOWNLOAD_TIMEOUT_SEC默认 600 秒控制下载行为。也可以使用 OpenAI 替代 Ollama 作为推理后端此时只需配置OPENAI_API_KEY无需本地模型。二、基础配置编辑 /etc/karakeep/karakeep.envKarakeep 主要通过环境变量进行配置所有受支持的环境变量统一在 packages/shared/config.ts 中定义与校验该文件基于 Zod schema 解析process.env并完成默认值填充与运行时约束检查。安装包通常会在/etc/karakeep/karakeep.env预置部分变量文档中未预置的变量需要你自行补充。必备变量以下变量是让实例正常运行并保持数据持久化的核心变量名是否必需默认值说明PORT否3000Web 服务监听端口。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-lunav0.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_LEVELdebug日志级别遵循 winston 级别定义生产环境建议notice或warning。MAX_ASSET_SIZE_MB50允许上传的最大资源大小MB。DISABLE_SIGNUPSfalse设为true时禁止新用户注册。DB_WAL_MODEfalse为 SQLite 启用 WAL 模式可显著提升数据库性能除非数据库位于网络挂载盘否则建议开启。DISABLE_NEW_RELEASE_CHECKfalse设为true时禁用管理面板中的新版本检查。完整的变量清单含资产存储 S3、OAuth、OCR、Webhook、SMTP、代理、OpenTelemetry 监控等请参阅 环境变量配置文档。例如启用视频下载与整页截图等爬取行为时可参考其中的 Crawler Configs 章节。配置示例一份面向 Arch Linux 本机部署的最小化示例按需增删# /etc/karakeep/karakeep.env DATA_DIR/var/lib/karakeep NEXTAUTH_URLhttp://localhost:3000 NEXTAUTH_SECRETopenssl rand -base64 36 生成的值 MEILI_ADDRhttp://127.0.0.1:7700 MEILI_MASTER_KEY为 Meilisearch 生成的主密钥 LOG_LEVELnotice DB_WAL_MODEtrue # 本地推理自动打标签 OLLAMA_BASE_URLhttp://127.0.0.1:11434 INFERENCE_TEXT_MODELllama3 INFERENCE_IMAGE_MODELllava INFERENCE_LANGenglish # 可选视频下载 CRAWLER_VIDEO_DOWNLOADtrue三、启用 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 更名为 KarakeepAUR 的 PKGBUILD 已全面将hoarder引用替换为karakeep。若希望在升级过程中保留已有的 Hoarder 数据请严格按照以下步骤操作1. 停止旧服务sudo systemctl stop hoarder-web.service hoarder-worker.service hoarder-browser.service sudo systemctl disable --now hoarder.target2. 卸载 Hoarder卸载后如有需要可手动清理旧的hoarder用户与用户组。paru -R hoarder3. 重命名旧数据目录sudo mv /var/lib/hoarder /var/lib/karakeep4. 安装 Karakeepparu -S karakeep5. 修正数据目录属主sudo chown -R karakeep:karakeep /var/lib/karakeep6. 配置 Karakeep编辑/etc/karakeep/karakeep.env参照环境变量配置文档 填写变量——文档未预置的变量需要自行补充。也可以直接将旧的环境变量文件复制过来若旧变量名与新版一致可省去逐项手写sudo cp -f /etc/hoarder/hoarder.env /etc/karakeep/karakeep.env7. 启动 Karakeepsudo systemctl enable --now karakeep.target迁移完成后旧数据的 SQLite 数据库与资产文件已位于新数据目录/var/lib/karakeep下且属主已修正为karakeep:karakeepKarakeep 可以直接接管使用。若迁移前旧实例还配置了 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_DOWNLOADtrue。数据目录权限问题/var/lib/karakeep的属主必须是运行服务的karakeep用户否则数据库写入会失败。通过上述安装、配置与迁移流程你可以在 Arch Linux 上获得一套完整的、可离线推理的自托管收藏系统Web 界面、后台 Worker 与无头浏览器协同工作Meilisearch 提供全文检索Ollama 提供本地 AI 自动打标签。相关源码入口包括 环境变量解析与校验、Worker 注册与启停 以及 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 Arch Linux 上安装与迁移 KarakeepAUR 包、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/hoarderKarakeep原 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 安装 KarakeepArch Linux 用户可以使用 AUR 助手例如paru安装 Karakeepparu -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_DOWNLOADtrue默认false还可通过CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE默认 50单位 MB-1表示不限制与CRAWLER_VIDEO_DOWNLOAD_TIMEOUT_SEC默认 600 秒控制下载行为。也可以使用 OpenAI 替代 Ollama 作为推理后端此时只需配置OPENAI_API_KEY无需本地模型。二、基础配置编辑 /etc/karakeep/karakeep.envKarakeep 主要通过环境变量进行配置所有受支持的环境变量统一在 packages/shared/config.ts 中定义与校验该文件基于 Zod schema 解析process.env并完成默认值填充与运行时约束检查。安装包通常会在/etc/karakeep/karakeep.env预置部分变量文档中未预置的变量需要你自行补充。必备变量以下变量是让实例正常运行并保持数据持久化的核心变量名是否必需默认值说明PORT否3000Web 服务监听端口。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-lunav0.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_LEVELdebug日志级别遵循 winston 级别定义生产环境建议notice或warning。MAX_ASSET_SIZE_MB50允许上传的最大资源大小MB。DISABLE_SIGNUPSfalse设为true时禁止新用户注册。DB_WAL_MODEfalse为 SQLite 启用 WAL 模式可显著提升数据库性能除非数据库位于网络挂载盘否则建议开启。DISABLE_NEW_RELEASE_CHECKfalse设为true时禁用管理面板中的新版本检查。完整的变量清单含资产存储 S3、OAuth、OCR、Webhook、SMTP、代理、OpenTelemetry 监控等请参阅 环境变量配置文档。例如启用视频下载与整页截图等爬取行为时可参考其中的 Crawler Configs 章节。配置示例一份面向 Arch Linux 本机部署的最小化示例按需增删# /etc/karakeep/karakeep.env DATA_DIR/var/lib/karakeep NEXTAUTH_URLhttp://localhost:3000 NEXTAUTH_SECRETopenssl rand -base64 36 生成的值 MEILI_ADDRhttp://127.0.0.1:7700 MEILI_MASTER_KEY为 Meilisearch 生成的主密钥 LOG_LEVELnotice DB_WAL_MODEtrue # 本地推理自动打标签 OLLAMA_BASE_URLhttp://127.0.0.1:11434 INFERENCE_TEXT_MODELllama3 INFERENCE_IMAGE_MODELllava INFERENCE_LANGenglish # 可选视频下载 CRAWLER_VIDEO_DOWNLOADtrue三、启用 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 更名为 KarakeepAUR 的 PKGBUILD 已全面将hoarder引用替换为karakeep。若希望在升级过程中保留已有的 Hoarder 数据请严格按照以下步骤操作1. 停止旧服务sudo systemctl stop hoarder-web.service hoarder-worker.service hoarder-browser.service sudo systemctl disable --now hoarder.target2. 卸载 Hoarder卸载后如有需要可手动清理旧的hoarder用户与用户组。paru -R hoarder3. 重命名旧数据目录sudo mv /var/lib/hoarder /var/lib/karakeep4. 安装 Karakeepparu -S karakeep5. 修正数据目录属主sudo chown -R karakeep:karakeep /var/lib/karakeep6. 配置 Karakeep编辑/etc/karakeep/karakeep.env参照环境变量配置文档 填写变量——文档未预置的变量需要自行补充。也可以直接将旧的环境变量文件复制过来若旧变量名与新版一致可省去逐项手写sudo cp -f /etc/hoarder/hoarder.env /etc/karakeep/karakeep.env7. 启动 Karakeepsudo systemctl enable --now karakeep.target迁移完成后旧数据的 SQLite 数据库与资产文件已位于新数据目录/var/lib/karakeep下且属主已修正为karakeep:karakeepKarakeep 可以直接接管使用。若迁移前旧实例还配置了 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_DOWNLOADtrue。数据目录权限问题/var/lib/karakeep的属主必须是运行服务的karakeep用户否则数据库写入会失败。通过上述安装、配置与迁移流程你可以在 Arch Linux 上获得一套完整的、可离线推理的自托管收藏系统Web 界面、后台 Worker 与无头浏览器协同工作Meilisearch 提供全文检索Ollama 提供本地 AI 自动打标签。相关源码入口包括 环境变量解析与校验、Worker 注册与启停 以及 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
