Karakeep 部署教程：自托管的收藏一切应用

Karakeep (原名 Hoarder) 是一款自托管的书签管理应用，支持收藏链接、笔记、图片和 PDF。它具备 AI 自动标签、全文搜索、RSS 自动抓取、全页存档和视频存档等功能，适合需要整理大量碎片化信息的“数字囤积者”。

本教程将指导你使用 Docker Compose（推荐） 完成部署。

在开始部署前，请确保你的服务器满足以下要求：

这是官方推荐且最简便的方式，它会启动 Karakeep 及其依赖服务。

克隆或下载 Compose 文件
从官方 GitHub 仓库获取 docker-compose.yml 文件。你可以直接克隆整个仓库，或只下载该文件。
1
2
3
# 推荐：克隆仓库以获得完整示例配置
git clone https://github.com/karakeep-app/karakeep.git
cd karakeep
在项目根目录下，你会找到 docker-compose.yml 文件。

配置环境变量 (可选)
在启动前，建议复制 .env.sample 为 .env 并按需修改。

1	cp .env.sample .env

关键环境变量解释：

变量名	默认值/示例	说明
`NEXTAUTH_SECRET`	(必须修改)	NextAuth 认证密钥。务必修改为强密码，例如 `openssl rand -base64 32` 生成。
`NEXTAUTH_URL`	`http://localhost:3000`	应用公开访问的 URL。如果使用域名，请修改为 `https://你的域名`。
`MEILI_MASTER_KEY`	(建议修改)	Meilisearch 搜索服务的密钥。建议修改为强密码。
`DATABASE_URL`	`postgresql://...`	PostgreSQL 数据库连接字符串。不建议修改，除非你使用外部数据库。
`OPENAI_API_KEY`	(可选)	启用 AI 功能 (如自动标签) 需要。可填写 OpenAI 或兼容的 API 密钥 (如 DeepSeek、本地 Ollama)。
`ENABLE_AUTO_TAGGING`	`false`	设为 `true` 以启用 AI 自动打标签功能。
`ENABLE_SUMMARIZATION`	`false`	设为 `true` 以启用 AI 自动摘要功能。

重要：如果使用 docker-compose.yml 默认配置，NEXTAUTH_SECRET 和 MEILI_MASTER_KEY 在 .env 文件中均有占位符，请务必替换为强密码。

启动服务
在包含 docker-compose.yml 的目录下，执行以下命令：
1
docker compose up -d
-d 参数表示在后台 (detach) 运行。首次启动会自动拉取所需的镜像。
验证部署
稍等片刻，待所有容器启动完成后，打开浏览器访问 http://你的服务器IP:3000 (或你配置的域名)。你应该能看到 Karakeep 的注册/登录页面。

创建账户：第一个注册的用户将自动成为管理员。
连接 AI (可选)：如果需要 AI 自动标签功能，在后台 Settings → AI 中配置 API Key。如果你在 .env 中已配置，则无需再操作。
添加书签：开始使用 “Add” 按钮或浏览器扩展，收藏链接、创建笔记或上传图片/PDF。
创建列表 (Lists)：将书签分类到不同列表中，并可邀请他人协作。

如果你希望使用本地模型，可以在 docker-compose.yml 中额外添加 Ollama 服务，或在 .env 中指向外部 Ollama 地址，例如：

1 2	OPENAI_API_KEY="ollama" # 任意非空值 OPENAI_BASE_URL="http://你的Ollama地址:11434/v1" # 确保网络可达

# 进入项目目录，拉取最新镜像并重新创建容器
cd /path/to/karakeep
docker compose pull
docker compose up -d

备份最重要的数据是数据库和上传的媒体文件。

数据库备份 (PostgreSQL)：建议使用 pg_dump 命令，或在 Docker 中执行 docker exec -t karakeep-db-1 pg_dump -U postgres karakeep > backup.sql。
文件备份：默认情况下，上传的文件存储在 Docker 卷 karakeep_uploads 中。你可以将此卷目录 (/var/lib/docker/volumes/karakeep_uploads/_data) 备份下来。

首次启动后访问 localhost:3000 显示无法连接？
- 使用 docker compose logs 查看后端服务 (web) 的日志，检查是否有数据库连接错误或启动失败信息。
- 确保防火墙放行了 3000 端口。
AI 自动标签/摘要不工作？
- 确认在设置中已启用 ENABLE_AUTO_TAGGING 或 ENABLE_SUMMARIZATION。
- 检查 API Key 是否正确，以及账户是否还有余额。如果使用 Ollama，确认其 API 端点可访问。
书签抓取失败或显示空白？
- 检查网络环境：Karakeep 使用 Puppeteer 抓取页面，需要能够访问目标网站。
- 查看 docker compose logs worker 日志，寻找具体错误信息 (如超时、HTTP 403 等)。
想将数据存储到外部 NFS 或 S3？
- 可以通过修改 docker-compose.yml 中 uploads 卷的映射路径，或配置环境变量使用 S3 兼容存储 (详情参考官方文档)。