HitKeep 2.15.1 常用 CLI 命令与工具详解

目标：把 HitKeep v2.15.1 单一二进制自带的命令面讲全——版本查看、帮助怪癖、配置模板生成与校验、内置健康检查、环境变量覆盖，以及原生部署配套的 systemd 托管与升级流程。所有命令与回显均来自 v2.15.1 容器与二进制的真实实测。

一、环境信息

• 实测对象：v2.15.1（ghcr.io/hitkeep/hitkeep:2.15.1 容器 + 从镜像提取的同一 linux-amd64 二进制，158MB）
• 实测方式：容器内 docker exec 直执行（镜像为 distroless，无 shell）、ubuntu:24.04 容器内跑宿主提取的二进制、运行中的 Compose 栈（部署篇同款）
• 命令面盘点：1 个入口 hitkeep + 2 个子命令（config init / config validate）+ 100 个旗标（--help 全量捕获 101 行 usage）
• 系统基线：官方二进制基于 Ubuntu 22.04 构建，要求 glibc 2.35+（官方兼容列表：Ubuntu 22.04+、Debian 12+、Amazon Linux 2023 及其他 glibc 2.35+ 发行版）
• 查询与实测日期：2026-11-01

二、工具概览

HitKeep 把「数据库、队列、缓存、前端」全部塞进一个 Go 二进制，命令面因此非常克制：

没有独立的管理子命令（建站、看数都走仪表盘或 REST API），运维重心在「启动参数 + 健康检查 + systemd」三件事上。

三、前置条件

• 可用的 v2.15.1 运行环境：容器（docker pull ghcr.io/hitkeep/hitkeep:2.15.1）或发行二进制（GitHub Releases，linux-amd64/arm64）；
• 原生二进制方案需 glibc 2.35+ 的系统，并按官方指南创建服务用户与数据目录；
• systemd 部分需要 root 或 sudo 权限。

四、各工具详解

4.1 hitkeep --version

hitkeep --version

实测回显（ubuntu:24.04 容器内执行）：

v2.15.1

退出码 0，输出即退出，是升级后最快的「装没装对」判据（官方 Verify 流程第一条就是它）。

4.2 hitkeep --help（有怪癖，正确姿势要记）

--help 的行为与常见 CLI 不同，实测结论：

1. usage 全文走 stderr（重定向 stdout 什么都看不到）；
2. 打印 usage 后不会退出，会继续读取配置并启动服务器——不加处理会让命令「卡住」。

正确捕获姿势（后台 + 延时 kill）：

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

实测得到 101 行（1 行 Usage of hitkeep: + 100 个旗标），节选：

Usage of hitkeep:
      --ai-api-key string                            Optional explicit AI provider API key, bearer token, or gateway key; provider-native goAI env vars are preferred
      --backup-interval int                          Minutes between backups (default 60)
      --bind-addr string                             Address for cluster gossip (default "0.0.0.0:7946")
      --data-retention-days int                      Default data retention in days (default 365)
      --http-addr string                             HTTP listen address (default ":8080")
      --trusted-proxies string                       Trusted proxy CIDRs (comma-separated) or '*' to trust all (default "*")

想看「带注释的参数字典」别用 --help，用下一节的 config init。

4.3 hitkeep config init：生成配置模板

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

实测回显：

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

要点：

• 模板 11276 字节、权限自动 0600（仅属主可读，防止敏感值泄露）；
• 内容与仓库 hitkeep.example.yaml 逐项一致：76 个可见键 + 24 个注释占位的敏感键，共 100 项、17 个分组；
• 官方推荐以专用用户身份生成：sudo -u hitkeep hitkeep config init --output /var/lib/hitkeep/hitkeep.yaml。

4.4 hitkeep config validate：校验配置

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

实测回显：

Configuration file /wk/hitkeep.yaml is valid

两个纪律：--config 必须放在所有参数最前（官方指南原文），先 validate 再上线。旗标与非空环境变量的优先级仍高于文件值。

4.5 hitkeep -healthcheck：内置健康检查

镜像的 HEALTHCHECK 机制就是这条命令。对运行中的部署篇栈实测：

docker exec hitkeep-2.15.1-app hitkeep -healthcheck
echo "exit=$?"

实测回显：无输出、exit=0（进程与共享库、租户库均就绪）。非 0 即异常，可直接接进脚本化巡检。

注意：该命令面向「已有实例」的场景，对没有服务在跑的环境执行会持续等待而不退出（实验中曾以后台任务形式挂起直到超时）——单独测试时务必加超时。配套的 HTTP 探针是 GET /healthz（进程存活，实测返回 ok）与 GET /readyz（全部租户库就绪，实测 200）。

