企业官网建设流程全解析

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）默认由三组外部依赖共同支撑核心体验：

这三种能力对发挥 Karakeep 的完整价值非常重要，但如果你运行在资源受限的环境（低配 VPS、树莓派、内网 NAS、临时验证环境）中，完全可以用下面这份最小化编排文件跳过全部外部依赖，只启动一个容器。

方式一：使用最小化 docker-compose.yml

将以下内容保存为docker-compose.yml并执行docker compose up -d：

services: 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:release：Karakeep 的 All-in-One（AIO）镜像。从 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_SECRET=super_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配置段看，搜索相关 worker（searchWorker）的索引任务在此场景下不会产生实际效果，系统不会因此崩溃，只会静默跳过。这也是官方文档强调"搜索功能会被完全禁用"的底层原因。

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环境变量按需启停。

两个必配环境变量详解

极简安装只需要理解两个环境变量，但它们承担了最关键的基础职责：

完整的变量清单（含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_MODE=true（SQLite 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_KEY（openssl 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