FusionPBX 5.6 常用 CLI 命令与工具详解

目标：掌握 FusionPBX 5.6 服务器上的命令行运维三板斧——FreeSWITCH 的 fs_cli（状态、Sofia profile、呼叫控制）、FusionPBX 自带的 upgrade.php 升级工具、fail2ban-client 入侵防护查询，全部命令与回显来自 Debian 12 实装环境逐条实测（实测日期：2026-10-25）。

一、环境信息

• 操作系统：Debian 12（bookworm），官方脚本路线安装的 FusionPBX 5.6（自报 5.6.6）
• 底层引擎：FreeSWITCH 1.11.3-release（/usr/bin/freeswitch、/usr/bin/fs_cli）
• 相关组件：Nginx 1.22.1、PHP 8.4.27、PostgreSQL 18.6、fail2ban（jails：fusionpbx、fusionpbx-mac、nginx-404、nginx-dos、ssh、sshd）
• 演示账号：Web 管理员 admin / q1w2e3r4

二、工具概览

💡 说明：FusionPBX 还有一组以 systemd 服务形态常驻的 PHP 守护（email_queue、fax_queue、active_calls、active_conferences、event_guard、operator_panel、system_status、transcribe_queue、websockets、xml_cdr 等，systemctl list-units 可见），它们由 systemctl 管理，没有独立 CLI。

三、前置条件

• FusionPBX 已按官方脚本安装完成，freeswitch 服务 active（fs_cli 依赖 Event Socket 127.0.0.1:8021 与本机认证，FreeSWITCH 未启动时 fs_cli 无法连接）；
• 以 root 或有权限用户登录服务器终端；
• 本文命令均可独立执行，回显为实测原样照抄。

四、fs_cli（FreeSWITCH 命令行）

4.1 连接与执行模式

交互模式（回车进入 FreeSWITCH 控制台，/exit 退出）：

fs_cli

非交互模式（-x 执行单条命令并退出，适合脚本与排障，本文统一用该模式）：

fs_cli -x 'status'

4.2 状态与版本

fs_cli -x 'status'

实测回显（节选）：UP 起步、运行时长、0 session(s) since startup、速率上限 max 30 per sec、会话上限 1000 max、CPU min idle cpu 0.00/61.43、栈 Stack 240K/8192K。

fs_cli -x 'version'

实测回显 FreeSWITCH 版本 1.11.3-release（git ef32e20，2026-08-28 构建）。

4.3 配置重载 reloadxml

修改静态 XML（vars.xml、autoload_configs 下模块配置）后重载：

fs_cli -x 'reloadxml'

实测回显：

+OK [Success]
+ Reload XML [Success]

⚠️ 注意：FusionPBX 5.6 的分机/dialplan/SIP profile 由 mod_lua xml_handler 从 PostgreSQL 动态生成（见《FusionPBX 5.6 配置参数详解》5.6 节），Web 界面的业务修改对新呼叫即时生效，reloadxml 只用于手工改过的静态 XML。实测 fs_cli -x 'module_exists mod_xml_curl' 返回 false——5.6 已不使用 mod_xml_curl。

4.4 Sofia profile 管理

查看全部 profile 运行状态：

fs_cli -x 'sofia status'

实测回显 4 个 profile 均 RUNNING：internal（服务器地址:5060）、external（:5080）、internal-ipv6 与 external-ipv6（::1）。

查看单个 profile 详细参数：

fs_cli -x 'sofia status profile internal'

实测要点：Context=public、Challenge Realm=auto_to、CODECS IN/OUT=G7221@32000h,G7221@16000h,G722,PCMU,PCMA、DTMF=rfc2833、TEL-EVENT=101、CNG=13、MAX-RECV-RPS=1000、hold-music=local_stream://default。

Web 侧改了 SIP profile 设置后重新扫描生效：

fs_cli -x 'sofia profile internal rescan'

实测回显：

+OK scan complete

4.5 呼叫控制：originate / show / uuid_kill

FusionPBX 默认 dialplan 内置测试号码：*9196 echo、*9195 delay_echo、*9664 保持音乐、*98 语音信箱主菜单（context global，实测 v_dialplans）。不接电话机即可自测媒体链路：

fs_cli -x 'originate loopback/*9664 &park'

实测回显为 +OK 后跟本次呼叫的通道 UUID。

查看当前通道与呼叫：

fs_cli -x 'show channels'

fs_cli -x 'show calls'

