在 VPS 上部署 Karakeep：拥有支持搜索与 AI 的个人书签档案库

2026/8/30阅读约需 11 分钟

Tropic

Karakeep：在 VPS 上安装个人书签档案库

保存一个链接很容易。半年后再找到它却困难得多——尤其是当页面已经发生变化、消失，或淹没在数百个书签之中时。

Karakeep 保存的不仅是 URL，还包括页面内容、预览、笔记、图片和 PDF。你可以按文本搜索档案、将内容整理到不同列表中，并借助 AI 自动添加标签。它运行在你自己的 VPS 上，而且并不强制要求连接语言模型。

下面将介绍 Karakeep 的功能、服务器要求，以及如何在 Ubuntu 24.04 上通过 Docker Compose 完成安装，并配置 HTTPS 与备份。

七步部署 Karakeep

创建一台 Linux VPS，并将子域名（例如 keep.example.com）解析到该服务器。
安装 Docker Engine 和 Docker Compose。
下载官方的 docker-compose.yml。
生成密钥，并启动 Karakeep、Chrome 和 Meilisearch。
关闭内部的 3000 端口，并通过 Caddy 启用 HTTPS。
创建第一个账户，然后关闭公开注册。
安装浏览器扩展或移动应用，并导入书签。

启动服务不需要 AI 密钥。没有密钥时，页面保存、列表、笔记、OCR 和全文搜索仍然可以正常工作，只是不会自动生成标签和摘要。

Karakeep 是什么

Karakeep 是一款开源的自托管应用，可在同一个资料库中保存链接、文本笔记、图片和 PDF。该项目以前名为 Hoarder。

它的名称来自阿拉伯语单词 karakeeb，指的是看似杂乱、却可能隐藏着价值的零散物品。这正好描述了常见的书签收藏：有用的内容很多，但真正需要时却很难找到。

添加链接后，Karakeep 会获取页面标题和描述、提取可阅读的正文、生成预览，并在需要时保存页面的本地副本。

功能	浏览器书签	Karakeep
保存的内容	URL 和标题	正文、预览、笔记和附件
搜索方式	按标题和地址	按内容、标签和笔记
页面消失后	只剩无法访问的 URL	仍保留正文、截图或完整归档
整理方式	文件夹	标签、手动列表和智能列表
访问方式	浏览器内	网页、扩展、iOS 和 Android
服务器	浏览器配置文件或其云服务	你的 VPS 或家庭服务器

Karakeep 的主要功能

链接、笔记、图片和 PDF

每条记录都可以是链接、文本笔记或上传的文件。OCR 会从图片和 PDF 中提取文字，因此这些内容也能被搜索。你还可以为资料附加笔记、引用或其他文件。

按内容搜索

Meilisearch 会索引保存的正文、笔记和元数据。你不必记住准确标题，只要输入一个短语或主题即可。配置嵌入向量后，还可以使用按语义匹配的搜索。

智能列表与协作列表

同一条记录可以同时加入多个列表，而不会产生重复副本。列表可以保持私有、通过链接分享，或由多个用户共同编辑。

智能列表本质上是一个已保存的搜索条件，并会自动更新。例如，它可以显示过去一周内添加、且带有 ai 标签的所有资料。

页面归档

默认情况下，Karakeep 会保存提取出的正文以及页面可见区域的截图。你还可以额外启用完整页面快照、PDF 或独立 HTML 归档。这可以避免资料库受到“死链”影响，但会增加磁盘占用。

需要登录、采用复杂反机器人保护或属于交互式应用的页面，可能无法被完整保存。重要资料最好再单独上传为 PDF 或文件。

可选的 AI 标注

Karakeep 可以通过外部 OpenAI 兼容 API 或本地 Ollama 模型生成标签和简短摘要。即使不使用 AI，它仍然是一款功能完整的书签管理器。

本地模型不会把资料发送给外部提供商，但会消耗明显更多的内存。因此，Ollama 通常会与主要的 Karakeep 实例分开部署。

