Flexisip 2.6.2 常用 CLI 命令与工具详解

flexisip 主程序管理标志、flexisip_cli.py 11 个子命令、flexisip_pusher 与 systemctl 服务管理实测。

FlexisipFlexisipSIP2026/10/25

Flexisip 2.6.2 常用 CLI 命令与工具详解

目标：讲清 Flexisip 2.6.2 命令行工具全集——主程序 flexisip 的管理类标志、在线管理工具 flexisip_cli.py 的 11 个子命令、推送测试工具 flexisip_pusher，以及 systemd 服务管理。所有命令与回显均来自 2026-10-25 在 Flexisip 2.6.2-1（Ubuntu 24.04）上的实测。

一、环境信息

  • 软件版本：Flexisip 2.6.2-1（官方 APT 仓库 noble/stable）
  • 工具位置：/opt/belledonne-communications/bin/（下含 flexisip、flexisip_cli.py、flexisip_pusher、linphone-daemon）
  • 运行前提：flexisip_cli.py 需 Python 3（deb 包已自动带齐依赖），且目标服务进程在运行
  • 服务管理：systemctl 管理 flexisip-proxy 等 6 类单元

二、工具概览

工具形态用途
flexisipC++ 主二进制启动各服务角色；导出/翻新配置；列模块与段
flexisip_cli.pyPython 脚本在线管理运行中的服务：注册库 CRUD、配置热查热改、认证缓存
flexisip_pusherC++ 二进制手动发送 APNs/FCM 推送（RFC 8599 参数），排障推送链路
systemctl系统工具服务启停、自启、状态查看

三、前置条件

/opt/belledonne-communications/bin/flexisip --version

实测回显：

/opt/belledonne-communications/bin/flexisip  version: 2.6.2 (sofia-sip: 1.13.45bc-70-g5c6c07ea2) compiled with SNMP - Transcoder - Redis - Soci - Presence - RegEvent - B2BUA - Voicemail

flexisip_cli.py 与运行中进程通过 IPC 通信：默认按 /var/run/flexisip-<类型>.pid 找 PID，找不到则按进程名匹配；也可用 -p <PID> 显式指定。

四、flexisip 主程序：启动与管理标志

4.1 启动服务（五种角色）

/opt/belledonne-communications/bin/flexisip --server proxy      # 代理（默认，可省略 --server）
/opt/belledonne-communications/bin/flexisip --server presence   # 呈现服务
/opt/belledonne-communications/bin/flexisip --server b2bua      # B2BUA 服务
/opt/belledonne-communications/bin/flexisip --server regevent   # 注册事件服务
/opt/belledonne-communications/bin/flexisip --server voicemail  # 语音信箱服务

前台调试常用组合：-c /etc/flexisip/flexisip.conf -d（-d 把 debug 日志打到终端）；后台运行加 --syslog -p /var/run/xx.pid（systemd 单元就是这么调的）。

4.2 配置导出与盘点标志（运维高频）

实测 --help 中的管理类标志（节选，实测首尾）：

  --dump-default <all>    Dump default configuration in the standard output. Use
                          'all' to dump the configuration of all modules, or
                          '<module_name>' to dump the configuration of a
                          specific module.
  --dump-all-default      Dump all default configurations in the standard output
                          (equivalent to '--dump-default all').
  --dump-format <file>    Output format of configuration dump (default: 'file').
                          Possible values: 'file', 'tex', 'doku', 'media',
                          'xwiki'.
  --list-modules          Dump the list of available modules in the standard
                          output.
  --list-sections         Dump the list of available sections in the standard
                          output.
  --rewrite-config        Load the configuration file and dump a new one in the
                          standard output adding the new settings and updating
                          documentations.
  --remove-deprecated     When dumping the configuration, remove all deprecated
                          settings.

典型用法：

/opt/belledonne-communications/bin/flexisip --list-modules

实测回显（2.6.2 共 23 个内置模块）：

module::DoSProtection
module::SanityChecker
module::GarbageIn
module::Capabilities
module::NatHelper
module::Authentication
module::AuthTrustedHosts
module::AuthOpenIDConnect
module::Authorization
module::Redirect
module::RegEvent
module::B2bua
module::GatewayAdapter
module::Presence
module::Registrar
module::StatisticsCollector
module::ContactRouteInserter
module::Router
module::PushNotification
module::LoadBalancer
module::MediaRelay
module::Transcoder
module::Forward

/opt/belledonne-communications/bin/flexisip --dump-default stun-server   # 查某段权威默认值
/opt/belledonne-communications/bin/flexisip --rewrite-config -c /etc/flexisip/flexisip.conf > flexisip.new   # 升级后翻新配置

4.3 其他实用标志

  • -t, --transports：命令行临时覆盖监听点（如 -t "sip:* sips:*"），优先于配置文件；
  • --hosts <host=ip>：临时注入 hosts 解析（排障 DNS 时好用）；
  • --show-experimental：连实验性参数一起导出；
  • --dump-mibs：导出 SNMP MIB 定义。

