openSIPS 4.0 常用 CLI 命令详解

面向负责 openSIPS 4.0 日常运维的工程师，系统梳理命令行工具箱——opensips 主程序的启动/校验/监听/内存参数（含 -l 与 socket= 优先级、最小配置传输模块报错等实测结论）、opensips-cli 的模块划分与 MI 命名空间命令、opensips-mi 轻量客户端，以及 usrloc 生命周期管理、在线调日志等场景实战，全部命令与回显均为实测。

openSIPSopenSIPSSIPVoIPUbuntu 22.042026/10/26

openSIPS 4.0 常用 CLI 命令详解

目标：面向负责 openSIPS 4.0 日常运维的工程师，系统梳理命令行工具箱——opensips 主程序的启动/校验/监听/内存参数（含 -l 与 socket= 优先级、最小配置传输模块报错等实测结论）、opensips-cli 的模块划分与 MI 命名空间命令、opensips-mi 轻量客户端，以及 usrloc 生命周期管理、在线调日志等场景实战，全部命令与回显均为实测。

一、环境信息

本章列出本次实测所用的环境，后续章节的全部命令与回显均基于该环境。

项目取值
服务器 IP10.89.62.3（内网地址）
操作系统Ubuntu 22.04.5 LTS
openSIPS 版本4.0.2-1（官方 APT 仓库安装，systemd 托管，active）
opensips-cli 版本0.4.1-1（官方 APT 仓库）
python3-opensips 版本0.1.10-1（提供 opensips-mi 命令）
SIP 测试客户端10.89.62.4（sipsak 0.9.8.1）
MI 通道mi_fifo（/run/opensips/opensips_fifo，配置见配置详解篇）

配置文件逐段解析与 MI 通道的启用机制见《openSIPS 4.0 核心配置参数详解》；安装过程见《Ubuntu 22.04 安装 openSIPS 4.0 指南》。

二、命令行工具箱总览

openSIPS 4.0 的服务器命令行工具是"1 + 2 + 1"结构：

工具提供包定位
opensipsopensips（主包）主程序：启动、前台调试、配置校验、内存与监听参数
opensips-cliopensips-cli全功能管理客户端：MI 命令、数据库 Schema 管理、用户管理、TLS 证书管理
opensips-mipython3-opensips一次性轻量 MI 客户端：单条命令进单条 JSON 出，适合脚本与容器健康检查
osipsconfigopensips（主包）交互式菜单工具：从模板生成定制配置文件

两个背景事实值得先交代（都实测过）：

  1. 主包不带任何 MI 客户端。仅装主包的服务器上 which opensipsctl opensips-cli opensips-mi 只有空输出；3.x 时代的 shell 脚本版 opensipsctl 在 4.0 的 Debian 打包中已不随主包分发，管理面由 Python 系的 opensips-cli / opensips-mi 承接；
  2. 装 opensips-cli 会连带装上 opensips-mi（依赖关系实测）：
apt-cache depends opensips-cli | grep Depends

  Depends: python3
  Depends: python3-opensips
  Depends: python3-pymysql
  Depends: python3-sqlalchemy

python3-opensips 这个包里就有 /usr/bin/opensips-mi；pymysql/sqlalchemy 则是 opensips-cli 数据库模块的后盾。

三、opensips 主程序：启动、校验与运行参数

3.1 参数全表

opensips -h 的完整输出就是主程序的权威参数表：

opensips -h

version: opensips 4.0.2 (x86_64/linux)
Usage: opensips -l address [-l address ...] [options]
Options:
    -f file      Configuration file (default /etc/opensips/opensips.cfg)
    -c           Check configuration file for errors
    -C           Similar to '-c' but in addition checks the flags of exported
                 functions from included route blocks
    -l address   Listen on the specified address/interface (multiple -l
                 mean listening on more addresses).  The address format is
                 [proto:]addr[:port], where proto=udp|tcp and
                 addr= host|ip_address|interface_name. E.g: -l locahost,
                 -l udp:127.0.0.1:5080, -l eth0:5062 The default behavior
                 is to listen on all the interfaces.
    -n processes Number of worker processes to fork per UDP interface
                 (default: 8)
    -r           Use dns to check if is necessary to add a "received="
                 field to a via
    -R           Same as `-r` but use reverse dns;
                 (to use both use `-rR`)
    -v           Turn on "via:" host checking when forwarding replies
    -d           Debugging mode (multiple -d increase the level)
    -D           Run in debug mode
    -F           Daemon mode, but leave main process foreground
    -i           Ignore SCM revision differences for loaded modules
    -N processes Number of TCP worker processes (default: equal to `-n`)
    -W method    poll method
    -V           Version number
    -h           This help message
    -b nr        Maximum receive buffer size which will not be exceeded by
                 auto-probing procedure even if  OS allows
    -a allocator The memory allocator to use for all memory segments
                 Possible values:
                     F_MALLOC            F_MALLOC_DBG
                     F_PARALLEL_MALLOC   F_PARALLEL_MALLOC_DBG
                     Q_MALLOC            Q_MALLOC_DBG
                     HP_MALLOC           HP_MALLOC_DBG
    -k allocator The pkg memory allocator to use (overrides -a)
    -s allocator The shared memory allocator to use (overrides -a)
    -e allocator The restart-persistent memory allocator to use (overrides -a)
    -m nr        Size of shared memory allocated in Megabytes
    -M nr        Size of pkg memory allocated in Megabytes
    -w dir       Change the working directory to "dir" (default "/")
    -t dir       Chroot to "dir"
    -u uid       Change uid
    -g gid       Change gid
    -p pp_cmd    Preprocess the configuration file (along with any others
                 included) using the specified system command. The command
                 shall receive input via stdin and it must output the
                 result to stdout
    -P file      Create a pid file