4.6 环境变量覆盖：HITKEEP_* 全集

每个旗标都有 HITKEEP_ + 大写下划线的等价环境变量。容器内覆盖实测——以 HITKEEP_HTTP_ADDR=:9090 启动临时实例，首行配置快照：

"HTTPAddr":":9090"

对照组（未设变量）：

"HTTPAddr":":8080"

常用速查：HITKEEP_PUBLIC_URL（对外地址）、HITKEEP_JWT_SECRET（密钥）、HITKEEP_BIND_ADDR（gossip 绑定）、HITKEEP_BACKUP_PATH/INTERVAL/RETENTION（备份）、HITKEEP_DUCKDB_MEMORY_LIMIT（内存上限）。全集与默认值见《HitKeep 2.15.1 配置参数详解》。

4.7 systemd 托管（原生部署标配）

以下为官方二进制指南的完整流程（本文照录并逐段说明）：

创建服务用户与数据目录：

sudo useradd -r -s /bin/false hitkeep
sudo mkdir -p /var/lib/hitkeep/data /var/lib/hitkeep/archive
sudo chown -R hitkeep:hitkeep /var/lib/hitkeep

/etc/systemd/system/hitkeep.service（官方原文）：

[Unit]
Description=HitKeep Analytics
After=network.target

[Service]
Type=simple
User=hitkeep
Group=hitkeep
WorkingDirectory=/var/lib/hitkeep

# Sensitive values via environment (not visible in ps aux).
# Generate the secret with: openssl rand -hex 32
Environment="HITKEEP_JWT_SECRET=change-this-to-a-long-random-string"
Environment="HITKEEP_MAIL_PASSWORD=your-smtp-password"

# General configuration via flags
ExecStart=/usr/local/bin/hitkeep \
  --public-url=https://analytics.example.com \
  --db-path=/var/lib/hitkeep/data/hitkeep.db \
  --data-path=/var/lib/hitkeep/data \
  --archive-path=/var/lib/hitkeep/archive \
  --http-addr=:8080

Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

更安全的密钥管理——drop-in 环境文件（官方推荐，替代 unit 内明文）：

sudo mkdir -p /etc/systemd/system/hitkeep.service.d
sudo tee /etc/systemd/system/hitkeep.service.d/secrets.conf << 'EOF'
[Service]
Environment="HITKEEP_JWT_SECRET=your-secret-here"
EOF
sudo chmod 600 /etc/systemd/system/hitkeep.service.d/secrets.conf

启用与验证（官方 Verify 流程）：

sudo systemctl daemon-reload
sudo systemctl enable --now hitkeep
sudo systemctl --no-pager status hitkeep
hitkeep --version
curl --fail http://127.0.0.1:8080/healthz
curl --fail http://127.0.0.1:8080/readyz

官方对两个探针的定义：/healthz 确认进程存活，/readyz 确认共享库与所有已打开的租户库就绪。

子路径发布（可选）：把 HitKeep 挂到 https://www.example.net/hitkeep/ 这类子目录，设 HITKEEP_PUBLIC_URL=https://www.example.net/hitkeep/，反代按相同前缀转发且不得重写（官方 Caddy 示例：handle /hitkeep* { reverse_proxy 127.0.0.1:8080 }）。

4.8 升级流程（官方原文）

sudo systemctl stop hitkeep
sudo install -m 0755 ./hitkeep /usr/local/bin/hitkeep
sudo systemctl start hitkeep
curl --fail http://127.0.0.1:8080/readyz
hitkeep --version

官方三条纪律：升级前读 release notes 并做完整备份；旧二进制与升级前备份保留到「readyz 通过 + 一条真实追踪请求成功」之后；带数据迁移的版本不支持用旧二进制读升级后的数据（降级前重读 release notes）。容器版升级路径见部署篇（改 tag → pull → up -d）。

备份可交给内置的 checkpoint 备份进程（systemd drop-in 追加后重启服务）：

[Service]
Environment="HITKEEP_BACKUP_PATH=/var/lib/hitkeep/backups"
Environment="HITKEEP_BACKUP_INTERVAL=60"
Environment="HITKEEP_BACKUP_RETENTION=24"

裸拷贝数据目录做备份则必须先停服务（WAL 一致性）。

4.9 Homebrew 安装（macOS / x86_64 Linux）

brew install HitKeep/hitkeep/hitkeep
hitkeep --version

官方限定 Apple silicon macOS 或 x86_64 Linux；Linux ARM64 请用发行二进制或 Docker。

五、注意事项