Karakeep 的服务器要求

官方文档没有规定固定的最低 CPU 和内存。完整安装包含三个容器：

Karakeep 保存数据库并提供用户界面；
无头 Chrome 打开页面、执行 JavaScript 并生成截图；
Meilisearch 为资料库建立索引。

对于一名用户且不运行本地 LLM，实用的起步配置为：

2 个 vCPU；
2 GB 内存；
20–30 GB SSD 或 NVMe；
Ubuntu 24.04 LTS；
公网 IP 和域名。

如果有多名用户、需要大规模导入、订阅大量 RSS 源或处理 PDF，使用 4 GB 内存会更舒适。磁盘需求取决于归档模式：纯文本占用很少，而完整截图、PDF 和视频会迅速扩大资料库。

如何在 VPS 上安装 Karakeep

以下示例使用 Ubuntu 24.04 和子域名 keep.example.com。

1. 配置 DNS 和防火墙

创建一条指向服务器 IP 地址的 DNS A 记录，然后通过 SSH 连接：

ssh root@SERVER_IP
apt update && apt upgrade -y

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable

在确认新的 SSH 连接能够正常建立之前，不要关闭当前会话。

2. 安装 Docker

apt install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt update
apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin
docker compose version

3. 下载 Karakeep 配置

mkdir -p /opt/karakeep
cd /opt/karakeep

curl -fsSLo docker-compose.yml \
  https://raw.githubusercontent.com/karakeep-app/karakeep/main/docker/docker-compose.yml

生成两个不同的密钥：

openssl rand -base64 36
openssl rand -base64 36 | tr -dc 'A-Za-z0-9'

创建 /opt/karakeep/.env：

KARAKEEP_VERSION=release
NEXTAUTH_SECRET=在此填入第一个密钥
MEILI_MASTER_KEY=在此填入第二个密钥
NEXTAUTH_URL=https://keep.example.com
DISABLE_SIGNUPS=false
DB_WAL_MODE=true
RATE_LIMITING_ENABLED=true

不要公开 .env：第一个密钥用于签署身份验证令牌，第二个密钥用于保护 Meilisearch。

4. 关闭内部端口

在 docker-compose.yml 中，将：

ports:
  - 3000:3000

替换为：

ports:
  - 127.0.0.1:3000:3000

这样，3000 端口就无法从互联网直接访问。

5. 启动容器

cd /opt/karakeep
docker compose up -d
docker compose ps

web、chrome 和 meilisearch 服务都应处于运行状态。可使用以下命令查看日志：

docker compose logs --tail=200

6. 启用 HTTPS

apt install -y caddy

cat > /etc/caddy/Caddyfile <<'EOF'
keep.example.com {
    reverse_proxy 127.0.0.1:3000
}
EOF

caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy

如果 DNS 已正确配置，且 80 和 443 端口开放，Caddy 会自动获取 TLS 证书。之后打开 https://keep.example.com。

7. 创建管理员并关闭注册

第一个注册的用户会自动成为管理员。创建账户后，在 .env 中设置：

DISABLE_SIGNUPS=true

应用更改：

cd /opt/karakeep
docker compose up -d

管理员仍然可以手动创建其他账户。

导入、扩展和移动应用

Karakeep 提供 Chrome、Firefox 和 Safari 扩展，同时也有 iOS 与 Android 应用。在手机上，可以通过系统的“分享”菜单把链接发送到档案库。

现有书签可以从浏览器标准 HTML 文件、Pocket、Omnivore 以及其他受支持的服务导入。大型档案最好分批添加，因为服务器需要打开页面、提取正文、生成截图并建立搜索索引。

如何启用 AI 和完整页面归档

使用 OpenAI 时，在 .env 中添加：

OPENAI_API_KEY=你的_API_密钥

其他 OpenAI 兼容服务可能还需要设置 OPENAI_BASE_URL。使用本地模型时，请通过 OLLAMA_BASE_URL 指定一个容器可以访问的地址。