按用途归成四组：

组参数要点
配置-f -c -C -p-f 换配置文件；-c 语法校验；-C 在 -c 之上再校验路由块中函数的导出 flags；-p 用外部命令预处理配置（生成式配置的入口，如 cpp/M4）
监听/进程-l -n -N-l 监听地址（可多次）；-n 每 UDP 接口的 worker 数（默认 8，配置文件 udp_workers 的命令行等价物）；-N TCP worker 数
内存-m -M -a -k -s -e共享内存/私有内存大小与分配器选择；systemd 单元的 -m $S_MEMORY -M $P_MEMORY 就是这两个参数（实测验证见配置详解篇第六章）
运行形态-F -D -d -P -w -t -u -g 等前台运行（容器入口点正是 opensips -F）、调试模式、pid 文件、工作目录、chroot、降权

日常最高频的是 -c/-C 校验与 -l 监听，下面逐个实测。

3.2 -c / -C：改配置前的两道校验

opensips -c

Listening on
             udp: 10.89.62.3 [10.89.62.3]:5060
Aliases:

Oct 26 11:09:10 [4443] NOTICE:core:main: config file ok, exiting...

-C 在语法之上再查路由块中函数导出 flags 的匹配（如 t_on_branch("per_branch_ops") 引用的路由是否存在、模块函数的 flag 依赖）：

opensips -C 2>&1 | grep -E "ok|ERROR"

Oct 26 11:19:36 [4585] NOTICE:core:main: config file ok, exiting...

默认配置两者皆过。纪律：-c 是底线，改完配置先 -c 再重启；对路由脚本动了函数调用的，用 -C 再加一道。

3.3 -f：指定配置文件与最小配置实验

opensips -c -f /path/to/other.cfg

顺带做一个有教学价值的实验：最小化配置能不能只写一行 socket？

printf 'socket=udp:10.89.62.3:5060\n' > /tmp/minimal.cfg
opensips -c -f /tmp/minimal.cfg

Oct 26 11:18:20 [4485] ERROR:core:main: no transport protocol loaded

报错 no transport protocol loaded：4.x 里传输协议本身就是模块，socket 之前必须先加载 proto_udp.so（且要先 mpath 指路）。补上两行：

printf 'mpath="/usr/lib/x86_64-linux-gnu/opensips/modules/"\nloadmodule "proto_udp.so"\n' > /tmp/minimal2.cfg
opensips -c -f /tmp/minimal2.cfg -l udp:10.89.62.3:5090

Oct 26 11:19:36 [4583] NOTICE:core:main: config file ok, exiting...
             udp: 10.89.62.3 [10.89.62.3]:5090

一个只有 2 行的合法配置诞生了（加载 UDP 传输 + 无 socket 声明）。这个实验同时带出了 3.4 节的结论。

3.4 -l 与配置文件 socket= 的优先级（实测）

对默认配置（36 行已声明 socket=udp:10.89.62.3:5060）追加 -l 改端口：

opensips -c -l udp:10.89.62.3:5090

Listening on
             udp: 10.89.62.3 [10.89.62.3]:5060

监听仍是 5060——配置文件里的 socket= 声明把 -l 参数整个压制了。而 3.3 节的 minimal2.cfg 没有声明 socket，-l 就生效了（5090）。

结论：-l 只在配置文件未声明 socket= 时生效。想改默认模板的监听，要么改配置文件（生产做法），要么用无 socket 的最小配置配合 -l（临时测试）。排查"改了 -l 却没生效"的现场，第一步就是 grep '^socket' 配置文件。

3.5 -p：配置预处理管道

