SIPCAPTURE Homer 11 配置参数详解

SIPCAPTURE Homer 11(homer-core 11.0.369)配置参数详解:config show 三层合并查看、homer.json 与 HOMER_* 环境变量双形态、六大配置段与冷热分层策略逐项详解、heplify 采集参数速查与分场景生产配置模板,全部实测回显。

SIPCAPTURE HomerSIPVoIP2026/10/27

SIPCAPTURE Homer 11 配置参数详解

目标:系统讲解 SIPCAPTURE Homer 11(homer-core 11.0.369)的全部配置面——参数查看(homer config show 三层合并)、修改方式(homer.json 文件 / HOMER_* 环境变量 / homer wizard 预设)、六大配置段(ingest/storage/node/coordinator/log/prometheus)与分层存储策略逐项详解、heplify 采集代理参数速查,并给出分场景生产配置模板。全部命令在 Ubuntu 22.04 + homer-core 11.0.369 实测,回显均为原始输出。

一、环境信息

项目内容
操作系统Ubuntu 22.04 LTS(x86_64)
homer-core11.0.369(官方 deb 安装,commit da04658,/usr/local/homer-core/bin/homer)
采集代理heplify 2.0.28(官方 deb)
主配置文件/usr/local/homer-core/etc/homer.json(由 homer.json.example 复制而来,3920 字节)
settings 库/var/lib/homer/homer_settings.duckdb
数据湖/data/homer/parquet + /data/homer/homer_catalog.sqlite
服务管理systemd(homer-core.service)
文档撰写日期2026-10-27

二、前置条件

systemctl is-active homer-core

实测输出:

active
  • homer config show 不依赖运行中的进程(官方注明 "Not attached to a live process"),服务停着也能查看配置。

三、参数查看与修改方式

3.1 查看生效配置:homer config show

Homer 11 的配置来自三个来源的合并:配置文件(homer.json)+ 环境变量(HOMER_*)+ 内置默认值。config show 子命令打印合并后的最终生效值:

/usr/local/homer-core/bin/homer config show --section ingest.udp.port --compact

实测输出:

9060

常用参数:

参数说明
--section <路径>只打印指定 JSON 路径的片段,如 storage.ducklake.compaction
--include-secrets不脱敏打印口令、令牌与密钥(默认打码)
--compact单行 JSON 输出
--config-path <path>指定配置文件路径(默认自动查找)

查看完整压实段(单行 JSON,含示例文件中未列出、实际存在的隐藏键):

/usr/local/homer-core/bin/homer config show --section storage.ducklake.compaction --compact

实测输出(节选整理为多行):

{"check_interval_sec":1800,"enable":true,"engine":"duckdb","max_compacted_files":32,"max_file_size_bytes":134217728,"max_row_group_bytes":0,"memory_limit":"","min_age_sec":3600,"min_file_size_bytes":0,"retention_days":30,"retention_days_by_table":{"hep_proto_1_registration":14},"retention_unit":"days","snapshot_expire_interval_sec":3600,"target_file_size_bytes":0}

⚠️ 注意:config show 的输出是"合并后生效值",比 homer.json 原文件多出内置默认键(如 engine、retention_days_by_table)——排查"我明明没配这个值"类问题时以它为准。

3.2 修改配置的三种途径

途径一:编辑 homer.json 后热重载(推荐)。改完文件向运行中进程发 SIGHUP:

vi /usr/local/homer-core/etc/homer.json
/usr/local/homer-core/bin/homer system --reload

实测输出:

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

等价的服务层操作:systemctl reload homer-core(单元支持时)或 systemctl restart homer-core。监听端口、数据路径等启动期参数改后需重启而非重载。

途径二:环境变量覆盖。HOMER_* 变量与 homer.json 是同一棵配置树,映射规则为下划线逐级展开 + _数字_ 数组索引(如 HOMER_INGEST_UDP_PORT → ingest.udp.port、HOMER_COORDINATOR_NODES_0_NAME → coordinator.nodes[0].name)。systemd 形态在单元文件中加 Environment=,镜像形态则完全靠它(Docker Compose 部署形态的差异与全表见 《SIPCAPTURE Homer 11 Docker Compose 部署指南》第六章)。

