SIP3 2026.2.1 Ubuntu 22.04 安装指南

一、环境信息

项目	内容
服务器	主机名 `sip3-server`，IP `10.89.59.10`（SIP 话务侧另有 `10.89.59.1` 作为信令源）
操作系统	Ubuntu Server 22.04 LTS（x86_64，最小化安装）
SIP3 版本	2026.2.1-1（apt 软件源，2026-10-26 实测最新）
Java 运行时	sip3-java 25.0.2-10（SIP3 专用 JDK，随组件自动安装）
存储组件	MongoDB 7.0.45、InfluxDB 1.8.10、Grafana 13.2.4
网络前提	服务器能接收 SIP 流量（本文以 UDP 5060 为例），可访问 repo.sip3.io、repo.mongodb.org、download.influxdata.com、apt.grafana.com
实测日期	2026-10-26

本文全程在 root 账号下操作。SIP3 官方安装指南明确 apt 路径仅支持 Debian ≥ 10 与 Ubuntu 20.04/22.04/22.10。

二、安装前准备

SIP3 CE 由四个 Java 组件（Captain/Salto/Twig/Hoof）加三个存储组件（MongoDB/InfluxDB/Grafana）组成。本文采用官方推荐的单机单体部署：四组件与存储全部安装在同一台服务器上，Captain 通过 libpcap 抓取本机网卡上的 SIP 流量。

先更新系统并安装基础工具：

root@sip3-server:~# apt-get update && apt-get install -y gnupg curl ca-certificates nginx libpcap0.8

三、配置 SIP3 软件源

3.1 导入签名密钥

root@sip3-server:~# curl -s https://repo.sip3.io/apt/keyFile | gpg --batch --dearmor -o /usr/share/keyrings/sip3-archive-keyring.gpg

3.2 添加 CE 与 Java 两个源

root@sip3-server:~# echo "deb [ arch=all signed-by=/usr/share/keyrings/sip3-archive-keyring.gpg ] https://repo.sip3.io/apt/ ce contrib" > /etc/apt/sources.list.d/sip3.list
root@sip3-server:~# echo "deb [ signed-by=/usr/share/keyrings/sip3-archive-keyring.gpg ] https://repo.sip3.io/apt/java/ all contrib" > /etc/apt/sources.list.d/sip3-java.list
root@sip3-server:~# apt-get update

刷新后确认可安装版本（2026-10-26 实测）：

root@sip3-server:~# apt-cache policy sip3-captain-ce sip3-salto-ce sip3-twig-ce sip3-hoof-ce sip3-java | grep -E "^sip3|Candidate:"
sip3-captain-ce:
  Candidate: 2026.2.1-1
sip3-salto-ce:
  Candidate: 2026.2.1-1
sip3-twig-ce:
  Candidate: 2026.2.1-1
sip3-hoof-ce:
  Candidate: 2026.2.1-1
sip3-java:
  Candidate: 25.0.2-10

四、安装 SIP3 组件

一条命令安装全部四个组件：

root@sip3-server:~# apt-get install -y sip3-captain-ce sip3-salto-ce sip3-twig-ce sip3-hoof-ce

安装完成后核对包与产物布局：

root@sip3-server:~# dpkg -l | grep -E "sip3" | awk '{print $2, $3}'
sip3-captain-ce  2026.2.1-1
sip3-hoof-ce     2026.2.1-1
sip3-java        25.0.2-10
sip3-salto-ce    2026.2.1-1
sip3-twig-ce     2026.2.1-1
root@sip3-server:~# ls /opt/
sip3-captain  sip3-java  sip3-salto  sip3-twig

各组件产物位置：

组件	程序	配置目录	systemd 单元
Captain	/opt/sip3-captain/sip3-captain.jar	/etc/sip3-captain/	sip3-captain.service（另有 sip3-captain-interface@.service 模板）
Salto	/opt/sip3-salto/sip3-salto.jar	/etc/sip3-salto/	sip3-salto.service
Twig	/opt/sip3-twig/sip3-twig.jar	/etc/sip3-twig/	sip3-twig.service
Hoof	/var/www/sip3-hoof（静态文件）	—	无（由 nginx 托管，见 6.4）

五、安装存储组件

5.1 MongoDB 7.0

