在 Debian 12 / Ubuntu 24.04 裸机部署 Karakeep一键脚本安装、systemd 服务管理与升级迁移实战指南【免费下载链接】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 是一个可自托管的收藏一切应用书签、笔记与图片内置基于 AI 的自动打标签与全文搜索。本文以仓库中的 Debian/Ubuntu 安装文档 为核心结合仓库根目录下的官方安装脚本 karakeep-linux.sh 逐行拆解完整讲解如何在 Debian 12bookworm与 Ubuntu 24.04noble裸机上完成安装、配置、升级以及从旧版 Hoarder 平滑迁移的全过程。读完本文你将掌握这套脚本化部署方案的目录布局、四个 systemd 服务的职责与端口、环境变量配置方法以及故障排查思路。适用前提与重要警告在使用脚本之前务必明确它的定位与边界该脚本是 Proxmox Community Scripts 仓库中对应脚本的精简改编版仅适用于裸机baremetalDebian 12 或 Ubuntu 24.04其他发行版与使用场景不受支持自行使用风险自负。脚本必须以 root 身份运行或由具有sudo权限的用户执行脚本 第 528 行 会直接校验id -u非 root 会以This script requires root privileges退出。脚本会下载并安装除 Ollama 之外的所有依赖完成 Karakeep 与 MeilisearchKarakeep 使用的全文检索引擎的基础配置并创建、启用开机自启所需的 systemd 服务文件。Karakeep 与 Meilisearch 均在低权限专用用户环境下运行以提高安全性。该脚本同时具备安装器与更新器双重职能详见下文 升级 Karakeep 一节。一、下载脚本从 Karakeep 官方仓库下载安装脚本到目标服务器wget https://raw.githubusercontent.com/karakeep-app/karakeep/main/karakeep-linux.sh当前仓库根目录下就保留了该脚本的完整源码karakeep-linux.sh版本 v3.0.0MIT 协议你可以先阅读它了解脚本行为再执行。脚本支持三个子命令与三个通用选项命令/选项作用install在全新的 Debian 12/Ubuntu 24.04 系统上安装 Karakeepupdate检查并安装更新仅适用于此前由本脚本安装的系统migrate对旧版 Hoarder 裸机安装执行完整迁移随后自动检查更新-h, --help打印帮助并退出-v, --verbose打印脚本标准输出默认静默运行--no-color禁用彩色输出二、全新安装install 模式步骤 1运行安装命令bash karakeep-linux.sh install脚本会依次完成安装系统依赖 → 安装 Node.js → 下载 Karakeep 源码并构建 web / workers / cli 三个应用 → 初始化数据库 → 生成 Meilisearch 与 Karakeep 的配置文件 → 创建低权限系统用户 → 写入 systemd 服务文件与日志轮转配置 → 启用并启动服务。步骤 2创建账号并登录安装完成后访问http://localhost:3000即可看到登录/注册页面创建你的第一个账号即可开始使用。若为远程服务器脚本完成时会打印本机 IP可访问http://服务器IP:3000。三、脚本幕后做了什么源码级解析对照 karakeep-linux.sh 的install_karakeep()函数第 175-410 行可以清晰还原安装的完整链路便于你判断部署是否符合预期。1. 系统依赖安装apt-get install --no-install-recommends -y \ g curl build-essential sudo unzip gnupg \ graphicsmagick ghostscript ca-certificates其中graphicsmagick图片处理、ghostscriptPDF 处理是书签内容处理链路的核心依赖。随后按发行版分支安装浏览器与视频下载工具Ubuntu 24.04noble通过ppa:xtradeb/apps安装ungoogled-chromium与yt-dlp并软链/usr/bin/chromiumDebian 12bookworm直接安装chromium并从 GitHub 下载yt-dlp二进制到/usr/bin/yt-dlp。此外还会安装monolith用于整页归档与meilisearch.deb全文搜索引擎本体。2. Node.js 与 Karakeep 构建通过 Nodesource 安装Node.js 24node_24.x仓库随后npm install -g corepacklatest以启用 pnpm对应 issue #967从 GitHub Releases 拉取最新 tag 对应的源码压缩包解压到/opt/karakeep依次对apps/web、apps/workers、apps/cli执行pnpm i --frozen-lockfile与pnpm build最后在packages/db下执行pnpm migrate完成数据库迁移。构建期间设置NEXT_TELEMETRY_DISABLED1、PLAYWRIGHT_SKIP_BROWSER_DOWNLOADtrue、CItrue避免遥测上报与重复下载浏览器。3. 目录布局脚本通过全局变量定义了清晰的目录分离策略第 168-173 行配置、数据、日志与安装代码相互分离这也是更新时能够整体替换安装目录而不丢数据的关键路径用途/opt/karakeepKarakeep 安装目录源码与构建产物INSTALL_DIR/var/lib/karakeepKarakeep 数据库目录DATA_DIR/etc/karakeepKarakeep 环境变量配置文件目录CONFIG_DIR/var/log/karakeepKarakeep 运行日志目录LOG_DIR4. 低权限用户脚本创建两个专用系统账号均以/usr/sbin/nologin为 shell禁止交互登录meilisearch-m -d /var/lib/meilisearch主目录即数据目录仅拥有 Meilisearch 相关文件karakeep-M -d /opt/karakeep仅拥有安装目录、配置目录、数据目录与日志目录。这保证了 Web 服务与 Worker 进程即使被攻破也无法越权访问系统其他部分。四、服务与端口安装完成后karakeep.target聚合了 4 个 systemd 服务karakeep-linux.sh 第 382-390 行服务职责端口meilisearch.service提供全文检索能力Karakeep Workers 服务连接它7700默认karakeep-web.service提供 Karakeep Web 服务3000默认karakeep-workers.service提供后台任务 Worker 服务爬取、打标签、索引无端口karakeep-browser.service提供无头浏览器服务用于网页抓取与截图9222默认常用管理命令# 查看聚合目标与各服务状态 systemctl status karakeep.target systemctl status meilisearch karakeep-web karakeep-workers karakeep-browser # 停止/启动整套服务 systemctl stop karakeep.target systemctl start karakeep.targetsystemd 安全加固细节从脚本生成的 unit 文件可以看出其安全设计meilisearch.service第 287-320 行以meilisearch用户运行声明NoNewPrivilegestrue、ProtectHometrue、ProtectSystemfull、ProtectKernelTunablestrue、PrivateTmptrue、CapabilityBoundingSet清空能力集、MemoryDenyWriteExecuteyes、RestrictRealtimeyes、RestrictNamespacesyes等一系列加固选项仅通过ReadWritePaths/var/lib/meilisearch放开数据目录写权限karakeep-browser.service第 322-336 行以 root 启动 Chromium 无头模式参数为--headless --no-sandbox --disable-gpu --disable-dev-shm-usage --remote-debugging-address127.0.0.1 --remote-debugging-port9222 --hide-scrollbars调试端口仅绑定本机回环地址karakeep-workers.service / karakeep-web.service第 338-380 行均以karakeep用户运行通过EnvironmentFile/etc/karakeep/karakeep.env注入配置ExecStart分别为node dist/index.jsworkers与pnpm startweb标准输出/错误追加写入/var/log/karakeep/下的对应日志文件日志轮转/etc/logrotate.d/karakeep对/var/log/karakeep/*.log每周轮转保留 4 份并压缩第 392-402 行。五、配置文件、ENV 文件与数据位置安装脚本在配置路径与数据库路径上刻意与安装路径分离便于后续平滑升级。各文件位置与作用如下路径作用/etc/meilisearch.tomlMeilisearch 基础配置数据库位置、关闭遥测分析、启用 master key防止未授权连接/var/lib/meilisearchMeilisearch 数据库位置/etc/karakeep/karakeep.envKarakeep 环境变量文件在此编辑以进行默认配置之外的调整/var/lib/karakeepKarakeep 数据库位置删除该目录内容将丢失全部数据Meilisearch 配置文件脚本生成第 243-251 行的/etc/meilisearch.toml内容为env production master_key openssl rand -base64 12 随机生成 db_path /var/lib/meilisearch/data dump_dir /var/lib/meilisearch/dumps snapshot_dir /var/lib/meilisearch/snapshots no_analytics true文件权限为600且属主为meilisearch。其中master_key会被同步写入 Karakeep 的MEILI_MASTER_KEY两者必须一致Karakeep 才能通过认证访问 Meilisearch。Karakeep 环境变量文件脚本生成第 254-269 行的/etc/karakeep/karakeep.env初始内容如下其中的密钥均由openssl rand随机生成NODE_ENVproduction SERVER_VERSION安装时的版本号 NEXTAUTH_SECRET随机 24 位密钥 NEXTAUTH_URLhttp://localhost:3000 DATA_DIR/var/lib/karakeep MEILI_ADDRhttp://127.0.0.1:7700 MEILI_MASTER_KEY与 meilisearch.toml 相同的 master key BROWSER_WEB_URLhttp://127.0.0.1:9222 # CRAWLER_VIDEO_DOWNLOADtrue # CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE # OPENAI_API_KEY # OLLAMA_BASE_URL # INFERENCE_TEXT_MODEL # INFERENCE_IMAGE_MODEL修改配置后重启服务编辑/etc/karakeep/karakeep.env后web 与 workers 两个服务必须重启才能生效sudo systemctl restart karakeep-workers karakeep-web注意meilisearch 的 master key 变更需要同时修改/etc/meilisearch.toml与karakeep.env并重启meilisearch.service与karakeep-workers.service。常用 ENV 参数速查以下参数与裸机部署关系最密切完整参数清单见 环境变量配置文档变量是否必填默认值说明NEXTAUTH_SECRET是无用于签名 JWT 的随机字符串可用openssl rand -base64 36生成NEXTAUTH_URL是无指向你服务器的地址不设置时登出等操作可能跳转到错误地址DATA_DIR是无持久化数据目录数据库所在位置未设置ASSETS_DIR时资源默认也存于此处MEILI_ADDR否无Meilisearch 地址不设置则搜索功能整体禁用MEILI_MASTER_KEY生产环境且启用搜索时必填无Meilisearch master key可用openssl rand -base64 36 \| tr -dc A-Za-z0-9生成BROWSER_WEB_URL否无无头浏览器调试地址不设置时 Worker 退化为纯 HTTP 请求跳过截图与 JS 执行OPENAI_API_KEY否无启用 AI 自动打标签所需的 OpenAI 密钥OLLAMA_BASE_URL否无使用 Ollama 做本地推理时的 API 地址INFERENCE_TEXT_MODEL否gpt-5.6-luna文本推理模型使用 Ollama 时必须改为本地模型名INFERENCE_IMAGE_MODEL否gpt-4o-mini图片推理模型Ollama 下需使用支持视觉的模型如 llavaCRAWLER_VIDEO_DOWNLOAD否false是否使用 yt-dlp 下载页面视频CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE否50下载视频的最大体积MB-1表示不限制DISABLE_SIGNUPS否false设为true后禁止新用户注册DB_WAL_MODE否false为 SQLite 启用 WAL 模式以提升数据库性能网络盘上不建议开启LOG_LEVEL否debug日志级别生产环境建议设为notice或warning需要说明的是自动打标签功能只有在配置了OPENAI_API_KEY或OLLAMA_BASE_URL之一时才会启用否则会自动跳过INFERENCE_*与EMBEDDING_*系列参数用于调节推理质量与并发裸机部署可参考 环境变量配置文档 中的完整表格按需调整。六、升级 Karakeepupdate 模式升级同样要求 root 或 sudo 权限且仅适用于此前由本脚本安装的 Karakeep脚本 第 414-416 行 会检查/opt/karakeep是否存在否则直接报错Is Karakeep even installed?bash karakeep-linux.sh update升级流程对应update_karakeep()第 412-470 行通过 GitHub API 获取最新 release 版本号与/opt/karakeep/version.txt中记录的上次安装版本比对无新版本则提示No update required.若有新版本先停止karakeep-web与karakeep-workers服务Debianbookworm下额外执行yt-dlp -U自更新用sed更新karakeep.env中的SERVER_VERSION整体删除并重新下载、解压、构建安装目录在packages/db执行pnpm migrate应用数据库迁移执行内置的迁移修补逻辑如 0.27 版本将 worker 编译产物从index.mjs改为index.js时会自动改写 unit 文件并daemon-reload见 第 456-462 行systemctl restart karakeep.target并通过service_check验证 4 个核心服务全部处于 active 状态。由于配置/etc/karakeep、数据/var/lib/karakeep与安装目录/opt/karakeep相互分离整个升级过程不会触碰你的数据与自定义配置。七、从 Hoarder 迁移Hoarder 已更名为 Karakeep。受 GitHub 限制旧 Docker 镜像可能在更名后不再获得更新需要将镜像指向新的 Karakeep 镜像详见 Hoarder to Karakeep 迁移文档web: - image: ghcr.io/hoarder-app/hoarder:${HOARDER_VERSION:-release} image: ghcr.io/karakeep-app/karakeep:${HOARDER_VERSION:-release}同时可在.env中修改HOARDER_VERSION变量若修改需两处同步。裸机安装的迁移如果你此前正是用本脚本或其 Hoarder 版本在 Debian/Ubuntu 上安装了 Hoarder直接执行bash karakeep-linux.sh migrate该命令无需任何用户输入全程自动完成migrate_karakeep()第 472-499 行停止hoarder-browser、hoarder-workers、hoarder-web服务将/etc/hoarder/hoarder.env及 systemd unit 文件中的hoarder/Hoarder字样批量替换为karakeep/Karakeep并重命名 unit 文件与hoarder.target移动目录/opt/hoarder → /opt/karakeep、/var/lib/hoarder → /var/lib/karakeep、/etc/hoarder → /etc/karakeep、/var/log/hoarder → /var/log/karakeep同时重命名日志文件通过usermod -l karakeep hoarder与groupmod -n karakeep hoarder重命名用户与用户组修正文件属主systemctl daemon-reload后启用并启动karakeep.target验证服务状态随后自动进入 update 流程检查并应用更新。若系统上已经是 Karakeep/opt/karakeep存在脚本会提示There is no need for a migration并跳过。迁移完成后你的书签、标签、列表与账号数据都会原样保留。八、故障排查脚本内置的service_check()第 501-526 行会在安装/更新/迁移结束时逐一检查karakeep-browser、karakeep-workers、karakeep-web、meilisearch四个服务的 active 状态若存在失败会提示Some services have failed. Check journalctl -xeu service-name to see what is going on常见排查手段# 查看某个服务失败的详细原因 journalctl -xeu karakeep-web journalctl -xeu karakeep-workers journalctl -xeu meilisearch # 查看 Karakeep 运行日志 tail -f /var/log/karakeep/karakeep-web.log tail -f /var/log/karakeep/karakeep-workers.log # 确认端口监听 ss -tlnp | grep -E 3000|7700|9222如果修改了环境变量后服务未生效请先执行sudo systemctl restart karakeep-workers karakeep-web若涉及 Meilisearch 配置变更还需重启meilisearch.service。结语借助 karakeep-linux.sh 这一脚本Debian 12 与 Ubuntu 24.04 裸机用户可以在一分钟内完成 Karakeep 的完整部署——它自动处理了依赖、构建、低权限用户、systemd 服务与日志轮转等全部环节并将配置与数据隔离在/etc/karakeep与/var/lib/karakeep之下为后续update升级与migrate迁移铺平了道路。对于希望摆脱 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），仅供参考