途径三:homer wizard 预设生成。五种内置角色预设一键生成完整模板:

/usr/local/homer-core/bin/homer wizard --profile all-in-one --output /root/homer-wizard.json

实测输出:

Config saved to /root/homer-wizard.json (11750 bytes)

预设清单(homer -help 原文):all-in-one(单机全模块)、writer(纯存储写手)、edge(边缘采集)、coordinator(协调/API)、node(查询节点)。

3.3 参数总览:六大配置段

homer.json 的顶层结构(与模块一一对应):

配置段对应模块核心内容
ingest采集UDP/TCP/TLS/HTTP 四通道监听、HEP 协议、SIP 头处理
storage存储DuckLake catalog/数据路径、批次落盘、调优、分层策略、压实
node查询节点Flight gRPC 服务、节点侧卷定义
coordinator协调API/Web UI 监听、节点清单、settings 库、JWT 与认证
log日志级别、格式、输出(stdout/file/syslog)与轮转
prometheus指标/metrics 监听与路径

四、核心参数分类详解

4.1 ingest:采集段

控制 HEP 数据的接收通道与解析行为。文件节选(homer.json.example 原文):

"ingest": {
    "enable": true,
    "udp": {
      "enable": true, "host": "0.0.0.0", "port": 9060, "multicore": true
    },
    "tcp": {
      "enable": true, "host": "0.0.0.0", "port": 9060, "multicore": true
    },
    "tls": {
      "enable": false, "host": "0.0.0.0", "port": 9061,
      "cert": "/etc/homer/certs/server.crt", "key": "/etc/homer/certs/server.key",
      "min_tls_version": "TLS1.2"
    },
    "http": {
      "enable": true, "host": "0.0.0.0", "port": 9080,
      "read_timeout": 30, "write_timeout": 30,
      "max_request_body_size": 67108864, "websocket_enable": false
    },
    "https": { "enable": false },
    "hep": {
      "hepv2_enable": true, "hepv3_enable": true,
      "protobuf_enable": true, "deduplicate": false
    },
    "sip": {
      "censored_methods": [], "discard_methods": [],
      "aleg_ids": ["X-CID", "X-Session-ID"],
      "custom_headers": [], "force_aleg_id": false
    }
}

逐项说明:

参数默认值说明
udp.enable/porttrue / 9060HEP over UDP 监听;multicore=true 时每核一个 socket 提升收包吞吐
tcp.enable/porttrue / 9060HEP over TCP;与 UDP 同端口可并存
tls.*enable=false, 9061HEP over TLS;跨公网采集建议开启,min_tls_version 最低 TLS1.2
http.enable/porttrue / 9080HTTP/JSON 批量投递接口;max_request_body_size 64MB
hep.hepv2_enable/hepv3_enabletrue / true新部署保持 v3 即可,v2 兼容老代理
hep.deduplicatefalse服务端去重开关(采集端去重更省带宽,见 4.8 heplify -dd)
sip.aleg_ids["X-CID", "X-Session-ID"]A 腿关联头:SIP 消息携带这些自定义头时按 A 腿归类
sip.discard_methods[]丢弃指定 SIP 方法不入库(如高噪声 NOTIFY),减卷首选项

socket 级隐藏键(config show --section ingest.udp 实测):

{"enable":true,"host":"0.0.0.0","multicore":true,"port":9060,"read_buffer_cap":131072,"socket_recv_buffer":8388608,"socket_send_buffer":1048576}

socket_recv_buffer(8MB)与 socket_send_buffer(1MB)是内核 socket 缓冲区字节数,高 PPS 场景可调大 socket_recv_buffer 缓解 UDP 丢包。

4.2 storage:湖仓写入段

控制 DuckLake 数据湖的落盘行为,是小流量"查不到数据"问题的根源所在:

