SIP3 2026.2.1 配置参数详解

目标：系统梳理 SIP3 社区版 2026.2.1（deb 路线）四组件的全部配置文件与参数项——JVM 启动层、应用配置层、日志层、运行时层逐层拆解，并给出 MongoDB 集合分片模型、InfluxDB 指标、Grafana 数据源三项存储对接的实测验证。所有参数默认值取自 repo.sip3.io 的 2026.2.1-1 软件包内置配置原文，全部回显在本机实测栈（主机名 sip3-server，IP 10.89.59.10）采集（实测日期 2026-10-27）。

一、配置体系总览

1.1 四层配置模型

SIP3 每个 Java 组件（Captain/Salto/Twig）的配置分四层，各管一件事：

Hoof 是静态前端，自身无 application.yml，其行为由 nginx 站点配置决定（见第六节）。

1.2 配置文件清单

三组件在 /etc 下的文件实测清单（含尺寸）：

root@sip3-server:~# ls -la /etc/sip3-salto/ /etc/sip3-captain/ /etc/sip3-twig/ | grep -v '^total\|^d'
/etc/sip3-captain/:
-rw-r--r-- 1 root root  395 Oct 27 01:52 application.yml
-rw-r--r-- 1 root root   82 Oct 27 00:17 environment.conf
-rw-r--r-- 1 root root 1504 Oct 27 01:53 logback.xml
-rw-r--r-- 1 root root  414 Sep  7 14:24 vertx-options.json

/etc/sip3-salto/:
-rw-r--r-- 1 root root 1035 Oct 27 01:52 application.yml
-rw-r--r-- 1 root root 1240 Sep  7 14:24 codecs.yml
-rw-r--r-- 1 root root   82 Oct 27 00:17 environment.conf
-rw-r--r-- 1 root root 1496 Sep  7 14:24 logback.xml
-rw-r--r-- 1 root root  414 Sep  7 14:24 vertx-options.json

/etc/sip3-twig/:
-rw-r--r-- 1 root root 1271 Oct 27 01:53 application.yml
-rw-r--r-- 1 root root  430 Sep  7 14:24 banner.txt
-rw-r--r-- 1 root root   82 Oct 27 00:17 environment.conf
-rw-r--r-- 1 root root  827 Sep  7 14:24 logback.xml

带日期的文件是本环境改写过的（application.yml、environment.conf、captain 的 logback.xml），带 Sep 7 时间戳的是软件包原生文件。Twig 多一个 banner.txt（启动横幅），Salto 多一个 codecs.yml（RTP 编解码目录），Captain 无 codecs.yml（它只抓包不评 MOS）。

1.3 段注释语法 #!

application.yml 用 #! 标注段名（如 #! Server），纯注释行用 #。deb 包内置的默认配置是全注释形态——只有 name/version 两行生效，其余段全部处于 # 注释状态，这是《SIP3 2026.2.1 Ubuntu 22.04 安装指南》6.2 节必须手工「激活」配置的原因。修改任何 application.yml 后重启对应服务生效：

root@sip3-server:~# systemctl restart sip3-salto

logback.xml 例外：scan="true" scanPeriod="60 seconds"，改日志配置 60 秒内自动生效，无需重启。

二、JVM 启动层（environment.conf）

2.1 systemd 启动模板

以 Salto 的服务单元为例（Captain/Twig 同构，仅路径不同）：

[Service]
User=sip3
Group=sip3
EnvironmentFile=-/etc/sip3-salto/environment.conf
ExecStart=/bin/sh -c '\
$JAVA_HOME/bin/java \
  $JAVA_XMS $JAVA_XMX $JAVA_GC $JAVA_OTHER \
 -Dlogback.configurationFile=/etc/sip3-salto/logback.xml \
 -jar /opt/sip3-salto/sip3-salto.jar \
 -Dconfig.location=/etc/sip3-salto/application.yml \
 -Dcodecs.location=/etc/sip3-salto/codecs.yml \
  $UDF_OPTS \
 -Dvertx.cacheDirBase=/tmp/sip3-salto \
 $APP_OPTS \
 $VERTX_OPTS \
 & echo $! > /run/sip3-salto/sip3-salto.pid'