五、flexisip_cli.py：在线管理（11 个子命令）

实测 --help 回显（节选核心）：

usage: flexisip_cli.py [-h] [-p PID] [-s {proxy,presence,b2bua}] command ...

positional arguments:
  command               Action to do on the server. Type `flexisip_cli.py
                        <command> --help` for detailed documentation about the
                        given command.
    AUTH_CACHE_LIST     List all cached authentication credentials (no
                        password is returned).
    AUTH_CACHE_GET      Get information on the state of cached credentials for
                        the provided user (no password is returned).
    AUTH_CACHE_DELETE   Remove cached credentials for the provided user.
    CONFIG_GET          Get the value of an internal variable of Flexisip.
    CONFIG_SET          Set the value of an internal variable of Flexisip.
    CONFIG_LIST         List all the available parameters of a section.
    REGISTRAR_GET       List all bindings under an address of record (AOR)
                        from the registrar database.
    REGISTRAR_UPSERT    Update or insert a binding for an address of record
                        (AOR) in the registrar database.
    REGISTRAR_DELETE    Remove a specific binding of an address of record
                        (AOR) from the registrar database.
    REGISTRAR_CLEAR     Remove an address of record (AOR) from the registrar
                        database.
    REGISTRAR_DUMP      Dump the list of registered address of records (AORs)
                        for this proxy instance only (not all the cluster!).
    SIP_BRIDGE          Send commands to the external SIP provider bridge (if
                        active).

options:
  -p PID, --pid PID     Process ID (PID) of the process to communicate with.
                        (default: 0 表示自动按 pidfile/进程名查找)
  -s {proxy,presence,b2bua}, --server {proxy,presence,b2bua}
                        Type of the server to communicate with. (default: proxy)

5.1 注册库管理（REGISTRAR_* 四件套 + DUMP）

查看本实例全部注册 AOR：

python3 /opt/belledonne-communications/bin/flexisip_cli.py REGISTRAR_DUMP

实测回显（已注册一个账号时）：

{
  "aors": [
    "alice@localhost"
  ]
}

手工插入/更新一条绑定（参数：AOR、联系地址 URI、有效期秒数、可选 uuid）：

python3 /opt/belledonne-communications/bin/flexisip_cli.py REGISTRAR_UPSERT sip:alice@localhost sip:10.0.0.10 3600

实测回显（JSON 给出完整绑定，含自动生成的 unique-id）：

{
  "contacts": [
    {
      "accept": [],
      "alias": 0,
      "call-id": "fs-cli-upsert",
      "contact": "sip:10.0.0.10",
      "cseq": 0,
      "expires-at": 1792915783,
      "path": [],
      "q": 1.0,
      "unique-id": "fs-cli-gen-z4l60DgKwmner2wVmCLj",
      "update-time": 1792912183,
      "user-agent": ""
    }
  ]
}

按 AOR 查绑定：

python3 /opt/belledonne-communications/bin/flexisip_cli.py REGISTRAR_GET sip:alice@localhost

回显与 UPSERT 相同的 JSON 结构。删除指定绑定需要 uuid（从 GET 结果取）：

python3 /opt/belledonne-communications/bin/flexisip_cli.py REGISTRAR_DELETE sip:alice@localhost fs-cli-gen-z4l60DgKwmner2wVmCLj

实测回显（剩余绑定列表，此处已空）：

{
  "contacts": []
}

清空整个 AOR：

python3 /opt/belledonne-communications/bin/flexisip_cli.py REGISTRAR_CLEAR sip:alice@localhost

⚠️ 注意：漏传 uuid 时 REGISTRAR_DELETE 会直接报参数错误 the following arguments are required: uuid——「按 uuid 删单条、CLEAR 清整个 AOR」是设计如此。另外 REGISTRAR_DUMP 只显示本实例的注册，集群部署时别拿它当全局视图。

5.2 配置热查热改（CONFIG_* 三件套）

python3 /opt/belledonne-communications/bin/flexisip_cli.py CONFIG_GET global/transports

实测回显：global/transports: sip:*

python3 /opt/belledonne-communications/bin/flexisip_cli.py CONFIG_SET global/log-level debug

实测回显：global/log-level: debug（立即生效，不写配置文件，重启回退）。

列出某段全部参数与说明（输出长，配 grep 用）：

python3 /opt/belledonne-communications/bin/flexisip_cli.py CONFIG_LIST global | grep -E "^(log|transports|aliases)"

实测回显：

log-directory: Path to the directory where log files will be created.
log-filename: Name of the log file
log-level: Logging verbosity.
transports: List of whitespace separated SIP URIs where the proxy must listen.
aliases: List of whitespace separated host names pointing to this machine.

5.3 认证缓存（AUTH_CACHE_* 三件套）

启用 module::Authentication 后，认证结果按 cache-expire（默认 1800 秒）缓存。三条命令分别列出/查询/剔除缓存凭据（均不回显密码）：

