部署教程

Karakeep 部署教程：自建收藏库、网页抓取与全文搜索

发布于 2026-10-03

使用 VPS 部署 Karakeep，介绍配置、访问方式、实际操作及数据备份。

开始前

一个链接放浏览器书签，一张参考图留在相册，几行想到的话写进聊天记录。等真正需要这些材料时，往往只记得“以前保存过”。Karakeep 可以把链接、图片和笔记集中收集，配合标签、列表和搜索整理素材。

这次先部署不接外部模型的收藏库。自动标签属于可选能力，没有 API Key 也能使用基本收藏功能。启用模型、内容抓取或截图以前，应知道哪些材料会交给哪些服务处理，不能把“自建网页入口”理解成所有功能都会在浏览器里离线完成。

部署前先确认 VPS 的磁盘、内存和公网访问条件，也可以查看雨云云服务器；注册时填写优惠码 `KuZhuJi`。

前往雨云选购 ↗

注册推荐码：KuZhuJi

三个服务不要省掉其中一个

官方 Docker 配置包含网页应用、用于抓取的 Chrome 和 Meilisearch。应用保存收藏与附件，Chrome 参与网页处理，Meilisearch 提供搜索索引。网页能够登录，只证明入口正常，不能证明抓取与搜索都接通。

这三个服务的镜像和配置应来自同一份当前部署模板。不要把旧版 Hoarder 教程里的镜像名、浏览器地址和搜索版本拼在一起。Karakeep 曾更名，旧材料有参考价值，但升级路径和当前参数需要按正式文档核对。

服务器准备好 Docker Engine、Compose 插件和宿主机 Caddy，域名 `keep.example.com` 指向 VPS。考虑收藏图片的容量，并给搜索索引和网页抓取留内存。没有必要给初次试用承诺最低配置能容纳多少收藏，先用小批内容观察任务队列和资源使用。

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

mkdir -p /opt/karakeep/data /opt/karakeep/meili-data
cd /opt/karakeep
umask 077
openssl rand -hex 32
openssl rand -hex 32

创建 `.env`，两个随机值分别作为会话密钥和搜索主密钥，不使用公开示例。初始化先通过 SSH 转发，本机访问地址为 `http://localhost:13000`；正式入口接好后改回域名。

ini；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

KARAKEEP_VERSION=release
NEXTAUTH_SECRET=your-generated-session-secret
MEILI_MASTER_KEY=your-generated-search-secret
NEXTAUTH_URL=http://localhost:13000

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

chmod 600 .env

按当前模板连接应用、浏览器和搜索

保存为 `compose.yaml`。以下采用研究时官方模板中的 Chrome 镜像与 Meilisearch 版本，应用和搜索都加载 `.env`。搜索和 Chrome 不发布宿主机端口，调试接口不应直接暴露到公网。

yaml；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

services:
  web:
    image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    env_file: .env
    volumes:
      - ./data:/data
    environment:
      DATA_DIR: /data
      MEILI_ADDR: http://meilisearch:7700
      BROWSER_WEB_URL: http://chrome:9222
  chrome:
    image: ghcr.io/karakeep-app/karakeep-chrome:release
    restart: unless-stopped
    init: true
    command:
      - --disable-gpu
      - --disable-dev-shm-usage
      - --hide-scrollbars
      - --disable-blink-features=AutomationControlled
      - --window-size=1440,900
  meilisearch:
    image: getmeili/meilisearch:v1.41.0
    restart: unless-stopped
    env_file: .env
    environment:
      MEILI_NO_ANALYTICS: "true"
    volumes:
      - ./meili-data:/meili_data

`DATA_DIR` 保持容器内 `/data`，要改宿主机存储位置时改冒号左边的路径。浏览器和搜索地址使用 Compose 服务名，不能写宿主机回环地址。首次部署后记录三个镜像的摘要，固定经过核对的版本，避免应用更新而依赖组件未按要求更新。

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 web chrome meilisearch

这里使用 `--quiet`，避免展开环境变量时把密钥写进日志截图。应用首次启动会初始化数据；如果没有成功，先看报错来自应用、搜索认证还是 Chrome 连接。重复启动不能解决错误密钥或写入权限。

收藏入口先给自己使用

在自己的电脑执行 SSH 转发，打开本机 13000 端口，创建账号并保存一条公开链接。初始化阶段应用地址与 `.env` 中的 NEXTAUTH_URL 一致。

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

ssh -N -L 13000:127.0.0.1:3000 user@server.example.com

接域名前把 NEXTAUTH_URL 改为 `https://keep.example.com`，重新运行 `docker compose up -d`。Caddy 在宿主机时采用下面的站点段，验证配置后重载；若代理在容器中，改用共享网络里的 `web:3000`。

