尧图网页设计 
Karakeep原 hoarder环境变量配置完全指南从部署到生产调优的 100 参数详解【免费下载链接】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.31.0 官方配置文档为核心骨架逐类拆解服务端、存储、认证、AI 推理、爬虫、OCR、Webhook、SMTP、代理与监控的 100 个环境变量每个变量都给出默认值、必填性、取值范围与实战建议并辅以当前仓库源码packages/shared/config.ts、apps/workers/index.ts、docker/docker-compose.yml佐证其底层实现帮助你完成从能跑到生产可用的配置进阶。Karakeep 架构图Karakeep 的架构以 Web 服务web与一组后台 Worker 为核心Web 服务负责用户界面与 APIWorker 负责抓取、索引、推理、Webhook 投递等异步任务二者通过队列如 Redis解耦共同读写 SQLite 数据库、Meilisearch 搜索索引并调用无头浏览器与 AI 推理服务。理解这张架构图后你会更容易理解为什么哪类变量需要配置在哪个进程上——例如 OAuth 相关变量必须传给web容器而爬虫与浏览器相关变量则作用于 Worker 进程。一、核心服务配置所有环境变量的统一入口Karakeep 的应用配置几乎全部由环境变量驱动。所有被使用的环境变量统一定义并解析于 packages/shared/config.ts该文件使用 Zod schema 对process.env做启动时校验与类型转换布尔值统一要求true/false字符串数字通过z.coerce.number()强转任何非法取值都会在启动阶段直接报错而不是运行到一半才暴露问题。这意味着环境变量拼写错误是最常见的启动失败原因排查时请优先核对变量名。下表是 v0.31.0 文档列出的最重要变量当前主分支源码中的默认值可能已演进下文标注处会提示变量名必填默认值说明PORT否3000Web 服务器监听端口。使用 Docker 时不要修改此值应改 Docker 映射的外部端口见 docker/docker-compose.yml 中ports: - 3000:3000的左侧值WORKERS_PORT否0随机端口Worker 导出 Prometheus 指标/metrics的端口。需要采集指标时请固定该值并在 Docker 中导出对应端口WORKERS_HOST否127.0.0.1Worker 指标端口绑定的主机。容器化部署时必须显式设置如0.0.0.0否则外部无法访问localhostWORKERS_ENABLED_WORKERS否未设置逗号分隔的启用的 Worker 名称列表设置后只运行这些 Worker。v0.31.0 合法值crawler,inference,search,adminMaintenance,video,feed,assetPreprocessing,webhook,ruleEngineWORKERS_DISABLED_WORKERS否未设置逗号分隔的禁用的 Worker 名称列表优先级高于WORKERS_ENABLED_WORKERSLOG_LEVEL否debug应用日志级别遵循 winston 日志级别定义。生产环境建议设为notice或warning以降低日志噪音DATA_DIR是未设置持久化数据目录数据库存放在此。未设置ASSETS_DIR时资产默认也存放在此目录下ASSETS_DIR否未设置抓取资产的存放路径。未设置时默认为${DATA_DIR}/assets源码见 packages/shared/config.tsNEXTAUTH_URL是未设置指向你的服务器地址。缺少它应用仍能运行但登出等场景会重定向到错误地址NEXTAUTH_SECRET是未设置用于签名 JWT 的随机字符串。生成命令openssl rand -base64 36MEILI_ADDR否未设置Meilisearch 地址如http://meilisearch:7700。未设置则全文搜索被禁用MEILI_MASTER_KEY生产环境开启搜索时必填未设置Meilisearch 主密钥开发环境不需要。生成命令openssl rand -base64 36 \| tr -dc A-Za-z0-9MAX_ASSET_SIZE_MB否50允许上传的单个资产最大体积MBDISABLE_NEW_RELEASE_CHECK否false设为true时禁用管理面板中的最新版本检查RATE_LIMITING_ENABLED否false设为true时启用 API 限流CRAWLER_DOMAIN_RATE_LIMIT_WINDOW_MS否未设置爬虫按域名限流的时间窗口毫秒CRAWLER_DOMAIN_RATE_LIMIT_MAX_REQUESTS否未设置窗口内每个域名允许的最大爬虫请求数DB_WAL_MODE否false为 SQLite 启用 WAL 模式可显著提升数据库性能。除非数据库位于网络挂载盘上否则建议设为true官方计划未来将其设为默认SEARCH_NUM_WORKERS否1搜索索引任务的并发 Worker 数。索引内容量大时可调高SEARCH_JOB_TIMEOUT_SEC否30搜索索引任务超时时间秒。大型书签内容索引较慢时可调高WEBHOOK_NUM_WORKERS否1Webhook 投递的并发 Worker 数。多 Webhook 端点或高流量时调高ASSET_PREPROCESSING_NUM_WORKERS否1资产预处理图片处理、OCR 等的并发 Worker 数ASSET_PREPROCESSING_JOB_TIMEOUT_SEC否60资产预处理任务超时时间秒。大图片或大 PDF 处理慢时可调高RULE_ENGINE_NUM_WORKERS否1规则引擎处理任务的并发 Worker 数。自动化规则复杂时可调高MAX_RSS_FEEDS_PER_USER否1000单个用户可创建的 RSS 订阅源数量上限MAX_WEBHOOKS_PER_USER否100单个用户可创建的 Webhook 数量上限Worker 启停的源码级原理WORKERS_ENABLED_WORKERS/WORKERS_DISABLED_WORKERS两个变量的实际生效逻辑位于 apps/workers/index.ts启动时分别构建enabledWorkers与disabledWorkers两个 SetisWorkerEnabled()先判断启用了白名单但当前 Worker 不在其中则返回false再判断在禁用名单中则返回false其余 Worker 才被构建并启动。disabled名单优先于enabled名单与文档描述一致。另外需要注意v0.31.0 文档列出的合法 Worker 名只有 9 个而当前主分支源码中的workerBuilders见 apps/workers/index.ts已经扩展到 12 个新增了lowPriorityCrawler、embeddings、backup且importWorker 独立于该名单之外由isWorkerEnabled(import)单独控制。如果你从旧版本升级务必核对新版本支持的 Worker 名称。Docker 部署中的落地示例在 Docker 部署下Web 容器统一加载.env文件并注入关键连接信息见 docker/docker-compose.ymlservices: web: image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release} restart: unless-stopped volumes: - data:/data ports: - 3000:3000 env_file: - .env environment: MEILI_ADDR: http://meilisearch:7700 BROWSER_WEB_URL: http://chrome:9222 # OPENAI_API_KEY: ... # 几乎不需要修改 DATA_DIR要改存储位置请改上面的 volume 映射 DATA_DIR: /data # DONT CHANGE THIS chrome: image: ghcr.io/karakeep-app/karakeep-chrome:release restart: unless-stopped init: true meilisearch: image: getmeili/meilisearch:v1.41.0 restart: unless-stopped env_file: - .env environment: MEILI_NO_ANALYTICS: true volumes: - meilisearch:/meili_data这份示例传达出三个关键实践一是DATA_DIR在容器内固定为/data持久化位置通过 volume 映射决定二是MEILI_ADDR、BROWSER_WEB_URL使用容器间服务名而非 IP三是敏感密钥如OPENAI_API_KEY、NEXTAUTH_SECRET统一放入.env通过env_file注入避免硬编码进 compose 文件。二、资产存储本地文件系统与 S3 兼容对象存储Karakeep 支持两种资产存储后端本地文件系统默认与 S3 兼容对象存储。S3 后端会在传入 S3 endpoint 时自动启用——源码中通过ASSET_STORE_S3_ENDPOINT是否存在来决定存储类型见 packages/shared/config.ts变量名必填默认值说明ASSET_STORE_S3_ENDPOINT否未设置S3 endpoint URL接入 MinIO 等 S3 兼容服务时必填。设置该项即启用 S3 存储ASSET_STORE_S3_REGION否未设置S3 区域ASSET_STORE_S3_BUCKET使用 S3 时必填未设置存储资产的 bucket 名称ASSET_STORE_S3_ACCESS_KEY_ID使用 S3 时必填未设置访问密钥 IDASSET_STORE_S3_SECRET_ACCESS_KEY使用 S3 时必填未设置访问密钥ASSET_STORE_S3_FORCE_PATH_STYLE否false是否强制使用 path-style URL。MinIO 等 S3 兼容服务需设为true使用 S3 存储时有两条官方提示需要特别注意确保 bucket 已存在且凭据具备对 bucket 内对象的读、写、删除权限切换存储后端后需手动迁移已有资产本地文件不会自动搬移到 S3。部署前务必规划好存储方案避免上线后迁移的麻烦。此外资产体积上限由第一节的MAX_ASSET_SIZE_MB默认 50控制而HTML_CONTENT_SIZE_INLINE_THRESHOLD_BYTES默认5 * 1024决定超过多少字节的 HTML 内容将存入 assetdb目录或 S3而非内联进数据库——这对控制 SQLite 体积有实际意义。三、认证与注册数据库账号、OIDC OAuth 与注册策略默认情况下 Karakeep 使用数据库存储用户账号同时支持接入 OIDC 兼容的 OAuth 提供方。所有认证相关变量必须传给web容器。配置 OAuth 时提供方侧允许的回调地址应设为KARAKEEP_ADDRESS/api/auth/callback/custom其中KARAKEEP_ADDRESS即NEXTAUTH_URL中配置的地址例如https://try.karakeep.app/api/auth/callback/custom。变量名必填默认值说明DISABLE_SIGNUPS否false启用后禁止新用户注册UI 上的注册按钮同时被禁用DISABLE_PASSWORD_AUTH否false启用后仅允许通过 OAuth 注册/登录本地账号的注册按钮与登录表单在 UI 中被禁用EMAIL_VERIFICATION_REQUIRED否false注册时是否强制邮箱验证。启用后用户必须验证邮箱才能使用账号且必须同时配置 SMTPOAUTH_AUTO_REDIRECT否false当密码认证被禁用时自动重定向到 OAuth 提供方而非展示登录页。适合 OAuth 是唯一认证方式的情形OAUTH_WELLKNOWN_URL否未设置提供方提供的 OpenID Configurationwell-known URLOAUTH_CLIENT_SECRET否未设置提供方签发的 Client SecretOAUTH_CLIENT_ID否未设置提供方签发的 Client IDOAUTH_SCOPE否openid email profile请求的 scope 列表空格分隔OAUTH_PROVIDER_NAME否Custom Provider提供方名称注册页会显示为 Sign in withnameOAUTH_ALLOW_DANGEROUS_EMAIL_ACCOUNT_LINKING否false是否自动将数据库中已有的同名邮箱账号与 OAuth 账号关联。仅在信任该 OAuth 提供方时启用OAUTH_TIMEOUT否3500等待 OAuth 提供方响应的毫秒数。遇到outgoing request timed out错误时调大两个值得深入说明的点1. 配置项的交叉校验。EMAIL_VERIFICATION_REQUIREDtrue而 SMTP 未配置时启动会直接失败——这是 packages/shared/config.ts 中 Zod schema 显式抛出的致命错误To enable email verification, SMTP settings must be configured。同理OAUTH_TIMEOUT默认 3500 毫秒在慢速提供方下可能不够调大它是最常见的 OAuth 故障修复手段。2. 旧版兼容与升级注意。v0.31.0 文档未收录OAUTH_ID_TOKEN_SIGNED_RESPONSE_ALG但当前主分支源码packages/shared/config.ts已支持通过它指定 ID Token 的 JWS 签名算法取值RS256/RS384/RS512/PS256/PS384/PS512/ES256/ES384/ES512/EdDSA。当提供方用非默认算法签名 ID Token 时OAuth 回调会以 unexpected JWT algorithm 失败此时就需要显式设置该变量。四、AI 推理配置自动打标签与自动摘要OPENAI_API_KEY与OLLAMA_BASE_URL至少设置其一自动打标签才会启用否则自动打标签会被跳过。源码中对应的判断为inference.isConfigured !!OPENAI_API_KEY || !!OLLAMA_BASE_URL见 packages/shared/config.ts。官方对推理配置给出两条警告标签质量取决于所选模型的质量建议调大INFERENCE_CONTEXT_LENGTH默认值偏小。值越大标签质量越高但推理成本越高OpenAI 侧花钱、Ollama 侧耗资源。变量名必填默认值说明OPENAI_API_KEY否未设置用于自动打标签的 OpenAI 密钥更多说明见 docs/docs/06-administration/03-openai.mdOPENAI_BASE_URL否未设置仅用 OpenAI 官方 API 时无需设置使用 Azure OpenAI 等兼容 API 时设为对应地址OPENAI_PROXY_URL否未设置OpenAI API 请求的 HTTP 代理如http://proxy.example.com:8080OPENAI_SERVICE_TIER否未设置auto、default或flex。flex 以更慢响应和偶发资源不可用换取更低成本OLLAMA_BASE_URL否未设置使用 Ollama 本地推理时填写 Ollama API 地址OLLAMA_KEEP_ALIVE否未设置请求后模型在内存中驻留时长5m表示 5 分钟-1m表示常驻内存0表示处理完立即卸载INFERENCE_TEXT_MODEL否gpt-4.1-miniv0.31.0文本推理模型。使用 Ollama 时必须更换当前主分支源码默认值已更新为gpt-5.6-luna见 packages/shared/config.tsINFERENCE_IMAGE_MODEL否gpt-4o-mini图片推理模型。Ollama 需要支持视觉 API 的模型如 llavaEMBEDDING_TEXT_MODEL否text-embedding-3-small生成文本 embedding 的模型INFERENCE_CONTEXT_LENGTH否2048传给推理模型的最大 token 数超出部分被截断。值越大参与打标签的内容越多成本也越高请对照所用模型的最大上下文INFERENCE_MAX_OUTPUT_TOKENS否2048推理模型允许生成的最大 token 数控制标签、摘要等 AI 内容的长度。需要更长输出时可调大但会提高成本与耗时INFERENCE_USE_MAX_COMPLETION_TOKENS否false[仅 OpenAI] 是否使用新的max_completion_tokens参数替代废弃的max_tokens。使用 GPT-5 或 o 系列模型时设为true未来版本将默认开启INFERENCE_LANG否english生成标签的语言INFERENCE_NUM_WORKERS否1AI 推理任务打标签与摘要的并发 Worker 数需要并行处理时可调高INFERENCE_ENABLE_AUTO_TAGGING否true是否启用自动 AI 打标签INFERENCE_ENABLE_AUTO_SUMMARIZATION否false是否启用自动 AI 摘要INFERENCE_JOB_TIMEOUT_SEC否30推理任务超时秒数。Ollama 无强力 GPU 时建议调大INFERENCE_FETCH_TIMEOUT_SEC否300[仅 Ollama] 请求 Ollama 服务器的 fetch 超时秒数。推理请求超过默认 5 分钟时调大INFERENCE_SUPPORTS_STRUCTURED_OUTPUT否未设置[已弃用] 模型是否支持结构化输出。true等价于INFERENCE_OUTPUT_SCHEMAstructuredfalse等价于plain请改用INFERENCE_OUTPUT_SCHEMAINFERENCE_OUTPUT_SCHEMA否structured取值structured、json、plain。首选structured模型不支持时若支持 JSON 模式用json否则用plain所有模型都支持但输出格式可能不规范自定义打标签提示词你可以在User Settings界面的AI Settings中为自动打标签追加额外指令并可使用三个占位符$tags全部标签$aiTagsAI 生成的标签$userTags人工创建的标签这些占位符在执行自动打标签时会被替换为实际标签列表例如[karakeep, computer, ai]。这为针对特定领域微调标签风格提供了无需改代码的入口。五、爬虫配置无头浏览器、截图、PDF 与整页归档爬虫是 Karakeep 的核心能力之一其行为高度可调。默认只允许 1 个并发抓取任务以避免资源占用过高。变量名必填默认值说明CRAWLER_NUM_WORKERS否1允许的并发抓取任务数BROWSER_WEB_URL否未设置浏览器的 HTTP 调试地址。Worker 通过它解析调试控制台的 WebSocket 地址已有 WebSocket 地址时直接用BROWSER_WEBSOCKET_URL。两者都未设置时Worker 退化为纯 HTTP 请求跳过截图与 JavaScript 执行BROWSER_WEBSOCKET_URL否未设置浏览器调试控制台的 WebSocket 地址使用 browserless 时填其 WebSocket 地址BROWSER_CONNECT_ONDEMAND否false为false时爬虫主动连接浏览器并保持长连接为true时仅在需要抓取时按需启动浏览器。使用按需提供浏览器实例的服务时设为trueCRAWLER_DOWNLOAD_BANNER_IMAGE否true是否将卡片横幅图缓存到本地。缓存更抗链接失效与站点限流但占用更多存储CRAWLER_STORE_SCREENSHOT否true是否保存抓取网站的截图。截图可作为无法从网站提取图片时的兜底也可随时查看CRAWLER_FULL_PAGE_SCREENSHOT否false是否保存整页截图。默认关闭磁盘占用高关闭时只截取可见区域CRAWLER_SCREENSHOT_TIMEOUT_SEC否5截图超时秒数。长网页整页截图可考虑调大CRAWLER_STORE_PDF否false是否保存抓取页面的 PDF 快照。默认关闭磁盘占用高开启后每个页面生成 PDF 资产可在书签预览中查看CRAWLER_FULL_PAGE_ARCHIVE否false是否保存页面完整本地副本。默认关闭磁盘占用高关闭时只归档页面可读文本CRAWLER_JOB_TIMEOUT_SEC否60抓取任务总超时秒数。网速慢或设备性能低时可调大CRAWLER_NAVIGATE_TIMEOUT_SEC否30页面导航含重定向超时秒数。网速慢时调大CRAWLER_PARSE_TIMEOUT_SEC否60HTML 解析子进程元数据提取 readability超时秒数CRAWLER_PARSER_MEM_LIMIT_MB否512HTML 解析子进程的最大堆内存MB。大页面解析 OOM 时调大子进程隔离OOM 不会拖垮主 WorkerCRAWLER_VIDEO_DOWNLOAD否false是否使用 yt-dlp 下载页面视频CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE否50下载视频的最大体积MB质量会相应调整。-1表示不限制CRAWLER_VIDEO_DOWNLOAD_TIMEOUT_SEC否600视频下载超时秒数CRAWLER_ENABLE_ADBLOCKER否true爬虫是否启用广告拦截。Worker 启动时下载广告拦截列表遇到困难可关闭CRAWLER_YTDLP_ARGS否[]抓取时传递给 yt-dlp 的额外参数用%%分隔多个参数BROWSER_COOKIE_PATH否未设置指向一个包含待加载进浏览器上下文的 cookies 的 JSON 文件路径HTML_CONTENT_SIZE_INLINE_THRESHOLD_BYTES否5 * 1024超过该字节数的较大资产存入 assetdb目录/S3而非内联进数据库BROWSER_COOKIE_PATH 详解BROWSER_COOKIE_PATH指向的 JSON 文件必须是一个 cookie 对象数组每个对象包含namecookie 名必填valuecookie 值必填可选字段domain、path、expires、httpOnly、secure、sameSite取值Strict、Lax或None示例文件内容[ { name: session, value: xxx, domain: .example.com, path: /, expires: 1735689600, httpOnly: true, secure: true, sameSite: Lax } ]该功能在抓取需要登录态或会话 cookie 的站点如内部系统、付费墙内容时非常实用。六、OCR 配置Tesseract 与 LLM 双引擎Karakeep 默认使用 tesseract.js 从图片中提取文本也可启用OCR_USE_LLM切换为 LLM 驱动的 OCR——后者复用已配置的推理模型OpenAI 或 Ollama对复杂图片效果更好但要求已配置推理提供方未配置推理提供方时自动回退到 Tesseract。变量名必填默认值说明OCR_CACHE_DIR否$TEMP_DIRTesseract 下载模型的目录。默认模型不持久化存放于系统临时目录OCR_LANGS否eng逗号分隔的 Tesseract 支持语言代码列表。设为空字符串可禁用 OCROCR_CONFIDENCE_THRESHOLD否500–100 之间的最低置信度阈值Tesseract 置信度低于该值时识别文本不存储OCR_USE_LLM否false设为true时用已配置的推理模型替代 Tesseract 做 OCR复杂图片效果更好七、Webhook 配置事件驱动的自动化出口Webhook 用于在书签被创建、变更或抓取完成时触发外部动作。除下面的超时与重试参数外鉴权与请求体格式也值得关注变量名必填默认值说明WEBHOOK_TIMEOUT_SEC否5Webhook 请求超时秒数WEBHOOK_RETRY_TIMES否3Webhook 请求重试次数鉴权方式WEBHOOK_TOKEN用于认证会以 Bearer token 形式出现在 Authorization 请求头Authorization: Bearer WEBHOOK_TOKEN该实现可在 apps/workers/workers/webhookWorker.ts 中看到——投递请求时携带Authorization: Bearer ${webhookToken}请求头。请求体Webhook 以 JSON 格式携带任务 ID用于幂等、书签 ID、书签类型、用户 ID、URL 与操作类型{ jobId: 123, type: link, bookmarkId: exampleBookmarkId, userId: exampleUserId, url: https://example.com, operation: crawled }接收方应利用jobId做去重保证重试投递不会造成重复处理。八、SMTP 配置邮箱验证等邮件功能Karakeep 可通过 SMTP 发送各类邮件如注册时的邮箱验证。启用邮件功能必须配置以下变量变量名必填默认值说明SMTP_HOST否未设置SMTP 服务器主机名或 IP。启用邮件功能时必填SMTP_PORT否587SMTP 端口。常用值587STARTTLS、465SSL/TLS、25不加密SMTP_SECURE否false是否使用 SSL/TLS。端口 465 设true端口 587 配 STARTTLS 设falseSMTP_USER否未设置SMTP 认证用户名通常是你的邮箱地址SMTP_PASSWORD否未设置SMTP 认证密码。Gmail 等服务请使用应用专用密码SMTP_FROM否未设置发件人地址将显示在邮件发件人字段如前文所述EMAIL_VERIFICATION_REQUIREDtrue会强制要求 SMTP 已配置否则启动失败校验逻辑见 packages/shared/config.ts。九、代理配置出站请求的代理与内网白名单当 Karakeep 实例需要经由代理服务器出网时配置以下变量。这些代理设置会被爬虫及其他发起出站 HTTP 请求的组件使用。变量名必填默认值说明CRAWLER_HTTP_PROXY否未设置出站 HTTP 请求的代理 URL如http://proxy.example.com:8080。可传多个逗号分隔的代理使用时随机挑选。用于爬取、RSS 订阅拉取与 WebhookCRAWLER_HTTPS_PROXY否未设置出站 HTTPS 请求的代理 URL规则同上CRAWLER_NO_PROXY否未设置绕过代理的主机名/IP 列表逗号分隔如localhost,127.0.0.1,.localCRAWLER_ALLOWED_INTERNAL_HOSTNAMES否未设置默认情况下 Karakeep 会拦截 DNS 解析到私网、回环、链路本地或 Tailscale CGNAT 地址的 Worker 出站请求。用此变量白名单化特定主机名如internal.company.com、app-name.local以点前缀支持域通配如.internal.company.com、.tailnet-name.ts.net传.放行所有域名。注意URL 配置了代理时内部 IP 校验会被绕过本地 DNS 解析器与代理所用不一定一致源码中这些变量均被解析为数组split(,)后 trim 过滤空项因此多个代理随机挑选与逗号分隔白名单的实现是确定的见 packages/shared/config.ts。十、监控OpenTelemetry 分布式追踪与 Prometheus 指标Karakeep 支持通过 OpenTelemetry 进行分布式追踪启用后tRPC API 调用、后台 Worker 操作及其他关键工作流都会收集 trace。同时它也导出基于 Prometheus 的指标。变量名必填默认值说明OTEL_TRACING_ENABLED否false设为true启用 OpenTelemetry 追踪。关闭时所有追踪操作均为 no-opOTEL_EXPORTER_OTLP_ENDPOINT否未设置发送 trace 的 OTLP HTTP 端点如http://jaeger:4318/v1/traces或http://otel-collector:4318/v1/traces。未设置时 trace 输出到控制台OTEL_SERVICE_NAME否karakeep追踪后端显示的服务名实际名称会带后缀如karakeep-api、karakeep-workersOTEL_SAMPLE_RATE否1.0trace 采样率取值 0.0–1.0。1.0全量采样0.1仅采样 10%。生产环境降低采样率可减少开销与存储成本PROMETHEUS_AUTH_TOKEN否随机生成在/api/metrics启用 Prometheus 指标端点请求需在 Authorization 头携带该 token 作为 Bearer token。未设置时每次启动随机生成。token 不能含特殊字符否则可能收到 400 Bad Request两个补充说明其一OTEL_SAMPLE_RATE在源码中通过z.coerce.number().min(0).max(1)强制限定在 0–1 区间越界配置会在启动时报错见 packages/shared/config.ts其二PROMETHEUS_AUTH_TOKEN未设置时源码用crypto.randomBytes(64).toString(hex)生成随机 token见 packages/shared/config.ts这意味着未设置即有保护——但重启后 token 会变化需要稳定采集时请显式配置。另外 v0.31.0 文档的监控节未提及事件日志当前主分支已扩展出EVENT_LOGS_ENABLED、OTEL_EVENT_LOGS_EXPORT_ENABLED、OTEL_EXPORTER_OTLP_LOGS_ENDPOINT等结构化事件日志变量见 packages/shared/config.ts升级后可按需启用。十一、配置实战清单从默认跑到生产可用综合以上十类配置给出一个从开发到生产的清单式建议必填三项DATA_DIR持久化目录、NEXTAUTH_URL公网地址、NEXTAUTH_SECRETopenssl rand -base64 36生成。缺一不可NEXTAUTH_SECRET缺失时signingSecret()会在运行期直接抛错见 packages/shared/config.ts。搜索设置MEILI_ADDR生产环境补MEILI_MASTER_KEY索引量大时调高SEARCH_NUM_WORKERS、SEARCH_JOB_TIMEOUT_SEC。AI 能力至少设置OPENAI_API_KEY或OLLAMA_BASE_URL之一Ollama 用户务必同步修改INFERENCE_TEXT_MODEL/INFERENCE_IMAGE_MODEL并根据显卡实力调整INFERENCE_JOB_TIMEOUT_SEC、INFERENCE_FETCH_TIMEOUT_SEC。数据库性能DB_WAL_MODEtrue非网络盘时。生产收敛LOG_LEVELwarning或notice、DISABLE_NEW_RELEASE_CHECKtrue、RATE_LIMITING_ENABLEDtrue可选。安全需要登录态抓取时配置BROWSER_COOKIE_PATH需要出站代理时配置CRAWLER_HTTP_PROXY/CRAWLER_HTTPS_PROXY/CRAWLER_NO_PROXY并留意CRAWLER_ALLOWED_INTERNAL_HOSTNAMES的内网拦截行为。存储规划无论选本地目录还是 S3部署前定下ASSETS_DIR或ASSET_STORE_S3_*因为后端切换需要手动迁移资产。监控开启OTEL_TRACING_ENABLED并配置OTEL_EXPORTER_OTLP_ENDPOINT用OTEL_SAMPLE_RATE控制成本固定PROMETHEUS_AUTH_TOKEN便于稳定采集/api/metrics。由于所有变量都在 packages/shared/config.ts 中统一声明与校验配置完成后可用docker compose config检查渲染结果或直接启动观察日志——任何拼写错误或非法取值都会在启动阶段被 Zod schema 拦截并给出明确报错这是 Karakeep 配置体系最友好的设计之一。【免费下载链接】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（原 hoarder）环境变量配置完全指南：从部署到生产调优的 100+ 参数详解
Karakeep原 hoarder环境变量配置完全指南从部署到生产调优的 100 参数详解【免费下载链接】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.31.0 官方配置文档为核心骨架逐类拆解服务端、存储、认证、AI 推理、爬虫、OCR、Webhook、SMTP、代理与监控的 100 个环境变量每个变量都给出默认值、必填性、取值范围与实战建议并辅以当前仓库源码packages/shared/config.ts、apps/workers/index.ts、docker/docker-compose.yml佐证其底层实现帮助你完成从能跑到生产可用的配置进阶。Karakeep 架构图Karakeep 的架构以 Web 服务web与一组后台 Worker 为核心Web 服务负责用户界面与 APIWorker 负责抓取、索引、推理、Webhook 投递等异步任务二者通过队列如 Redis解耦共同读写 SQLite 数据库、Meilisearch 搜索索引并调用无头浏览器与 AI 推理服务。理解这张架构图后你会更容易理解为什么哪类变量需要配置在哪个进程上——例如 OAuth 相关变量必须传给web容器而爬虫与浏览器相关变量则作用于 Worker 进程。一、核心服务配置所有环境变量的统一入口Karakeep 的应用配置几乎全部由环境变量驱动。所有被使用的环境变量统一定义并解析于 packages/shared/config.ts该文件使用 Zod schema 对process.env做启动时校验与类型转换布尔值统一要求true/false字符串数字通过z.coerce.number()强转任何非法取值都会在启动阶段直接报错而不是运行到一半才暴露问题。这意味着环境变量拼写错误是最常见的启动失败原因排查时请优先核对变量名。下表是 v0.31.0 文档列出的最重要变量当前主分支源码中的默认值可能已演进下文标注处会提示变量名必填默认值说明PORT否3000Web 服务器监听端口。使用 Docker 时不要修改此值应改 Docker 映射的外部端口见 docker/docker-compose.yml 中ports: - 3000:3000的左侧值WORKERS_PORT否0随机端口Worker 导出 Prometheus 指标/metrics的端口。需要采集指标时请固定该值并在 Docker 中导出对应端口WORKERS_HOST否127.0.0.1Worker 指标端口绑定的主机。容器化部署时必须显式设置如0.0.0.0否则外部无法访问localhostWORKERS_ENABLED_WORKERS否未设置逗号分隔的启用的 Worker 名称列表设置后只运行这些 Worker。v0.31.0 合法值crawler,inference,search,adminMaintenance,video,feed,assetPreprocessing,webhook,ruleEngineWORKERS_DISABLED_WORKERS否未设置逗号分隔的禁用的 Worker 名称列表优先级高于WORKERS_ENABLED_WORKERSLOG_LEVEL否debug应用日志级别遵循 winston 日志级别定义。生产环境建议设为notice或warning以降低日志噪音DATA_DIR是未设置持久化数据目录数据库存放在此。未设置ASSETS_DIR时资产默认也存放在此目录下ASSETS_DIR否未设置抓取资产的存放路径。未设置时默认为${DATA_DIR}/assets源码见 packages/shared/config.tsNEXTAUTH_URL是未设置指向你的服务器地址。缺少它应用仍能运行但登出等场景会重定向到错误地址NEXTAUTH_SECRET是未设置用于签名 JWT 的随机字符串。生成命令openssl rand -base64 36MEILI_ADDR否未设置Meilisearch 地址如http://meilisearch:7700。未设置则全文搜索被禁用MEILI_MASTER_KEY生产环境开启搜索时必填未设置Meilisearch 主密钥开发环境不需要。生成命令openssl rand -base64 36 \| tr -dc A-Za-z0-9MAX_ASSET_SIZE_MB否50允许上传的单个资产最大体积MBDISABLE_NEW_RELEASE_CHECK否false设为true时禁用管理面板中的最新版本检查RATE_LIMITING_ENABLED否false设为true时启用 API 限流CRAWLER_DOMAIN_RATE_LIMIT_WINDOW_MS否未设置爬虫按域名限流的时间窗口毫秒CRAWLER_DOMAIN_RATE_LIMIT_MAX_REQUESTS否未设置窗口内每个域名允许的最大爬虫请求数DB_WAL_MODE否false为 SQLite 启用 WAL 模式可显著提升数据库性能。除非数据库位于网络挂载盘上否则建议设为true官方计划未来将其设为默认SEARCH_NUM_WORKERS否1搜索索引任务的并发 Worker 数。索引内容量大时可调高SEARCH_JOB_TIMEOUT_SEC否30搜索索引任务超时时间秒。大型书签内容索引较慢时可调高WEBHOOK_NUM_WORKERS否1Webhook 投递的并发 Worker 数。多 Webhook 端点或高流量时调高ASSET_PREPROCESSING_NUM_WORKERS否1资产预处理图片处理、OCR 等的并发 Worker 数ASSET_PREPROCESSING_JOB_TIMEOUT_SEC否60资产预处理任务超时时间秒。大图片或大 PDF 处理慢时可调高RULE_ENGINE_NUM_WORKERS否1规则引擎处理任务的并发 Worker 数。自动化规则复杂时可调高MAX_RSS_FEEDS_PER_USER否1000单个用户可创建的 RSS 订阅源数量上限MAX_WEBHOOKS_PER_USER否100单个用户可创建的 Webhook 数量上限Worker 启停的源码级原理WORKERS_ENABLED_WORKERS/WORKERS_DISABLED_WORKERS两个变量的实际生效逻辑位于 apps/workers/index.ts启动时分别构建enabledWorkers与disabledWorkers两个 SetisWorkerEnabled()先判断启用了白名单但当前 Worker 不在其中则返回false再判断在禁用名单中则返回false其余 Worker 才被构建并启动。disabled名单优先于enabled名单与文档描述一致。另外需要注意v0.31.0 文档列出的合法 Worker 名只有 9 个而当前主分支源码中的workerBuilders见 apps/workers/index.ts已经扩展到 12 个新增了lowPriorityCrawler、embeddings、backup且importWorker 独立于该名单之外由isWorkerEnabled(import)单独控制。如果你从旧版本升级务必核对新版本支持的 Worker 名称。Docker 部署中的落地示例在 Docker 部署下Web 容器统一加载.env文件并注入关键连接信息见 docker/docker-compose.ymlservices: web: image: ghcr.io/karakeep-app/karakeep:${KARAKEEP_VERSION:-release} restart: unless-stopped volumes: - data:/data ports: - 3000:3000 env_file: - .env environment: MEILI_ADDR: http://meilisearch:7700 BROWSER_WEB_URL: http://chrome:9222 # OPENAI_API_KEY: ... # 几乎不需要修改 DATA_DIR要改存储位置请改上面的 volume 映射 DATA_DIR: /data # DONT CHANGE THIS chrome: image: ghcr.io/karakeep-app/karakeep-chrome:release restart: unless-stopped init: true meilisearch: image: getmeili/meilisearch:v1.41.0 restart: unless-stopped env_file: - .env environment: MEILI_NO_ANALYTICS: true volumes: - meilisearch:/meili_data这份示例传达出三个关键实践一是DATA_DIR在容器内固定为/data持久化位置通过 volume 映射决定二是MEILI_ADDR、BROWSER_WEB_URL使用容器间服务名而非 IP三是敏感密钥如OPENAI_API_KEY、NEXTAUTH_SECRET统一放入.env通过env_file注入避免硬编码进 compose 文件。二、资产存储本地文件系统与 S3 兼容对象存储Karakeep 支持两种资产存储后端本地文件系统默认与 S3 兼容对象存储。S3 后端会在传入 S3 endpoint 时自动启用——源码中通过ASSET_STORE_S3_ENDPOINT是否存在来决定存储类型见 packages/shared/config.ts变量名必填默认值说明ASSET_STORE_S3_ENDPOINT否未设置S3 endpoint URL接入 MinIO 等 S3 兼容服务时必填。设置该项即启用 S3 存储ASSET_STORE_S3_REGION否未设置S3 区域ASSET_STORE_S3_BUCKET使用 S3 时必填未设置存储资产的 bucket 名称ASSET_STORE_S3_ACCESS_KEY_ID使用 S3 时必填未设置访问密钥 IDASSET_STORE_S3_SECRET_ACCESS_KEY使用 S3 时必填未设置访问密钥ASSET_STORE_S3_FORCE_PATH_STYLE否false是否强制使用 path-style URL。MinIO 等 S3 兼容服务需设为true使用 S3 存储时有两条官方提示需要特别注意确保 bucket 已存在且凭据具备对 bucket 内对象的读、写、删除权限切换存储后端后需手动迁移已有资产本地文件不会自动搬移到 S3。部署前务必规划好存储方案避免上线后迁移的麻烦。此外资产体积上限由第一节的MAX_ASSET_SIZE_MB默认 50控制而HTML_CONTENT_SIZE_INLINE_THRESHOLD_BYTES默认5 * 1024决定超过多少字节的 HTML 内容将存入 assetdb目录或 S3而非内联进数据库——这对控制 SQLite 体积有实际意义。三、认证与注册数据库账号、OIDC OAuth 与注册策略默认情况下 Karakeep 使用数据库存储用户账号同时支持接入 OIDC 兼容的 OAuth 提供方。所有认证相关变量必须传给web容器。配置 OAuth 时提供方侧允许的回调地址应设为KARAKEEP_ADDRESS/api/auth/callback/custom其中KARAKEEP_ADDRESS即NEXTAUTH_URL中配置的地址例如https://try.karakeep.app/api/auth/callback/custom。变量名必填默认值说明DISABLE_SIGNUPS否false启用后禁止新用户注册UI 上的注册按钮同时被禁用DISABLE_PASSWORD_AUTH否false启用后仅允许通过 OAuth 注册/登录本地账号的注册按钮与登录表单在 UI 中被禁用EMAIL_VERIFICATION_REQUIRED否false注册时是否强制邮箱验证。启用后用户必须验证邮箱才能使用账号且必须同时配置 SMTPOAUTH_AUTO_REDIRECT否false当密码认证被禁用时自动重定向到 OAuth 提供方而非展示登录页。适合 OAuth 是唯一认证方式的情形OAUTH_WELLKNOWN_URL否未设置提供方提供的 OpenID Configurationwell-known URLOAUTH_CLIENT_SECRET否未设置提供方签发的 Client SecretOAUTH_CLIENT_ID否未设置提供方签发的 Client IDOAUTH_SCOPE否openid email profile请求的 scope 列表空格分隔OAUTH_PROVIDER_NAME否Custom Provider提供方名称注册页会显示为 Sign in withnameOAUTH_ALLOW_DANGEROUS_EMAIL_ACCOUNT_LINKING否false是否自动将数据库中已有的同名邮箱账号与 OAuth 账号关联。仅在信任该 OAuth 提供方时启用OAUTH_TIMEOUT否3500等待 OAuth 提供方响应的毫秒数。遇到outgoing request timed out错误时调大两个值得深入说明的点1. 配置项的交叉校验。EMAIL_VERIFICATION_REQUIREDtrue而 SMTP 未配置时启动会直接失败——这是 packages/shared/config.ts 中 Zod schema 显式抛出的致命错误To enable email verification, SMTP settings must be configured。同理OAUTH_TIMEOUT默认 3500 毫秒在慢速提供方下可能不够调大它是最常见的 OAuth 故障修复手段。2. 旧版兼容与升级注意。v0.31.0 文档未收录OAUTH_ID_TOKEN_SIGNED_RESPONSE_ALG但当前主分支源码packages/shared/config.ts已支持通过它指定 ID Token 的 JWS 签名算法取值RS256/RS384/RS512/PS256/PS384/PS512/ES256/ES384/ES512/EdDSA。当提供方用非默认算法签名 ID Token 时OAuth 回调会以 unexpected JWT algorithm 失败此时就需要显式设置该变量。四、AI 推理配置自动打标签与自动摘要OPENAI_API_KEY与OLLAMA_BASE_URL至少设置其一自动打标签才会启用否则自动打标签会被跳过。源码中对应的判断为inference.isConfigured !!OPENAI_API_KEY || !!OLLAMA_BASE_URL见 packages/shared/config.ts。官方对推理配置给出两条警告标签质量取决于所选模型的质量建议调大INFERENCE_CONTEXT_LENGTH默认值偏小。值越大标签质量越高但推理成本越高OpenAI 侧花钱、Ollama 侧耗资源。变量名必填默认值说明OPENAI_API_KEY否未设置用于自动打标签的 OpenAI 密钥更多说明见 docs/docs/06-administration/03-openai.mdOPENAI_BASE_URL否未设置仅用 OpenAI 官方 API 时无需设置使用 Azure OpenAI 等兼容 API 时设为对应地址OPENAI_PROXY_URL否未设置OpenAI API 请求的 HTTP 代理如http://proxy.example.com:8080OPENAI_SERVICE_TIER否未设置auto、default或flex。flex 以更慢响应和偶发资源不可用换取更低成本OLLAMA_BASE_URL否未设置使用 Ollama 本地推理时填写 Ollama API 地址OLLAMA_KEEP_ALIVE否未设置请求后模型在内存中驻留时长5m表示 5 分钟-1m表示常驻内存0表示处理完立即卸载INFERENCE_TEXT_MODEL否gpt-4.1-miniv0.31.0文本推理模型。使用 Ollama 时必须更换当前主分支源码默认值已更新为gpt-5.6-luna见 packages/shared/config.tsINFERENCE_IMAGE_MODEL否gpt-4o-mini图片推理模型。Ollama 需要支持视觉 API 的模型如 llavaEMBEDDING_TEXT_MODEL否text-embedding-3-small生成文本 embedding 的模型INFERENCE_CONTEXT_LENGTH否2048传给推理模型的最大 token 数超出部分被截断。值越大参与打标签的内容越多成本也越高请对照所用模型的最大上下文INFERENCE_MAX_OUTPUT_TOKENS否2048推理模型允许生成的最大 token 数控制标签、摘要等 AI 内容的长度。需要更长输出时可调大但会提高成本与耗时INFERENCE_USE_MAX_COMPLETION_TOKENS否false[仅 OpenAI] 是否使用新的max_completion_tokens参数替代废弃的max_tokens。使用 GPT-5 或 o 系列模型时设为true未来版本将默认开启INFERENCE_LANG否english生成标签的语言INFERENCE_NUM_WORKERS否1AI 推理任务打标签与摘要的并发 Worker 数需要并行处理时可调高INFERENCE_ENABLE_AUTO_TAGGING否true是否启用自动 AI 打标签INFERENCE_ENABLE_AUTO_SUMMARIZATION否false是否启用自动 AI 摘要INFERENCE_JOB_TIMEOUT_SEC否30推理任务超时秒数。Ollama 无强力 GPU 时建议调大INFERENCE_FETCH_TIMEOUT_SEC否300[仅 Ollama] 请求 Ollama 服务器的 fetch 超时秒数。推理请求超过默认 5 分钟时调大INFERENCE_SUPPORTS_STRUCTURED_OUTPUT否未设置[已弃用] 模型是否支持结构化输出。true等价于INFERENCE_OUTPUT_SCHEMAstructuredfalse等价于plain请改用INFERENCE_OUTPUT_SCHEMAINFERENCE_OUTPUT_SCHEMA否structured取值structured、json、plain。首选structured模型不支持时若支持 JSON 模式用json否则用plain所有模型都支持但输出格式可能不规范自定义打标签提示词你可以在User Settings界面的AI Settings中为自动打标签追加额外指令并可使用三个占位符$tags全部标签$aiTagsAI 生成的标签$userTags人工创建的标签这些占位符在执行自动打标签时会被替换为实际标签列表例如[karakeep, computer, ai]。这为针对特定领域微调标签风格提供了无需改代码的入口。五、爬虫配置无头浏览器、截图、PDF 与整页归档爬虫是 Karakeep 的核心能力之一其行为高度可调。默认只允许 1 个并发抓取任务以避免资源占用过高。变量名必填默认值说明CRAWLER_NUM_WORKERS否1允许的并发抓取任务数BROWSER_WEB_URL否未设置浏览器的 HTTP 调试地址。Worker 通过它解析调试控制台的 WebSocket 地址已有 WebSocket 地址时直接用BROWSER_WEBSOCKET_URL。两者都未设置时Worker 退化为纯 HTTP 请求跳过截图与 JavaScript 执行BROWSER_WEBSOCKET_URL否未设置浏览器调试控制台的 WebSocket 地址使用 browserless 时填其 WebSocket 地址BROWSER_CONNECT_ONDEMAND否false为false时爬虫主动连接浏览器并保持长连接为true时仅在需要抓取时按需启动浏览器。使用按需提供浏览器实例的服务时设为trueCRAWLER_DOWNLOAD_BANNER_IMAGE否true是否将卡片横幅图缓存到本地。缓存更抗链接失效与站点限流但占用更多存储CRAWLER_STORE_SCREENSHOT否true是否保存抓取网站的截图。截图可作为无法从网站提取图片时的兜底也可随时查看CRAWLER_FULL_PAGE_SCREENSHOT否false是否保存整页截图。默认关闭磁盘占用高关闭时只截取可见区域CRAWLER_SCREENSHOT_TIMEOUT_SEC否5截图超时秒数。长网页整页截图可考虑调大CRAWLER_STORE_PDF否false是否保存抓取页面的 PDF 快照。默认关闭磁盘占用高开启后每个页面生成 PDF 资产可在书签预览中查看CRAWLER_FULL_PAGE_ARCHIVE否false是否保存页面完整本地副本。默认关闭磁盘占用高关闭时只归档页面可读文本CRAWLER_JOB_TIMEOUT_SEC否60抓取任务总超时秒数。网速慢或设备性能低时可调大CRAWLER_NAVIGATE_TIMEOUT_SEC否30页面导航含重定向超时秒数。网速慢时调大CRAWLER_PARSE_TIMEOUT_SEC否60HTML 解析子进程元数据提取 readability超时秒数CRAWLER_PARSER_MEM_LIMIT_MB否512HTML 解析子进程的最大堆内存MB。大页面解析 OOM 时调大子进程隔离OOM 不会拖垮主 WorkerCRAWLER_VIDEO_DOWNLOAD否false是否使用 yt-dlp 下载页面视频CRAWLER_VIDEO_DOWNLOAD_MAX_SIZE否50下载视频的最大体积MB质量会相应调整。-1表示不限制CRAWLER_VIDEO_DOWNLOAD_TIMEOUT_SEC否600视频下载超时秒数CRAWLER_ENABLE_ADBLOCKER否true爬虫是否启用广告拦截。Worker 启动时下载广告拦截列表遇到困难可关闭CRAWLER_YTDLP_ARGS否[]抓取时传递给 yt-dlp 的额外参数用%%分隔多个参数BROWSER_COOKIE_PATH否未设置指向一个包含待加载进浏览器上下文的 cookies 的 JSON 文件路径HTML_CONTENT_SIZE_INLINE_THRESHOLD_BYTES否5 * 1024超过该字节数的较大资产存入 assetdb目录/S3而非内联进数据库BROWSER_COOKIE_PATH 详解BROWSER_COOKIE_PATH指向的 JSON 文件必须是一个 cookie 对象数组每个对象包含namecookie 名必填valuecookie 值必填可选字段domain、path、expires、httpOnly、secure、sameSite取值Strict、Lax或None示例文件内容[ { name: session, value: xxx, domain: .example.com, path: /, expires: 1735689600, httpOnly: true, secure: true, sameSite: Lax } ]该功能在抓取需要登录态或会话 cookie 的站点如内部系统、付费墙内容时非常实用。六、OCR 配置Tesseract 与 LLM 双引擎Karakeep 默认使用 tesseract.js 从图片中提取文本也可启用OCR_USE_LLM切换为 LLM 驱动的 OCR——后者复用已配置的推理模型OpenAI 或 Ollama对复杂图片效果更好但要求已配置推理提供方未配置推理提供方时自动回退到 Tesseract。变量名必填默认值说明OCR_CACHE_DIR否$TEMP_DIRTesseract 下载模型的目录。默认模型不持久化存放于系统临时目录OCR_LANGS否eng逗号分隔的 Tesseract 支持语言代码列表。设为空字符串可禁用 OCROCR_CONFIDENCE_THRESHOLD否500–100 之间的最低置信度阈值Tesseract 置信度低于该值时识别文本不存储OCR_USE_LLM否false设为true时用已配置的推理模型替代 Tesseract 做 OCR复杂图片效果更好七、Webhook 配置事件驱动的自动化出口Webhook 用于在书签被创建、变更或抓取完成时触发外部动作。除下面的超时与重试参数外鉴权与请求体格式也值得关注变量名必填默认值说明WEBHOOK_TIMEOUT_SEC否5Webhook 请求超时秒数WEBHOOK_RETRY_TIMES否3Webhook 请求重试次数鉴权方式WEBHOOK_TOKEN用于认证会以 Bearer token 形式出现在 Authorization 请求头Authorization: Bearer WEBHOOK_TOKEN该实现可在 apps/workers/workers/webhookWorker.ts 中看到——投递请求时携带Authorization: Bearer ${webhookToken}请求头。请求体Webhook 以 JSON 格式携带任务 ID用于幂等、书签 ID、书签类型、用户 ID、URL 与操作类型{ jobId: 123, type: link, bookmarkId: exampleBookmarkId, userId: exampleUserId, url: https://example.com, operation: crawled }接收方应利用jobId做去重保证重试投递不会造成重复处理。八、SMTP 配置邮箱验证等邮件功能Karakeep 可通过 SMTP 发送各类邮件如注册时的邮箱验证。启用邮件功能必须配置以下变量变量名必填默认值说明SMTP_HOST否未设置SMTP 服务器主机名或 IP。启用邮件功能时必填SMTP_PORT否587SMTP 端口。常用值587STARTTLS、465SSL/TLS、25不加密SMTP_SECURE否false是否使用 SSL/TLS。端口 465 设true端口 587 配 STARTTLS 设falseSMTP_USER否未设置SMTP 认证用户名通常是你的邮箱地址SMTP_PASSWORD否未设置SMTP 认证密码。Gmail 等服务请使用应用专用密码SMTP_FROM否未设置发件人地址将显示在邮件发件人字段如前文所述EMAIL_VERIFICATION_REQUIREDtrue会强制要求 SMTP 已配置否则启动失败校验逻辑见 packages/shared/config.ts。九、代理配置出站请求的代理与内网白名单当 Karakeep 实例需要经由代理服务器出网时配置以下变量。这些代理设置会被爬虫及其他发起出站 HTTP 请求的组件使用。变量名必填默认值说明CRAWLER_HTTP_PROXY否未设置出站 HTTP 请求的代理 URL如http://proxy.example.com:8080。可传多个逗号分隔的代理使用时随机挑选。用于爬取、RSS 订阅拉取与 WebhookCRAWLER_HTTPS_PROXY否未设置出站 HTTPS 请求的代理 URL规则同上CRAWLER_NO_PROXY否未设置绕过代理的主机名/IP 列表逗号分隔如localhost,127.0.0.1,.localCRAWLER_ALLOWED_INTERNAL_HOSTNAMES否未设置默认情况下 Karakeep 会拦截 DNS 解析到私网、回环、链路本地或 Tailscale CGNAT 地址的 Worker 出站请求。用此变量白名单化特定主机名如internal.company.com、app-name.local以点前缀支持域通配如.internal.company.com、.tailnet-name.ts.net传.放行所有域名。注意URL 配置了代理时内部 IP 校验会被绕过本地 DNS 解析器与代理所用不一定一致源码中这些变量均被解析为数组split(,)后 trim 过滤空项因此多个代理随机挑选与逗号分隔白名单的实现是确定的见 packages/shared/config.ts。十、监控OpenTelemetry 分布式追踪与 Prometheus 指标Karakeep 支持通过 OpenTelemetry 进行分布式追踪启用后tRPC API 调用、后台 Worker 操作及其他关键工作流都会收集 trace。同时它也导出基于 Prometheus 的指标。变量名必填默认值说明OTEL_TRACING_ENABLED否false设为true启用 OpenTelemetry 追踪。关闭时所有追踪操作均为 no-opOTEL_EXPORTER_OTLP_ENDPOINT否未设置发送 trace 的 OTLP HTTP 端点如http://jaeger:4318/v1/traces或http://otel-collector:4318/v1/traces。未设置时 trace 输出到控制台OTEL_SERVICE_NAME否karakeep追踪后端显示的服务名实际名称会带后缀如karakeep-api、karakeep-workersOTEL_SAMPLE_RATE否1.0trace 采样率取值 0.0–1.0。1.0全量采样0.1仅采样 10%。生产环境降低采样率可减少开销与存储成本PROMETHEUS_AUTH_TOKEN否随机生成在/api/metrics启用 Prometheus 指标端点请求需在 Authorization 头携带该 token 作为 Bearer token。未设置时每次启动随机生成。token 不能含特殊字符否则可能收到 400 Bad Request两个补充说明其一OTEL_SAMPLE_RATE在源码中通过z.coerce.number().min(0).max(1)强制限定在 0–1 区间越界配置会在启动时报错见 packages/shared/config.ts其二PROMETHEUS_AUTH_TOKEN未设置时源码用crypto.randomBytes(64).toString(hex)生成随机 token见 packages/shared/config.ts这意味着未设置即有保护——但重启后 token 会变化需要稳定采集时请显式配置。另外 v0.31.0 文档的监控节未提及事件日志当前主分支已扩展出EVENT_LOGS_ENABLED、OTEL_EVENT_LOGS_EXPORT_ENABLED、OTEL_EXPORTER_OTLP_LOGS_ENDPOINT等结构化事件日志变量见 packages/shared/config.ts升级后可按需启用。十一、配置实战清单从默认跑到生产可用综合以上十类配置给出一个从开发到生产的清单式建议必填三项DATA_DIR持久化目录、NEXTAUTH_URL公网地址、NEXTAUTH_SECRETopenssl rand -base64 36生成。缺一不可NEXTAUTH_SECRET缺失时signingSecret()会在运行期直接抛错见 packages/shared/config.ts。搜索设置MEILI_ADDR生产环境补MEILI_MASTER_KEY索引量大时调高SEARCH_NUM_WORKERS、SEARCH_JOB_TIMEOUT_SEC。AI 能力至少设置OPENAI_API_KEY或OLLAMA_BASE_URL之一Ollama 用户务必同步修改INFERENCE_TEXT_MODEL/INFERENCE_IMAGE_MODEL并根据显卡实力调整INFERENCE_JOB_TIMEOUT_SEC、INFERENCE_FETCH_TIMEOUT_SEC。数据库性能DB_WAL_MODEtrue非网络盘时。生产收敛LOG_LEVELwarning或notice、DISABLE_NEW_RELEASE_CHECKtrue、RATE_LIMITING_ENABLEDtrue可选。安全需要登录态抓取时配置BROWSER_COOKIE_PATH需要出站代理时配置CRAWLER_HTTP_PROXY/CRAWLER_HTTPS_PROXY/CRAWLER_NO_PROXY并留意CRAWLER_ALLOWED_INTERNAL_HOSTNAMES的内网拦截行为。存储规划无论选本地目录还是 S3部署前定下ASSETS_DIR或ASSET_STORE_S3_*因为后端切换需要手动迁移资产。监控开启OTEL_TRACING_ENABLED并配置OTEL_EXPORTER_OTLP_ENDPOINT用OTEL_SAMPLE_RATE控制成本固定PROMETHEUS_AUTH_TOKEN便于稳定采集/api/metrics。由于所有变量都在 packages/shared/config.ts 中统一声明与校验配置完成后可用docker compose config检查渲染结果或直接启动观察日志——任何拼写错误或非法取值都会在启动阶段被 Zod schema 拦截并给出明确报错这是 Karakeep 配置体系最友好的设计之一。【免费下载链接】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），仅供参考