python3 /opt/belledonne-communications/bin/flexisip_cli.py AUTH_CACHE_LIST
python3 /opt/belledonne-communications/bin/flexisip_cli.py AUTH_CACHE_GET sip:alice@localhost
python3 /opt/belledonne-communications/bin/flexisip_cli.py AUTH_CACHE_DELETE sip:alice@localhost

未启用认证时 LIST 实测无输出（空缓存）。

5.4 SIP_BRIDGE

向外接 SIP 运营商桥（B2BUA sip-bridge）发管理命令，当前子命令为 INFO：

python3 /opt/belledonne-communications/bin/flexisip_cli.py SIP_BRIDGE INFO

仅在启用 b2bua-server::sip-bridge 时有实际输出。

六、flexisip_pusher：推送链路测试

手动向 APNs/FCM 发推送，用于不打电话先验证推送证书与令牌。实测 --help 回显（节选）：

usage: /opt/belledonne-communications/bin/flexisip_pusher [options] --pn-provider {apns,apns.dev,fcm} --pn-param <param> --pn-prid <prid> [<prid> ...]

A tool to send push notifications to Android and iOS applications, based on parameters defined by RFC8599.

Mandatory parameters:
---------------------
  --pn-provider {apns,apns.dev,fcm}  The service in charge to send the push notification.
                                       * 'apns'     for iOS production applications;
                                       * 'apns.dev' for iOS development applications;
                                       * 'fcm'      for Android applications.
  --pn-param <param>                 Provider specific ID of the application.
                                       * Android:   Firebase Project ID.
                                       * iOS:       <TeamID>.<BundleID>[.voip], where '.voip' is only added
                                                    for VoIP push notification.
  --pn-prid <prid>                   Provider specific ID of the targeted application instance.
                                       * Android:   Registration token.
                                       * iOS:       Device token.

General options:
----------------
  -h, --help                         Show this help message and exit.
  --debug                            Print all debug messages on the standard output.
  --customPayload <payload>          Add custom parameters in the PN request body. <payload> must be a JSON structure
                                     and will be placed in the top-level JSON attribute.

示例形态（需真实设备令牌才可送达）：

/opt/belledonne-communications/bin/flexisip_pusher --pn-provider fcm --pn-param <Firebase项目ID> --pn-prid <设备注册令牌> --debug

⚠️ 注意：推送属系统级凭据场景，--pn-param/--pn-prid 用实际值前先确认对应 APNs 证书已放入 /etc/flexisip/apn 或 FCM 服务账号已配置（module::PushNotification 段）。

七、systemd 服务管理

deb 包为每种角色装了独立单元（及 @ 模板单元，用于多实例）：

ls /usr/lib/systemd/system/ | grep flexisip

实测回显：

flexisip-b2bua.service
flexisip-b2bua@.service
flexisip-linphone-daemon.service
flexisip-presence.service
flexisip-presence@.service
flexisip-proxy.service
flexisip-proxy@.service
flexisip-regevent.service
flexisip-regevent@.service
flexisip-voicemail.service
flexisip-voicemail@.service

日常操作（每行一个单元）：

systemctl start flexisip-proxy        # 启动
systemctl stop flexisip-proxy         # 停止
systemctl restart flexisip-proxy      # 重启（改配置文件后）
systemctl enable flexisip-proxy       # 开机自启
systemctl is-active flexisip-proxy    # 运行状态（实测回显 active）
systemctl is-enabled flexisip-proxy   # 自启状态（实测回显 enabled）
systemctl status flexisip-proxy --no-pager   # 详情（含最近日志）
journalctl -u flexisip-proxy -f       # 跟踪 syslog 日志

八、注意事项

  1. flexisip_cli.py 的 -s 决定连哪类服务（proxy/presence/b2bua），默认 proxy；管 presence 时别忘加 -s presence。
  2. CONFIG_SET 热改不落盘；持久配置一律回写 /etc/flexisip/flexisip.conf 后 systemctl restart。
  3. 无 systemd 的前台运行形态（如自管进程）没有 pidfile，CLI 需 -p <PID> 显式指定。
  4. 注册库默认在内存：REGISTRAR_UPSERT 造的数据重启即失，生产接 Redis/MySQL 见《Flexisip 2.6 配置参数详解》5.4。

九、常见问题

Q1：flexisip_cli.py 报 could not find flexisip process pid？

服务没启动，或前台运行无 pidfile。先 systemctl status flexisip-proxy 确认；前台形态加 -p <PID>。

Q2：怎么确认热改的配置生效了？

改完立即 CONFIG_GET 同一参数复核，如 CONFIG_GET global/log-level 回显 debug 即生效。

Q3：REGISTRAR_DUMP 是空的，但客户端明明显示已注册？

两个高频原因：① 注册到了集群里的另一台实例（DUMP 只看本机）；② 注册实际失败（401 未通过认证）。开 debug 日志看 REGISTER 事务。

Q4：linphone-daemon 是什么？

同包附带的 Linphone 守护进程（Flexisip 的 B2BUA 等能力基于 linphone-sdk），日常管理 Flexisip 用不到它，无需启动对应单元。

十、参考链接