root@sip3-server:~# curl -fsSL https://pgp.mongodb.com/server-7.0.asc | gpg --batch --dearmor -o /usr/share/keyrings/mongodb-server-7.0.gpg
root@sip3-server:~# echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" > /etc/apt/sources.list.d/mongodb-org-7.0.list
root@sip3-server:~# apt-get update && apt-get install -y mongodb-org

5.2 InfluxDB 1.8.10

SIP3 通过 InfluxDB 的 v1 HTTP API（db 参数）写指标，需要 1.x 版本。实测 Ubuntu 22.04 下 influxdata 源的 influxdb（1.13.1）deb 包安装脚本在最小化系统上会失败，因此改用官方二进制包部署（与 SIP3 官方 Ansible 工程的 v1 布局一致）：

root@sip3-server:~# curl -fsSL -o /tmp/influxdb.tar.gz https://download.influxdata.com/influxdb/releases/influxdb-1.8.10_linux_amd64.tar.gz
root@sip3-server:~# tar -C /opt -xzf /tmp/influxdb.tar.gz && rm /tmp/influxdb.tar.gz
root@sip3-server:~# cp /opt/influxdb-1.8.10-1/usr/bin/{influxd,influx,influx_inspect} /usr/bin/
root@sip3-server:~# mkdir -p /etc/influxdb /var/lib/influxdb
root@sip3-server:~# cp /opt/influxdb-1.8.10-1/etc/influxdb/influxdb.conf /etc/influxdb/

创建 systemd 单元：

root@sip3-server:~# cat > /etc/systemd/system/influxdb.service <<'EOF'
[Unit]
Description=InfluxDB 1.8.10 time-series database
After=network.target

[Service]
ExecStart=/usr/bin/influxd -config /etc/influxdb/influxdb.conf
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF
root@sip3-server:~# systemctl daemon-reload

5.3 Grafana

root@sip3-server:~# curl -fsSL https://apt.grafana.com/gpg.key | gpg --batch --dearmor -o /usr/share/keyrings/grafana.gpg
root@sip3-server:~# echo "deb [ signed-by=/usr/share/keyrings/grafana.gpg ] https://apt.grafana.com stable main" > /etc/apt/sources.list.d/grafana.list
root@sip3-server:~# apt-get update && apt-get install -y grafana

5.4 启动存储服务并创建数据库

root@sip3-server:~# systemctl enable --now mongod influxdb grafana-server
root@sip3-server:~# systemctl is-active mongod influxdb grafana-server
active
active
active
root@sip3-server:~# influx -execute "CREATE DATABASE sip3"
root@sip3-server:~# influx -execute "SHOW DATABASES" | tail -3
name: databases
name
----
sip3

六、基础配置

重要：apt 包安装后的配置文件采用"全注释"形态，不会自动生效。 三个 Java 组件的 /etc/sip3-*/application.yml 中所有段落默认被注释，JVM 参数文件 /etc/sip3-*/environment.conf 为 0 字节空文件，必须手工写入，否则服务无法正常工作（实测 Salto 在无 Mongo 配置时会因 MongoCollectionManager 空指针反复重启）。

6.1 配置 JVM 参数（三组件统一）

systemd 单元按 $JAVA_HOME/bin/java $JAVA_XMS $JAVA_XMX $JAVA_GC $JAVA_OTHER 启动，全部取自 environment.conf。为四个组件写入相同内容（演示环境下调堆内存）：

root@sip3-server:~# for comp in captain salto twig; do
  cat > /etc/sip3-$comp/environment.conf <<'EOF'
JAVA_HOME=/opt/sip3-java
JAVA_XMS=-Xms256m
JAVA_XMX=-Xmx512m
JAVA_GC=-XX:+UseG1GC
EOF
done

6.2 激活 Salto 配置

Salto 需要显式声明数据接收端口、MongoDB、InfluxDB 与集合分片规则。注意 2026.2.1 的管理端口默认值为 15091（不是旧文档的 15090），该端口必须与 Captain 的 management.uri 一致（见 6.3）：

root@sip3-server:~# cat > /etc/sip3-salto/application.yml <<'EOF'
#! Name
name: sip3-salto

#! Server
server:
  uri: udp://0.0.0.0:15060
  buffer_size: 65535