-p 把配置文件先经过一个外部命令再喂给解析器（stdin 进 stdout 出），是 M4/cpp 生成式配置的官方入口。用 /bin/cat 做恒等预处理验证通道：

opensips -c -p /bin/cat 2>&1 | grep ok

Oct 26 11:19:36 [4587] NOTICE:core:main: config file ok, exiting...

预处理命令正常接入。配合 -p 可以做到"同一份模板按主机角色生成不同 socket/worker 组合"，比手工维护多份配置更适合规模化装机。

四、opensips-cli：全功能管理客户端

4.1 模块清单

opensips-cli 按功能分模块，安装后的模块文件可直接盘点：

ls /usr/lib/python3/dist-packages/opensipscli/modules/

__init__.py
database.py
diagnose.py
instance.py
mi.py
tls.py
trace.py
trap.py
user.py

各模块的命令面（opensips-cli -x <模块> 不带命令时会报错并列出全部合法命令，以下均为实测输出）：

模块命令面依赖
mi52 条 MI 命令（第五章速查）服务器启用 mi_fifo
databasecreate, drop, add, migrate, pi数据库连接（pymysql/sqlalchemy），create 可一键建库表 Schema
useradd, delete, passwordsubscriber 表所在数据库
tlsrootCA, userCERT服务器加载 tls_mgm 模块
instancelist, show, switch配置文件声明多实例（配合 -i 参数）
tracetrace_start 等服务器加载 siptrace 模块（未加载时报 Method not found，实测）
diagnose交互式诊断界面终端（非交互执行报 TERM environment variable not set）
trap调试信号收集需在 cli 配置中显式启用（默认未加载，实测报 module not available）

数据库类模块（database/user）在没有 DB 的纯代理部署上不可用，但命令面照常枚举——这也是排查"cli 报错"时先跑 -x <模块> 拿命令清单的技巧来源。

4.2 MI 命令的命名空间语法

cli 的 mi 模块把服务器端全部 MI 命令按 <模块>:<命令> 命名空间暴露，写法是：

opensips-cli -x mi <模块>:<命令> [参数...]

直接写裸命令名（如 opensips-cli -x mi uptime）会报错——这是从旧版 cli 或 opensipsctl 语法迁移过来最常见的坑：

ERROR: no command 'uptime' in module 'mi'

不带命令跑一次 opensips-cli -x mi 即可拿到全部合法命令清单（输出见第五章 5.1）。

五、MI 常用命令速查与场景实战

5.1 命令清单速查

opensips-cli -x mi 的报错文本即全量清单，按命名空间分组整理：

分组命令
core:uptime, version, pwd, arg, which, ps, kill, log_level, xlog_level, profiling_proc, log_level_filter, log_mute_state, reload_routes, help
statistics:get, list, reset, reset_all
mem:shm_check, pkg_dump, shm_dump, rpm_dump
tm:uac_dlg, uac_cancel, hash, reply
usrloc:rm, rm_contact, dump, flush, add, show_contact, sync, cluster_sync
tcp:list, close
blacklists:list, check_all, check, add_rule, del_rule
cache:store, fetch, remove
status_report:get, status, reports, identifiers
evi:subscribe, list, subscribers, raise

5.2 场景一：健康巡检

opensips-cli -x mi core:uptime

{
    "Now": "Mon Oct 26 11:04:48 2026",
    "Up since": "Mon Oct 26 10:30:17 2026",
    "Up time": "2071 [sec]"
}

opensips-cli -x mi statistics:get shmem:

{
    "shmem:total_size": 67108864,
    "shmem:max_used_size": 3627680,
    "shmem:free_size": 63481184,
    "shmem:used_size": 3539600,
    "shmem:real_used_size": 3627680,
    "shmem:fragments": 970
}

巡检三件套：core:uptime（活没活、跑了多久）、core:ps（进程树，输出见配置详解篇 3.4 节）、statistics:get shmem:（内存水位，total_size 应与 -m 参数一致）。statistics:get 支持前缀通配，tm:、sl:、usrloc: 等模块统计同理。

5.3 场景二：在线调日志级别

排障时想把日志临时开到 debug 而不重启：

opensips-cli -x mi core:log_level 4

{
    "New global log level": 4
}

实时生效（逐进程列表可用不带参数的 core:log_level 查看，见配置详解篇 3.2 节）。排障结束记得调回：

opensips-cli -x mi core:log_level 3

5.4 场景三：usrloc 生命周期管理

从注册到注销的完整闭环（客户端先注册用户 1001）：

sipsak -U -x 300 -s sip:1001@10.89.62.3   # 客户端侧注册
opensips-cli -x mi usrloc:show_contact location 1001@10.89.62.3

