Kamailio 6.1 配置参数详解

Kamailio 6.1 配置参数详解：核心全局参数、内存、tm 事务定时器、registrar/usrloc 注册、rr/acc 等模块参数逐类实测，特性开关体系与运行时动态修改验证。

KamailioKamailio即时通信2026/10/22

Kamailio 6.1 配置参数详解

目标：系统梳理 Kamailio 6.1.5 的配置参数体系——核心全局参数、内存分配、tm 事务定时器、registrar/usrloc 注册位置、rr/acc 等模块参数，以及官方配置脚本的 #!define WITH_* 特性开关体系；全部参数附实测查看与修改手段（kamcmd cfg.get/seti 运行时验证）。已在 Ubuntu 22.04（kamailio 6.1.5，x86_64）实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Kamailio：6.1.5（官方 apt 仓库安装，安装步骤见《Ubuntu 22.04 安装 Kamailio 6.1 指南》）
  • 主配置：/etc/kamailio/kamailio.cfg（官方默认脚本 + 本地覆盖文件 kamailio-local.cfg）
  • 监听：udp/tcp 0.0.0.0:5070，alias 10.0.0.8（默认 5060 的自定义化）
  • 管理通道：kamcmd（ctl 模块 unix socket）与 kamctl（jsonrpcs FIFO）

二、前置条件

本文参数修改与验证操作要求：

  1. Kamailio 6.1.5 已安装并在运行（kamcmd core.uptime 能返回正常输出）。
  2. ctl.so 与 jsonrpcs.so 模块已加载（官方默认 cfg 已内置，无需额外配置）。
  3. 理解 YAML 无关的 Kamailio 配置语法：参数分三层——核心参数（debug=2 形式，cfg 顶层）、模块参数（modparam("tm", "fr_timer", 30000) 形式）、特性开关（#!define WITH_AUTH 预处理定义）。

三、参数查看与修改方式

Kamailio 参数有三条查看/修改路径，各自适用场景不同，先给全景：

路径形式生效时机适用
配置文件静态修改debug=2 / modparam(...)重启后生产永久配置
RPC 运行时修改kamcmd cfg.seti core debug 3立即排障临时调整
统计观测kamcmd stats.get_statistics ...只读验证参数效果

3.1 静态修改（配置文件）

核心参数写在 cfg 顶层全局区，模块参数集中在 # ----- tm params ----- 这类注释段，实测（默认 cfg 摘录）：

/* LOG Levels: 3=DBG, 2=INFO, 1=NOTICE, 0=WARN, -1=ERR */
debug=2
log_facility=LOG_LOCAL0
children=8

# ----- tm params -----
modparam("tm", "failure_reply_mode", 3)
modparam("tm", "fr_timer", 30000)
modparam("tm", "fr_inv_timer", 120000)

改动后必须重启进程才生效：

service kamailio restart

3.2 运行时查看与修改（kamcmd cfg.get / cfg.seti）

无需重启，立即生效，排障首选。查看 core 组全部运行参数：

kamcmd cfg.get core

实测输出（节选）：

{
        debug: 2
        memdbg: 5
        dst_blocklist_expire: 60
        dst_blocklist_udp_imask: 0
        dns_try_naptr: 0
        dns_udp_pref: 30
        dns_tcp_pref: 20
        dns_retr_time: -1
        dns_use_search_list: 1
        dns_search_full_match: 1
        ...
}

查看单个参数值、修改、再查回（实测闭环）：

kamcmd cfg.get core debug
kamcmd cfg.seti core debug 3
kamcmd cfg.get core debug
kamcmd cfg.seti core debug 2
kamcmd cfg.get core debug

实测回显：

2
3
2
2

debug 从 2（INFO）提到 3（DBG）再还原，全程无重启。数值参数用 cfg.seti，字符串参数用 cfg.sets。查看模块参数组：

kamcmd cfg.get tm

实测输出（节选）：

{
        auto_inv_100_reason: trying -- your call is important to us
        default_reason: Server Internal Error
        ruri_matching: 1
        via1_matching: 1
        fr_inv_timer_next: 30000
        noisy_ctimer: 1
        auto_inv_100: 1
        unix_tx_timeout: 500
        ...
}

⚠️ 注意：运行时修改不落盘，进程重启后回到 cfg 文件中的值。排障验证有效后，务必把同值写回 kamailio.cfg 再重启一次，否则配置漂移。

3.3 统计观测（验证参数效果）

参数改完用统计计数器验证实际行为：

kamcmd stats.get_statistics core: sl: usrloc:

实测输出（节选）：