参数示例文件值说明
storage.enabletrue存储模块开关
storage.ducklake.catalog_typesqlitecatalog 后端类型(SQLite 单文件,免外部数据库)
storage.ducklake.catalog_path/data/homer/homer_catalog.sqlitecatalog 文件路径
storage.ducklake.data_path/data/homer/parquetParquet 数据目录
storage.ducklake.lake_namehomer_lake湖仓名
storage.ducklake.batch_size25000内存缓冲行数,凑满即批量落盘
storage.ducklake.flush_interval_sec30落盘周期(秒);两者任一满足即 flush
storage.ducklake.search_buffertrue搜索时合并未落盘的内存缓冲(小流量立查可见的关键开关)
storage.ducklake.tuning.threads2writer DuckDB 线程数
storage.ducklake.tuning.memory_limit4GBwriter DuckDB 内存上限

实测验证文件值(config show --section storage.ducklake.batch_size --compact):

25000

⚠️ 注意:batch_size 与 flush_interval_sec 决定数据可见延迟——注入测试流量后立即检索可能返回空,等 flush 周期后同一查询即有数据(实测过程见 B1 篇排障 7.3)。生产调优方向:话务高峰调大 batch_size 提升吞吐,验证环境调小 flush_interval_sec 换实时性。

4.3 storage.ducklake.storage_policy:冷热分层策略

分层策略段在 homer.json.example 中未列出,属"示例文件未含、程序已支持"的进阶段(homer wizard --profile all-in-one 生成的模板中含完整骨架)。生成的骨架实测(python3 -c 解析 wizard 产物):

{
 "enable": false,
 "volumes": null,
 "ttl_move_interval_sec": 0,
 "move_factor": 0,
 "concurrent_moves": 0,
 "move_on_startup": false,
 "move_engine": ""
}

启用分层时填入热/冷两级卷(完整可运行示例见 Compose 篇第六章环境变量表,两种形态字段一一对应):

参数说明
enable分层总开关
volumes[].name/type/path卷定义;type 取 local 或 s3,path 为目录或 s3://bucket
volumes[].priority0 最热;新数据写 priority 最小的卷
volumes[].max_data_age_days该卷数据最大保留天数,超龄搬往下一级(0=永久保留)
volumes[].max_size_gb容量上限触发搬迁
volumes[].s3.*S3 卷专用:endpoint、region、access_key_id、secret_access_key、use_ssl
ttl_move_interval_sec搬迁扫描周期(秒),默认每小时
move_factor容量因子
concurrent_moves并发搬迁任务数
move_on_startup启动即执行一轮搬迁检查

node 段的 node.ducklake.volumes[] 需同步声明同一组卷(冷卷使用独立 catalog 文件,如 /data/homer/homer_catalog_cold.sqlite),查询时才可跨冷热合并检索。

4.4 storage.ducklake.compaction:压实与保留

参数默认值说明
enabletrue后台压实总开关
check_interval_sec1800压实检查周期(秒)
retention_days30全局数据保留天数
retention_unitdays保留单位(days/hours)
retention_days_by_table{"hep_proto_1_registration": 14}按表覆盖全局保留期——实测默认对注册表(registration)只留 14 天;话单类表可单独延长
snapshot_expire_interval_sec3600DuckLake 快照过期周期
min_age_sec3600文件最短存活时间,防止压实正在写入的文件
min_file_size_bytes / max_file_size_bytes0 / 134217728参与合并的文件下限/合并目标上限(128MB)
max_compacted_files32单轮合并参与文件数上限
engineduckdb压实引擎(内置默认,示例文件未列)

4.5 node:查询节点段

