Karakeep Docker 自托管部署指南从零搭建链接收藏与全文搜索服务【免费下载链接】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原 Hoarder是一款可自托管的收藏一切应用支持链接、笔记与图片的保存并内置基于 AI 的自动打标签与全文搜索能力。本文以官方 v0.30.0 的 Docker 安装文档为主线结合仓库中真实的docker-compose.yml、Dockerfile与packages/shared/config.ts配置源码完整讲解如何在一台 Linux 服务器上用 Docker Compose 一键部署 Karakeep、配置环境变量、接入 OpenAI 或 Ollama 自动打标签以及如何平滑升级与排查问题。读完本文你将能够独立完成一套可长期运行的 Karakeep 实例的部署与维护。1. 部署前置条件在开始之前请确保你的服务器满足以下条件Docker需要能正常运行 Docker 守护进程版本无特殊要求使用官方稳定版即可Docker Compose推荐使用 Docker Compose v2即docker compose子命令形式本文所有命令均以 v2 语法编写。注官方文档中的命令均以 Compose v2 语法docker compose中间有空格为准如果环境里只有旧版docker-composev1需要把命令中的空格换成连字符docker-compose并自行确认兼容性。2. 整体架构Compose 文件里的三个服务官方 docker/docker-compose.yml 把整套应用拆成三个相互协作的容器理解它们各自的分工有助于后续排障服务名镜像职责webghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}主应用Next.js Web 服务监听 3000 端口、tRPC API、后台 Worker爬虫、推理、搜索索引等均由 s6-overlay 在同一容器内拉起chromeghcr.io/karakeep-app/karakeep-chrome:release无头浏览器用于抓取网页时执行 JavaScript、截图与整页归档Worker 通过http://chrome:9222的调试端口与其通信meilisearchgetmeili/meilisearch:v1.41.0全文搜索引擎为书签内容提供全文检索能力数据挂载到meilisearch命名卷关键设计点均可在 docker/docker-compose.yml 中验证web服务通过env_file: .env注入环境变量并在environment段硬编码了服务间内部通信地址MEILI_ADDR: http://meilisearch:7700、BROWSER_WEB_URL: http://chrome:9222也就是说服务间连线在 Compose 文件里已经全部接好你不需要手动配置数据持久化由两个 Docker 命名卷负责dataSQLite 数据库与默认资产目录挂在容器的/data和meilisearch搜索引擎索引挂在/meili_dataDATA_DIR: /data被注释标注为DONT CHANGE THIS——如果想把数据放到宿主机指定目录正确做法是修改卷映射把data:/data改成/path/to/your/directory:/data而不是改DATA_DIR环境变量chrome服务设置了init: true以及一组 Chromium 启动参数--disable-gpu、--disable-dev-shm-usage等这些是容器内运行无头浏览器的常规调优项。3. 分步部署流程3.1 创建部署目录先为 Compose 文件和.env环境变量文件创建一个独立目录例如mkdir karakeep-app后续所有文件都放在这个目录中便于统一管理与备份。3.2 获取 Compose 文件将官方 Compose 文件下载到新目录中。仓库内的原始文件位于 docker/docker-compose.yml你可以直接拉取发布分支上的同名文件wget https://raw.githubusercontent.com/karakeep-app/karakeep/main/docker/docker-compose.yml下载完成后建议先cat docker-compose.yml检查内容完整再进入下一步。3.3 配置环境变量.env在目录中创建.env文件写入官方提供的最小配置KARAKEEP_VERSIONrelease NEXTAUTH_SECRETsuper_random_string MEILI_MASTER_KEYanother_random_string NEXTAUTH_URLhttp://localhost:3000各变量含义与注意事项KARAKEEP_VERSION决定拉取的ghcr.io/karakeep-app/karakeep镜像标签。release表示最新稳定版也可以固定到具体版本号如0.10.0以便完全掌控升级节奏。Compose 文件中的写法是${KARAKEEP_VERSION:-release}即未设置时默认releaseNEXTAUTH_SECRET用于签名 JWT 会话令牌的随机字符串必须替换为强随机值。官方推荐用openssl rand -base64 36生成MEILI_MASTER_KEYMeilisearch 的主密钥生产环境且启用搜索时为必填同样需要替换。生成时建议只保留字母数字以避免特殊字符引发问题openssl rand -base64 36 | tr -dc A-Za-z0-9NEXTAUTH_URL指向你服务器的对外地址。本地测试用http://localhost:3000公网部署应改成实际域名或 IP例如https://bookmarks.example.com。从 packages/shared/config.ts 的源码可以看到该变量会被去掉末尾斜杠后用于拼接登录/登出等回调地址设置错误会导致跳转异常。需要注意的两个约定每次修改.env后都要重新执行docker compose up或up -d让 Compose 重新读取环境变量并重建受影响的容器持久化存储与服务间连线已由 Compose 文件托管你无需手动创建卷或配置服务发现。3.4 启动服务在包含docker-compose.yml与.env的目录下执行docker compose up -d-d表示后台运行。首次启动会拉取三个镜像耗时取决于网络。启动完成后浏览器访问http://localhost:3000应当看到 Sign In 登录页面。至此一套可用的 Karakeep 已经跑起来了。如果 3000 端口已被占用不要修改容器内的PORT环境变量Docker 场景下源码规定该值不可变而应修改 Compose 文件中web服务的端口映射例如把3000:3000改为8080:3000然后通过http://localhost:8080访问。3.5 验证部署是否成功可以通过以下方式快速验证# 查看三个服务是否都处于运行状态 docker compose ps # 查看 web 容器日志确认没有启动报错 docker compose logs -f web仓库的 docker/Dockerfile 中为镜像配置了健康检查每 30 秒探测一次http://127.0.0.1:3000/api/health连续 3 次失败即判定不健康因此docker compose ps中STATUS列显示(healthy)即代表主服务就绪。日志中出现爬虫、搜索等 Worker 正常注册的信息说明后台任务体系已随容器启动。4. 配置 AI 自动打标签可选但强烈推荐Karakeep 的核心卖点之一是AI 自动打标签收藏链接后系统会自动分析内容并生成标签。这一步完全可选但开启后体验提升明显。4.1 方案一OpenAI云端推理在 OpenAI 平台获取 API Key官方帮助文档有详细说明搜索 where do I find my openai api key 即可在.env中追加OPENAI_API_KEY你的key重新执行docker compose up -d生效。默认情况下文本推理使用INFERENCE_TEXT_MODEL当前默认gpt-5.6-luna图像推理使用INFERENCE_IMAGE_MODEL默认gpt-4o-mini无需额外配置即可工作。相关成本与计费说明可参考 OpenAI 配置说明。4.2 方案二Ollama本地推理如果希望数据不出本地或想省去 API 费用可以使用 Ollama 进行本地推理。需要特别提醒的是标签质量取决于所选模型的质量。配置步骤确保服务器上已运行 Ollama 服务在.env中设置以下变量# Ollama API 地址例如 http://localhost:11434 或局域网内的 Ollama 主机 OLLAMA_BASE_URLhttp://ollama-host:11434 # 文本推理模型例如 llama3.1 INFERENCE_TEXT_MODELllama3.1 # 图像推理模型必须支持视觉 API例如 llava INFERENCE_IMAGE_MODELllava先手动拉取所需模型ollama pull llama3.1、ollama pull llava视情况调大INFERENCE_CONTEXT_LENGTH。源码默认值仅为 2048token偏小调大后模型能看到更多内容、标签质量更好但推理开销Ollama 侧是资源OpenAI 侧是费用也会上升重新docker compose up -d。如果 Ollama 运行在宿主机而非容器注意容器内访问宿主机通常需要使用host.docker.internal或宿主机局域网 IP而不是localhost——因为localhost在容器内指向容器自身。4.3 更细粒度的推理参数从 docs/versioned_docs/version-v0.30.0/03-configuration/01-environment-variables.md 的 Inference 一节可以看到官方还支持大量推理相关参数常用几个如下变量默认值说明INFERENCE_LANGenglish生成标签使用的语言可改为chinese等INFERENCE_ENABLE_AUTO_TAGGINGtrue是否启用自动打标签INFERENCE_ENABLE_AUTO_SUMMARIZATIONfalse是否启用自动摘要INFERENCE_NUM_WORKERS1并行推理任务数收藏量大时可调高INFERENCE_JOB_TIMEOUT_SEC30推理任务超时Ollama 无独显时可调大INFERENCE_OUTPUT_SCHEMAstructured模型输出格式可选structured/json/plainOPENAI_BASE_URL未设置兼容 OpenAI 协议的 API 地址如 Azure OpenAIOPENAI_PROXY_URL未设置OpenAI 请求的 HTTP 代理OLLAMA_KEEP_ALIVE未设置模型驻留内存时长如5m、-1m常驻、0立即卸载这些变量与 packages/shared/config.ts 中 zod schema 的定义一一对应所有布尔值均严格接受true/false字符串。另外你可以在 Web 界面User Settings → AI Settings中为自动打标签补充自定义提示词并可使用$tags、$aiTags、$userTags三个占位符引用全部标签 / AI 生成的标签 / 用户手动标签。5. 可选功能与扩展5.1 官方可选功能部署完成后环境变量配置文档 中还列出了大量可开启的增强功能例如整页归档CRAWLER_FULL_PAGE_ARCHIVEtrue保存网页的完整本地副本整页截图CRAWLER_FULL_PAGE_SCREENSHOTtrue保存整页长截图会显著增加磁盘占用默认关闭PDF 快照CRAWLER_STORE_PDFtrue保存页面 PDF 版本视频下载CRAWLER_VIDEO_DOWNLOADtrue用 yt-dlp 下载页面中的视频OCR 语言OCR_LANGSeng,chi_sim调整图片 OCR 识别的语言集合推理语言INFERENCE_LANG切换自动标签的语言。这些功能多数在 packages/shared/config.ts 中有对应默认值例如CRAWLER_FULL_PAGE_ARCHIVE默认false、OCR_LANGS默认eng按需在.env中开启后重新docker compose up -d即可。注意开启归档/截图/PDF 类功能前请评估磁盘空间。5.2 快速分享移动端 App 与浏览器插件安装 快速分享指南 中介绍的移动端 App 与浏览器扩展后你可以随时随地把链接、文字、图片一键囤进自己的实例配合自动打标签与全文搜索收藏效率会大幅提升。6. 升级与维护Karakeep 的升级方式取决于KARAKEEP_VERSION的取值固定了具体版本号如KARAKEEP_VERSION0.10.0把版本号改成新版如0.11.0然后重新执行docker compose up -dCompose 会拉取新镜像并重建容器数据库迁移会在启动流程中自动完成见 docker/Dockerfile 中 s6-overlay 编排的init-db-migration服务。使用release标签由于标签本身不变需要强制 Docker 重新拉取docker compose up --pull always -d两个额外的维护提醒Meilisearch 升级/迁移如果你需要升级或迁移 Meilisearch 版本请务必参考 故障排查指南不要直接更换镜像版本避免索引不兼容旧版 Chrome 镜像迁移如果你的自定义 Compose 文件仍在使用旧的 Alpine Chrome 镜像请按照 Chrome 镜像迁移指南 操作由于数据存放在命名卷中升级通常不会丢失数据但建议在升级前对data与meilisearch卷做一次备份例如docker run --rm -v karakeep-app_data:/data -v $(pwd):/backup alpine tar czf /backup/data-backup.tar.gz -C /data .。7. 常见问题与排障思路结合 故障排查指南 与源码结构整理几个高频问题的排查思路访问http://localhost:3000打不开先docker compose ps看三个服务状态再用docker compose logs web查看日志重点确认 3000 端口是否被占用、.env是否被正确挂载搜索不可用检查MEILI_ADDR是否指向http://meilisearch:7700Compose 已默认配好以及MEILI_MASTER_KEY是否与 Meilisearch 侧一致自动打标签不生效确认OPENAI_API_KEY或OLLAMA_BASE_URL至少配置了一个环境变量文档 明确两者都未设置时自动打标签会被跳过并检查推理相关超时是否过短抓取图片/截图缺失chrome容器是否正常运行、BROWSER_WEB_URL是否正确指向http://chrome:9222若两个浏览器地址变量均未设置爬虫会退化为纯 HTTP 请求跳过截图与 JS 执行修改.env后不生效环境变量只在docker compose up时读取修改后必须重新执行docker compose up -d。8. 总结通过docker compose up -d一条命令Karakeep 的 Web 主应用、无头浏览器与 Meilisearch 搜索三大组件即可协同运行数据与索引分别持久化在data和meilisearch命名卷中服务间通信由 Compose 内部网络自动打通。再加上.env中配置OPENAI_API_KEY或OLLAMA_BASE_URL即可解锁 AI 自动打标签按需开启整页归档、PDF 快照等高级功能并根据KARAKEEP_VERSION的取值选择固定版本或跟随release平滑升级。如果你还需要更精细的调优OAuth 登录、S3 资产存储、SMTP 邮件、OpenTelemetry 监控、限流与代理等环境变量配置文档 提供了完整的参数清单packages/shared/config.ts 则是这些参数的唯一事实来源zod schema 定义了全部变量、默认值与合法取值两者配合阅读即可对部署配置做到完全掌控。【免费下载链接】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），仅供参考
