HitKeep 2.15.1 配置参数详解

目标：把 HitKeep v2.15.1 的 100 个配置项一次讲透——查看方式、四层修改途径与优先级、17 个分组的逐项含义与默认值、生产模板与高频坑位。全部内容基于 v2.15.1 容器与二进制的真实实测，配合官方配置参考交叉核对。

一、环境信息

本文实测环境与证据来源：

• 版本基线：v2.15.1（容器 ghcr.io/hitkeep/hitkeep:2.15.1，与从镜像提取的 linux-amd64 二进制一致）
• 旗标全集证据：hitkeep --help 全量输出 100 个旗标（实测捕获 101 行 usage 文本）
• YAML 全集证据：hitkeep config init 生成的配置模板（实测 11276 字节、权限 0600），与仓库 hitkeep.example.yaml 逐项一致：76 个可见键 + 24 个注释占位的敏感键 = 100 项
• 分组证据：模板按 17 个分组组织（general/data/custom-tracking/spam-filtering/backups/s3/clustering/oauth/mcp/ai/webhooks/search-console/social-sign-in/email/rate-limits/trusted-proxies/internals）
• 环境变量等价证据：HITKEEP_HTTP_ADDR=:9090 启动实测（见 3.2）；部署栈实测 HITKEEP_PUBLIC_URL、HITKEEP_BACKUP_PATH、HITKEEP_MCP_ENABLED 均在启动日志的 PublicURL/BackupPath/MCPEnabled 字段生效
• 官方口径来源：https://hitkeep.com/reference/configuration/ 与二进制安装指南（查询日期 2026-11-01）

二、前置条件

• 一份可运行的 HitKeep v2.15.1（容器 docker exec 进容器执行，或宿主二进制；注意二进制基线为 Ubuntu 22.04 构建、glibc 2.35+，老系统请用容器）；
• 了解自己的部署形态：容器部署以环境变量为主，原生部署可选 YAML/旗标；
• 生产环境准备好 openssl（生成 jwt-secret）与备份目标。

三、参数查看与修改方式

3.1 查看全量参数：两条互补路径

路径一：--help 旗标清单（注意怪癖：usage 走 stderr，且打印后不会退出、会继续启动服务，务必配合超时或后台捕获）：

hitkeep --help 2> usage.txt &
sleep 1 && kill %1

实测得到 100 个旗标及默认值，例如（节选）：

      --http-addr string                             HTTP listen address (default ":8080")
      --log-level string                             Log level (debug/info/warn/error) (default "info")
      --data-retention-days int                      Default data retention in days (default 365)
      --bind-addr string                             Address for cluster gossip (default "0.0.0.0:7946")

路径二：config init 生成带注释的 YAML 模板（推荐，含每个参数的类型与默认值注释）：

hitkeep config init --output /wk/hitkeep.yaml

实测回显：

Created configuration file /wk/hitkeep.yaml

ls -l /wk/hitkeep.yaml

-rw------- 1 root root 11276 Nov  1 04:26 /wk/hitkeep.yaml

模板内容即官方 hitkeep.example.yaml 同款，按 17 组组织，形如：

# general settings
# HTTP listen address (type: string; default: ":8080")
http-addr: ":8080"
# Log level (debug/info/warn/error) (type: string; default: "info")
log-level: "info"
# Secret key for JWT (type: string; default: "unset"; sensitive; derived)
# jwt-secret:

3.2 修改途径与优先级（附实测）

四条途径按优先级从高到低：命令行旗标 > 非空环境变量 > YAML 配置文件 > 默认值。官方二进制指南原文："Flags and non-empty environment variables still override file values."

环境变量命名规则：HITKEEP_ + 旗标名大写、- 换 _（如 http-addr → HITKEEP_HTTP_ADDR）。覆盖实测——在容器内以 HITKEEP_HTTP_ADDR=:9090 启动临时实例，首行启动日志的配置快照：

"HTTPAddr":":9090"

对照组（不带该变量）：

"HTTPAddr":":8080"

部署栈中的等效实证：compose 注入的 HITKEEP_PUBLIC_URL=http://localhost:8128、HITKEEP_BACKUP_PATH=/var/lib/hitkeep/backups、HITKEEP_MCP_ENABLED=true 分别体现在启动日志 "PublicURL":"http://localhost:8128"、"BackupPath":"/var/lib/hitkeep/backups"、"MCPEnabled":true。

3.3 配置文件校验

YAML 写好后先校验再上线（--config 必须放在所有参数最前，官方指南明确）：

hitkeep config validate --config /wk/hitkeep.yaml

实测回显：

Configuration file /wk/hitkeep.yaml is valid

3.4 敏感参数的注释占位机制

config init 对 24 项敏感参数（jwt-secret、public-url、mail-password、全部 *-client-secret、S3 三件套等）只生成注释掉的键名，不生成值——避免模板文件本身泄密。启用时取消注释手动填值，或保持注释改用环境变量注入（推荐后者，密钥不落盘）。

四、参数总览

17 个分组、100 个配置项的分布与一句话定位：