Restart=on-failure
RestartSec=10

要点：EnvironmentFile=- 前缀表示文件可缺失（缺失不报错，但 JVM 走默认堆）；$JAVA_OTHER、$UDF_OPTS、$APP_OPTS、$VERTX_OPTS 是四个预留口——JAVA_OTHER 追加 JVM 参数（如 -Duser.timezone=Asia/Shanghai），后三个分别向 UDF 脚本、应用、Vert.x 传参，environment.conf 里不写即为空。

2.2 变量表与生效验证

三组件内容一致（实测）：

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

运行中进程复核（回显与《安装指南》6.1 一致）：

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

三、Salto 参数详解（/etc/sip3-salto/application.yml）

Salto 是数据聚合核心，参数最多。以下逐段给出 2026.2.1-1 包内默认值（未标注的均为包内默认）与本环境的激活写法。

3.1 server（数据接收）

3.2 management（管理通道）

3.3 mongo（呼叫数据落库）

本环境激活写法（《安装指南》6.2）与包内默认的对照：

集合分片模型是 Salto 配置的重头。包内默认定义了 13 个前缀，按天分片（time_suffix: yyyyMMdd 拼接在集合名后）：

每个前缀还带 max_collections: 30（保留 30 天分片，滚动删除最旧）与可选 hint（call_id: hashed 指定查询提示）。索引字段表意味着：检索条件里能用的字段就是 ascending 列表里的这些，自定义扩展需同步改配置重建索引。本环境按最小可用原则只激活了 attributes/sip_call_index/sip_call_raw/unknown_raw 四个（unknown_raw 承接未归类报文），生产环境按需照包内默认抄全。

3.4 metrics（服务指标）

三个指标后端可并存，至少启用一个。本环境走 influxdb（实测验证见 8.2）。

3.5 sip（SIP 聚合规则）

3.6 media / udf / attributes / 杂项

3.7 查看生效配置

启动日志第一屏会打印渲染后的完整生效配置（JSON 形态），排障时先看它：

root@sip3-server:~# journalctl -u sip3-salto -b --no-pager | grep -A5 '"name"'

四、Captain 参数详解（/etc/sip3-captain/application.yml）

Captain 只做抓包与转发，参数围绕 pcap 与出口。

4.1 pcap（抓包）

4.2 数据出口与协议开关

4.3 host（本机身份声明）与 management

五、Twig 参数详解（/etc/sip3-twig/application.yml）

Twig 的默认配置开箱即生效（不像 Salto/Captain 全注释），是 Spring Boot 多文档 YAML（段间用 --- 分隔）。包内默认全文即为运行配置：

调优提示：session.default_limit 是界面每次检索的默认条数上限；mongo.max_execution_time 拉长可容忍大时间窗查询；security.enabled 打开后 Twig 校验 Grafana 会话（security.grafana.url 指向 Grafana 用户接口），实现界面单点登录。

六、Hoof 与 nginx 配置

Hoof 是静态前端（/var/www/sip3-hoof），nginx 站点配置就是它的全部行为（《安装指南》6.4 已给出全文），三个 location 各司其职：

改 Twig 端口或上下文时，nginx 的 /api/ 与 Twig 的 server.servlet.context_path 必须成对改；改 Grafana 的 root_url 时同理。nginx 改后 nginx -t && systemctl reload nginx。

七、日志与运行时层

7.1 logback.xml

Salto 默认双 appender（Captain/Twig 结构相同、路径不同）：

调整日志级别改 <logger name="io.sip3" level="INFO"> 一行即可，60 秒热扫描生效（DEBUG 排障后记得改回）。metrics.log 是指标写日志通道（配合 metrics.logging），磁盘紧张时可在 logback 中把该 appender 级别上调。

7.2 vertx-options.json

{
  "metricsOptions": {
    "enabled": false,
    "jvmMetricsEnabled": false,
    "labels": ["EB_ADDRESS", "EB_FAILURE", "EB_SIDE", "LOCAL", "REMOTE", "POOL_TYPE", "POOL_NAME", "CLASS_NAME"],
    "influxDbOptions": {
      "enabled": true,
      "uri": "http://127.0.0.1:8086",
      "db": "sip3",
      "step": 5,
      "retention-duration": "7d"
    }
  }
}

