SIPCAPTURE Homer 11 常用 CLI 命令与工具详解

目标：全面梳理 SIPCAPTURE Homer 11（homer-core 11.0.369）自带的 10 个 CLI 子命令——search（信令检索）、cli（只读 SQL 直查）、catalog（DuckLake 目录备份恢复）、system（运维/压实/扩展安装）、agent（采集代理观测）、config show（配置查看）、wizard（配置模板生成）、mcp（AI 集成）、migrate（Homer 7 迁移）、version，逐个给出参数表与实测回显，并标注两条实测发现的异常行为。安装与配置见专栏前篇，本文聚焦"装好之后怎么用命令行干活"。

一、环境信息

项目	内容
操作系统	Ubuntu 22.04 LTS（x86_64）
homer-core	11.0.369（官方 deb 安装，commit da04658，`/usr/local/homer-core/bin/homer`）
采集代理	heplify 2.0.28（同机演示，node_id 2002）
数据湖	/data/homer/parquet（含 B1 篇实测注入的 4 行注册信令）
服务管理	systemd（homer-core.service）
文档撰写日期	2026-10-27

二、前置条件

2.1 CLI 位置

deb/rpm 安装后二进制位于 /usr/local/homer-core/bin/homer（已加入 PATH，直接 homer 即可）；官方镜像形态则由入口 /homer 承载，homer <子命令> 换成 homer <子命令>（Compose 场景经 docker compose exec homer /homer <子命令> 调用，见《SIPCAPTURE Homer 11 Docker Compose 部署指南》第十章）。两种形态的二进制完全同构（本文实测两者 -help 输出逐字节一致）。

2.2 子命令全景

homer -help 顶部原文：

Homer - HEPer Home（SIP/VoIP capture and monitoring platform）

Usage:
  homer <command> [flags]
  homer <command> --help

Commands:
  search        Search HEP data via the HTTP API
  catalog       DuckLake catalog backup, restore and list
  cli           Interactive DuckLake SQL shell (read-only)
  system        System operations (reload, compaction, extensions)
  agent         Query the heplify agent API (stats, health, sync)
  wizard        Generate example JSON configuration presets
  config show   Print effective config (file + env + defaults)
  mcp           Model Context Protocol (MCP) server for LLM/AI agent integration
  migrate       Migrate data from Homer 7 settings/hepb tables
  version       Show version and build info

命令依赖关系决定用法：search/agent 是"远程客户端"（经 HTTP 访问服务端或采集代理 API，可在任意机器执行）；catalog/cli/system 是"本地工具"（直接读数据目录，须在与服务同机的部署路径执行，多数操作要求先停服务）；config show/wizard/version 随处可用。

三、检索类工具：homer search

3.1 参数表

参数	说明
`--host`	Homer API 地址（如 `127.0.0.1:8080`）
`--user` / `--pass`	API 账号（管理员或普通用户）
`--from` / `--to`	时间范围，支持 `48h`、`24h`、`7d` 等相对值；`--to` 缺省为 now
`--event-type`	数据表类型：`registration`、`call`、`default`、`rest` 等
`--protocol`	按传输协议过滤（UDP/TCP 等）
`--grep`	按 SIP 内容关键字过滤（Call-ID、号码、User-Agent 等）
`--format`	输出格式：`table`（默认）/`json`/`jsonl`/`csv`
`--select` / `--group-by`	结构化聚合列与分组列（见 3.4 实测异常）
`--sql`	原生 SQL 查询（绕过结构化封装，见 3.3）

3.2 表格检索实测

homer search --host 127.0.0.1:8080 --user admin --pass q1w2e3r4 \
  --from 48h --event-type registration --format table

实测输出（节选，payload/data_extra 列为截断展示）：