"node": {
    "enable": true,
    "flight_server": {
      "host": "0.0.0.0", "port": 50051,
      "auth_token": "", "max_message_size": 16777216
    },
    "flightsql_server": {
      "enable": false, "host": "0.0.0.0", "port": 50055,
      "auth_token": "", "catalog_refresh_interval_sec": 30
    },
    "ducklake": {
      "lake_name": "homer_lake",
      "volumes": [ { "name": "default", "type": "local",
        "catalog_type": "sqlite", "catalog_path": "/data/homer/homer_catalog.sqlite",
        "path": "/data/homer/parquet" } ]
    }
}
参数默认值说明
flight_server.port50051Airport gRPC 查询服务,coordinator 经它下发查询
flight_server.auth_token空非空时节点间查询需携带令牌(跨机部署建议设置;节点侧同时生成 .homer_node_auth_token)
flight_server.max_message_size16777216gRPC 单消息上限 16MB
flightsql_server.enablefalse标准 FlightSQL 接口开关(可用第三方 Arrow 客户端直连,端口 50055)
ducklake.volumes[]单本地卷节点侧可见卷清单,冷卷场景补第二项

4.6 coordinator:协调与认证段

"coordinator": {
    "enable": true,
    "http_server": {
      "enable": true, "host": "0.0.0.0", "port": 8080,
      "read_timeout": 30, "write_timeout": 30,
      "static_path": "/usr/local/homer-core/dist"
    },
    "nodes": [
      { "name": "local", "host": "127.0.0.1", "port": 50051,
        "flightsql_port": 0, "use_tls": false, "token": "", "priority": 1 }
    ],
    "settings_db_path": "/var/lib/homer/homer_settings.duckdb",
    "jwt": { "secret": "", "expire_hours": 24 },
    "auth": { "type": "internal" }
}
参数默认值说明
http_server.port8080REST API + Web UI 端口
http_server.static_path/usr/local/homer-core/distWeb UI 静态资源目录(随包安装)
nodes[]本机 local查询节点清单;多节点部署在此登记远端节点(name/host/port/priority)
settings_db_path/var/lib/homer/homer_settings.duckdb设置库(用户/仪表盘/令牌)。DuckDB 单写锁模型:任何绕过服务的该文件运维(重置口令等)必须先停服,实测排障见 B1 篇 4.3.2
jwt.secret空空=首启自动生成并落 .homer_jwt_secret;多副本部署需统一为相同密钥
jwt.expire_hours24登录令牌有效期
auth.typeinternal认证后端

管理员账号口令(HOMER_COORDINATOR_AUTH_ADMIN_USER/_PASSWORD_HASH 环境变量或对应 JSON 键)以 SHA-256 十六进制哈希存储:演示口令 q1w2e3r4 的哈希为 13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9(echo -n 'q1w2e3r4' | sha256sum 实测),重置流程见 B1 篇 4.3.2。

4.7 log 与 prometheus 段

"log": {
    "level": "info", "json": false, "output": ["stdout"],
    "file": { "path": "/var/log/homer", "name": "homer.log",
      "max_age_days": 7, "rotation_hours": 24, "max_size_mb": 100 },
    "stdout": { "colored": true },
    "syslog": { "uri": "", "facility": "local0",
      "level": "LOG_INFO", "tag": "homer" }
},
"prometheus": {
    "enable": true, "host": "0.0.0.0", "port": 9090,
    "path": "/metrics", "agent_label": "node_id"
}

要点:log.output 数组可同时启用 stdout/file/syslog;prometheus.agent_label 决定指标中采集节点的标签维度(默认按 heplify 的 node ID 区分)。

4.8 heplify:采集代理参数

heplify 与 homer-core 是独立项目(单独发版),运行在被监控主机上抓包封装 HEP 投递。heplify -help 全量参数速查(v2.0.28 实测,按用途分组):

抓包与投递(核心):