#! Management socket
management:
  uri: udp://0.0.0.0:15091
  expiration_delay: 60000
  expiration_timeout: 120000

#! MongoDB
mongo:
  uri: mongodb://127.0.0.1:27017
  db: sip3
  bulk_size: 1
  update_period: 300000
  collections:
    - prefix: attributes
      indexes:
        hashed: [name]
      max_collections: 30
    - prefix: sip_call_index
      indexes:
        ascending: [created_at, terminated_at, src_addr, dst_addr, caller, callee, state, error_code, duration]
        hashed: [call_id]
      max_collections: 30
    - prefix: sip_call_raw
      indexes:
        ascending: [created_at]
        hashed: [call_id]
      max_collections: 30
    - prefix: unknown_raw
      indexes:
        ascending: [created_at]
        hashed: [call_id]
      max_collections: 30

#! Metrics
metrics:
  influxdb:
    uri: http://127.0.0.1:8086
    db: sip3

#! Application
time_suffix: yyyyMMdd

sip:
  message:
    exclusions:
      - REGISTER
EOF

6.3 激活 Captain 抓包配置

把 dev 指向接收 SIP 流量的网卡（本文 eth0），BPF 过滤器只放行 SIP 端口；sender/management 指向本机 Salto（management 必须是 15091）：

root@sip3-server:~# cat > /etc/sip3-captain/application.yml <<'EOF'
#! Name
name: sip3-captain

#! Pcap (libpcap, WinPcap, Npcap)
pcap:
  dev: eth0
  sll: false
  bpf_filter: udp and port 5060
  snaplen: 65535
  buffer_size: 2097152
  timeout_millis: 1

#! Sender
sender:
  uri: udp://127.0.0.1:15060
  reconnection_timeout: 1000

#! ManagementSocket
management:
  uri: udp://127.0.0.1:15091
  register_delay: 60000

#! Metrics
metrics:
  logging:
    step: 5000
EOF

Twig 的 /etc/sip3-twig/application.yml 默认已包含可用配置（8080 端口、/api 上下文、MongoDB 127.0.0.1:27017），无需修改。

6.4 配置 nginx（Hoof 界面）

Hoof 是静态前端，需要 nginx 反代 Twig API 与 Grafana。写入站点配置：