Vert.x 框架级指标（enabled/jvmMetricsEnabled）默认关闭；influxDbOptions 是 Salto 业务指标的第二通道（step 单位为秒）。保持默认即可，勿把 influxDbOptions.enabled 改 false——业务指标会断流。

7.3 codecs.yml（仅 Salto）

RTP 编解码目录，按 ITU-T G.113 与 RFC 3551 维护，是 MOS/R 因子计算的依据。每条目必含 name（对齐 SDP 中的编解码名）、payload_types、clock_rate、ie（设备损伤因子）、bpl（丢包鲁棒因子）：

codecs:
  - name: PCMA
    payload_types: [ 8 ]
    clock_rate: 8000
    ie: 0
    bpl: 4.3

话务环境用到非默认编解码时在此追加条目；漏配的编解码不影响抓包，但该流不出质量分。

八、存储对接实测

8.1 MongoDB：集合分片与索引核验

按 3.3 的 collections 配置，数据按天落片。本环境实测集合名：

root@sip3-server:~# mongosh --quiet sip3 --eval 'db.getCollectionNames().sort()'
[
  'attributes_20261027',
  'components',
  'sip_call_index_20261027',
  'sip_call_raw_20261027',
  'sip_register_index_20261027',
  'sip_register_raw_20261027',
  'unknown_raw_20261027'
]

索引声明必须用 YAML 列表写法，不能加引号——这是本环境实测踩到的一个真坑。初始激活配置把索引写成了带引号字符串（ascending: "[created_at, ...]"），Salto 启动后集合里只有 _id_ 一个默认索引；把引号去掉改成流式列表（ascending: [created_at, ...]）并重启后，索引全部补建成功（含已存在的旧分片）：

root@sip3-server:~# grep -n 'ascending\|hashed' /etc/sip3-salto/application.yml
  ascending: [created_at, terminated_at, src_addr, dst_addr, caller, callee, state, error_code, duration]
  hashed: [call_id]
root@sip3-server:~# systemctl restart sip3-salto
root@sip3-server:~# mongosh --quiet sip3 --eval 'db.sip_call_index_20261027.getIndexes().map(i=>i.name)'
[
  '_id_',
  'created_at_1',
  'terminated_at_1',
  'src_addr_1',
  'dst_addr_1',
  'caller_1',
  'callee_1',
  'state_1',
  'error_code_1',
  'duration_1',
  'call_id_hashed'
]

（ascending 列表里的每个字段生成一个单字段升序索引，hashed 列表生成同名哈希索引；sip_call_raw 实测为 _id_ / created_at_1 / call_id_hashed 三索引，attributes 实测为 _id_ / name_hashed。）带引号的字符串写法不报错、静默不建索引，小数据量毫无感知，数据一大查询就退化成全表扫描——务必用列表写法。另外注意：未在 collections 里声明的段也可能建集合——本环境只声明了 4 个前缀，sip_register_index/raw 两片仍随注册数据流入被自动创建（走默认索引），声明的作用是定制索引与保留策略，而非开关集合。

8.2 InfluxDB：指标落地核验

Salto→InfluxDB 指标通道实测（库 sip3）：

root@sip3-server:~# influx -database sip3 -execute "SHOW MEASUREMENTS"
name: measurements
name
----
packets_decoded
packets_processed
packets_received
packets_routed
sip_call_attempts
sip_call_messages
sip_call_retransmits
sip_call_transactions
sip_register_messages

（回显节选（实测首尾）：另有 sip_register_attempts 等注册侧指标。）packets_* 四项是 Captain 数据面指标，sip_call_/sip_register_ 是 Salto 聚合指标——两条链路都健康。

8.3 Grafana：数据源预置实测

Grafana 用 provisioning 目录声明式管理数据源（比界面手点可复制、可审计）。写入 /etc/grafana/provisioning/datasources/sip3.yml：

apiVersion: 1

datasources:
 - name: Sip3
   type: influxdb
   access: proxy
   url: http://127.0.0.1:8086
   database: sip3
   isDefault: true
   jsonData:
     timeInterval: 1s