参数默认值说明
-iany抓包网卡;生产填业务网卡(如 eth0),环回演示用 lo
-pr5060-5090SIP 抓包端口范围
-hs127.0.0.1:9060Homer 采集地址,逗号分隔可投多套(如 -hs "10.0.0.1:9060,10.0.0.2:9060")
-tafpacket抓包方式 pcap / afpacket
-ntudp网络类型 udp/tcp/tls
-mSIPRTCP抓包模式 SIP、SIPDNS、SIPLOG、SIPRTCP、SIPRTP、SIPDIAMETER、DIAMETER
-hi2002HEP node ID(Homer 指标按它区分采集节点)
-hn / -hp空HEP 节点名 / 节点口令
-b32网卡缓冲区(MB),高 PPS 调大
-s8192snaplen 抓包长度
-dd关包去重(服务端 hep.deduplicate 的采集端版本)

过滤与丢弃:

参数说明
-bpf自定义 BPF 过滤器
-fi / -di按负载内容包含/包含即丢弃(字符串过滤)
-disip / -didip / -diip按源 IP / 目的 IP / 双向 IP 丢弃
-dim丢弃指定 SIP 方法(如 -dim OPTIONS,NOTIFY)
-pi-i any 时指定参与混杂模式的网卡列表

断网缓冲与重放:

参数默认值说明
-hep-buffer-activate关Homer 不可达时启用本地缓冲,恢复后续传
-hep-buffer-file / -hep-buffer-max-sizeHEP-Buffer.dump / 100MB缓冲文件与上限
-rf—从 pcap 文件重放(配合 -lp 循环次数、-rs 全速重放、-eof-exit 放完即退)
-wf / -zf / -rt— / 关 / 60抓包落盘目录 / gzip 压缩 / 轮转分钟数

自观测与运维:

参数默认值说明
-api空(禁用)heplify 自身 API 监听地址(:9060 等),供 homer agent 查询抓包统计
-api-user / -api-pass / -api-tls空API Basic Auth 与 HTTPS
-prometheus空(禁用)heplify 自身 /metrics 地址(如 :9096)
-l / -log-format / -Sinfo / text / 关日志级别 / 格式 / 输出 stdout
-config—JSON 配置文件(CLI 显式旗标优先于文件;HEPLIFY_CONFIG 环境变量同理,-no-config 全忽略)
-tcpassembly / -sipassembly关TCP 重组(SIP over TCP 场景开启)
-vlan / -erspan关VLAN / ERSPAN 解封
-keepalive5TCP keepalive 秒数(0 关闭)

生产最小启动命令(与 B1 篇 4.5 实测一致):

heplify -i eth0 -pr 5060-5090 -hs <homer服务器IP>:9060

实测启动日志关键行:

INF Starting heplify build_date=2026-09-04T08:47:09Z git_commit=21b03cf go_version=go1.25.0 os_arch=linux/amd64 version=2.0.28
INF Effective runtime configuration socket_devices=["lo"] transport_kinds=["udp"] transport_targets=["127.0.0.1:9060"] transports_active=1 transports_total=1
INF Started packet capture
INF Connected to HEP server addr=127.0.0.1:9060 transport=udp component=sender reason="initial connect"
INF BPF filter applied interface=lo filter="((udp and portrange 5060-5090) or (tcp and portrange 5060-5090) or (udp and portrange 1024-65535)) and not dst port 9060"

五、生产配置模板

5.1 模板一:单机 all-in-one(8GB 内存 / 200GB SSD / 中小话务)

适用:日千万行级信令、单服务器、本地盘 + 可选 S3 冷层。以 homer.json.example 为基底的推荐修改点(完整文件 = example 全文 + 以下各段替换):

{
  "storage": {
    "enable": true,
    "ducklake": {
      "catalog_type": "sqlite",
      "catalog_path": "/data/homer/homer_catalog.sqlite",
      "data_path": "/data/homer/parquet",
      "lake_name": "homer_lake",
      "batch_size": 25000,
      "flush_interval_sec": 30,
      "search_buffer": true,
      "tuning": { "threads": 4, "memory_limit": "4GB" },
      "compaction": {
        "enable": true,
        "check_interval_sec": 1800,
        "retention_days": 90,
        "retention_unit": "days",
        "retention_days_by_table": {
          "hep_proto_1_registration": 30
        },
        "max_file_size_bytes": 134217728,
        "max_compacted_files": 32
      }
    }
  },
  "coordinator": {
    "enable": true,
    "http_server": { "enable": true, "host": "0.0.0.0", "port": 8080,
      "static_path": "/usr/local/homer-core/dist" },
    "settings_db_path": "/var/lib/homer/homer_settings.duckdb",
    "jwt": { "secret": "", "expire_hours": 24 }
  }
}