1. --help 不退出：捕获后记得 kill，别在交互终端裸跑；
2. --config 位置：必须放在所有参数最前（官方明确）；
3. config init 产物权限 0600：换属主或换目录时保留该权限语义；
4. distroless 容器没有 shell：docker exec ... sh 会得到 exec: "sh": executable file not found in $PATH（实测），只能直接 exec 二进制（如 hitkeep -healthcheck），调配置用 config init 产物挂载或环境变量；
5. 容器数据目录属主是 65532:65532：bind mount 前先 chown（部署篇排障实录）；
6. 原生部署用专用用户：useradd -r -s /bin/false hitkeep + chown 数据目录，不要以 root 跑；
7. 升级不可跳步验证：readyz + --version 是官方定式的收尾两连。

六、常见问题

1. 运行二进制直接报 GLIBCXX 符号缺失 在 glibc 低于 2.35 的宿主机（本系列实验环境）实测报错（逐行照抄，hitkeep-bin 为下载的二进制路径）：

/opt/data/quzuo/tmp/hitkeep/hitkeep-bin: /root/.trae-cn-server/bin/stable-871bca3bb55e7a37af74c1eef2a9696f29aa7b26-debian10/modules/ai-agent/libstdc++.so.6: version `GLIBCXX_3.4.30' not found (required by /opt/data/quzuo/tmp/hitkeep/hitkeep-bin)
/opt/data/quzuo/tmp/hitkeep/hitkeep-bin: /root/.trae-cn-server/bin/stable-871bca3bb55e7a37af74c1eef2a9696f29aa7b26-debian10/modules/ai-agent/libstdc++.so.6: version `GLIBCXX_3.4.29' not found (required by /opt/data/quzuo/tmp/hitkeep/hitkeep-bin)
/opt/data/quzuo/tmp/hitkeep/hitkeep-bin: /root/.trae-cn-server/bin/stable-871bca3bb55e7a37af74c1eef2a9696f29aa7b26-debian10/modules/ai-agent/libstdc++.so.6: version `GLIBCXX_3.4.26' not found (required by /opt/data/quzuo/tmp/hitkeep/hitkeep-bin)
/opt/data/quzuo/tmp/hitkeep/hitkeep-bin: /root/.trae-cn-server/bin/stable-871bca3bb55e7a37af74c1eef2a9696f29aa7b26-debian10/modules/ai-agent/libstdc++.so.6: version `CXXABI_1.3.13' not found (required by /opt/data/quzuo/tmp/hitkeep/hitkeep-bin)

官方兼容列表为 Ubuntu 22.04+、Debian 12+、Amazon Linux 2023 等基线；老系统（Ubuntu 20.04、Debian 11、Amazon Linux 2）官方明确建议改用 Docker Compose 镜像（本系列实验中，同一二进制在 ubuntu:24.04 容器内一切正常，--version 即出 v2.15.1）。

2. --help 之后服务「自己」起来了 这是它的怪癖不是 bug（见 4.2）——usage 打印到 stderr 后继续正常启动流程。测试环境里表现为「命令卡住」或端口被占。

3. 启动即退并报 failed to get final advertise address 完整报错（官方排障节）：failed to get final advertise address: no private IP address found, and explicit IP not provided——内嵌集群层找不到可声明的私网 IP。单机本地跑显式绑回环即可：

./hitkeep --bind-addr=127.0.0.1:7946
# 或
HITKEEP_BIND_ADDR=127.0.0.1:7946 ./hitkeep

多节点集群则把 --bind-addr/HITKEEP_BIND_ADDR 设为对端可达的真实私网地址。

4. -healthcheck 到底怎么判定健康 退出码 0 即健康（实测无输出、exit=0）；非 0 为异常。它检查的是进程内部状态，与 HTTP 探针 /healthz、/readyz 构成三层信号：进程内 → 进程活 → 数据就绪。

5. docker exec hitkeep sh 报 executable file not found 官方镜像为 distroless 无 shell，见注意事项第 4 条；需要临时 shell 调试时用 docker cp 取产物或另挂调试容器共享目录。

6. 旧版二进制还能读新版数据吗 不能一概而论：官方明确带数据迁移的版本升级后，旧二进制读取新数据不受支持——降级前先读 release notes，并回滚到升级前备份。

七、参考链接

• 官方二进制安装指南（systemd/升级/排障原文来源）：https://hitkeep.com/guides/installation/binary/
• GitHub Releases：https://github.com/HitKeep/hitkeep/releases
• Homebrew 安装指南：https://hitkeep.com/guides/installation/homebrew/
• 配置参考：https://hitkeep.com/reference/configuration/
• 本系列：《HitKeep 2.15.1 Docker Compose 部署指南》、《HitKeep 2.15.1 配置参数详解》、《HitKeep 介绍与选型指南》（认知与选型）
• 站内同类：《GoatCounter 2.7.0 常用 CLI 命令与工具详解》