core:bad_URIs_rcvd = 0
core:bad_msg_hdr = 0
core:rcv_requests = 5
core:rcv_replies = 0
sl:200_replies = 4
sl:403_replies = 1
usrloc:location-contacts = 1
usrloc:location-expires = 0
usrloc:location-users = 1

实测环境中 sl:200_replies = 4 与 sl:403_replies = 1 精确对应此前 REGISTER 验证：4 次 200 OK、1 次故意复现的 403（见《Ubuntu 22.04 安装 Kamailio 6.1 指南》第八章），计数器与真实信令一一对应。

四、参数总览

按功能域划分的参数地图（本章逐类详解）：

分类代表参数所在位置
全局核心debug、children、listen、alias、log_facilitycfg 顶层
内存SHM_MEMORY（-m）、PKG_MEMORY（-M）、memdbg/memlog/etc/default/kamailio + cfg
TCP/TLStcp_connection_lifetime、tcp_max_connections、enable_tlscfg 顶层
事务定时器fr_timer、fr_inv_timer、failure_reply_mode（tm）modparam
注册与位置max_expires、timer_interval、db_mode（registrar/usrloc）modparam
记录路由enable_full_lr、append_fromtag（rr）modparam
计费log_flag、early_media、log_extra（acc）modparam
特性开关WITH_AUTH、WITH_MYSQL、WITH_USRLOCDB、WITH_DEBUG…#!define

五、核心参数分类详解

5.1 全局核心参数

debug：日志级别。3=DBG, 2=INFO, 1=NOTICE, 0=WARN, -1=ERR。默认 cfg 通过 #!ifdef WITH_DEBUG 在 2/3 间切换。排障时临时 cfg.seti core debug 3（3.2 已实测），长期开 debug 会放大日志量与 CPU 开销。

log_facility：syslog facility，默认 LOG_LOCAL0。配合 rsyslog 规则可把 Kamailio 日志单独落文件（如 local0.* /var/log/kamailio.log）。

children：每个 UDP 套接字的 SIP 处理子进程数。默认 cfg children=8。验证：kamcmd core.psx 列出进程，实测恰好 8 个 UDP worker：

{
        IDX: 0
        PID: 4153
        DSC: main process - attendant
}
{
        IDX: 1
        PID: 4154
        DSC: udp receiver child=0 sock=0.0.0.0:5070
}
{
        IDX: 2
        PID: 4155
        DSC: udp receiver child=1 sock=0.0.0.0:5070
        ...
}

kamcmd core.psx | grep -c "udp receiver"

实测回显：

8

经验值：UDP worker 数 ≈ CPU 核数；高并发 REGISTRAR 场景可到 16，纯代理转发场景 4 也够。

listen / alias：监听套接字与本地域声明。listen 可多次出现，每条声明一个套接字；alias 把额外的主机名/IP 纳入 myself 判定。本文实测配置（kamailio-local.cfg）：

listen=udp:0.0.0.0:5070
listen=tcp:0.0.0.0:5070
alias="10.0.0.8"

运行时核对生效结果：

kamcmd core.sockets_list

实测输出（节选）：

{
        socket: {
                af: IPv4
                proto: udp
                address: 0.0.0.0
                port: 5070
                mcast: no
                mhomed: no
                virtual: no
        }
        socket: {
                af: IPv4
                proto: tcp
                ...
        }
}

alias 缺失的典型故障就是 REGISTER 被 403 拒绝（uri!=myself），完整排障过程见安装指南第八章。

5.2 内存参数

Kamailio 内存分两池：共享内存 SHM（全进程共享，事务/对话/usrloc）与私有内存 PKG（每进程独立，解析缓冲）。

包管理路径：/etc/default/kamailio（systemd EnvironmentFile 读取）：

#SHM_MEMORY=64
#PKG_MEMORY=8

对应服务单元的启动参数（/lib/systemd/system/kamailio.service）：

Environment='SHM_MEMORY=64'
Environment='PKG_MEMORY=8'
ExecStart=/usr/sbin/kamailio -P /run/kamailio/kamailio.pid -f $CFGFILE -m $SHM_MEMORY -M $PKG_MEMORY --atexit=no

-m 即共享内存 MB 数、-M 即私有内存 MB 数。实测当前分配与水位：

kamcmd core.shmmem

实测输出：

{
        total: 67108864
        free: 64223392
        used: 2607008
        real_used: 2885472
        max_used: 2885472
        fragments: 1
}

total: 67108864 = 64MB，与 /etc/default/kamailio 的 SHM_MEMORY=64 严格一致；空载仅用 2.8MB，水位极低。调参经验：SHM 按"每 1000 个在线注册约 10-20KB + 每 1000 并发对话约 30-50KB"估算，生产 1000 路并发建议起步 256MB；PKG 默认 8MB 对纯信令足够，用了重解析/大消息变换再加大。

