Ubuntu 22.04 安装 SIPCAPTURE Homer 11 指南

Ubuntu 22.04 LTS 上从零安装 SIPCAPTURE Homer 11（homer-core 11.0.369）：官方 deb 包与源码编译双路线、systemd 托管、管理员口令初始化、heplify 采集代理部署，并以 sipsak 注入流量完成端到端检索验证。

SIPCAPTURE HomerSIPVoIP2026/10/27

Ubuntu 22.04 安装 SIPCAPTURE Homer 11 指南

Homer 11（homer eleven）将采集、存储、查询与协调四大模块收敛为一个 homer-core 单二进制，安装半径比 Homer 7 时代（heplify-server + homer-app + PostgreSQL + InfluxDB）缩小了一个数量级。本文在 Ubuntu 22.04 LTS 服务器上完整实操两条安装路线——官方 deb 软件包安装与源码编译安装，覆盖从系统布局、systemd 服务管理、管理员口令初始化，到 heplify 采集代理部署、SIP 流量注入与检索验证的端到端闭环，并把过程中的真实报错与解决步骤沉淀为排障实录。

一、环境信息

本文所有操作均在以下环境中实测完成，实测回显均为原始输出：

项目内容
操作系统Ubuntu 22.04 LTS（Jammy，x86_64）
Homer 版本homer-core 11.0.369（官方 deb 包；源码 tag 11.0.369，commit da04658）
采集代理heplify 2.0.28（官方 deb 包）
编译工具链Go 1.26.10 + GOTOOLCHAIN 自动升级 go1.27.2
流量工具sipsak 0.9.8.1、Python 3.10（自带 mini-UAS 应答脚本）
服务管理systemd（homer-core.service）
文档撰写日期2026-10-27

二、前置条件

2.1 硬件与系统要求

  • 内存：官方建议 all-in-one 模式预留约 8GB 内存（内置 DuckDB writer 默认 MEMORY_LIMIT=4GB，可按需调整）；纯测试环境 2GB 亦可启动。
  • 磁盘：数据目录存放 Parquet 列存文件，按话务量规划；安装本身占用约 200MB。
  • 系统：x86_64 或 arm64 架构；内核需支持 UDP/TCP 网络栈常规操作，无额外内核依赖。
  • 外部依赖：无。homer-core 为静态单二进制，不需要 PostgreSQL/InfluxDB 等外部数据库——这是 11.x 相对 7.x 的核心简化。

2.2 端口规划

安装前确认以下端口未被占用（默认配置）：

端口协议用途
9060UDP/TCPHEP 采集（heplify 等代理投递）
9061TCPHEP over TLS（默认关闭）
9080TCPHTTP/JSON 批量投递接口
8080TCPREST API + Web UI + 健康检查
50051TCPAirport gRPC 查询节点服务
50052TCP节点 HTTP /query
9090TCPPrometheus /metrics

2.3 示例约定

本文统一使用：服务器 IP 为 192.168.1.100，管理员账号 admin，口令 q1w2e3r4。实际部署请替换为你的真实值。

三、版本选型

官方在 GitHub Releases 为每个版本发布以下资产（以 11.0.369 为例，2026-10-26 查询）：

资产适用场景
homer-core_11.0.369_amd64.debUbuntu/Debian x86_64（本文主用）
homer-core_11.0.369_arm64.debUbuntu/Debian arm64
homer-core_11.0.369_amd64.rpm / _arm64.rpmRHEL/CentOS/Rocky
Source code (tar.gz / zip)源码编译

选型建议：

  • 生产服务器：优先 deb/rpm 包安装——安装快、自带 systemd 单元、升级只需换包重装。
  • 需要定制/二次开发：源码编译，可加自定义 build 标签并修改源码。
  • 版本查询：发版频率很高（11.0.x 数日一版），安装前查 https://github.com/sipcapture/homer/releases 取最新稳定 tag；生产建议跟随最新 patch，跨大版本升级先看 Release Notes。

四、安装方案

4.1 方案一：官方 deb 包安装（推荐）

4.1.1 下载软件包

在线下载（服务器可直连 GitHub 时）：

wget https://github.com/sipcapture/homer/releases/download/11.0.369/homer-core_11.0.369_amd64.deb
wget https://github.com/sipcapture/homer/releases/download/11.0.369/heplify_2.0.28_amd64.deb