五、核心参数分类详解

5.1 general（8 项）

5.2 data（15 项）

5.3 backups + s3（3 + 7 项）

5.4 clustering + internals（3 + 2 项）

5.5 rate-limits + trusted-proxies（8 + 1 项）

5.6 mcp + ai（6 + 11 项）

5.7 webhooks（9 项）

5.8 email + search-console + social-sign-in + custom-tracking + spam-filtering + oauth（9 + 3 + 8 + 3 + 3 + 1 项）

六、生产配置模板

形态一：YAML + 环境变量注密（原生部署推荐）——非敏感项进文件，敏感项走环境：

# general
public-url: "https://analytics.example.com"
http-addr: ":8080"
log-level: "info"

# data
data-path: "/var/lib/hitkeep/data"
archive-path: "/var/lib/hitkeep/archive"
db-path: "/var/lib/hitkeep/data/hitkeep.db"
data-retention-days: 365
duckdb-memory-limit: "2GB"

# backups（本地目录；对象存储改 s3:// 并配 s3-* 组）
backup-path: "/var/lib/hitkeep/backups"
backup-interval: 60
backup-retention: 24

# spam / mcp
spam-filter-auto-update: true
mcp-enabled: true
mcp-path: /mcp

# 安全
trusted-proxies: "10.89.0.0/16"
auth-rate-limit: 2
auth-burst: 5

# email
mail-host: "smtp.example.com"
mail-port: 587
mail-from-address: "analytics@example.com"
mail-from-name: "Analytics"

配套环境变量（systemd drop-in 或 compose 注入，文件保持 0600）：

HITKEEP_JWT_SECRET=<openssl rand -hex 32 生成>
HITKEEP_MAIL_PASSWORD=<SMTP 密码>

启动：hitkeep --config /etc/hitkeep/hitkeep.yaml（--config 必须最前）。

形态二：纯环境变量（容器部署推荐）——见部署篇 compose.yml，每个 YAML 键都有 HITKEEP_ 等价物。改完任一形态后执行 hitkeep config validate 或观察启动日志的配置快照行确认生效。

七、常见问题

1. 改了参数不生效？ 按优先级排查：旗标 > 非空环境变量 > YAML > 默认值。特别注意「非空」——空字符串环境变量不参与覆盖；容器里挂了 YAML 但没加 command: ["--config", ...] 时文件根本不会被读取，且 --config 必须放参数最前。

2. config init 生成的文件里找不到 jwt-secret 的值？ 24 项敏感参数只生成注释键名（防模板泄密），需手动取消注释填值或用环境变量注入，见 3.4。

3. DuckDB 内存上限「派生」是什么逻辑？ 按运行环境自动推导：本系列实测 15Gi 内存、6 vCPU 的宿主上容器派生 7714MiB（约为宿主一半）与 6 线程；显式 duckdb-memory-limit: "2GB" 可收紧；none 则用 DuckDB 默认的 80% 系统内存——容器里务必显式设置，防止 OOM。

4. 启动日志出现 Mailer configuration rejected 警告？ mail-host 为空时邮件子系统拒绝加载（启动日志实录该 WARN），邀请/密码重置/邮件报告不可用，统计与告警之外的其余功能不受影响。

5. 反代后面访客 IP 全是代理 IP？ trusted-proxies 没有收紧或反代未传 X-Forwarded-For。把代理网段写进 trusted-proxies（多个用逗号分隔），并确认官方 trusted-proxies 指南中的转发头配置。

6. 登录十几分钟就掉线？ auth-session-minutes 默认 15 分钟（部署篇实测会话接口 duration_seconds:900）。浏览器端勾选「记住我」走 auth-remember-me-days（30 天），或按需调大 auth-session-minutes。

7. 离线环境怎么配？ spam-filter-auto-update: false、mcp-docs-enabled: false（默认会访问 hitkeep.com 拉文档），备份用本地目录而非 s3://；DuckDB 扩展已随包内置、不会启动时联网下载。

8. 参数到底有多少个？会不会有遗漏？ 以 hitkeep --help（100 个旗标）与 config init 模板（100 个 YAML 键）互为全集校验：实测两者一一对应（无仅存在于单侧的参数）；新增参数以当次 --help 输出为准，本文口径为 v2.15.1（2026-11-01 实测）。

八、参考链接

• 官方配置参考：https://hitkeep.com/reference/configuration/
• 官方二进制安装指南（优先级与 --config 口径来源）：https://hitkeep.com/guides/installation/binary/
• 仓库配置模板：https://raw.githubusercontent.com/HitKeep/hitkeep/main/hitkeep.example.yaml
• 受信代理指南：https://hitkeep.com/guides/installation/trusted-proxies/
• 备份与恢复：https://hitkeep.com/guides/data/backups-and-restore/
• 本系列：《HitKeep 2.15.1 Docker Compose 部署指南》（环境变量实战与持久化）、《HitKeep 介绍与选型指南》（认知与选型）、《HitKeep 2.15.1 常用 CLI 命令与工具详解》（config 子命令与排障实录）