Karakeep 极简安装指南无 Meilisearch、Chrome 与 AI 依赖的单容器部署方案【免费下载链接】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的极简安装Minimal Installation方案在不引入 Meilisearch 全文检索引擎、Chrome 无头浏览器与 OpenAI/Ollama 推理服务的前提下仅用单个容器完成自托管部署。你将掌握完整的最小化docker-compose.yml与docker run命令写法、关键环境变量的底层校验逻辑以及极简模式下各功能模块的实际降级行为并了解后续向完整安装平滑升级的路径。极简安装的本质牺牲哪些功能保留哪些能力Karakeep 的完整安装见 Docker 安装指南 与仓库根目录的 docker/docker-compose.yml默认由三组外部依赖共同支撑核心体验依赖组件在完整安装中的角色极简安装不部署后的行为Meilisearch全文检索后端通过MEILI_ADDR连接搜索功能被完全禁用搜索入口与索引任务均不生效Chrome无头浏览器负责页面 JS 渲染、网站截图、整页归档爬取仍可工作但退化为纯 HTTP 请求无法截取网站截图含 JavaScript 动态内容的页面无法被正确抓取OpenAI / OllamaAI 自动打标签、摘要、图像理解AI 自动打标签被禁用这三种能力对发挥 Karakeep 的完整价值非常重要但如果你运行在资源受限的环境低配 VPS、树莓派、内网 NAS、临时验证环境中完全可以用下面这份最小化编排文件跳过全部外部依赖只启动一个容器。方式一使用最小化 docker-compose.yml将以下内容保存为docker-compose.yml并执行docker compose up -dservices: web: image: ghcr.io/karakeep-app/karakeep:release restart: unless-stopped volumes: - data:/data ports: - 3000:3000 environment: DATA_DIR: /data NEXTAUTH_SECRET: super_random_string volumes: data:逐项拆解这份编排文件image: ghcr.io/karakeep-app/karakeep:releaseKarakeep 的 All-in-OneAIO镜像。从 docker/Dockerfile 的构建结构aio_builder、aio、web、workers等多个 target可以看出该镜像内置了 Web 服务与全部后台 worker单容器即可运行完整应用release标签指向最新稳定版生产环境建议锁定具体版本号如0.29.0以便控制升级节奏。volumes: - data:/data将数据目录挂载为 Docker 命名卷。数据库SQLite、默认资产存储${DATA_DIR}/assets都位于该目录下请务必保留持久化否则容器重建会丢失全部数据。ports: - 3000:3000将容器内 3000 端口映射到宿主机。若宿主机 3000 被占用只需修改左侧宿主端口即可例如8080:3000不要去改动容器内端口。environment仅需两个关键变量DATA_DIR指定持久化目录NEXTAUTH_SECRET用于签名 JWT 会话令牌详见下文。方式二使用单条 docker run 命令不习惯 compose 的话也可以用下面这条等价命令直接启动docker run -d \ --restart unless-stopped \ -v data:/data \ -p 3000:3000 \ -e DATA_DIR/data \ -e NEXTAUTH_SECRETsuper_random_string \ ghcr.io/karakeep-app/karakeep:release参数与 compose 版本一一对应-d后台运行、--restart unless-stopped保证崩溃后自动拉起、-v data:/data挂载数据卷、-p 3000:3000暴露端口、两个-e注入环境变量。启动后访问http://localhost:3000即可看到注册/登录页面。必读警告NEXTAUTH_SECRET 必须替换为真随机串两份配置示例中的super_random_string只是占位符必须替换为真正随机的字符串。原文档给出的推荐生成命令为openssl rand -hex 32为什么这个变量如此关键在 packages/shared/config.ts 中可以看到应用启动时会调用signingSecret()若NEXTAUTH_SECRET未设置会直接抛出NEXTAUTH_SECRET is not set异常而该秘密用于签发与校验 NextAuth 的 JWT 令牌。使用固定弱口令意味着所有会话令牌都可被预测或伪造属于严重安全风险。同理若日后启用 Meilisearch其MEILI_MASTER_KEY也建议用openssl rand -base64 36之类的方式生成。极简模式下仍然可用的功能源码级佐证很多用户担心极简安装会残废实际上核心的书签管理能力链接、笔记、图片的增删改查、标签、列表、导入导出、RSS 等都完整保留。以下从源码确认三处关键行为1. 爬取降级为纯 HTTP 模式截图与 JS 渲染不可用在 apps/workers/workers/crawler/crawlPage.ts 中browserlessCrawlPage()函数明确处理了无浏览器后端的场景日志会打印Running in browserless mode. Will do a plain http request ... Screenshots will be disabled.随后通过fetchWithProxy直接抓取 URL 内容返回的screenshot与pdf均为undefined。对应地apps/workers/workers/crawler/browser.ts 只在配置了BROWSER_WEBSOCKET_URL直连调试 WebSocket或BROWSER_WEB_URL先取调试地址再解析 WebSocket时才启动 Playwright 浏览器连接两者都未设置时worker 走纯 HTTP 路径。因此在极简模式下纯静态页面服务端渲染的 HTML可以正常抓取正文与元数据依赖 JS 动态渲染的 SPA 页面只会拿到初始 HTML内容可能缺失网站截图、整页归档CRAWLER_FULL_PAGE_ARCHIVE、PDF 快照等能力无法使用。2. 搜索功能整体关闭但索引逻辑不会报错未设置MEILI_ADDR时搜索后端不可用全文搜索入口被整体禁用从 packages/shared/config.ts 的search配置段看搜索相关 workersearchWorker的索引任务在此场景下不会产生实际效果系统不会因此崩溃只会静默跳过。这也是官方文档强调搜索功能会被完全禁用的底层原因。3. 后台 worker 仍然全部随容器启动极简安装并非只有一个 Web 进程。镜像内通过 s6-overlay 同时拉起 Web 与 workers 服务见 docker/Dockerfile 中svc-web与svc-workers两个服务定义。在 apps/workers/index.ts 中注册的 worker 包括crawler、inference、search、adminMaintenance、video、feed、assetPreprocessing、webhook、ruleEngine、backup等。未配置对应依赖的 worker如无 Meilisearch 时的search、无 OpenAI/Ollama 时的inference会保持空闲而crawler纯 HTTP 模式、adminMaintenance、feed等仍正常运转。如需进一步裁剪可结合WORKERS_ENABLED_WORKERS/WORKERS_DISABLED_WORKERS环境变量按需启停。两个必配环境变量详解极简安装只需要理解两个环境变量但它们承担了最关键的基础职责变量必填默认值说明DATA_DIR是未设置持久化数据目录数据库SQLite存放于此资产图片、截图等默认存储在${DATA_DIR}/assets可被ASSETS_DIR覆盖。在容器内固定为/data与卷挂载点对应不要改动容器内值NEXTAUTH_SECRET是未设置用于签名 JWT 令牌的随机字符串缺失时应用启动即失败见 packages/shared/config.ts完整的变量清单含PORT、NEXTAUTH_URL、LOG_LEVEL、DB_WAL_MODE、MAX_ASSET_SIZE_MB、CRAWLER_*、INFERENCE_*、ASSET_STORE_S3_*、SMTP_*、OTEL_*等数十项请查阅 环境变量配置文档其权威定义位于 packages/shared/config.ts通过 zod schema 解析process.env并对非法值做启动期校验。两点提示若部署在非本机、且后续要接入浏览器扩展或移动端建议同时设置NEXTAUTH_URL指向实例的实际访问地址如http://192.168.1.10:3000否则登出等场景可能出现跳转地址错误极简部署后若磁盘空间紧张可考虑DB_WAL_MODEtrueSQLite WAL 模式提升并发读写性能但不要在网络盘上开启。从极简到完整按需补齐依赖的升级路径极简安装适合受限环境但若后续需要全文搜索、截图与 AI 打标签无需重新部署数据只需在 compose 中补齐对应服务并增加环境变量。参照仓库根目录的 docker/docker-compose.yml 完整编排services: web: image: ghcr.io/karakeep-app/karakeep:release restart: unless-stopped volumes: - data:/data ports: - 3000:3000 environment: MEILI_ADDR: http://meilisearch:7700 BROWSER_WEB_URL: http://chrome:9222 # OPENAI_API_KEY: ... # 需要自动打标签时取消注释 DATA_DIR: /data chrome: image: ghcr.io/karakeep-app/karakeep-chrome:release restart: unless-stopped init: true meilisearch: image: getmeili/meilisearch:v1.41.0 restart: unless-stopped environment: MEILI_NO_ANALYTICS: true volumes: - meilisearch:/meili_data volumes: meilisearch: data:升级要点启用搜索设置MEILI_ADDR指向 Meilisearch 服务地址生产环境还需为 Meilisearch 配置MEILI_MASTER_KEYopenssl rand -base64 36 | tr -dc A-Za-z0-9生成。启用浏览器爬取设置BROWSER_WEB_URL或直连 WebSocket 的BROWSER_WEBSOCKET_URL指向 Chrome 容器即可恢复截图、JS 渲染、整页归档能力。启用 AI 打标签设置OPENAI_API_KEY或自建 Ollama 时设置OLLAMA_BASE_URL。从 packages/shared/config.ts 可见inference.isConfigured的判定逻辑正是!!OPENAI_API_KEY || !!OLLAMA_BASE_URL两者均未配置时自动打标签会被跳过。版本固定release标签会在镜像更新后需要显式拉取docker compose up --pull always -d锁版本号则每次升级只需修改版本并docker compose up -d。结语极简安装是 Karakeep 在资源受限环境下的务实之选一个容器、两个环境变量即可跑起完整的书签管理核心搜索、截图、AI 打标签等增强能力按需通过MEILI_ADDR、BROWSER_WEB_URL、OPENAI_API_KEY/OLLAMA_BASE_URL逐步补齐。无论从极简起步还是直接完整部署都建议先通读 环境变量配置文档对应本版本归档见 version-v0.29.0 配置章节并结合 packages/shared/config.ts 理解每一项配置的真实作用避免出现配置了却不生效的困惑。若需要整页归档、整页截图、推理语言等更多进阶能力请参考 完整 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/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Karakeep 极简安装指南：无 Meilisearch、Chrome 与 AI 依赖的单容器部署方案
Karakeep 极简安装指南无 Meilisearch、Chrome 与 AI 依赖的单容器部署方案【免费下载链接】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的极简安装Minimal Installation方案在不引入 Meilisearch 全文检索引擎、Chrome 无头浏览器与 OpenAI/Ollama 推理服务的前提下仅用单个容器完成自托管部署。你将掌握完整的最小化docker-compose.yml与docker run命令写法、关键环境变量的底层校验逻辑以及极简模式下各功能模块的实际降级行为并了解后续向完整安装平滑升级的路径。极简安装的本质牺牲哪些功能保留哪些能力Karakeep 的完整安装见 Docker 安装指南 与仓库根目录的 docker/docker-compose.yml默认由三组外部依赖共同支撑核心体验依赖组件在完整安装中的角色极简安装不部署后的行为Meilisearch全文检索后端通过MEILI_ADDR连接搜索功能被完全禁用搜索入口与索引任务均不生效Chrome无头浏览器负责页面 JS 渲染、网站截图、整页归档爬取仍可工作但退化为纯 HTTP 请求无法截取网站截图含 JavaScript 动态内容的页面无法被正确抓取OpenAI / OllamaAI 自动打标签、摘要、图像理解AI 自动打标签被禁用这三种能力对发挥 Karakeep 的完整价值非常重要但如果你运行在资源受限的环境低配 VPS、树莓派、内网 NAS、临时验证环境中完全可以用下面这份最小化编排文件跳过全部外部依赖只启动一个容器。方式一使用最小化 docker-compose.yml将以下内容保存为docker-compose.yml并执行docker compose up -dservices: web: image: ghcr.io/karakeep-app/karakeep:release restart: unless-stopped volumes: - data:/data ports: - 3000:3000 environment: DATA_DIR: /data NEXTAUTH_SECRET: super_random_string volumes: data:逐项拆解这份编排文件image: ghcr.io/karakeep-app/karakeep:releaseKarakeep 的 All-in-OneAIO镜像。从 docker/Dockerfile 的构建结构aio_builder、aio、web、workers等多个 target可以看出该镜像内置了 Web 服务与全部后台 worker单容器即可运行完整应用release标签指向最新稳定版生产环境建议锁定具体版本号如0.29.0以便控制升级节奏。volumes: - data:/data将数据目录挂载为 Docker 命名卷。数据库SQLite、默认资产存储${DATA_DIR}/assets都位于该目录下请务必保留持久化否则容器重建会丢失全部数据。ports: - 3000:3000将容器内 3000 端口映射到宿主机。若宿主机 3000 被占用只需修改左侧宿主端口即可例如8080:3000不要去改动容器内端口。environment仅需两个关键变量DATA_DIR指定持久化目录NEXTAUTH_SECRET用于签名 JWT 会话令牌详见下文。方式二使用单条 docker run 命令不习惯 compose 的话也可以用下面这条等价命令直接启动docker run -d \ --restart unless-stopped \ -v data:/data \ -p 3000:3000 \ -e DATA_DIR/data \ -e NEXTAUTH_SECRETsuper_random_string \ ghcr.io/karakeep-app/karakeep:release参数与 compose 版本一一对应-d后台运行、--restart unless-stopped保证崩溃后自动拉起、-v data:/data挂载数据卷、-p 3000:3000暴露端口、两个-e注入环境变量。启动后访问http://localhost:3000即可看到注册/登录页面。必读警告NEXTAUTH_SECRET 必须替换为真随机串两份配置示例中的super_random_string只是占位符必须替换为真正随机的字符串。原文档给出的推荐生成命令为openssl rand -hex 32为什么这个变量如此关键在 packages/shared/config.ts 中可以看到应用启动时会调用signingSecret()若NEXTAUTH_SECRET未设置会直接抛出NEXTAUTH_SECRET is not set异常而该秘密用于签发与校验 NextAuth 的 JWT 令牌。使用固定弱口令意味着所有会话令牌都可被预测或伪造属于严重安全风险。同理若日后启用 Meilisearch其MEILI_MASTER_KEY也建议用openssl rand -base64 36之类的方式生成。极简模式下仍然可用的功能源码级佐证很多用户担心极简安装会残废实际上核心的书签管理能力链接、笔记、图片的增删改查、标签、列表、导入导出、RSS 等都完整保留。以下从源码确认三处关键行为1. 爬取降级为纯 HTTP 模式截图与 JS 渲染不可用在 apps/workers/workers/crawler/crawlPage.ts 中browserlessCrawlPage()函数明确处理了无浏览器后端的场景日志会打印Running in browserless mode. Will do a plain http request ... Screenshots will be disabled.随后通过fetchWithProxy直接抓取 URL 内容返回的screenshot与pdf均为undefined。对应地apps/workers/workers/crawler/browser.ts 只在配置了BROWSER_WEBSOCKET_URL直连调试 WebSocket或BROWSER_WEB_URL先取调试地址再解析 WebSocket时才启动 Playwright 浏览器连接两者都未设置时worker 走纯 HTTP 路径。因此在极简模式下纯静态页面服务端渲染的 HTML可以正常抓取正文与元数据依赖 JS 动态渲染的 SPA 页面只会拿到初始 HTML内容可能缺失网站截图、整页归档CRAWLER_FULL_PAGE_ARCHIVE、PDF 快照等能力无法使用。2. 搜索功能整体关闭但索引逻辑不会报错未设置MEILI_ADDR时搜索后端不可用全文搜索入口被整体禁用从 packages/shared/config.ts 的search配置段看搜索相关 workersearchWorker的索引任务在此场景下不会产生实际效果系统不会因此崩溃只会静默跳过。这也是官方文档强调搜索功能会被完全禁用的底层原因。3. 后台 worker 仍然全部随容器启动极简安装并非只有一个 Web 进程。镜像内通过 s6-overlay 同时拉起 Web 与 workers 服务见 docker/Dockerfile 中svc-web与svc-workers两个服务定义。在 apps/workers/index.ts 中注册的 worker 包括crawler、inference、search、adminMaintenance、video、feed、assetPreprocessing、webhook、ruleEngine、backup等。未配置对应依赖的 worker如无 Meilisearch 时的search、无 OpenAI/Ollama 时的inference会保持空闲而crawler纯 HTTP 模式、adminMaintenance、feed等仍正常运转。如需进一步裁剪可结合WORKERS_ENABLED_WORKERS/WORKERS_DISABLED_WORKERS环境变量按需启停。两个必配环境变量详解极简安装只需要理解两个环境变量但它们承担了最关键的基础职责变量必填默认值说明DATA_DIR是未设置持久化数据目录数据库SQLite存放于此资产图片、截图等默认存储在${DATA_DIR}/assets可被ASSETS_DIR覆盖。在容器内固定为/data与卷挂载点对应不要改动容器内值NEXTAUTH_SECRET是未设置用于签名 JWT 令牌的随机字符串缺失时应用启动即失败见 packages/shared/config.ts完整的变量清单含PORT、NEXTAUTH_URL、LOG_LEVEL、DB_WAL_MODE、MAX_ASSET_SIZE_MB、CRAWLER_*、INFERENCE_*、ASSET_STORE_S3_*、SMTP_*、OTEL_*等数十项请查阅 环境变量配置文档其权威定义位于 packages/shared/config.ts通过 zod schema 解析process.env并对非法值做启动期校验。两点提示若部署在非本机、且后续要接入浏览器扩展或移动端建议同时设置NEXTAUTH_URL指向实例的实际访问地址如http://192.168.1.10:3000否则登出等场景可能出现跳转地址错误极简部署后若磁盘空间紧张可考虑DB_WAL_MODEtrueSQLite WAL 模式提升并发读写性能但不要在网络盘上开启。从极简到完整按需补齐依赖的升级路径极简安装适合受限环境但若后续需要全文搜索、截图与 AI 打标签无需重新部署数据只需在 compose 中补齐对应服务并增加环境变量。参照仓库根目录的 docker/docker-compose.yml 完整编排services: web: image: ghcr.io/karakeep-app/karakeep:release restart: unless-stopped volumes: - data:/data ports: - 3000:3000 environment: MEILI_ADDR: http://meilisearch:7700 BROWSER_WEB_URL: http://chrome:9222 # OPENAI_API_KEY: ... # 需要自动打标签时取消注释 DATA_DIR: /data chrome: image: ghcr.io/karakeep-app/karakeep-chrome:release restart: unless-stopped init: true meilisearch: image: getmeili/meilisearch:v1.41.0 restart: unless-stopped environment: MEILI_NO_ANALYTICS: true volumes: - meilisearch:/meili_data volumes: meilisearch: data:升级要点启用搜索设置MEILI_ADDR指向 Meilisearch 服务地址生产环境还需为 Meilisearch 配置MEILI_MASTER_KEYopenssl rand -base64 36 | tr -dc A-Za-z0-9生成。启用浏览器爬取设置BROWSER_WEB_URL或直连 WebSocket 的BROWSER_WEBSOCKET_URL指向 Chrome 容器即可恢复截图、JS 渲染、整页归档能力。启用 AI 打标签设置OPENAI_API_KEY或自建 Ollama 时设置OLLAMA_BASE_URL。从 packages/shared/config.ts 可见inference.isConfigured的判定逻辑正是!!OPENAI_API_KEY || !!OLLAMA_BASE_URL两者均未配置时自动打标签会被跳过。版本固定release标签会在镜像更新后需要显式拉取docker compose up --pull always -d锁版本号则每次升级只需修改版本并docker compose up -d。结语极简安装是 Karakeep 在资源受限环境下的务实之选一个容器、两个环境变量即可跑起完整的书签管理核心搜索、截图、AI 打标签等增强能力按需通过MEILI_ADDR、BROWSER_WEB_URL、OPENAI_API_KEY/OLLAMA_BASE_URL逐步补齐。无论从极简起步还是直接完整部署都建议先通读 环境变量配置文档对应本版本归档见 version-v0.29.0 配置章节并结合 packages/shared/config.ts 理解每一项配置的真实作用避免出现配置了却不生效的困惑。若需要整页归档、整页截图、推理语言等更多进阶能力请参考 完整 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/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考