完整的页面本地副本需要单独启用：

CRAWLER_FULL_PAGE_ARCHIVE=true

还可以使用 CRAWLER_FULL_PAGE_SCREENSHOT=true 和 CRAWLER_STORE_PDF=true。除非确有需要，不要同时启用所有模式，因为它们会明显增加磁盘占用。修改 .env 后，运行 docker compose up -d。

安全、更新与备份

Karakeep 的爬虫会从你的服务器网络中打开用户保存的地址。因此，不要保持公开注册，只允许可信人员访问。项目提供基础 SSRF 防护，但对于公共服务，官方建议隔离浏览器，或让其流量经过受限制的代理。

同时应使用 HTTPS 和高强度密码，不要暴露 3000 端口，并定期更新容器：

cd /opt/karakeep
docker compose up --pull always -d

主数据库和已保存的资料位于名为 data 的 Docker 卷中。复制前先停止容器：

mkdir -p /var/backups/karakeep
cd /opt/karakeep
docker compose stop

docker run --rm \
  -v karakeep_data:/source:ro \
  -v /var/backups/karakeep:/backup \
  alpine sh -c 'tar czf /backup/data-$(date +%F).tar.gz -C /source .'

cp .env docker-compose.yml /var/backups/karakeep/
docker compose start

名称 karakeep_data 假设项目目录为 /opt/karakeep；可通过 docker volume ls 进行确认。Meilisearch 索引可以重新构建，但对于大型资料库，也建议备份 karakeep_meilisearch 卷。

请把 /var/backups/karakeep 中的归档发送到另一台服务器、NAS 或对象存储。保存在同一台 VPS 上的副本无法防止磁盘故障或虚拟机被删除。

Karakeep 应选择怎样的 VPS

对于不使用 Ollama 的个人资料库，配置为 2 个 vCPU、2 GB 内存和 20–30 GB NVMe 的 Linux VPS 就足够了。若要进行大规模导入、支持多名用户并启用完整归档，建议选择 4 GB 内存和更大的磁盘。

Karakeep 可以部署在 tropic.host 的 VPS 上：固定 IP 便于绑定域名，而 NVMe 对 SQLite、搜索索引和大量小文件很有帮助。随着档案库增长，可以逐步增加资源。

本地 Ollama 的资源应单独计算：即使是较小的语言模型，也可能比整个 Karakeep 主服务栈需要更多内存。

总结

Karakeep 可以把零散链接变成一个可搜索的个人资料库。它能够保存页面、笔记、图片和 PDF，并支持 OCR、列表、浏览器扩展、移动应用以及可选的 AI 标注。

部署只需要一台小型 VPS、Docker Compose、域名和 HTTPS。安装后应关闭公开注册、监控磁盘占用，并保留外部备份。

FAQ

Karakeep 免费吗？

自托管版本是开源的，不要求强制订阅。你需要支付 VPS、域名、备份存储，以及在需要时使用外部 AI API 的费用。

Karakeep 运行时必须使用 API 密钥吗？

不需要。即使不使用 AI，资料保存与索引、列表、笔记、OCR 和全文搜索仍可正常工作。自动标签、摘要及相关功能才需要模型。

Karakeep 需要多少内存？

对于一名用户且不使用 Ollama，实用的起步配置是 2 GB 内存。若要进行大型导入、支持多名用户和频繁处理，4 GB 会更舒适。

可以从浏览器或 Pocket 导入书签吗？

可以。Karakeep 支持浏览器标准书签 HTML 文件、Pocket、Omnivore 和多种其他格式。导入后，Karakeep 会处理页面并将其加入搜索索引。

如果原网站消失，文章还能保留下来吗？

Karakeep 会保存提取出的正文和截图；启用完整归档后，还会保存本地副本或 PDF。需要登录的页面和复杂 Web 应用可能只能部分保存。

返回博客