{
    "AOR": "1001@10.89.62.3",
    "Contacts": [
        {
            "Contact": "sip:1001@10.89.62.4:48380",
            ...

（输出节选，实测）删除该用户的全部绑定：

opensips-cli -x mi usrloc:rm location 1001@10.89.62.3

"OK"

opensips-cli -x mi usrloc:show_contact location 1001@10.89.62.3

ERROR: command 'usrloc:show_contact' returned: Error executing command: 404: AOR not found

查（show_contact/dump）→ 删（rm）→ 复查（404）闭环。参数规则的两个坑见第七章 7.2 节。若要强制把内存绑定刷写/同步到后端 DB（配置了 DB 模式的 usrloc），用 usrloc:flush / usrloc:sync。

5.5 场景四：TCP 连接排查

opensips-cli -x mi tcp:list

当前服务器只启用了 UDP 传输，输出为空列表——这正是 TCP 未启用时的正常表现；启用 TCP 后这里会列出每条连接的对端地址、状态与存活时间，配合 tcp:close 可在线断开可疑连接。

六、opensips-mi：脚本友好的轻量客户端

opensips-mi（python3-opensips 包）与 opensips-cli 同源但走极简路线：一条命令、一次执行、纯 JSON 输出，没有交互态与模块体系，专为脚本和健康检查设计（官方镜像的容器健康检查用的就是它）：

opensips-mi uptime

{
    "Now": "Mon Oct 26 11:20:52 2026",
    "Up since": "Mon Oct 26 10:30:17 2026",
    "Up time": "3035 [sec]"
}

注意 opensips-mi uptime 不带 mi 前缀（与 opensips-cli 的 mi core:uptime 不同），命令名就是 MI 原生命令名。-h 里可以看到它支持 fifo/http/datagram 三种 MI 通道：

usage: opensips-mi [-h] [--env-file ENV_FILE] [-t {fifo,http,datagram}]
                   [-i IP] [-p PORT] [-f FIFO_FILE] [-fb FIFO_FALLBACK_FILE]
                   [-fd FIFO_DIR] [-ds SOCK] [-dt DATAGRAM_TIMEOUT]
                   [-db DATAGRAM_BUFFER_SIZE] [-s STATS [STATS ...]]
                   [-bc [BASH_COMPLETE]] [-j JSON]
                   [command] [parameters ...]

选型建议：cron 脚本、监控探针、健康检查用 opensips-mi；交互排障、批量管理、需要数据库/TLS 子命令时用 opensips-cli。

七、排障实录

7.1 最小配置报 no transport protocol loaded

现象：一行 socket=udp:...:5060 的配置校验失败：

ERROR:core:main: no transport protocol loaded

原因与解法：4.x 的传输协议是模块，socket 之前必须 mpath + loadmodule "proto_udp.so"（3.3 节有完整修复实录）。同理，启用 TCP/TLS 监听都要先加载对应 proto 模块。

7.2 -l 改了监听却不生效

现象：opensips -c -l udp:10.89.62.3:5090 后监听清单仍是 5060。

原因与解法：配置文件已声明 socket= 时，-l 参数被完全忽略（3.4 节对照实验）。改配置文件中的 socket 行，或使用无 socket 声明的配置。

7.3 usrloc 命令的参数坑

三个实测报错与对应正解：

-- dump 的首参是 brief 开关，不是表名 --
ERROR: command 'usrloc:dump' returned: Error executing command: -32602: Invalid params (Bad type for parameter 'brief')

-- show_contact 的 AOR 必须带域 --
ERROR: command 'usrloc:show_contact' returned: Error executing command: 400: Domain missing in AOR

-- usrloc:add 的参数个数不对 --
ERROR: command 'usrloc:add' returned: Error executing command: -32602: Invalid params (Too few or too many parameters)

正解：usrloc:dump 0（首参为 brief 开关）；usrloc:show_contact location 1001@10.89.62.3（AOR 带域名，与绑定表中的形式一致）；usrloc:add 的参数签名较长（表名/AOR/Contact/expires/flags 等），线上增补绑定更推荐让终端重新 REGISTER，少用手工 add。

7.4 trace 模块报 Method not found

现象：opensips-cli -x trace 返回：

ERROR: command 'trace_start' returned: Error executing command: -32601: Method not found

原因：trace 模块的命令要转发给服务器端的 siptrace 模块执行，而默认配置未加载 siptrace.so。解法：服务器 loadmodule "siptrace.so" 并配置后端后再用；只装 cli 不代表服务器端能力就绪——cli 的模块命令面 ⊆ 服务器端已加载模块的能力，报 Method not found 时先查服务器模块加载清单。

八、参考链接