caddyfile；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

keep.example.com {
    reverse_proxy 127.0.0.1:3000
}

账号建立后，在 `.env` 中加入 `DISABLE_SIGNUPS=true`，运行 `docker compose up -d`，再用未登录窗口验证注册已经关闭。私人收藏可以限制在 VPN 中，给自己的浏览器与手机访问即可。用户之间的私有内容、分享链接和公开列表要分别检查，不能只因为登录页存在就判断所有收藏都被保护。

浏览器扩展和移动客户端填写正式地址。为每个集成分别管理访问凭据，设备不用时撤销对应凭据。临时 IP 与域名来回切换，可能让客户端指向两个不同入口，排障时先确认保存到了哪个实例和账号。

准备独立实例时，可在雨云选择适合的云服务器配置，优惠码 `KuZhuJi`。配置按实际任务选择，数据库和附件另做备份。

试用时保存三种材料

先保存一篇公开文章、一张无敏感内容的图片，再写一条短笔记。对照原页面检查标题、正文和图片；网页加入收藏之后，抓取任务可能还未结束，列表里出现一个卡片不代表已经保存完整正文。

图片写一段用途说明，例如“首页布局参考，想保留导航间距”。只堆几百张没有说明的截图，全文搜索也难以知道你当时关注什么。短笔记适合记录素材用途或待核实的问题，正式项目结论仍需要保留来源与时间。

标签先按稳定的主题分类，不把每篇文章标题变成一个标签。列表可以按项目组织，例如“迁移准备”“设计参考”，把完成的项目移出常用入口。项目结束以后留下有复用价值的材料，删掉明显失败或重复的收藏，能减少下次搜索时的干扰。

测试搜索时，选正文中出现而标题中没有的词，检查结果能否找回文章；再搜索一条笔记里的词。标题搜索正常、正文搜索不正常，可能是抓取尚未完成或索引没有更新，需要分别检查任务和搜索日志。

自动标签和截图按需开启

基础功能跑通以后再考虑自动标签。外部模型服务会按照所启用功能处理相关内容，需要费用与凭据；本地模型也需要额外的服务资源。不要把默认示例里的模型 Key 保留下来，更不要把私人收藏导入以后才决定是否允许外部处理。

网页截图和完整归档也应先用几条公开网页验证。登录页面、动态网站、反爬限制可能让抓取结果缺内容或只剩验证页。改抓取参数时保留当前可用配置，不要直接关闭所有检查；收藏工具不能保证完整复现任何网页。

服务器负责请求用户提交的地址，私人实例应限制用户范围。只允许你自己保存内容，比把入口开放给陌生人更容易控制抓取目标和资源消耗。收藏第三方网页时也要尊重访问与使用条件，不把工具用于绕过权限。

需要增加服务器时，可以打开雨云选购页面，填写优惠码 `KuZhuJi`；迁移前保留数据与原有部署配置。

从任务状态判断故障

网页返回 502，先从宿主机访问 3000 端口，再查代理。界面正常但所有抓取失败，看 Chrome 是否启动、服务名是否正确和服务器到目标站点的网络。只有某个网站失败，保留样本，先判断页面或目标站点的限制，不要立即迁移整个实例。

搜索报错重点看 Meilisearch 日志与主密钥。修改 `.env` 后要重建相关容器，仅重启进程不会更新旧的容器环境。Meilisearch 版本迁移有自己的流程，不能把数据库目录原样交给任意新版本就假定成功。

磁盘紧张时，先统计 `data` 和 `meili-data` 的占用，区分附件与索引。不要把删除搜索目录当成通用清理命令；即便理论上能重建，也要先确认当前版本提供的重建方式、时间和完整数据是否还在。

备份应用数据与索引，记录版本组合

小规模实例可以停止三个服务后打包完整目录。这样备份处于同一时点，避免应用正在写入而索引和数据库分别复制。执行前确认空间够用，失败也要恢复容器运行。

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

cd /opt/karakeep
mkdir -p /opt/backups
docker compose stop
tar -czf "/opt/backups/karakeep-$(date +%F-%H%M).tgz" compose.yaml .env data meili-data
docker compose start

将备份复制到另一处存储，保护其中的账号、附件和密钥。恢复时采用对应镜像，在独立目录与不同端口启动，调整测试 NEXTAUTH_URL，暂时不接外部模型。检查链接、图片、笔记、标签与正文搜索，再判断是否完成恢复。

迁移以后重新核对浏览器扩展和手机入口，确认新保存的材料出现在同一库里。先保持少量标签和清楚的用途说明，这个收藏库才会成为能找回材料的地方，而不是又一个积满未读链接的列表。