memdbg / memlog：内存调试与统计的日志阈值级别，默认 5——只有 debug 级别 ≥5 时才打印内存报告，日常不动。

5.3 事务定时器参数（tm 模块）

tm 模块管理 SIP 事务状态机，两个定时器决定响应等待行为：

modparam("tm", "fr_timer", 30000)
modparam("tm", "fr_inv_timer", 120000)
  • fr_timer（默认 30000ms）：等待非 INVITE 请求（含 REGISTER）最终响应的时长，超时回 408。联动排障：下游网关慢响应时适当加大。
  • fr_inv_timer（默认 120000ms）：INVITE 收到 1xx 后等待最终响应（180/200/486…）的时长，即"振铃上限"。
  • failure_reply_mode（默认 3）：失败时自动回最优响应给上游，保持默认。
  • auto_inv_100（默认 1）：收到 INVITE 立即自动回 100 trying，抑制 UA 重传；auto_inv_100_reason 可改 100 的 reason 短语。

验证运行值（3.2 节 cfg.get tm 输出中 fr_inv_timer_next: 30000、auto_inv_100: 1 即实时生效值）。

5.4 注册与位置参数（registrar / usrloc）

这对模块共同实现注册服务器：registrar 处理 REGISTER 报文，usrloc 存储位置数据。

modparam("registrar", "method_filtering", 1)
modparam("registrar", "max_expires", 3600)
modparam("registrar", "gruu_enabled", 0)
modparam("usrloc", "timer_interval", 60)
modparam("usrloc", "timer_procs", 1)
modparam("usrloc", "use_domain", 0)
  • registrar/max_expires（默认 3600）：允许 UA 注册的最长有效期秒数，REGISTER 里 Expires 超过会被钳制到该值。实测 7.3 的注册回包 Contact: ...;expires=300（UA 请求 300，未触顶）。
  • registrar/method_filtering（默认 1）：按 usrloc 记录的 Methods 位图过滤非注册方法。
  • registrar/gruu_enabled（默认 0）：GRUU（全局可路由 UA URI，RFC 5627）开关，无特殊需求保持关闭。
  • usrloc/timer_interval（默认 60s）：内存位置表的过期清理周期。
  • usrloc/timer_procs（默认 0）：过期清理独立进程数，0 = 复用主 timer；高注册量建议 1。
  • usrloc/db_mode：位置表持久化模式——0 纯内存（重启丢失）、1 即时写库、2 定时批量写库（配合 WITH_USRLOCDB 默认 2）。use_domain（默认 0）：AOR 是否带域维度隔离，多域部署改 1。

内存表水位验证：

kamcmd stats.get_statistics usrloc:

实测输出（节选，对应 7.3 注册的 1 个用户）：

usrloc:location-contacts = 1
usrloc:location-users = 1
usrloc:location-expires = 0

5.5 记录路由参数（rr 模块）

rr 模块为对话型请求（INVITE/SUBSCRIBE）插入 Record-Route 头，锁定后续请求路径：

modparam("rr", "enable_full_lr", 0)
modparam("rr", "append_fromtag", 0)
  • enable_full_lr（默认 0）：;lr 参数是否用全格式（<sip:ip;lr> vs sip:ip;lr）。兼容古董 UA（RFC 2543 时代）才改 1。
  • append_fromtag（默认 0）：Record-Route 是否附 From tag，用于严格对话方向判定。配合 acc detect_direction 才需要打开。

5.6 计费参数（acc 模块）

acc 负责通话计费记录（CDR 雏形），默认只记 INVITE：

modparam("acc", "early_media", 0)
modparam("acc", "report_ack", 0)
modparam("acc", "log_flag", 1)
modparam("acc", "log_missed_flag", 2)
modparam("acc", "failed_transaction_flag", 3)
modparam("acc", "log_extra",
	"src_user=$fU;src_domain=$fd;src_ip=$si;"
	"dst_ouser=$tU;dst_user=$rU;dst_domain=$rd")
  • log_flag = 1（FLT_ACC）：打上此 flag 的事务写计费日志（syslog）。
  • early_media（默认 0）：是否对 183 早媒体计费。
  • report_ack / report_cancels（默认 0）：ACK/CANCEL 是否单独成账，一般关闭（挂在事务上）。
  • log_extra：额外计费字段模板，$fU/$fd/$si/$tU/$rU 分别是主叫用户/域、源 IP、被叫原始用户/域——记账信息面的最小集。
  • 启用数据库计费还需 WITH_ACCDB，并配 db_flag/db_url（依赖 db_mysql 模块）。