💡 技术拓展：heplify 是独立的采集代理项目（github.com/sipcapture/heplify），单独发版。被监控服务器上只需装 heplify，不必装 homer-core。

离线场景：在能上网的机器下载后，用 scp 将 deb 包拷贝到服务器的 /root/pkg/ 目录即可，后续安装步骤完全相同。

4.1.2 安装 homer-core 与 heplify

mkdir -p /root/pkg && cd /root/pkg
dpkg -i ./homer-core_11.0.369_amd64.deb
dpkg -i ./heplify_2.0.28_amd64.deb

实测输出：

Selecting previously unselected package homer-core.
(Reading database ... 6535 files and directories currently installed.)
Preparing to unpack .../homer-core_11.0.369_amd64.deb ...
Unpacking homer-core (11.0.369) ...
Setting up homer-core (11.0.369) ...

(Reading database ... 6613 files and directories currently installed.)
Preparing to unpack ./heplify_2.0.28_amd64.deb ...
Unpacking heplify (2.0.28) ...
Setting up heplify (2.0.28) ...

4.1.3 安装布局确认

ls /usr/local/homer-core/bin/
ls /usr/local/homer-core/etc/
ls /etc/systemd/system/ | grep -i homer
/usr/local/homer-core/bin/homer version

实测输出：

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

三个关键落点：单二进制 /usr/local/homer-core/bin/homer、示例配置 /usr/local/homer-core/etc/homer.json.example、systemd 单元 /etc/systemd/system/homer-core.service。单元内容：

[Unit]
Description=HEPAgent
After=network.target

[Service]
Environment="HOME=/usr/local/homer-core"
ExecStart=/usr/local/homer-core/bin/homer -config-path /usr/local/homer-core/etc/homer.json
Restart=always
RestartSec=3s
Type=simple

[Install]
WantedBy=multi-user.target

4.2 初始配置与首次启动

4.2.1 生成配置文件

deb 包默认只带示例配置，必须先复制出正式配置（否则服务无配置可读）：

cp /usr/local/homer-core/etc/homer.json.example /usr/local/homer-core/etc/homer.json

4.2.2 启动并设置开机自启

systemctl daemon-reload
systemctl enable --now homer-core

实测输出：

Executing: /lib/systemd/systemd-sysv-install enable homer-core
Created symlink /etc/systemd/system/multi-user.target.wants/homer-core.service → /etc/systemd/system/homer-core.service.

确认服务状态与健康端点：

systemctl is-active homer-core
curl -s http://127.0.0.1:8080/health

实测输出：

active
{"module":"coordinator","nodes":1,"status":"ok","version":"11.0.369"}

/health 返回 status: ok 且 nodes: 1，说明 Coordinator 与本地查询节点均已就绪。

4.3 管理员口令初始化（含排障实录）

4.3.1 口令机制

Homer 11 新装不再使用历史默认口令 admin/sipcapture（已废弃）。口令初始化二选一：

  • 方式 A（推荐）：启动前注入环境变量 HOMER_COORDINATOR_AUTH_ADMIN_PASSWORD_HASH（值为口令的 SHA-256 十六进制串）。
  • 方式 B：不注入，首次启动时自动生成随机口令并仅打印一次在日志里（grep bootstrap_password）。

计算口令 q1w2e3r4 的 SHA-256 哈希：

printf '%s' 'q1w2e3r4' | sha256sum

实测输出：

13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9

4.3.2 排障实录：运行中重置口令触发 DuckDB 锁冲突

系统已安装时重置口令的官方途径是 homer --reset-admin-password，它会读环境变量中的哈希写入 settings 库（DuckDB 单文件库）。该库是单写锁模型，服务运行中执行必然失败——以下是真实踩坑与正确流程。

错误操作（服务运行中直接重置）：

HOMER_COORDINATOR_AUTH_ADMIN_PASSWORD_HASH=13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9 \
  /usr/local/homer-core/bin/homer -config-path /usr/local/homer-core/etc/homer.json --reset-admin-password

实测报错（完整保留）：

