Karakeep 裸机部署指南在 Debian 12 / Ubuntu 24.04 上使用官方 Linux 脚本完成安装、更新与迁移【免费下载链接】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 官方除了提供 Docker 部署方式外还维护了一个面向裸机baremetalDebian 12 / Ubuntu 24.04的一键安装脚本 karakeep-linux.sh。本指南以docs/versioned_docs/version-v0.28.0/02-installation/06-debuntu.md为核心脉络结合仓库内脚本源码完整讲解该脚本的安装、更新、迁移三大功能以及安装后涉及的系统服务、端口、配置文件与数据目录的运维要点。读完本文你将能够在一台干净的 Debian 12 或 Ubuntu 24.04 主机上以低权限用户方式跑起完整的 KarakeepWeb、后台任务、全文检索、无头浏览器并掌握后续升级与从 Hoarder 迁移的完整路径。适用环境与前置要求该脚本是 Proxmox Community Scripts 仓库中同类脚本的精简改编版仅适配以下两种系统的裸机安装其他发行版或虚拟化平台不受支持使用风险自负Debian 12版本代号bookwormUbuntu 24.04Noble Numbat版本代号noble脚本通过读取/etc/os-release中的VERSION_CODENAME来判断发行版见 karakeep-linux.shOS$(awk -F /^VERSION_CODENAME/{ print $NF } /etc/os-release)在此基础上脚本会按系统类型差异化安装依赖Ubuntu 24.04noble通过ppa:xtradeb/apps安装ungoogled-chromium与yt-dlp并建立/usr/bin/chromium软链接Debian 12 则直接安装chromium包并从 GitHub Releases 下载yt-dlp到/usr/bin/yt-dlp见 karakeep-linux.sh。注意安装脚本必须使用root身份或具备sudo权限的用户运行脚本开头会直接校验id -u是否为 0否则立即退出见 karakeep-linux.sh。脚本会完成以下全部工作安装除 Ollama 以外的所有依赖系统编译工具、Chromium、yt-dlp、monolith、Meilisearch 等从 GitHub 拉取指定版本源码构建 Web、Workers、CLI 三个子应用执行数据库迁移packages/db下的pnpm migrate生成 Meilisearch 配置与 Karakeep 环境变量文件创建低权限系统用户karakeep与meilisearch并据此编写、启用 systemd 服务实现开机自启。同时该脚本既是安装器也是更新器安装完成后再次运行update子命令即可完成版本升级详见下文「更新」小节。全新安装三步完成部署第一步下载脚本从 Karakeep 仓库下载脚本到目标主机wget https://raw.githubusercontent.com/karakeep-app/karakeep/main/karakeep-linux.sh第二步运行安装器在全新系统上执行install子命令bash karakeep-linux.sh install安装过程会依次执行依赖安装、Node.js 24通过 NodeSource 仓库安装、源码构建、配置生成、用户与权限设置、systemd 服务创建与启用最后通过service_check install校验 4 个服务是否全部处于active状态见 karakeep-linux.sh。校验通过后脚本会提示访问本机 IP 的3000端口创建账号。第三步创建账号并登录安装完成后访问http://localhost:3000页面会呈现 Sign In 登录页首次使用点击注册创建管理员账号即可开始使用。小提示脚本同时支持-h/--help、-v/--verbose打印脚本标准输出与--no-color禁用彩色输出三个选项排障时可加-v观察完整执行过程。更新一条命令完成版本升级若 Karakeep 此前正是通过该脚本安装的则升级同样只需一行命令同样需要 root/sudo 权限bash karakeep-linux.sh update更新器的工作逻辑见 karakeep-linux.sh可以拆解为版本比对通过 GitHub API 获取最新 release 版本号与$INSTALL_DIR/version.txt中记录的已安装版本比对版本一致则直接提示No update required.服务停机先停止karakeep-web与karakeep-workersMeilisearch 与浏览器服务保持运行依赖同步Debian 12bookworm上先执行yt-dlp -U自更新替换代码删除旧安装目录/opt/karakeep下载新版源码压缩包并解压回原位同步用sed更新karakeep.env中的SERVER_VERSION重新构建依次对apps/web、apps/workers、apps/cli执行pnpm i --frozen-lockfile与pnpm build并在packages/db执行pnpm migrate应用数据库迁移服务迁移修补脚本内置了历史版本迁移逻辑例如 0.27 版本将 worker 编译产物从.mjs改为.js更新器会自动改写karakeep-workers.service中的ExecStart并执行systemctl daemon-reload重启与校验systemctl restart karakeep.target后再次做服务健康检查。值得强调的是脚本会在更新前删除整个/opt/karakeep安装目录而配置/etc/karakeep、数据/var/lib/karakeep与日志/var/log/karakeep全部独立存放在安装目录之外因此升级不会触碰任何用户数据——这正是脚本将「配置与数据路径与安装路径分离」设计的直接收益。服务与端口karakeep.target 下的 4 个 systemd 服务安装完成后karakeep.target这个 systemd 聚合目标包含 4 个服务分别承担 Karakeep 的不同职责。脚本源码中为每个服务都生成了完整的 systemd unit 文件见 karakeep-linux.sh。服务职责默认端口运行用户meilisearch.service提供全文检索能力Workers 服务连接它写入/查询索引7700meilisearchkarakeep-web.service提供 Karakeep Web 服务Next.js 前端 API3000karakeepkarakeep-workers.service提供后台任务服务爬取、推理、索引等不对外监听端口无karakeepkarakeep-browser.service提供无头 Chromium 浏览器服务供爬虫抓取页面、截图9222root各服务的单元文件要点如下meilisearch.service以meilisearch低权限用户运行ExecStart/usr/bin/meilisearch --config-file-path /etc/meilisearch.toml并启用了一整套 systemd 加固选项NoNewPrivileges、ProtectHome、ProtectSystemfull、PrivateTmp、RestrictNamespaces等最大限度收敛权限面karakeep-browser.service无头浏览器以--headless --no-sandbox --disable-gpu --disable-dev-shm-usage --remote-debugging-address127.0.0.1 --remote-debugging-port9222启动只监听本机回环地址不会暴露到公网karakeep-workers.service通过EnvironmentFile/etc/karakeep/karakeep.env注入配置WorkingDirectory/opt/karakeep/apps/workers执行node dist/index.js标准输出/错误追加写入/var/log/karakeep/karakeep-workers.log其Wants/After声明依赖 browser 与 meilisearch 服务保证启动顺序正确karakeep-web.service同样以karakeep用户运行WorkingDirectory/opt/karakeep/apps/web执行pnpm start日志写入/var/log/karakeep/karakeep-web.logkarakeep.target作为聚合目标Wants上述 4 个服务安装时执行systemctl enable -q --now meilisearch.service karakeep.target实现开机自启。常用运维命令systemctl status karakeep.target # 查看整体状态 systemctl status karakeep-web # 查看单个服务状态 journalctl -xeu karakeep-workers # 查看 workers 最近日志 tail -f /var/log/karakeep/karakeep-web.log脚本还额外生成了一份 logrotate 配置/etc/logrotate.d/karakeep对/var/log/karakeep/*.log实行每周轮转、保留 4 份、压缩归档避免日志无限膨胀。配置文件、ENV 文件与数据目录安装脚本刻意将「程序本体」与「配置/数据」分离程序装在/opt/karakeep而所有需要持久化或手工编辑的内容集中在以下位置升级时程序目录整体替换、其余目录原样保留。/etc/meilisearch.toml — Meilisearch 配置脚本生成的基础配置见 karakeep-linux.sh如下env production master_key 随机生成的 12 字节 base64 主密钥 db_path /var/lib/meilisearch/data dump_dir /var/lib/meilisearch/dumps snapshot_dir /var/lib/meilisearch/snapshots no_analytics true要点解读master_key由openssl rand -base64 12随机生成用于阻止未授权连接——Meilisearch 的所有请求都必须携带该密钥Karakeep 侧则通过MEILI_MASTER_KEY环境变量与之对应no_analytics true关闭了 Meilisearch 的分析数据上报该文件权限被收紧为chmod 600并属主设置为meilisearch用户数据库、dump、snapshot 三个目录均位于/var/lib/meilisearch之下。/var/lib/meilisearch — Meilisearch 数据目录存放 Meilisearch 的索引数据库、dump 与 snapshot。若需备份全文索引应备份此目录。/etc/karakeep/karakeep.env — Karakeep 环境变量文件这是配置 Karakeep 的核心入口。安装脚本生成的默认内容如下见 karakeep-linux.shNODE_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该文件同样被设置为chmod 600内含密钥切勿泄露。编辑此文件后必须重启 Web 与 Workers 两个服务才能生效sudo systemctl restart karakeep-workers karakeep-web脚本预置的注释行给出了最常用的扩展方向OPENAI_API_KEY/OLLAMA_BASE_URL配置 AI 自动打标签与摘要的推理后端二选一即可启用自动打标签否则该功能会被跳过INFERENCE_TEXT_MODEL/INFERENCE_IMAGE_MODEL指定文本/图片推理模型使用 Ollama 时必须改为本地模型名图片模型需支持视觉 API如llavaCRAWLER_VIDEO_DOWNLOAD/CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE启用页面内视频下载基于 yt-dlp及其大小上限。关于该 ENV 文件中每个变量的完整定义、默认值与取值范围仓库维护了权威参考文档 环境变量配置参考其底层实现则由 packages/shared/config.ts 中基于 zod 的allEnvschema 统一解析例如PORT默认 3000、NEXTAUTH_URL默认http://localhost:3000、DATA_DIR默认空字符串生产环境必须显式指定、BROWSER_WEB_URL为可选见 packages/shared/config.ts。/var/lib/karakeep — Karakeep 数据库目录SQLite 数据库及默认的资产assets存储都位于此目录。如果删除该目录内容将丢失全部数据。升级脚本会在替换程序目录后重新chown -R karakeep:karakeep此目录确保属主正确。配置纵深从 ENV 文件解锁完整能力默认 ENV 文件只是「最小可用」配置。结合 packages/shared/config.ts 的源码以下类别的变量都可以按需在karakeep.env中追加随后重启服务全文检索与 Worker 并发SEARCH_NUM_WORKERS默认 1、SEARCH_JOB_TIMEOUT_SEC默认 30Meilisearch 地址固定由MEILI_ADDR指定Worker 选择性启停WORKERS_ENABLED_WORKERS/WORKERS_DISABLED_WORKERS接受逗号分隔的 worker 名列表可选值包括crawler、inference、search、adminMaintenance、video、feed、assetPreprocessing、webhook、ruleEngine、backup见 apps/workers/index.ts 中的workerBuilders注册表爬虫行为CRAWLER_NUM_WORKERS默认 1串行爬取以节省资源、CRAWLER_STORE_PDF、CRAWLER_FULL_PAGE_ARCHIVEmonolith 整页归档、CRAWLER_VIDEO_DOWNLOAD等OCR 识别OCR_LANGS默认eng、OCR_CONFIDENCE_THRESHOLD默认 50、OCR_USE_LLM切换为 LLM 驱动 OCR邮件与验证SMTP_HOST、SMTP_PORT默认 587、SMTP_SECURE、EMAIL_VERIFICATION_REQUIRED等出网代理CRAWLER_HTTP_PROXY、CRAWLER_HTTPS_PROXY、CRAWLER_NO_PROXY监控PROMETHEUS_AUTH_TOKEN、OTEL_TRACING_ENABLED、EVENT_LOGS_ENABLED等。一个典型的「启用本地 Ollama 自动打标签 提高推理并发」追加示例OLLAMA_BASE_URLhttp://127.0.0.1:11434 INFERENCE_TEXT_MODELqwen2.5:7b INFERENCE_IMAGE_MODELllava INFERENCE_NUM_WORKERS2 INFERENCE_JOB_TIMEOUT_SEC60 LOG_LEVELnotice编辑后执行sudo systemctl restart karakeep-workers karakeep-web生效。仍在运行 Hoarder一键迁移到 Karakeep如果你此前使用本脚本安装了HoarderKarakeep 的前身当前版本的脚本仓库根目录 karakeep-linux.sh v3.0.0提供了migrate子命令可无人工干预地完成整体迁移迁移完成后还会自动检查更新bash karakeep-linux.sh migrate迁移逻辑见 karakeep-linux.sh包括停止旧的hoarder-browser/workers/web服务用sed批量把环境变量与服务文件中的hoarder→karakeep、Hoarder→Karakeep重命名将/opt/hoarder、/var/lib/hoarder、/etc/hoarder、/var/log/hoarder整体搬迁为/opt/karakeep、/var/lib/karakeep、/etc/karakeep、/var/log/karakeep重命名系统用户与用户组hoarder→karakeep随后daemon-reload、启用karakeep.target并做服务健康检查。需要注意的是migrate仅在/opt/karakeep不存在时执行若 Karakeep 已安装会提示无需迁移该脚本不会处理通过 Docker 等其他方式部署的 HoarderDocker 用户的迁移方式请参考 Hoarder 到 Karakeep 迁移指南其中包含修改镜像名为ghcr.io/karakeep-app/karakeep的 diff 说明无论迁移还是更新脚本都明确提示先备份现有数据。常见问题与排障思路服务启动失败service_check检测到任一服务非active即会报错并提示journalctl -xeu service-name排查。优先检查karakeep-workers与karakeep-web的日志文件/var/log/karakeep/。修改 env 后不生效确认已执行sudo systemctl restart karakeep-workers karakeep-web且文件权限未被意外放开应保持 600。端口占用默认占用3000Web、7700Meilisearch、9222无头浏览器如被占用可先systemctl stop冲突服务或调整karakeep.env中的PORT与对应 unit 文件中的监听端口后systemctl daemon-reload。升级卡在构建阶段可在bash karakeep-linux.sh update前确认网络可访问 GitHub源码包、yt-dlp、monolith 均从 GitHub Releases 下载必要时加-v观察详细输出。小结karakeep-linux.sh为 Debian 12 / Ubuntu 24.04 裸机用户提供了一条完整、可重复的部署链路install负责从零搭建含依赖、构建、配置、systemd 与低权限加固update负责无痛升级配置与数据独立于程序目录之外migrate负责从旧版 Hoarder 无缝过渡。安装完成后运维的日常操作集中在三处/etc/karakeep/karakeep.envKarakeep 配置、/etc/meilisearch.toml检索配置、/var/lib/karakeep数据备份对象。结合 环境变量配置参考 与 packages/shared/config.ts 源码你可以在不依赖 Docker 的前提下把 Karakeep 打磨成完全符合自己需求的私有书签中心。【免费下载链接】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），仅供参考