5.7 特性开关体系（#!define WITH_*）

官方 cfg 用预处理定义控制能力面，等价于"注释开关"——定义即启用，注释即关闭：

开关启用能力依赖
WITH_DEBUGdebug=3 + debugger 模块 cfgtrace 逐语句跟踪debugger.so
WITH_MYSQL数据库驱动 DBURL 生效db_mysql.so + kamdbctl 建库
WITH_AUTHREGISTER/请求鉴权（auth_check/auth_challenge）auth.so、auth_db.so、subscriber 表
WITH_USRLOCDB注册位置落库（usrloc db_mode=2）WITH_MYSQL
WITH_IPAUTH源 IP 白名单鉴权permissions.so + address 表
WITH_NATNAT 检测与 RTP 中继nathelper.so + rtpproxy/rtpengine
WITH_TLSSIP over TLStls.so + tls.cfg 证书
WITH_ANTIFLOODpike 抗洪泛（2 秒 16 请求阈值封 300 秒）pike.so + htable.so

启用方式：编辑 kamailio.cfg，把对应 #!define WITH_AUTH 前的 # 去掉再重启。启用 WITH_AUTH/WITH_MYSQL 的完整流程（kamdbctl 建库、kamctl add 加用户、Digest 认证实测）属于安全与数据库主题，见《Kamailio 6.1 常用 CLI 命令与工具详解》。

六、生产配置模板

一套经实测验证的最小可用生产模板（适用场景：1000 注册用户、100 并发对话的信令面代理，8GB 内存、SSD 磁盘，Ubuntu 22.04），由三部分组成。

第一部分：/etc/default/kamailio（内存与开关）：

RUN_KAMAILIO=yes
SHM_MEMORY=256
PKG_MEMORY=8
CFGFILE=/etc/kamailio/kamailio.cfg

第二部分：/etc/kamailio/kamailio-local.cfg（监听与本地域，按实际 IP 调整 alias）：

listen=udp:0.0.0.0:5060
listen=tcp:0.0.0.0:5060
alias="10.0.0.8"

第三部分：kamailio.cfg 顶部启用的特性定义（按需）：

#!define WITH_MYSQL
#!define WITH_AUTH
#!define WITH_USRLOCDB
#!define WITH_ANTIFLOOD

模板要点：SHM 256MB 覆盖 1000 并发对话 + 1000 AOR 有余量（5.2 实测空载 2.8MB 基线）；WITH_ANTIFLOOD 开启 pike 默认阈值（2 秒内同源 16 请求即封 300 秒）抗 SIP 扫描；监听保持通配 + alias 声明，避免 403。改动后 kamailio -c（cfg 语法检查，见 CLI 篇）通过再重启。

七、常见问题（FAQ）

Q1：参数用 kamcmd 改了，重启后为什么回退？ 运行时 cfg.seti 只改内存中的值，不回写文件。永久生效必须写进 kamailio.cfg（或 kamailio-local.cfg）后重启。正确姿势：先 cfg.seti 验证行为，确认后把值落文件，再重启一次核对 cfg.get。

Q2：改了 cfg 重启失败，怎么在不中断的情况下先验证语法？ 用 kamailio -c -f /etc/kamailio/kamailio.cfg 做离线语法检查（不启动进程、不占端口），通过后再 restart。这是 CLI 篇实测命令。

Q3：debug 日志去哪了，怎么单独收集？ log_facility=LOG_LOCAL0 下日志进 syslog 的 local0 通道。Ubuntu 的 rsyslog 默认把 local0 归入 /var/log/syslog；单独落盘需在 /etc/rsyslog.d/ 加一行 local0.* -/var/log/kamailio.log 并重启 rsyslog。日志行自带 log_prefix="{$mt $hdr(CSeq) $ci} "（方法、CSeq、Call-ID），便于按对话 grep。

Q4：children 调大越多越好吗？ 不是。每个 child 是一个独立进程（非线程），8 个 UDP worker 空载约 90MB RSS 总量。UDP worker 数超过 CPU 核数无收益；真正的大并发瓶颈通常在 TCP 连接池（tcp_max_connections=2048 默认）与 SHM 水位，先看 stats.get_statistics 再动 children。

Q5：usrloc 注册数据重启会丢吗？ 纯内存模式（默认，db_mode=0）会丢——UA 重注册周期（默认 Expires 300-3600s）到了会自己补上，但期间呼叫该用户 404。生产开启 WITH_USRLOCDB（db_mode=2 定时写库，默认 60 秒批量），重启后从库恢复 AOR。

八、参考链接