Karakeep 裸机部署指南基于官方脚本在 Debian 12 / Ubuntu 24.04 上安装、升级与迁移【免费下载链接】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 官方安装脚本 karakeep-linux.sh 为主线完整讲解如何在裸机 Debian 12 或 Ubuntu 24.04 上完成 Karakeep自托管书签收藏应用支持链接、笔记与图片收藏内置 AI 自动打标签与全文搜索的安装、systemd 服务管理、配置文件修改、版本升级以及从旧版 Hoarder 的无缝迁移。读完本文你将掌握这套脚本化部署方案的全部命令、端口与目录布局并能独立完成一台裸机服务器的日常运维。本文对应的官方文档为 docs/docs/02-installation/06-debuntu.md版本化副本见 docs/versioned_docs/version-v0.33.0/02-installation/06-debuntu.md以下操作细节均可在仓库根目录的 karakeep-linux.sh 脚本源码中得到印证。一、脚本方案概述与适用前提1.1 脚本来源与适用范围karakeep-linux.sh是一个精简自 Proxmox Community Scripts 仓库的安装脚本脚本头注释标注为 v3.0.0作者 vhsdreamMIT 许可经过改造后只适用于裸机 Debian 12 或 Ubuntu 24.04 系统任何其他发行版、容器或虚拟化平台上的使用均不受官方支持自行使用风险自负见 karakeep-linux.sh 与文档开头的警告框。一个值得注意的细节是文档中写的 Debian 12 (Buster) 实际存在笔误——Debian 12 的代号是Bookworm。脚本源码中正是通过读取/etc/os-release的VERSION_CODENAME字段区分发行版并在安装依赖时按bookwormDebian与nobleUbuntu 24.04分支处理例如 Ubuntu 需要额外添加ppa:xtradeb/apps源来安装 ungoogled-chromiumOS$(awk -F /^VERSION_CODENAME/{ print $NF } /etc/os-release)因此实际支持的系统为Debian 12Bookworm与Ubuntu 24.04Noble Numbat。1.2 脚本自动完成的工作运行安装后脚本会自动完成以下全部工作对应 karakeep-linux.sh 中的install_karakeep函数安装系统依赖g、curl、build-essential、sudo、unzip、gnupg、graphicsmagick、ghostscript、ca-certificates等Ollama 除外如需本地 AI 推理需自行安装安装抓取相关组件Chromium 无头浏览器Ubuntu 使用ungoogled-chromiumDebian 使用chromium、yt-dlp视频下载、monolith整页归档安装 Meilisearch通过官方.deb包安装用于 Karakeep 的全文搜索安装 Node.js 24.x通过 NodeSource 官方源安装并启用 corepack用于 pnpm编译安装 Karakeep从 GitHub 最新 release 下载源码依次构建web、workers、cli三个应用并执行数据库迁移cd $INSTALL_DIR/packages/db pnpm migrate对应 packages/db/package.json 中的migrate脚本生成基础配置写入 Meilisearch 配置与 Karakeep 环境变量文件并随机生成 master key 与 JWT 密钥创建低权限系统用户并修正目录权限生成并启用 systemd 服务与日志轮转配置。脚本还内置了完善的错误处理与视觉反馈通过trap捕获异常catch函数会输出出错行号与退出码、spinner 动画显示进度、-v参数可输出完整日志、支持--no-color关闭彩色输出karakeep-linux.sh。二、三步完成首次安装2.1 下载脚本从 Karakeep 官方仓库下载安装脚本到服务器wget https://raw.githubusercontent.com/karakeep-app/karakeep/main/karakeep-linux.sh该脚本同时存在于本仓库根目录karakeep-linux.sh也可以直接查看其源码了解全部实现细节。2.2 运行安装命令权限要求脚本必须以root身份运行或使用具有sudo权限的用户执行。脚本内部会在启动时校验[ $(id -u) -ne 0 ] die This script requires root privileges...karakeep-linux.sh。全新安装时执行bash karakeep-linux.sh install安装过程中脚本会按顺序完成以下关键步骤可结合-v参数观察完整输出阶段具体操作源码位置安装依赖apt-get install安装基础包Ubuntu 额外安装 ungoogled-chromium 与 yt-dlpkarakeep-linux.sh安装 Node.js配置 NodeSourcenode_24.x源并安装 nodejs再全局安装最新 corepack解决 issue #967karakeep-linux.sh下载并编译 Karakeep查询 GitHub 最新 release 的tag_name解压到/opt/karakeep依次pnpm i --frozen-lockfile pnpm build构建 web/workers/clikarakeep-linux.sh数据库迁移在packages/db目录执行pnpm migrate基于 drizzle 的迁移工具karakeep-linux.sh生成配置文件随机生成 Meilisearch master key 与 Karakeep 密钥并写入配置karakeep-linux.sh创建用户创建meilisearch、karakeep两个nologin系统用户并设置目录属主karakeep-linux.sh生成服务写入 4 个 systemd service 1 个 target 文件与 logrotate 配置karakeep-linux.sh启动服务systemctl enable --now meilisearch.service karakeep.target并做健康检查karakeep-linux.sh安装脚本还会导出构建时环境变量NEXT_TELEMETRY_DISABLED1、PLAYWRIGHT_SKIP_BROWSER_DOWNLOADtrue、CItrue其中跳过 Playwright 浏览器下载是因为裸机方案使用系统自带的 Chromium 作为无头浏览器而不是 Playwright 内置的浏览器。2.3 创建账号并登录安装完成后浏览器访问http://localhost:3000如果服务器有独立 IP脚本最后会提示访问http://服务器IP:3000即可看到登录/注册页面并创建你的第一个账号。http://localhost:3000三、升级把脚本当更新器用这套脚本不仅是安装器同时承担更新器的职责。如果 Karakeep 之前是通过该脚本安装的那么升级只需要一条命令bash karakeep-linux.sh update同样必须以root或具有sudo权限的用户运行。升级逻辑对应 karakeep-linux.sh 的update_karakeep函数值得了解便于你判断升级风险读取/opt/karakeep/version.txt中的当前版本号与 GitHub 最新 release 对比若无新版本直接提示 No update required 并退出若有新版本先停止karakeep-web与karakeep-workers服务删除/opt/karakeep注意数据目录/var/lib/karakeep独立于安装目录之外因此不会被删除重新下载新版本源码、重新构建三个应用并执行数据库迁移更新/etc/karakeep/karakeep.env中的SERVER_VERSION字段若 corepack 版本过低 0.31.0则先升级 corepack重启karakeep.target并执行服务健康检查。升级脚本还内置了历史迁移逻辑例如 Karakeep 0.27 起 workers 的编译产物从dist/index.mjs改为dist/index.js升级时会自动通过sed修正 systemd 服务文件中的ExecStart路径并执行daemon-reloadkarakeep-linux.sh。这说明脚本对跨版本升级做了兼容处理但仍建议升级前备份数据目录。重要限制脚本明确声明——它不会更新或迁移通过其他任何方式如 Docker安装的 Karakeep/Hoarder 实例升级前请务必做好数据备份。四、服务与端口体系安装完成后karakeep.target这个 systemd target 聚合了 4 个服务它们共同组成 Karakeep 的运行体系服务文件生成逻辑见 karakeep-linux.sh服务名职责默认端口运行用户关键说明meilisearch.service提供全文搜索由 Karakeep Workers 连接7700meilisearch通过--config-file-path /etc/meilisearch.toml启动karakeep-web.service提供 Karakeep Web 界面与 API3000karakeep执行pnpm startNODE_ENVproductionkarakeep-workers.service后台任务抓取、AI 推理、搜索索引、视频、RSS、备份等无端口karakeep执行node dist/index.jskarakeep-browser.service无头浏览器用于网页抓取与截图9222root以 Chromium--headless模式监听127.0.0.1:9222服务之间的依赖关系在 unit 文件中显式声明karakeep-workers.service声明Wants与Afterkarakeep-browser.service和meilisearch.servicekarakeep-linux.shkarakeep-web.service声明Wants与Afterkarakeep-workers.servicekarakeep.target聚合全部四个服务karakeep-linux.sh。日常管理命令# 查看整体状态 systemctl status karakeep.target # 查看单个服务状态 systemctl status karakeep-web karakeep-workers karakeep-browser meilisearch # 查看失败服务的日志 journalctl -xeu service-name安全方面值得一提meilisearch.service使用了大量 systemd 加固选项NoNewPrivilegestrue、ProtectHometrue、ProtectSystemfull、PrivateTmptrue、RestrictNamespacesyes、MemoryDenyWriteExecuteyes等karakeep-web/karakeep-workers以非特权用户karakeep运行Meilisearch 以专用用户meilisearch运行这是文档强调的低权限用户环境提升安全性的具体实现。五、配置文件、环境变量与数据目录安装脚本刻意将配置文件与数据目录放在与安装目录/opt/karakeep分离的位置这样升级时只需整体替换安装目录配置与数据得以保留。核心路径如下路径用途备注/etc/meilisearch.tomlMeilisearch 基础配置含数据库路径、关闭分析上报、master key防止未授权连接/var/lib/meilisearchMeilisearch 数据库目录属主meilisearch:meilisearch/etc/karakeep/karakeep.envKarakeep 环境变量文件编辑后需重启 web 与 workers 服务/var/lib/karakeepKarakeep 数据库目录删除其中内容将丢失全部数据/opt/karakeepKarakeep 安装目录升级时整体替换/var/log/karakeep运行日志目录配合/etc/logrotate.d/karakeep每周轮转、保留 4 份、压缩5.1 Meilisearch 配置/etc/meilisearch.toml脚本生成的内容如下karakeep-linux.sh其中MASTER_KEY由openssl rand -base64 12随机生成env production master_key 随机生成的master key db_path /var/lib/meilisearch/data dump_dir /var/lib/meilisearch/dumps snapshot_dir /var/lib/meilisearch/snapshots no_analytics truemaster_keyMeilisearch 的主密钥禁止未授权连接Karakeep 通过环境变量MEILI_MASTER_KEY持有同一密钥进行认证no_analytics true关闭 Meilisearch 的分析数据上报注重隐私的自托管用户通常希望如此配置文件权限被设为600并归属于meilisearch用户。5.2 Karakeep 环境变量文件/etc/karakeep/karakeep.env脚本生成的最小可用配置如下karakeep-linux.shNODE_ENVproduction SERVER_VERSION安装的版本号 NEXTAUTH_SECRET随机生成的JWT密钥 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各关键变量的作用这些变量在 packages/shared/config.ts 与 docs/docs/03-configuration/01-environment-variables.md 中有完整定义NEXTAUTH_SECRET用于签名 JWT 令牌的随机字符串脚本用openssl rand -base64 36 | cut -c1-24生成。若缺失应用启动时会抛出 NEXTAUTH_SECRET is not set 错误packages/shared/config.tsNEXTAUTH_URL服务器对外地址。文档说明应用在缺少它时仍可运行但注销等场景会跳转到错误地址config.ts 中其默认值为http://localhost:3000且会自动去除末尾斜杠packages/shared/config.tsDATA_DIR必填的持久化数据目录数据库存放于此资产抓取的文件、图片默认存放在${DATA_DIR}/assetsMEILI_ADDRMeilisearch 地址未设置时全文搜索将被禁用MEILI_MASTER_KEY与/etc/meilisearch.toml中的master_key一致BROWSER_WEB_URL无头浏览器的 HTTP 调试地址workers 通过它解析调试端口的 WebSocket 地址来完成截图与 JS 执行packages/shared/config.ts。文件底部预置的注释项即为常见扩展配置入口取消注释OPENAI_API_KEY或OLLAMA_BASE_URL可开启AI 自动打标签两者至少设置其一否则自动打标签会被跳过CRAWLER_VIDEO_DOWNLOADtrue可让抓取器通过 yt-dlp 下载页面视频INFERENCE_TEXT_MODEL/INFERENCE_IMAGE_MODEL可切换推理模型使用 Ollama 时必须修改且图片模型需支持视觉能力如 llava。完整的环境变量清单含 OCR、Webhook、SMTP、代理、监控等数百项请查阅 docs/docs/03-configuration/01-environment-variables.md。5.3 修改配置后的生效方式编辑完/etc/karakeep/karakeep.env后需要重启加载该环境变量的两个服务sudo systemctl restart karakeep-workers karakeep-web若修改的是 Meilisearch 相关配置则需重启meilisearch.service若修改了karakeep-browser.service的启动参数则重启karakeep-browser。5.4 数据安全提醒/var/lib/karakeep保存着 Karakeep 的全部数据书签、用户、标签等。如果你删除此文件夹中的内容将丢失所有数据。建议定期备份或参考 docs/docs/06-administration/06-server-migration.md 了解迁移备份方案。六、仍在运行 Hoarder一条命令完成迁移Hoarder 已更名为 Karakeep仓库与镜像均已迁移到新名称。如果你此前是用本脚本或其 Hoarder 版本在 Debian/Ubuntu 裸机上安装的 Hoarder那么脚本提供了无需交互的migrate命令bash karakeep-linux.sh migrate迁移过程karakeep-linux.sh 的migrate_karakeep函数会依次完成停止旧的hoarder-browser、hoarder-workers、hoarder-web服务通过sed将/etc/hoarder/hoarder.env、各 systemd 服务文件与 target 文件中的hoarder替换为karakeep重命名迁移/opt/hoarder→/opt/karakeep、/var/lib/hoarder→/var/lib/karakeep、/etc/hoarder→/etc/karakeep、/var/log/hoarder→/var/log/karakeep将用户hoarder重命名为karakeepusermod -l karakeep hoarder -d $INSTALL_DIR并同步修改组名修正目录属主、systemctl daemon-reload后启用并启动karakeep.target迁移完成后自动衔接update流程检查并安装最新版本。如果检测到/opt/karakeep已存在脚本会提示 There is no need for a migration 并跳过。若你的 Hoarder 是通过 Docker 部署的迁移方式则不同——需要将 docker-compose 中的镜像从ghcr.io/hoarder-app/hoarder改为ghcr.io/karakeep-app/karakeep详见 docs/docs/06-administration/08-hoarder-to-karakeep-migration.md。当前仓库的 docker/docker-compose.yml 已经是新镜像名ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}可作为对照参考。七、常见问题排查某个服务启动失败脚本的service_check会逐一检查 4 个服务是否处于active状态只要有任一服务未激活即报错并提示查看日志karakeep-linux.sh。用以下命令定位问题journalctl -xeu karakeep-web journalctl -xeu karakeep-workers journalctl -xeu meilisearch journalctl -xeu karakeep-browser升级报 corepack 相关错误脚本会在升级时检查corepack -v是否低于0.31.0并自动处理若手动环境异常可执行npm install -g corepacklatest后重试karakeep-linux.sh。无法访问 Web 界面确认karakeep-web服务在 3000 端口监听、防火墙放行该端口且NEXTAUTH_URL与你的实际访问地址一致。想要关闭 AI 自动打标签Karakeep 也支持 Ollama 本地推理只需在/etc/karakeep/karakeep.env中取消注释并设置OLLAMA_BASE_URLOllama 本身需自行安装脚本不负责。各推理相关参数如INFERENCE_CONTEXT_LENGTH默认 2048、INFERENCE_TEXT_MODEL默认gpt-5.6-luna的详细说明见 docs/docs/03-configuration/01-environment-variables.md 的 Inference Configs 一节。八、总结Karakeep 的裸机安装脚本把安装依赖 → 编译应用 → 生成配置 → 创建用户 → 注册 systemd 服务 → 健康检查整条链路自动化同时兼顾了升级与旧版迁移且通过将数据/配置目录与安装目录分离、以低权限用户运行服务、对 systemd 单元做安全加固等方式提升了可维护性与安全性。无论是个人 NAS 式的小型自托管还是需要精细控制 systemd 服务行为的服务器场景这套方案都是 Docker 部署参考 docker/docker-compose.yml之外的一条可靠路径。部署完成后可结合 docs/docs/03-configuration/01-environment-variables.md 逐步解锁 AI 打标签、视频抓取、RSS、Webhook 等高级能力。【免费下载链接】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），仅供参考