systemctl restart grafana-server 后从 API 核验（管理口令改法见《安装指南》6.5）：

root@sip3-server:~# curl -s -u admin:q1w2e3r4 http://127.0.0.1:3000/api/datasources
[{"id":1,"uid":"P7A1C86AEE7F2EC26","orgId":1,"name":"Sip3","type":"influxdb","typeName":"InfluxDB","typeLogoUrl":"public/plugins/influxdb/img/influxdb_logo.svg","access":"proxy","url":"http://127.0.0.1:8086","user":"","database":"sip3","basicAuth":false,"isDefault":true,"jsonData":{"timeInterval":"1s"},"readOnly":true}]

服务日志同步记录加载行为：

root@sip3-server:~# journalctl -u grafana-server | grep "inserting datasource"
... logger=provisioning.datasources ... msg="inserting datasource from configuration" name=Sip3 uid=P7A1C86AEE7F2EC26

（输出节选（实测首尾）：省略时间戳等前缀字段，关键是 msg 与 name=Sip3。）

注意 readOnly: true——预置的数据源不能在界面编辑/删除，改参数必须改文件重启（FAQ 10.4）。仪表盘 JSON 可放 /etc/grafana/provisioning/dashboards/ 用文件提供者加载（做法见《SIP3 2025.2.1 Docker Compose 部署指南》4.1，deb 路线同构）。

九、镜像路线环境变量对照

官方镜像（2025.2.1）用环境变量 + Jinja2 模板渲染出同一套 application.yml，变量名与 deb 配置键一一对应（机制详见《SIP3 2025.2.1 Docker Compose 部署指南》2.2）。常用对照：

镜像线变量名规律：组件名 + 配置段驼峰拼接。同一套调优思路（3.33.6、4.14.3 的键值含义）在两条路线完全通用。

十、常见问题（FAQ）

10.1 首次启动失败：配置全注释

deb 包内置 application.yml 仅 name/version 生效，Salto 无 Mongo 配置时因 MongoCollectionManager 空指针反复重启（Restart=on-failure 每 10 秒重试）。按《安装指南》6.2/6.3 激活最小配置即可。

10.2 Captain 与 Salto 的管理端口配对

2026.2.1 的 Salto 包内默认 management.uri 是 15091，Captain 包内默认仍是 15090——两个默认值不相等，直接各自用默认会互相找不到。两端改成同一个值（本文统一 15091），这是从旧版本升级时最容易踩的坑。

10.3 version 字段显示 2026.1.1-SNAPSHOT

2026.2.1-1 包内置默认配置里 version: 2026.1.1-SNAPSHOT 是打包时的应用构建串（实测两处一致：salto/captain 默认文件第三行）。以 apt 包版本号 2026.2.1-1 与 Twig 启动横幅为准，不影响功能。

10.4 Grafana 预置数据源 readOnly:true

provisioning 创建的数据源在界面锁定编辑（API 也拒改），调整参数走「改 yml → 重启 grafana-server」；要从界面手工管理的场景就不放 provisioning 文件。

10.5 Twig 检索超时

大时间窗查询报超时时按序调三处：mongo.max_execution_time（默认 10000）、mongo.batch_size（默认 128）、session.default_limit（默认 50），并确认 MongoDB 侧索引与 3.3 的声明一致（查询字段必须在 ascending 索引清单内）。

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

现象： mongosh 查 getIndexes() 只见 _id_，检索仍能用但越用越慢。原因：collections 段的 indexes 值写成了带引号字符串（ascending: "[created_at, ...]"），Salto 按字符串解析无法展开字段清单，静默跳过建索引。修复：去掉引号改为 YAML 流式列表（ascending: [created_at, ...]），systemctl restart sip3-salto 后索引对已存在的分片一并补建（实测见 8.1）。

十一、参考链接

• 官方文档：https://sip3.io/documentation/
• GitHub 组织：https://github.com/sip3io
• 软件源：https://repo.sip3.io
• 本专栏安装篇：https://www.quzuo.net/document/sk2pjogv1eNG
• 本专栏镜像部署篇：https://www.quzuo.net/document/GcOCvkAnJl6o
• 本专栏 API 篇：https://www.quzuo.net/document/0Oxnl7ike1iB