reset-admin-password: open settings db: database/sql/driver: could not connect to database: IO Error: Could not set lock on file "/var/lib/homer/homer_settings.duckdb": Conflicting lock is held in /usr/local/homer-core/bin/homer (PID 172). See also https://duckdb.org/docs/stable/connect/concurrency

正确流程：先停服 → 重置 → 再启动：

systemctl stop homer-core
HOMER_COORDINATOR_AUTH_ADMIN_PASSWORD_HASH=13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9 \
  /usr/local/homer-core/bin/homer -config-path /usr/local/homer-core/etc/homer.json --reset-admin-password
systemctl start homer-core

实测输出：

admin password updated for user "admin" in settings DB

4.3.3 验证管理员登录

curl -s -X POST http://127.0.0.1:8080/api/v4/auth/sessions \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"q1w2e3r4"}'

实测返回（截取，JWT 为有效登录凭据）：

{"data":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwiYWRtaW4iOnRydWUsImlzcyI6ImhvbWVyLWNvcmUiLCJleHAiOjE3OTMxNDYyMzAsImlhdCI6MTc5MzA1OTgzMCwianRpIjoiY2FhMzJjNDNjZTFjMmViNzI5YmUyZWUwOTU1M2JlNjYifQ.tBXjaS-5P75RJ9EziWF_oTpBaa1az8ee46aOTEl7nBg","scope":"admin","user":{"admi

4.4 方案二：源码编译安装

需要定制或内网无法使用官方包时，可从源码编译。homer-core 使用 Go 开发，go.mod 声明 go 1.27.2。

4.4.1 获取源码

apt-get install -y git
git clone --depth 1 --branch 11.0.369 https://github.com/sipcapture/homer.git /usr/local/src/homer
cd /usr/local/src/homer/src

4.4.2 安装 Go 工具链

Ubuntu 22.04 官方源的 golang 为 1.18，低于要求。从官方下载 Go 1.27.2：

wget https://go.dev/dl/go1.27.2.linux-amd64.tar.gz
tar -C /usr/local -xzf go1.27.2.linux-amd64.tar.gz
export PATH=/usr/local/go/bin:$PATH

💡 技术拓展：Go 1.21+ 支持 GOTOOLCHAIN=auto——若手头 Go 版本略低（如 1.26.10），构建时自动下载并切换到 go.mod 声明的 1.27.2 工具链，无需手动替换。本文实测即采用该方式（宿有 Go 1.26.10，构建中自动升级）。

4.4.3 编译

模块化模式（四模块合一，等价官方 all-in-one）直接 go build；国内网络建议指定模块代理：

export GOPROXY=https://goproxy.cn,direct GOTOOLCHAIN=auto
go build -ldflags "-X main.VERSION_APPLICATION=11.0.369-srcbuild -X main.BuildDate=$(date +%Y-%m-%d)" -o /usr/local/bin/homer .
/usr/local/bin/homer version

实测输出：

TODO-COMPILE-VERSION

编译完成后可复用官方 systemd 单元（将 ExecStart 指向自编译二进制与配置路径），或参考仓库 examples/homer-core.service。

💡 技术拓展：Makefile 还有 homer-only（静态链接 luajit 的兼容构建）与 release（含前端构建）目标，面向发行版打包；日常自用 go build 即可。前端 UI 已随主程序内嵌，无需单独构建。

4.5 heplify 采集代理安装与配置

heplify 与 homer-core 同为单二进制，deb 安装即用。在被监控主机上（本文为同一台服务器环回演示）：

heplify -i lo -pr 5060-5090 -hs 127.0.0.1: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"

关键参数：-i 抓包网卡（生产环境为业务网卡如 eth0，本例环回演示用 lo）、-pr SIP 端口范围、-hs Homer 采集地址（生产填 Homer 服务器 IP）。Connected to HEP server 即表示采集链路建立。

生产环境建议写成 systemd 服务常驻运行。

五、安装后验证：注入第一条 SIP 流量

5.1 准备最小 SIP 环境

在服务器上安装 sipsak（轻量 SIP 测试工具）并启动一个最小 UAS 应答器（监听 UDP 5060，对收到的请求回 200 OK）：

apt-get install -y sipsak
nohup python3 /root/sip_responder.py > /root/uas.log 2>&1 &

mini-UAS 就绪输出：

mini-uas listening on udp/5060

5.2 发送 OPTIONS 与 REGISTER

sipsak -s sip:stress@127.0.0.1
sipsak -U -s sip:100@127.0.0.1

UAS 侧实测收到（截取）：

<-- from ('127.0.0.1', 46889): [b'', b'7.0.3:46087;branch=z9hG4bK.0a97ab62;rport;alias
From: sip:sipsak@172.17.0.3:46087;tag=2e5be014
To: sip:stress@127.0.0.1
Call-ID: 777773076@172.17.0.3
CSeq: 1 OPTIONS ...']
<-- from ('127.0.0.1', 50282): [b'', b'58349;branch=z9hG4bK.2c40b7ca;rport;alias
From: sip:100@127.0.0.1;tag=6679e729
To: sip:100@127.0.0.1
Call-ID: 1719265065@172.17.0.3
CSeq: 1 REGISTER ...']

heplify 捕获并封装为 HEPv3 投递到 9060，Homer 完成解析入库。用 Prometheus 指标确认（type="sip" 计数）：

curl -s http://127.0.0.1:9090/metrics | grep '^homer_packets_by_type_total'

实测输出：

homer_packets_by_type_total{node_id="2002",type="sip"} 12

5.3 REST 检索验证端到端闭环

TOKEN=$(curl -s -X POST http://127.0.0.1:8080/api/v4/auth/sessions \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"q1w2e3r4"}' | python3 -c 'import json,sys;print(json.load(sys.stdin)["data"]["token"])')
NOW=$(date +%s)000; FROM=$((NOW-3600000))
curl -s -X POST http://127.0.0.1:8080/api/v4/transactions/search \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"filter\":{\"proto_type\":1,\"event_type\":\"registration\"},\"timestamp\":{\"from\":$FROM,\"to\":$NOW}}" | python3 -m json.tool | head -30

实测返回（截取，REGISTER 200 OK 事务完整落库，含原始 payload）：

{
    "aor": "100@127.0.0.1",
    "data_extra": {
        "branch": "z9hG4bK.2c40b7ca",
        "cseq": "1 REGISTER",
        "node_name": "homer11-ubuntu22",
        "response_code": "200",
        "response_reason": "OK",
        "user_agent": "mini-uas/0.1",
        "via": "SIP/2.0/UDP 172.17.0.3:58349;branch=z9hG4bK.2c40b7ca;rport;alias"
    },
    "dst_ip": "127.0.0.1",
    "method": "200",
    "node_id": "2002",
    "payload": "SIP/2.0 200 OK\r\nVia: SIP/2.0/UDP 172.17.0.3:58349;branch=z9hG4bK.2c40b7ca;rport;alias\r\nFrom: sip:100@127.0.0.1;tag=6679e729\r\nTo: sip:100@127.0.0.1;tag=resp200\r\nCall-ID: 1719265065@172.17.0.3\r\nCSeq: 1 REGISTER\r\nUser-Agent: mini-uas/0.1\r\nContent-Length: 0\r\n\r\n",
    "response_code": "200",
    ...
}

命令行等价操作——内置 homer search 子命令（自动缓存 JWT 到 ~/.homer_token）：

/usr/local/homer-core/bin/homer search --host 127.0.0.1:8080 \
  --user admin --pass q1w2e3r4 --from 1h --event-type registration --format table

实测输出（截取，REGISTER 与 200 OK 成对出现）：

+--------------------------+---------+-----------------------+-----------+----------+-----------------------------+----------+----------+---------------+---------------+-----------+
| contact                  | node_id | session_id            | src_ip    | src_port | timestamp                   | method   | protocol | storage_lake  | aor           | dst_port  |
+--------------------------+---------+-----------------------+-----------+----------+-----------------------------+----------+----------+---------------+---------------+-----------+
|                          | 2002    | 1719265065@172.17.0.3 | 127.0.0.1 | 5060     | 2026-10-27T00:11:28.664649Z | 200      | 17       | homer_lake    | 100@127.0.0.1 | 50282     |
| sip:100@172.17.0.3:58349 | 2002    | 1719265065@172.17.0.3 | 127.0.0.1 | 50282    | 2026-10-27T00:11:28.664412Z | REGISTER | 17       | homer_lake    | 100@127.0.0.1 | 5060      |
+--------------------------+---------+-----------------------+-----------+----------+-----------------------------+----------+----------+---------------+---------------+-----------+

至此"heplify 抓包 → HEP 投递 → 解析入库 → REST/CLI 检索"全链路闭环。

六、配置说明（最小集）

安装后的关键配置落点（参数逐项详解见本专栏《SIPCAPTURE Homer 11 配置参数详解》）：

落点说明
/usr/local/homer-core/etc/homer.json主配置文件，含 ingest/storage/node/coordinator/log/prometheus 六大段
/var/lib/homer/homer_settings.duckdbsettings 库（用户、仪表盘），单写锁，运维操作需先停服
/data/homer/parquet 与 /data/homer/homer_catalog.sqliteDuckLake 数据湖（Parquet 数据文件 + SQLite catalog）
/etc/systemd/system/homer-core.service服务单元；改口令环境变量可在此文件加 Environment=
端口9060(HEP)/9080(HTTP ingest)/8080(API+UI)/50051(gRPC)/9090(metrics)

常用服务管理命令：

systemctl start|stop|restart|status homer-core
journalctl -u homer-core -f          # 实时日志

七、排障实录汇总

本文实测过程中踩到并解决的三类典型问题：

7.1 运行中重置口令报 Conflicting lock

现象与解法见 4.3.2。根因：homer_settings.duckdb 为 DuckDB 单文件库，单写锁模型；--reset-admin-password 与常驻服务互斥。任何绕过服务的 settings 库运维（备份除外）都应先 systemctl stop homer-core。

7.2 deb 安装后服务起不来：缺少正式配置

deb 包只提供 homer.json.example。未复制配置直接 systemctl start 时服务无法读取配置。解法：先 cp /usr/local/homer-core/etc/homer.json.example /usr/local/homer-core/etc/homer.json 再启动（见 4.2.1）。

7.3 注入流量后检索返回空

实测中注入 sipsak 流量后立即调用搜索接口返回 {"data":{"items":[]}}，数十秒后同一查询即返回数据。根因：Homer 11 的写入路径是"内存缓冲 → 批量落盘"（默认 batch_size=25000 或 flush_interval_sec=30 触发 flush）；小流量测试未凑满批次，需等 flush 周期。验证方法：curl -s http://127.0.0.1:9090/metrics | grep flushed_rows_total 出现计数后即可检索到。生产排查时同理，先确认指标计数再查检索。

八、常见问题

Q1：如何查询最新稳定版本号？ 访问 https://github.com/sipcapture/homer/releases ，页面顶端即最新 Release；或用 curl -s https://api.github.com/repos/sipcapture/homer/releases/latest | grep tag_name。

Q2：忘记 admin 口令怎么办？ 按 4.3.2 流程：停服 → 带 HOMER_COORDINATOR_AUTH_ADMIN_PASSWORD_HASH 执行 homer --reset-admin-password → 启动。若是全新部署且丢失了首启随机口令，同样用该流程覆盖。

Q3：heplify 抓不到包？ 检查三点：网卡名是否正确（-i）；BPF 端口范围是否覆盖业务端口（-pr）；Homer 侧 9060 是否可达（nc -zvu <homer_ip> 9060）。heplify 日志出现 Connected to HEP server 且 Homer 指标 homer_packets_by_type_total 有增长即为通。

Q4：与 Homer 7 的 heplify-server 配置能否直接迁移？ 不能直接复用。Homer 11 用单一 homer.json 替代了 heplify-server 的 yaml + homer-app 的 PostgreSQL 配置体系；建议用 homer wizard --profile all-in-one 生成模板后对照迁移。HEP 代理（heplify）无需改动，仅 -hs 指向新服务地址。

Q5：如何升级到新版？ 下载新版本 deb 后直接 dpkg -i 覆盖安装，systemctl restart homer-core。数据湖文件向后兼容，升级前建议按 C1 篇的方法备份 settings 库与 catalog。

九、卸载与清理

systemctl disable --now homer-core
dpkg -P homer-core heplify
rm -rf /usr/local/homer-core /var/lib/homer /var/log/homer /data/homer

dpkg -P 会移除软件包及其 systemd 单元；/data/homer（数据湖）与 /var/lib/homer（settings 库）为数据目录，删除前确认无需保留历史话单。

十、参考链接