Karakeep Docker 部署指南docker-compose 快速安装、环境变量配置与版本升级【免费下载链接】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原 Hoarder自托管应用的 Docker 安装路径完整讲解基于docker compose的部署流程从目录准备、compose 文件下载、最小.env配置、OpenAI/Ollama 等 AI 标注automatic tagging接入到服务启动、可选功能开启与版本升级策略。读完本文你将能够独立完成一套生产可用的 Karakeep 单机部署并理解web、chrome、meilisearch三个服务之间的容器网络关系与关键环境变量的底层作用。本文以 docs/versioned_docs/version-v0.32.0/02-installation/01-docker.md 为骨架并结合仓库中的 docker/docker-compose.yml、docker/Dockerfile 与 packages/shared/config.ts 源码进行纵深展开。1. 部署前提与环境要求Karakeep 的 Docker 安装只依赖两样东西Docker建议使用较新的稳定版本支持 Compose v2 语法Docker Composedocker compose子命令或独立的docker-compose官方镜像托管于 GHCR应用镜像为ghcr.io/karakeep-app/karakeepChrome 爬虫镜像为ghcr.io/karakeep-app/karakeep-chrome。由于镜像较大且拉取自国外容器仓库在国内网络环境下建议预先配置 Docker 镜像加速器或代理。2. 第一步创建工作目录创建一个专门存放 compose 文件与环境变量的目录例如karakeep-appmkdir karakeep-app cd karakeep-app这个目录将承载后面步骤下载的docker-compose.yml以及.env文件。后续所有docker compose命令都需要在该目录下执行因为 Compose 默认读取当前目录下的.env与docker-compose.yml。3. 第二步下载 compose 文件将项目仓库提供的docker-compose.yml直接下载到新目录wget https://raw.githubusercontent.com/karakeep-app/karakeep/main/docker/docker-compose.yml如果你无法使用wget例如 macOS 默认环境也可以用curl -O代替。3.1 compose 文件的服务构成仓库内的 docker/docker-compose.yml 定义了三个服务理解它们的职责对排障很有帮助服务镜像作用webghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}主应用Next.js Web 服务 数据库迁移 后台 workerAI 推理、爬虫调度等对外暴露3000:3000chromeghcr.io/karakeep-app/karakeep-chrome:release无头 Chrome 浏览器供爬虫执行 JS、截图监听调试端口 9222meilisearchgetmeili/meilisearch:v1.41.0全文搜索引擎容器内地址meilisearch:7700服务间的接线由 compose 的environment段完成environment: MEILI_ADDR: http://meilisearch:7700 BROWSER_WEB_URL: http://chrome:9222 DATA_DIR: /data # DONT CHANGE THIS关键点MEILI_ADDR指向 meilisearch 服务的容器名而不是localhost——容器间通信必须使用 compose 服务名BROWSER_WEB_URL指向 chrome 容器的调试端口worker 通过它获取 DevTools websocket 地址后驱动浏览器爬取DATA_DIR被固定为/data这是应用内部约定的数据目录不要修改该值。要改变宿主机上的持久化位置应修改卷映射- data:/data为- /path/to/your/directory:/data数据持久化由两个命名卷完成data挂载到/data存放 SQLite 数据库与默认资产、meilisearch挂载到/meili_data存放搜索索引。官方 compose 已处理好持久化与服务间接线无需自行添加。4. 第三步填充环境变量在目录中创建.env文件写入最小可用配置KARAKEEP_VERSIONrelease NEXTAUTH_SECRETsuper_random_string MEILI_MASTER_KEYanother_random_string NEXTAUTH_URLhttp://localhost:3000四个变量的含义与注意事项KARAKEEP_VERSION应用镜像版本标签。release表示拉取最新稳定版也可以固定到具体版本如KARAKEEP_VERSION0.10.0以控制升级节奏。在 compose 中它通过${KARAKEEP_VERSION:-release}插值进镜像名见 docker/docker-compose.ymlNEXTAUTH_SECRET用于签名 JWT 令牌的随机字符串必填。若未设置应用启动时会在 packages/shared/config.ts 的配置解析阶段直接抛出NEXTAUTH_SECRET is not set错误MEILI_MASTER_KEYmeilisearch 的主密钥。生产环境启用搜索时必须设置生成时建议去掉/、、等特殊字符openssl rand -base64 36 | tr -dc A-Za-z0-9NEXTAUTH_URL你的服务对外地址。不设置时默认回退为http://localhost:3000见 packages/shared/config.ts但注销等场景会跳转到错误地址因此应改为实际访问地址。4.1 生成随机字符串强烈建议替换上面两个占位随机串用openssl在终端生成openssl rand -base64 364.2 修改 .env 后必须重新执行每次修改.env后都需要重新执行docker compose upcompose 不会自动感知.env变化。例如docker compose up -d更完整的配置参数清单见 docs/docs/03-configuration/01-environment-variables.md其中所有变量的解析与默认值都能在 packages/shared/config.ts 中逐一对号入座例如LOG_LEVEL默认debug、MAX_ASSET_SIZE_MB默认 50、DB_WAL_MODE默认关闭等。5. 第四步配置 OpenAI 以实现自动打标自动打标automatic tagging是 Karakeep 的核心能力之一需要配置一个推理提供商。直接使用 OpenAI 是最简单的方式按照 OpenAI 官方指引获取 API Key在.env中追加OPENAI_API_KEYkey在 packages/shared/config.ts 中可以看到推理是否配置成功的判定逻辑isConfigured: !!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL——即只要设置了OPENAI_API_KEY或OLLAMA_BASE_URL二者之一自动打标即被启用。关于成本AI 推理按 token 计费INFERENCE_CONTEXT_LENGTH默认 2048控制传给模型的 token 上限值越大打标质量越好但成本越高。费用与模型选择细节可参考 docs/docs/06-administration/03-openai.md。5.1 更换其他 AI 提供商Karakeep 兼容所有 OpenAI-compatible API 以及 Ollama 本地推理完整指南见 docs/docs/03-configuration/02-different-ai-providers.md。几个典型配置Ollama本地推理推荐方式一OpenAI 兼容端点OPENAI_API_KEYollama OPENAI_BASE_URLhttp://ollama.mylab.com:11434/v1 # 需先在 ollama 中拉取模型 INFERENCE_TEXT_MODELgemma3 INFERENCE_IMAGE_MODELllava EMBEDDING_TEXT_MODELembeddinggemma EMBEDDING_DIMENSIONS768Ollama原生 API 方式# 注意不要设置 OPENAI_API_KEY否则会优先走 OpenAI 路径 OLLAMA_BASE_URLhttp://ollama.mylab.com:11434 INFERENCE_TEXT_MODELgemma3 INFERENCE_IMAGE_MODELllava # 若模型不支持结构化输出追加 # INFERENCE_OUTPUT_SCHEMAplainGemini / OpenRouter / Perplexity / Azure / Cloudflare等均通过OPENAI_BASE_URLOPENAI_API_KEY组合接入例如OPENAI_BASE_URLhttps://generativelanguage.googleapis.com/v1beta OPENAI_API_KEYYOUR_API_KEY INFERENCE_TEXT_MODELgemini-2.5-flash-lite EMBEDDING_DIMENSIONS30725.2 关键推理与嵌入参数速查以下参数在自动打标、摘要与语义搜索中高频使用均可在 packages/shared/config.ts 中找到默认值定义变量默认值说明INFERENCE_TEXT_MODELgpt-5.6-luna文本推理打标/摘要模型换用 Ollama 时必须改为本地模型INFERENCE_IMAGE_MODELgpt-4o-mini图片推理模型Ollama 需支持视觉如 llavaINFERENCE_LANGenglish标签生成语言INFERENCE_CONTEXT_LENGTH2048传给推理模型的 token 上限INFERENCE_ENABLE_AUTO_TAGGINGtrue自动打标开关INFERENCE_ENABLE_AUTO_SUMMARIZATIONfalse自动摘要开关INFERENCE_NUM_WORKERS1AI 推理并发 worker 数INFERENCE_JOB_TIMEOUT_SEC30推理任务超时Ollama 无 GPU 时建议调大EMBEDDING_TEXT_MODELtext-embedding-3-small语义搜索嵌入模型EMBEDDING_DIMENSIONS1536嵌入向量维度必须与模型/向量库匹配EMBEDDING_ENABLE_AUTO_INDEXING使用默认 OpenAI 时自动开启书签嵌入生成与向量索引开关语义搜索的前置条件SEMANTIC_SEARCH_ENABLEDtrue混合/语义搜索开关实验性注意不同嵌入模型产出的向量互不兼容若日后更换嵌入模型或维度需要为全部书签重新生成嵌入。6. 第五步启动服务在包含.env的目录下执行docker compose up -d首次启动会拉取karakeep、karakeep-chrome、meilisearch三个镜像体积较大耐心等待随后自动完成数据库迁移并启动所有服务。完成后访问http://localhost:3000即可看到 Sign In登录/注册页面。其他常用命令docker compose logs -f web # 跟踪主应用日志 docker compose ps # 查看服务状态 docker compose down # 停止数据保留在卷中从 docker/Dockerfile 可以看到镜像内置了健康检查HEALTHCHECK每 30 秒探测一次/api/health便于编排系统感知容器存活状态。7. [可选] 第六步开启可选功能Karakeep 的大量能力由环境变量控制见 docs/docs/03-configuration/01-environment-variables.md。以下分类列举高频选项爬虫与归档类影响磁盘占用变量默认值说明CRAWLER_FULL_PAGE_ARCHIVEfalse是否保存页面完整本地副本monolith默认只归档可读文本CRAWLER_FULL_PAGE_SCREENSHOTfalse是否保存整页截图磁盘占用高CRAWLER_STORE_PDFfalse是否保存页面 PDF 快照CRAWLER_STORE_SCREENSHOTtrue是否保存普通截图作为封面图兜底CRAWLER_VIDEO_DOWNLOADfalse是否用 yt-dlp 下载页面视频CRAWLER_ENABLE_ADBLOCKERtrue爬虫内置广告拦截下载拦截列表失败时可关闭搜索与数据库类变量默认值说明SEARCH_NUM_WORKERS1搜索索引并发数内容量大时可调高DB_WAL_MODEfalse开启 SQLite WAL 模式提升性能网络盘上不建议开启认证与邮件类变量默认值说明DISABLE_SIGNUPSfalse禁止新用户注册DISABLE_PASSWORD_AUTHfalse仅允许 OAuth 登录需同时配置 OIDC 相关变量SMTP_HOST等未设置配置 SMTP 后可启用邮件验证等功能监控类变量默认值说明OTEL_TRACING_ENABLEDfalse开启 OpenTelemetry 分布式追踪PROMETHEUS_AUTH_TOKEN随机生成开启/api/metricsPrometheus 指标端点8. [可选] 第七步安装快捷分享扩展部署完成后前往 docs/docs/04-using-karakeep/quick-sharing.md 安装移动端 App 与浏览器扩展Chrome/Firefox/Safari。这些客户端通过NEXTAUTH_URL指向的服务地址连接能让你在任何场景下快速把链接、文字、图片存入 Karakeep。9. 版本升级升级方式取决于KARAKEEP_VERSION的取值固定了具体版本修改.env中的版本号后重新执行docker compose up -dCompose 会自动拉取新镜像并重建容器使用release标签需要强制拉取最新镜像docker compose up --pull always -d9.1 Chrome 镜像迁移说明若你维护的是自定义 compose 文件且仍在使用旧的 Alpine Chrome 镜像gcr.io/zenika-hub/alpine-chrome:124需要迁移到 Karakeep 官方发布的ghcr.io/karakeep-app/karakeep-chrome:release镜像。迁移要点详见 docs/docs/06-administration/09-chrome-image-migration.md移除--no-sandbox与--remote-debugging-address0.0.0.0/--remote-debugging-port9222参数新镜像入口自行处理调试端口转发并提供--no-sandbox增加init: true迁移不影响业务数据无需数据库迁移。9.2 Meilisearch 升级注意官方 compose 固定使用getmeili/meilisearch:v1.41.0不建议无理由升级。若升级后出现数据库版本不兼容报错可参考 docs/docs/06-administration/05-troubleshooting.md 的处理流程停止 meilisearch 容器 → 在/meili_data卷中清空data.ms目录 → 重启容器 → 以管理员登录后在Admin Settings Background Jobs中点击Reindex All Bookmarks重建索引。10. 常见问题速查SqliteError: no such table: user通常是DATA_DIR被清空、或自定义 compose 中遗漏了DATA_DIR/data环境变量导致数据库目录不一致重启容器或补全变量即可见 docs/docs/06-administration/05-troubleshooting.mdAI 打标不生效OpenAI检查OPENAI_API_KEY是否拼写正确、修改.env后是否重新docker compose up、账户是否预充值AI 打标不生效Ollama除上述检查外还需确认INFERENCE_TEXT_MODEL已改为本地模型且OLLAMA_BASE_URL不能写成localhost容器内localhost指向容器自身应写宿主机可达地址或使用host.docker.internal类地址爬取不工作若重命名了 chrome 容器需同步修改BROWSER_WEB_URL环境变量。11. 小结通过本文的七个步骤你已经掌握了 Karakeep 基于 Docker 的完整部署链路最小.env四件套KARAKEEP_VERSION、NEXTAUTH_SECRET、MEILI_MASTER_KEY、NEXTAUTH_URL是启动的底线webchromemeilisearch三服务的容器网络接线决定了爬虫与搜索是否可用而 AI 打标、全文归档、语义搜索等进阶能力则全部由环境变量驱动其默认值与校验逻辑集中在 packages/shared/config.ts可作为排查配置问题的第一手源码依据。升级时根据KARAKEEP_VERSION选择拉取策略并留意 Chrome 镜像迁移与 Meilisearch 索引重建两个特殊场景即可长期稳定运行。【免费下载链接】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），仅供参考 Karakeep Docker 部署指南：docker-compose 快速安装、环境变量配置与版本升级
Karakeep Docker 部署指南docker-compose 快速安装、环境变量配置与版本升级【免费下载链接】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原 Hoarder自托管应用的 Docker 安装路径完整讲解基于docker compose的部署流程从目录准备、compose 文件下载、最小.env配置、OpenAI/Ollama 等 AI 标注automatic tagging接入到服务启动、可选功能开启与版本升级策略。读完本文你将能够独立完成一套生产可用的 Karakeep 单机部署并理解web、chrome、meilisearch三个服务之间的容器网络关系与关键环境变量的底层作用。本文以 docs/versioned_docs/version-v0.32.0/02-installation/01-docker.md 为骨架并结合仓库中的 docker/docker-compose.yml、docker/Dockerfile 与 packages/shared/config.ts 源码进行纵深展开。1. 部署前提与环境要求Karakeep 的 Docker 安装只依赖两样东西Docker建议使用较新的稳定版本支持 Compose v2 语法Docker Composedocker compose子命令或独立的docker-compose官方镜像托管于 GHCR应用镜像为ghcr.io/karakeep-app/karakeepChrome 爬虫镜像为ghcr.io/karakeep-app/karakeep-chrome。由于镜像较大且拉取自国外容器仓库在国内网络环境下建议预先配置 Docker 镜像加速器或代理。2. 第一步创建工作目录创建一个专门存放 compose 文件与环境变量的目录例如karakeep-appmkdir karakeep-app cd karakeep-app这个目录将承载后面步骤下载的docker-compose.yml以及.env文件。后续所有docker compose命令都需要在该目录下执行因为 Compose 默认读取当前目录下的.env与docker-compose.yml。3. 第二步下载 compose 文件将项目仓库提供的docker-compose.yml直接下载到新目录wget https://raw.githubusercontent.com/karakeep-app/karakeep/main/docker/docker-compose.yml如果你无法使用wget例如 macOS 默认环境也可以用curl -O代替。3.1 compose 文件的服务构成仓库内的 docker/docker-compose.yml 定义了三个服务理解它们的职责对排障很有帮助服务镜像作用webghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release}主应用Next.js Web 服务 数据库迁移 后台 workerAI 推理、爬虫调度等对外暴露3000:3000chromeghcr.io/karakeep-app/karakeep-chrome:release无头 Chrome 浏览器供爬虫执行 JS、截图监听调试端口 9222meilisearchgetmeili/meilisearch:v1.41.0全文搜索引擎容器内地址meilisearch:7700服务间的接线由 compose 的environment段完成environment: MEILI_ADDR: http://meilisearch:7700 BROWSER_WEB_URL: http://chrome:9222 DATA_DIR: /data # DONT CHANGE THIS关键点MEILI_ADDR指向 meilisearch 服务的容器名而不是localhost——容器间通信必须使用 compose 服务名BROWSER_WEB_URL指向 chrome 容器的调试端口worker 通过它获取 DevTools websocket 地址后驱动浏览器爬取DATA_DIR被固定为/data这是应用内部约定的数据目录不要修改该值。要改变宿主机上的持久化位置应修改卷映射- data:/data为- /path/to/your/directory:/data数据持久化由两个命名卷完成data挂载到/data存放 SQLite 数据库与默认资产、meilisearch挂载到/meili_data存放搜索索引。官方 compose 已处理好持久化与服务间接线无需自行添加。4. 第三步填充环境变量在目录中创建.env文件写入最小可用配置KARAKEEP_VERSIONrelease NEXTAUTH_SECRETsuper_random_string MEILI_MASTER_KEYanother_random_string NEXTAUTH_URLhttp://localhost:3000四个变量的含义与注意事项KARAKEEP_VERSION应用镜像版本标签。release表示拉取最新稳定版也可以固定到具体版本如KARAKEEP_VERSION0.10.0以控制升级节奏。在 compose 中它通过${KARAKEEP_VERSION:-release}插值进镜像名见 docker/docker-compose.ymlNEXTAUTH_SECRET用于签名 JWT 令牌的随机字符串必填。若未设置应用启动时会在 packages/shared/config.ts 的配置解析阶段直接抛出NEXTAUTH_SECRET is not set错误MEILI_MASTER_KEYmeilisearch 的主密钥。生产环境启用搜索时必须设置生成时建议去掉/、、等特殊字符openssl rand -base64 36 | tr -dc A-Za-z0-9NEXTAUTH_URL你的服务对外地址。不设置时默认回退为http://localhost:3000见 packages/shared/config.ts但注销等场景会跳转到错误地址因此应改为实际访问地址。4.1 生成随机字符串强烈建议替换上面两个占位随机串用openssl在终端生成openssl rand -base64 364.2 修改 .env 后必须重新执行每次修改.env后都需要重新执行docker compose upcompose 不会自动感知.env变化。例如docker compose up -d更完整的配置参数清单见 docs/docs/03-configuration/01-environment-variables.md其中所有变量的解析与默认值都能在 packages/shared/config.ts 中逐一对号入座例如LOG_LEVEL默认debug、MAX_ASSET_SIZE_MB默认 50、DB_WAL_MODE默认关闭等。5. 第四步配置 OpenAI 以实现自动打标自动打标automatic tagging是 Karakeep 的核心能力之一需要配置一个推理提供商。直接使用 OpenAI 是最简单的方式按照 OpenAI 官方指引获取 API Key在.env中追加OPENAI_API_KEYkey在 packages/shared/config.ts 中可以看到推理是否配置成功的判定逻辑isConfigured: !!val.OPENAI_API_KEY || !!val.OLLAMA_BASE_URL——即只要设置了OPENAI_API_KEY或OLLAMA_BASE_URL二者之一自动打标即被启用。关于成本AI 推理按 token 计费INFERENCE_CONTEXT_LENGTH默认 2048控制传给模型的 token 上限值越大打标质量越好但成本越高。费用与模型选择细节可参考 docs/docs/06-administration/03-openai.md。5.1 更换其他 AI 提供商Karakeep 兼容所有 OpenAI-compatible API 以及 Ollama 本地推理完整指南见 docs/docs/03-configuration/02-different-ai-providers.md。几个典型配置Ollama本地推理推荐方式一OpenAI 兼容端点OPENAI_API_KEYollama OPENAI_BASE_URLhttp://ollama.mylab.com:11434/v1 # 需先在 ollama 中拉取模型 INFERENCE_TEXT_MODELgemma3 INFERENCE_IMAGE_MODELllava EMBEDDING_TEXT_MODELembeddinggemma EMBEDDING_DIMENSIONS768Ollama原生 API 方式# 注意不要设置 OPENAI_API_KEY否则会优先走 OpenAI 路径 OLLAMA_BASE_URLhttp://ollama.mylab.com:11434 INFERENCE_TEXT_MODELgemma3 INFERENCE_IMAGE_MODELllava # 若模型不支持结构化输出追加 # INFERENCE_OUTPUT_SCHEMAplainGemini / OpenRouter / Perplexity / Azure / Cloudflare等均通过OPENAI_BASE_URLOPENAI_API_KEY组合接入例如OPENAI_BASE_URLhttps://generativelanguage.googleapis.com/v1beta OPENAI_API_KEYYOUR_API_KEY INFERENCE_TEXT_MODELgemini-2.5-flash-lite EMBEDDING_DIMENSIONS30725.2 关键推理与嵌入参数速查以下参数在自动打标、摘要与语义搜索中高频使用均可在 packages/shared/config.ts 中找到默认值定义变量默认值说明INFERENCE_TEXT_MODELgpt-5.6-luna文本推理打标/摘要模型换用 Ollama 时必须改为本地模型INFERENCE_IMAGE_MODELgpt-4o-mini图片推理模型Ollama 需支持视觉如 llavaINFERENCE_LANGenglish标签生成语言INFERENCE_CONTEXT_LENGTH2048传给推理模型的 token 上限INFERENCE_ENABLE_AUTO_TAGGINGtrue自动打标开关INFERENCE_ENABLE_AUTO_SUMMARIZATIONfalse自动摘要开关INFERENCE_NUM_WORKERS1AI 推理并发 worker 数INFERENCE_JOB_TIMEOUT_SEC30推理任务超时Ollama 无 GPU 时建议调大EMBEDDING_TEXT_MODELtext-embedding-3-small语义搜索嵌入模型EMBEDDING_DIMENSIONS1536嵌入向量维度必须与模型/向量库匹配EMBEDDING_ENABLE_AUTO_INDEXING使用默认 OpenAI 时自动开启书签嵌入生成与向量索引开关语义搜索的前置条件SEMANTIC_SEARCH_ENABLEDtrue混合/语义搜索开关实验性注意不同嵌入模型产出的向量互不兼容若日后更换嵌入模型或维度需要为全部书签重新生成嵌入。6. 第五步启动服务在包含.env的目录下执行docker compose up -d首次启动会拉取karakeep、karakeep-chrome、meilisearch三个镜像体积较大耐心等待随后自动完成数据库迁移并启动所有服务。完成后访问http://localhost:3000即可看到 Sign In登录/注册页面。其他常用命令docker compose logs -f web # 跟踪主应用日志 docker compose ps # 查看服务状态 docker compose down # 停止数据保留在卷中从 docker/Dockerfile 可以看到镜像内置了健康检查HEALTHCHECK每 30 秒探测一次/api/health便于编排系统感知容器存活状态。7. [可选] 第六步开启可选功能Karakeep 的大量能力由环境变量控制见 docs/docs/03-configuration/01-environment-variables.md。以下分类列举高频选项爬虫与归档类影响磁盘占用变量默认值说明CRAWLER_FULL_PAGE_ARCHIVEfalse是否保存页面完整本地副本monolith默认只归档可读文本CRAWLER_FULL_PAGE_SCREENSHOTfalse是否保存整页截图磁盘占用高CRAWLER_STORE_PDFfalse是否保存页面 PDF 快照CRAWLER_STORE_SCREENSHOTtrue是否保存普通截图作为封面图兜底CRAWLER_VIDEO_DOWNLOADfalse是否用 yt-dlp 下载页面视频CRAWLER_ENABLE_ADBLOCKERtrue爬虫内置广告拦截下载拦截列表失败时可关闭搜索与数据库类变量默认值说明SEARCH_NUM_WORKERS1搜索索引并发数内容量大时可调高DB_WAL_MODEfalse开启 SQLite WAL 模式提升性能网络盘上不建议开启认证与邮件类变量默认值说明DISABLE_SIGNUPSfalse禁止新用户注册DISABLE_PASSWORD_AUTHfalse仅允许 OAuth 登录需同时配置 OIDC 相关变量SMTP_HOST等未设置配置 SMTP 后可启用邮件验证等功能监控类变量默认值说明OTEL_TRACING_ENABLEDfalse开启 OpenTelemetry 分布式追踪PROMETHEUS_AUTH_TOKEN随机生成开启/api/metricsPrometheus 指标端点8. [可选] 第七步安装快捷分享扩展部署完成后前往 docs/docs/04-using-karakeep/quick-sharing.md 安装移动端 App 与浏览器扩展Chrome/Firefox/Safari。这些客户端通过NEXTAUTH_URL指向的服务地址连接能让你在任何场景下快速把链接、文字、图片存入 Karakeep。9. 版本升级升级方式取决于KARAKEEP_VERSION的取值固定了具体版本修改.env中的版本号后重新执行docker compose up -dCompose 会自动拉取新镜像并重建容器使用release标签需要强制拉取最新镜像docker compose up --pull always -d9.1 Chrome 镜像迁移说明若你维护的是自定义 compose 文件且仍在使用旧的 Alpine Chrome 镜像gcr.io/zenika-hub/alpine-chrome:124需要迁移到 Karakeep 官方发布的ghcr.io/karakeep-app/karakeep-chrome:release镜像。迁移要点详见 docs/docs/06-administration/09-chrome-image-migration.md移除--no-sandbox与--remote-debugging-address0.0.0.0/--remote-debugging-port9222参数新镜像入口自行处理调试端口转发并提供--no-sandbox增加init: true迁移不影响业务数据无需数据库迁移。9.2 Meilisearch 升级注意官方 compose 固定使用getmeili/meilisearch:v1.41.0不建议无理由升级。若升级后出现数据库版本不兼容报错可参考 docs/docs/06-administration/05-troubleshooting.md 的处理流程停止 meilisearch 容器 → 在/meili_data卷中清空data.ms目录 → 重启容器 → 以管理员登录后在Admin Settings Background Jobs中点击Reindex All Bookmarks重建索引。10. 常见问题速查SqliteError: no such table: user通常是DATA_DIR被清空、或自定义 compose 中遗漏了DATA_DIR/data环境变量导致数据库目录不一致重启容器或补全变量即可见 docs/docs/06-administration/05-troubleshooting.mdAI 打标不生效OpenAI检查OPENAI_API_KEY是否拼写正确、修改.env后是否重新docker compose up、账户是否预充值AI 打标不生效Ollama除上述检查外还需确认INFERENCE_TEXT_MODEL已改为本地模型且OLLAMA_BASE_URL不能写成localhost容器内localhost指向容器自身应写宿主机可达地址或使用host.docker.internal类地址爬取不工作若重命名了 chrome 容器需同步修改BROWSER_WEB_URL环境变量。11. 小结通过本文的七个步骤你已经掌握了 Karakeep 基于 Docker 的完整部署链路最小.env四件套KARAKEEP_VERSION、NEXTAUTH_SECRET、MEILI_MASTER_KEY、NEXTAUTH_URL是启动的底线webchromemeilisearch三服务的容器网络接线决定了爬虫与搜索是否可用而 AI 打标、全文归档、语义搜索等进阶能力则全部由环境变量驱动其默认值与校验逻辑集中在 packages/shared/config.ts可作为排查配置问题的第一手源码依据。升级时根据KARAKEEP_VERSION选择拉取策略并留意 Chrome 镜像迁移与 Meilisearch 索引重建两个特殊场景即可长期稳定运行。【免费下载链接】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），仅供参考