root@sip3-server:~# cat > /etc/nginx/conf.d/sip3-hoof.conf <<'EOF'
server {
    listen 80 default_server;
    server_name _;

    root /var/www/sip3-hoof;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location /grafana/ {
        proxy_pass http://127.0.0.1:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
EOF
root@sip3-server:~# nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
root@sip3-server:~# systemctl restart nginx

6.5 Grafana 管理密码

将 Grafana 管理账号密码改为本文统一演示口令：

root@sip3-server:~# grafana cli --homepath /usr/share/grafana admin reset-admin-password q1w2e3r4

七、启动与验证

7.1 启动三个 Java 服务

root@sip3-server:~# systemctl enable --now sip3-salto sip3-twig sip3-captain
root@sip3-server:~# systemctl is-active sip3-salto sip3-twig sip3-captain
active
active
active

7.2 端口核验

root@sip3-server:~# ss -lnutp | grep -E "15060|15091|8080|8086|27017|:80 " | awk '{print $1, $5}'
tcp   0.0.0.0:80
tcp   127.0.0.1:27017
udp   0.0.0.0:15060
udp   0.0.0.0:15091
tcp   *:8080
tcp   *:8086

7.3 JVM 参数核验

root@sip3-server:~# ps aux | grep "[j]ava" | grep -oE "^\S+\s+\S+.*-Xms\S+\s+-Xmx\S+" | head -3
sip3     /opt/sip3-java/bin/java -Xms256m -Xmx512m
sip3     /opt/sip3-java/bin/java -Xms256m -Xmx512m
sip3     /opt/sip3-java/bin/java -Xms256m -Xmx512m

7.4 注入 SIP 信令验证采集闭环

从话务侧主机（10.89.59.1）向服务器发一条 SIP INVITE（注意：在本机向本机地址发包走回环口，libpcap 的 eth0 抓不到，必须从外部主机发送）：

root@pbx:~# python3 - <<'EOF'
import socket
msg = ("INVITE sip:1002@10.89.59.10 SIP/2.0\r\n"
"Via: SIP/2.0/UDP 10.89.59.1:5060;branch=z9hG4bK-test1\r\n"
"From: <sip:1001@10.89.59.1>;tag=abc123\r\n"
"To: <sip:1002@10.89.59.10>\r\n"
"Call-ID: test-call-001@10.89.59.1\r\n"
"CSeq: 1 INVITE\r\n"
"Contact: <sip:1001@10.89.59.1:5060>\r\n"
"Max-Forwards: 70\r\n"
"Content-Length: 0\r\n\r\n")
socket.socket(socket.AF_INET, socket.SOCK_DGRAM).sendto(msg.encode(), ("10.89.59.10", 5060))
EOF

约 10 秒后在 MongoDB 中确认呼叫被聚合：

root@sip3-server:~# mongosh --quiet sip3 --eval 'db.sip_call_index_20261026.find({}, {call_id:1, caller:1, callee:1, state:1}).limit(3).forEach(printjson)'
{
  _id: ObjectId('6adfefee918919586d5e87eb'),
  call_id: 'test-call-001@10.89.59.1',
  caller: '1001',
  callee: '1002',
  state: 'unknown'
}

集合名按日期分片（sip_call_index_20261026 等），Salto 在收到首条数据时自动创建。

7.5 访问界面与 API

入口	地址	说明
Hoof 界面	http://10.89.59.10/	呼叫搜索、呼叫流程图
Grafana	http://10.89.59.10/grafana/	服务指标仪表盘（admin / q1w2e3r4）
Twig OpenAPI 描述	http://10.89.59.10/api/v3/api-docs	REST API 元数据（实测返回 200）
Twig API（经 nginx）	http://10.89.59.10/api/...	与 8080 直连等价

八、常见问题

8.1 服务起不来，日志报 MongoCollectionManager 空指针

原因：apt 包默认的 /etc/sip3-salto/application.yml 全部处于注释状态，Mongo 段为空。按 6.2 写入激活配置后 systemctl restart sip3-salto。

8.2 Captain 抓不到包，MongoDB 无呼叫记录

依次排查三点：

management 端口不匹配：2026.2.1 中 Salto 管理端口默认 15091，若 Captain 的 management.uri 仍写旧值 15090，Captain 只能打开数据通道而无法完成注册（实测现象：Sender 连接打开但无呼叫入库）。两侧必须一致。
流量走了回环口：在本机对本机 IP 发包走 lo，pcap.dev: eth0 抓不到。应从外部主机发送测试流量，或将 dev 改为 lo。
BPF 过滤器：bpf_filter: udp and port 5060 只抓 5060 端口的 UDP；测试环境 SIP 端口不同时要同步调整。

8.3 jps 找不到

sip3-java 是裁剪版 JDK，不含 jps。核验 JVM 参数改用 ps aux | grep java。

8.4 influxdb deb 包安装失败

Ubuntu 22.04 上 influxdata 源的 influxdb 1.13.1 deb 包在最小化系统实测安装脚本报错。改按 5.2 的官方二进制方式部署 1.8.10。

8.5 集合索引未生成（引号写法坑）

若 6.2 配置里 collections 的 indexes 值写成带引号字符串（如 ascending: "[created_at, ...]"），Salto 会静默跳过建索引——getIndexes() 只剩 _id_，检索功能正常但数据量大后全表扫描。必须用 YAML 流式列表写法（ascending: [created_at, ...]），本文 6.2 已按正确写法给出。修复后 systemctl restart sip3-salto，索引会对已存在分片一并补建（实测验证），逐项含义见配置参数详解 3.3 与 10.6。

九、参考链接

官方安装指南：https://sip3.io/documentation/
SIP3 软件源：https://repo.sip3.io
MongoDB 仓库：https://repo.mongodb.org
InfluxDB 下载：https://download.influxdata.com/influxdb/releases/
Grafana 仓库：https://apt.grafana.com
本专栏部署篇：https://www.quzuo.net/document/C5WeLhZIbIpK
本专栏镜像部署篇：https://www.quzuo.net/document/GcOCvkAnJl6o
本专栏配置篇：https://www.quzuo.net/document/Ws3fH3mFueEd
本专栏 API 篇：https://www.quzuo.net/document/0Oxnl7ike1iB