模板解读:tuning.threads 从 2 提到 4 换取查询并发;retention_days 90 天、注册表单独 30 天(注册量远小于呼叫量);内存 8GB 中给 writer 4GB 上限,其余留给系统与页缓存。磁盘按"日增 Parquet × 保留天数 × 1.5 余量"规划并监控 /data/homer/parquet。

5.2 模板二:高话务分离部署(16GB+ 内存 / 多机)

适用:日亿行级、采集与查询压力需隔离。用 wizard 预设起步再改差异:

  • 采集机:homer wizard --profile edge——只开 ingest,4 通道监听 + ingest.udp.multicore + 大 queue_size,disk 要求低;
  • 存储机:--profile writer——只开 storage,batch_size 调大、tuning.threads 按 CPU 核数、本地 NVMe;
  • API 机:--profile coordinator——只开 coordinator,coordinator.nodes[] 登记 writer/node 节点;
  • 查询机:--profile node——node.ducklake.volumes[] 指向共享存储或本机卷,flight_server.auth_token 设置令牌。

跨机部署固定三件事:节点间 token/auth_token 两端一致;coordinator.jwt.secret 多副本统一;时钟同步(检索按时间戳分片路由)。

5.3 模板三:离线环境(禁外网 / S3 冷层)

关键点只有一个——DuckDB 扩展必须预就位,否则 writer 起不来(实测报错与完整解法见 Compose 篇常见问题 Q1)。裸机形态的等价操作:

# 版本必须与内置 DuckDB 一致(先查询实测版本)
/usr/local/homer-core/bin/homer system --duckdb-version
# 可联网机器下载后离线拷入扩展目录
/usr/local/homer-core/bin/homer system --install-extensions

实测 --duckdb-version 输出:

v1.5.6

扩展落位目录:/data/homer/.duckdb/extensions/v1.5.6/linux_amd64/(需 aws、ducklake、httpfs、sqlite_scanner、azure 五件,S3 冷卷场景缺 aws/httpfs 会挂起)。

六、常见问题

Q1:homer.json 里没有的键(如 storage_policy、engine)为什么出现在 config show 里?

config show 打印"文件 + 环境变量 + 内置默认值"三层合并结果,内置默认键本来就不在示例文件中。以 config show 为生效事实、以 homer.json 为编辑对象。

Q2:改了 homer.json 不生效?

先确认改的是生效文件:deb 形态为 /usr/local/homer-core/etc/homer.json(B1 篇排障 7.2:deb 只带 example,未复制文件服务起不来)。再用 config show --section <路径> 核对合并值;HOMER_* 环境变量会覆盖同名文件值(systemd 单元 Environment= 与镜像形态均如此)。监听端口类启动期参数需 systemctl restart 而非 --reload。

Q3:注入流量后立即检索为空?

写入路径是"内存缓冲 → 批量落盘":batch_size(25000 行)或 flush_interval_sec(30 秒)任一满足才 flush。验证环境把 flush_interval_sec 调小;生产排查先看 homer_packets_by_type_total 与 flush 指标计数再查检索(实测过程见 B1 篇排障 7.3)。

Q4:注册数据 14 天就没了?

全局保留 30 天,但内置默认 retention_days_by_table 对 hep_proto_1_registration 单独 14 天。按 4.4 节覆盖该键或改全局值。

Q5:settings 库相关运维报 Conflicting lock?

homer_settings.duckdb 是单写锁 DuckDB 文件,与常驻服务互斥。重置口令、手工改设置等操作先 systemctl stop homer-core,做完再启(实测排障见 B1 篇 4.3.2)。

七、参考链接