Searching http://127.0.0.1:8080 ...
+----------+--------------+----------------+-----------------------------+---------------+-----------+---------+-----------+--------------------------+---------------+----------+---------+----------+-----------------------+----------+--------------+----------+---------------+------+
| method   | storage_lake | storage_volume | timestamp                   | aor           | dst_ip    | expires | src_ip    | contact                  | data_extra    | dst_port | node_id | payload  | session_id            | src_port | user_agent    | date     | response_code | uuid |
+----------+--------------+----------------+-----------------------------+---------------+-----------+---------+-----------+--------------------------+---------------+----------+---------+----------+-----------------------+----------+--------------+----------+---------------+------+
| 200      | homer_lake   | default        | 2026-10-27T00:11:28.664649Z | 100@127.0.0.1 | 127.0.0.1 |         | 127.0.0.1 |                          | map[branch:…  | 50282    | 2002    | SIP/2.0… | 1719265065@172.17.0.3 | 5060     | mini-uas/0.1  | 2026-10-27T00:00:00Z | 17 | 200 | 0b26e463-…-0006 |
| REGISTER | homer_lake   | default        | 2026-10-27T00:11:28.664412Z | 100@127.0.0.1 | 127.0.0.1 | 15      | 127.0.0.1 | sip:100@172.17.0.3:58349 | map[branch:…  | 5060     | 2002    | REGISTER…| 1719265065@172.17.0.3 | 50282    | sipsak 0.9.8.1 | 2026-10-27T00:00:00Z |   | 0b26e463-…-0008 |
+----------+--------------+----------------+-----------------------------+---------------+-----------+---------+-----------+--------------------------+---------------+----------+---------+----------+-----------------------+----------+--------------+----------+---------------+------+
4 rows in set

Query completed. 4 rows returned in 24.78 ms

字段解读：storage_lake/storage_volume 标明数据所在湖与卷（分层部署时可据此确认冷热归属）；node_id 即采集代理的 HEP node ID；method/response_code 把请求与响应分列，一次 REGISTER 事务对应两行（REGISTER 请求 + 200 应答）。

3.3 原生 SQL 检索实测

需要聚合统计时用 --sql 直传 SQL（经 node 的 DuckLake 查询引擎执行）：

homer search --host 127.0.0.1:8080 --user admin --pass q1w2e3r4 --from 48h \
  --sql 'SELECT method, count(*) AS cnt FROM homer_lake.hep_proto_1_registration GROUP BY method ORDER BY cnt DESC'

实测输出：

Querying http://127.0.0.1:8080 (raw SQL) ...
+------+----------+
| cnt  | method   |
+------+----------+
| 2    | REGISTER |
| 2    | 200      |
+------+----------+

2 rows in set

Query completed. 2 rows returned in 8.02 ms

3.4 实测异常：--select/--group-by 聚合报 HTTP 500

结构化聚合参数在 11.0.369 实测不可用——同样语义的查询走 --select/--group-by 路径报服务端 500（实测原文）：

homer search ... --from 48h --select 'method, count(*) as cnt' --group-by method

Searching http://127.0.0.1:8080 ...
Search error: search failed (HTTP 500): {"error":{"type":"https://api.homer/errors/internal","title":"Server Error","status":500,"detail":"Query failed"}}

规避方案：聚合一律改走 3.3 的 --sql（同查询 8.02ms 正常返回）；明细检索用 --event-type/--grep 不受影响。

四、SQL 直查工具：homer cli

homer cli 是本地只读 DuckLake SQL 外壳，不经 API、直连数据目录，适合深度排查与对账：

homer cli --query 'SHOW TABLES'

实测输出：

Data path: /data/homer/parquet
Created 2 table views
Homer DuckLake SQL CLI (read-only)
===================================
Schema: homer_lake
SELECT/WITH without LIMIT are capped at 10000 rows (use --no-limit to disable)
Type 'help' for commands, 'exit' or Ctrl+D to quit
TAB completes SQL keywords, tables, columns, and parquet paths

| name                     |
+--------------------------+
| hep_proto_1_default      |
| hep_proto_1_registration |

(2 rows)

计数验证：

homer cli --query 'SELECT count(*) AS total FROM homer_lake.hep_proto_1_registration'

实测输出（节选）：

| total |
+-------+
| 4     |

(1 rows)

要点：

只读：仅允许 SELECT/WITH，杜绝误改湖数据；
单条模式 --query 与交互模式（不带参数进入，支持 TAB 补全表名/列名/Parquet 路径、help 内置命令）；
无 LIMIT 的查询默认截断 10000 行，需全量时加 --no-limit；
表命名规则 hep_proto_<协议号>_<类型>：hep_proto_1_registration（注册，HEP 协议 1 号承载）、hep_proto_1_default（默认信令）。

💡 技术拓展：homer cli 本质是把内置 DuckDB 以只读方式 attach 到 DuckLake catalog 后开放 SQL——因此 DuckDB 方言的函数（时间桶 date_trunc、正则、JSON 解包等）都能用，做"API 检索做不到的复杂对账"时是利器。代价是本地直读：运行中服务的 catalog 有写入锁，查询遇锁冲突时稍候重试；大批量导出建议放到业务低峰。

五、目录运维工具：homer catalog

DuckLake 的 catalog（SQLite 文件）是整个数据湖的元数据中枢，catalog 损坏 = 数据不可检索。catalog 子命令提供备份/恢复/清点三件套：

子命令	作用
`homer catalog backup`	立即备份 catalog（文件名自动带时间戳）
`homer catalog list`	列出现有备份文件与大小
`homer catalog restore --file <备份文件>`	用指定备份恢复 catalog

实测备份与清点：

homer catalog backup

catalog backup: /data/homer/homer_catalog.sqlite.bak-20261027T042216Z

homer catalog list

/data/homer/homer_catalog.sqlite.bak-20261027T042216Z	155648	2026-10-27T04:22:16Z

⚠️ 注意：catalog restore 是覆盖写操作，恢复前必须先停服务（systemctl stop homer-core），否则运行中的 catalog 写锁与恢复动作冲突；分层部署时冷卷有独立 catalog（如 homer_catalog_cold.sqlite），两份都要纳入备份节奏（冷卷 catalog 的备份对象与桶数据成对，见 Compose 篇 5.2）。

💡 技术拓展：备份产物是 原文件名.bak-<UTC时间戳> 的裸拷贝（本例 155648 字节），可直接 cp 异机保存。DuckLake 的 catalog 只存"哪些 Parquet 文件属于哪张表"的元数据，文件本体在 data_path 下——所以"catalog 备份 + 数据目录快照"才是完整备份；反过来，catalog 丢了但 Parquet 还在时，可用 homer system --rebuild-catalog 从盘面重建（见第六章）。

六、system：运维子命令

homer system 汇集了重载、压实、扩展安装、目录修复等系统级操作（homer system -help 全量旗标）：

旗标	类别	作用
`--reload`	配置	向运行中进程发 SIGHUP 热重载配置（见 C1 篇 3.2）
`--duckdb-version`	信息	打印内置 DuckDB 版本（扩展目录版本依据）
`--install-extensions`	扩展	预装 DuckDB 扩展（ducklake、sqlite、httpfs、aws），离线部署前置步骤
`--generate-example-config`	配置	生成示例 JSON 配置并退出
`--compaction-merge`	压实	立即合并相邻小文件后退出
`--compaction-merge-list`	压实	列出合并前后的最小文件清单（干跑预览）
`--compaction-force`	压实	全量压实（合并+快照过期+清理+孤儿处理）后退出
`--compaction-retention-days N`	保留	删除 N 天前数据后退出
`--compaction-expire-snapshots`	保留	过期 DuckLake 快照后退出
`--compaction-repair`	修复	清理指向缺失 Parquet 的失效 catalog 条目
`--compaction-recover`	修复	重新把盘面 Parquet 注册回 catalog 表
`--rebuild-catalog`	修复	备份旧 catalog 后按盘面文件原位重建（配合 `--rebuild-cleanup-orphans` 清孤儿）
`--config-path <path>`	通用	指定配置文件路径
`--pid-file <path>`	通用	PID 文件路径（`--reload` 用，默认 /var/run/homer-core.pid）

实测可用的两个旗标：

homer system --duckdb-version

v1.5.6

homer system --reload

Sent SIGHUP to homer-core (PID 2924) - reload triggered

6.1 实测异常：--compaction-merge-list 无法执行

-help 中明确列出的 --compaction-merge-list 旗标在 11.0.369（deb 形态，二进制 commit da04658）实测无法执行——两种传参形式均报"no system operation specified"（实测原文）：

homer system -compaction-merge-list
homer system --compaction-merge-list=true

System error: no system operation specified; use --help for available flags

处置建议：该旗标当前版本不可依赖，压实预览与执行以服务内置的周期压实（C1 篇 4.4 参数组）与维护窗 --compaction-force 为准；升级新版后先复测此旗标再纳入运维手册。

⚠️ 注意：--compaction-* 修复类与保留类旗标都是改状态的一次性操作（删除数据、重建 catalog、覆盖修复），必须在维护窗停服执行；执行前先 homer catalog backup 留退路。日常周期性的压实/过期由 storage.ducklake.compaction 配置段自动完成，无需手工干预。

七、采集代理观测：homer agent

heplify 自带 API 观测面（-api 启动参数开启），homer agent 子命令是它的官方查询客户端：

子命令	作用
`homer agent health --host <agent地址> --user --pass`	采集代理健康探针
`homer agent stats --host <agent地址> --user --pass`	抓包计数、传输队列、缓冲等运行统计
`homer agent sync`	同步节点配置到代理
`homer agent defaults`	打印代理默认参数

实测（heplify 以 -i lo -pr 5061-5062 -hs 127.0.0.1:9060 -api :8008 -api-user admin -api-pass q1w2e3r4 启动后）：

homer agent health --host 127.0.0.1:8008 --user admin --pass q1w2e3r4

heplify @ 127.0.0.1:8008  status=ok        connected_transports=1  queue=0  buffer=0 B

homer agent stats --host 127.0.0.1:8008 --user admin --pass q1w2e3r4

实测输出（节选）：

heplify @ 127.0.0.1:8008

-- Node
  node_name   homer11-ubuntu22
  node_id     2002
  interfaces  lo
  uptime      3s

-- Packets
  total       0
  sip         0
  rtcp        0
  rtp         0
  hep_sent    0
  duplicates  0

⚠️ 注意：heplify 必须显式带 -api 参数启动才会开放观测端口，否则 agent 子命令一律拒绝连接——实测未开 API 时（heplify 仅以 -hs 投递参数运行）：

Agent error: connect to http://127.0.0.1:8008/health: Get "http://127.0.0.1:8008/health": dial tcp 127.0.0.1:8008: connect: connection refused

生产建议：heplify 统一加 -api :8008 -api-user/-api-pass（并配 -prometheus :9096 暴露代理自身指标），采集器集群的存活与丢包即可集中用 homer agent health/stats 或 Prometheus 巡检。heplify 全量抓包/过滤/缓冲参数见 C1 篇 4.8。

八、配置与辅助工具

8.1 config show 与 wizard

homer config show（三层合并查看生效配置）与 homer wizard（五种角色预设生成配置模板）的完整用法、参数表与实测回显见 C1 篇第三章，此处不赘。

8.2 version

homer version

实测输出：

homer-core 11.0.369
built 2026-10-25 20:29:40, commit da04658, go go1.27.2, linux/amd64

报障与版本核对以此为准（commit 短哈希 + 构建日期）。

8.3 mcp：AI 集成服务器

homer mcp -help

实测输出（Go flag 包对 -help 的处理会先打印 Usage 再报错退出，属正常行为）：

Usage of mcp:
  -config-path string
    	path to config file or directory
MCP error: flag: help requested

💡 技术拓展：homer mcp 让 Homer 以 Model Context Protocol 服务器身份对外提供能力（stdio 通道），支持 Claude、Cursor 等 MCP 客户端直连 Homer 做信令检索与运维问答——把"用自然语言查话单"变成标准协议集成，是 11.x 新增的 AI 运维接口，无需额外装组件。

8.4 migrate：Homer 7 数据迁移

从 Homer 7（Homer 5/7 时代的 MySQL schema）搬迁历史数据，关键旗标：

旗标	说明
`--from-uri`	源库 DSN（Homer 7 MySQL）
`--tables`	迁移表清单
`--dry-run`	只统计与报告、不写任何数据（迁移前必跑）
`--batch-size`	每批 SELECT 行数（默认 5000）
`--checkpoint`	断点文件（记录 table → 最大已处理 id，可续跑）
`--duckdb`	显式指定目标 settings DuckDB 文件（覆盖配置）
`--hep-capture-id`	迁移数据的采集节点 ID 归属（0=保留源 captureId）

迁移是重操作：先 --dry-run 评估体量，再用 --checkpoint 分窗执行、失败续跑。

九、常用命令速查

# —— 检索 ——
homer search --host 127.0.0.1:8080 --user admin --pass '***' --from 24h --event-type registration   # 明细表格式
homer search --host ... --from 1h --event-type call --grep '404'                                    # 按内容过滤
homer search --host ... --from 24h --sql 'SELECT ...' --format json                                 # SQL + JSON 导出
homer cli --query 'SELECT count(*) FROM homer_lake.hep_proto_1_registration'                        # 本地只读 SQL
# —— 运维 ——
homer catalog backup                                                                                # 备份 catalog
homer catalog list                                                                                  # 清点备份
homer system --reload                                                                               # 热重载配置
homer system --duckdb-version                                                                       # DuckDB 版本（扩展目录依据）
homer system --install-extensions                                                                   # 预装 DuckDB 扩展（离线部署）
homer system --compaction-force                                                                     # 维护窗全量压实
# —— 采集代理 ——
homer agent health --host 10.0.0.5:8008 --user admin --pass '***'                                   # 代理存活
homer agent stats  --host 10.0.0.5:8008 --user admin --pass '***'                                   # 抓包统计
# —— 版本与配置 ——
homer version                                                                                       # 版本核对
homer config show --section ingest.udp --compact                                                    # 生效配置
homer wizard --profile all-in-one --output /root/homer-wizard.json                                  # 模板生成

十、常见问题

Q1：homer search 明细正常、聚合却报 HTTP 500？

11.0.369 实测缺陷：--select/--group-by 结构化聚合路径服务端报 500（3.4 实录）。改用 --sql 原生查询（3.3），语义等价且更快；升级后可复测结构化参数。

Q2：homer system -help 里有的旗标执行报 no system operation specified？

--compaction-merge-list 在本版本 help 可见但不可执行（6.1 实录）。改用内置周期压实或 --compaction-force；执行任何 --compaction-* 改状态操作前先 catalog backup 并停服。

Q3：homer agent 全部 connection refused？

heplify 启动时没带 -api 参数（第七章实测对照）。采集端补 -api :8008 -api-user/-api-pass 后重试；批量巡检用 Prometheus 端点而非逐台 agent 查询。

Q4：homer cli 查询偶发锁冲突？

cli 直读 catalog，与常驻服务的 catalog 写锁互斥（同文件单写模型）。低峰执行或重试；重活（备份恢复、批量导出）在维护窗做完再启服务。

Q5：search 输出的列超宽把终端刷乱？

明细列（payload/data_extra）天然宽，机器消费用 --format jsonl/csv；人工排查缩小 --from 窗口并配合 --grep 减行数，或改用 Web UI 检索页。

十一、参考链接

本专栏配置篇（config show/wizard 详解与参数全集）：《SIPCAPTURE Homer 11 配置参数详解》
本专栏部署篇（镜像形态与 Compose 运维命令）：《SIPCAPTURE Homer 11 Docker Compose 部署指南》
本专栏安装篇（deb 安装与验证闭环）：《Ubuntu 22.04 安装 SIPCAPTURE Homer 11 指南》
homer 项目与 Releases：https://github.com/sipcapture/homer
heplify 项目：https://github.com/sipcapture/heplify
DuckLake 概念与 catalog：https://ducklake.select