实测均为 2 total：loopback/*9664 的 a 腿处于 CS_EXECUTE park，b 腿播放 silence_stream://2000，编解码 L16 8000。

挂断指定通道（UUID 取 originate 回显值）：

fs_cli -x 'uuid_kill originate回显中的UUID'

实测回显 +OK，再次 show channels 为 0 total。

⚠️ 注意：originate 参数里的 * 不要加反斜杠转义，否则通道名带 \* 字面量，呼叫以 NORMAL_CLEARING 立即结束（实测排障结论）。

4.6 全局变量查询 global_getvar

fs_cli -x 'global_getvar local_ip_v4'

实测回显（值为服务器实际 IP）：

10.89.56.10

其他实测值：base_dir=/usr、conf_dir=/etc/freeswitch、log_dir=/var/log/freeswitch、db_dir=/var/lib/freeswitch/db、recordings_dir=/var/lib/freeswitch/recordings、sounds_dir=/usr/share/freeswitch/sounds。

4.7 help 全量清单（节选）

fs_cli -x 'help'

实测共 233 行，按字母序覆盖：acl、alias、av、banner、bgapi、break、callcenter_config …… xml_locate、xml_wrap 等（中间为完整 API 命令清单，用到时以 help 现场查询为准）。

五、FusionPBX 升级工具 upgrade.php

FusionPBX 的版本升级（库结构、默认数据、菜单、权限）由命令行脚本完成，位于 Web 代码内：

cd /var/www/fusionpbx/core/upgrade

5.1 参数一览（--help 实测）

php upgrade.php --help

实测参数（每个开关可组合）：

5.2 常用命令实测

查看当前代码版本：

php upgrade.php --version

实测回显：

5.6.6

只更新数据库结构（版本升级后最常用的单项）：

php upgrade.php --schema

实测回显：

[ Update ] Table and field structure.

典型升级流程：git 拉取新版本代码后，依次执行 --schema（结构）、--defaults（默认数据）、--menu（菜单）、--permissions（权限），再从 Web 界面确认 Dashboard 正常。

六、fail2ban-client（爆破防护）

官方脚本默认安装 fail2ban。查看全部 jail：

fail2ban-client status

实测 jail 列表：fusionpbx、fusionpbx-mac、nginx-404、nginx-dos、ssh、sshd。

查看指定 jail 详情：

fail2ban-client status sshd

实测回显（关键行）：

Currently failed: 0
File list: /var/log/auth.log
Currently banned: 0

排查 fail2ban 启动失败时的两个实测原因：缺 /var/log/auth.log（sshd jail）与缺 /var/log/syslog（fusionpbx-mac jail），touch 创建后 systemctl restart fail2ban 即恢复（完整过程见《Debian 12 安装 FusionPBX 5.6 指南》常见问题 Q4）。

七、服务与站点自检命令

日常巡检可按下列顺序逐项执行：

systemctl is-active freeswitch

systemctl is-active nginx

systemctl is-active php8.4-fpm

systemctl is-active postgresql@18-main

systemctl is-active fail2ban

实测回显均应为 active。Nginx 改动站点配置后先自检再重载：

nginx -t

实测回显：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

八、注意事项

• fs_cli 走 Event Socket（127.0.0.1:8021）连接 FreeSWITCH，8021 仅监听本机是安全特性，不要为远程管理把它暴露到公网；
• originate/uuid_kill 直接作用于实时呼叫，生产环境操作前先用 show channels 核对 UUID；
• upgrade.php 会改库结构与权限，执行前建议备份 PostgreSQL（su - postgres -c "pg_dump fusionpbx > /root/fusionpbx.bak.sql"）；
• fail2ban 误封合法话机 IP 时，先用 fail2ban-client status fusionpbx 确认，再按 jail 解封。

九、常见问题

Q1：fs_cli 连接失败（无法进入控制台）？

先查 systemctl is-active freeswitch 是否 active；再确认 Event Socket 在监听：ss -tlnp | grep 8021 应有 127.0.0.1:8021。FreeSWITCH 启动中（-ncwait 尚未返回）时 fs_cli 会短暂连不上，稍等重试。

Q2：执行 reloadxml 后业务配置没变？

FusionPBX 的分机/dialplan 由 xml_handler 动态生成，不读静态 XML，Web 修改本就对呼叫即时生效；reloadxml 只对 vars.xml、autoload_configs 等静态文件起作用（见 4.3）。

Q3：upgrade.php 执行报错或权限不足？

需以能读 /etc/fusionpbx/config.conf 的用户执行（root 或 www-data），脚本要读取其中的数据库连接参数；Web 端升级入口 /core/upgrade/index.php 与该 CLI 等价，Nginx 已为其单独放宽 fastcgi_read_timeout 到 15 分钟。

Q4：话机突然注册不上，且确认密码无误？

大概率被 fail2ban 封禁（SIP 爆破防护误伤）：fail2ban-client status fusionpbx 查看 Currently banned 列表确认。

十、参考链接

• 官方文档：https://docs.fusionpbx.com/
• 主仓库：https://github.com/fusionpbx/fusionpbx
• 本专栏安装篇：《Debian 12 安装 FusionPBX 5.6 指南》
• 本专栏配置篇：《FusionPBX 5.6 配置参数详解》
• 姊妹专栏底层引擎命令：《FreeSWITCH 1.11 常用 CLI 命令与工具详解》