FreeSWITCH 1.11 常用 CLI 命令与工具详解
FreeSWITCH 1.11.3 命令行管理三层体系详解：freeswitch 启动器与 fs_cli 全量参数实测、交互模式与斜杠命令、status/show/sofia/originate/uuid/fsctl/console 等 API 命令逐条实测回显与连接排错。
FreeSWITCH 1.11 常用 CLI 命令与工具详解
目标：讲清 FreeSWITCH 1.11.3 日常管理的三层命令体系——
freeswitch服务进程启动器（运行模式与目录覆盖全量选项）、fs_cli控制台客户端（单命令/交互两种模式与全量连接参数），以及经它们执行的核心 API 命令（status/version/show/sofia/originate/uuid 系列/fsctl 等，逐条实测回显）。全部命令与回显均已在 Ubuntu 22.04 实测环境逐条实测（2026-10-21/22）；安装步骤见 《Ubuntu 22.04 安装 FreeSWITCH 1.11 指南》，配置参数详见 《FreeSWITCH 1.11 配置参数详解》，选型背景见 《FreeSWITCH 介绍与选型指南》。
一、环境信息
本章列出本文所有命令与回显所依据的实测环境，读者环境若版本一致即可逐条复现：
- 操作系统：Ubuntu 22.04 LTS（x86_64）
- FreeSWITCH 版本：1.11.3-release~64bit（
/usr/local/freeswitch/bin/freeswitch -version实测，回显FreeSWITCH version: 1.11.3-release~64bit (-release 64bit)） - 安装前缀：
/usr/local/freeswitch（源码编译安装，目录布局为 1.11 autoconf 标准式） - 两个可执行文件：
/usr/local/freeswitch/bin/freeswitch（核心服务进程）、/usr/local/freeswitch/bin/fs_cli（控制台客户端） - 运行状态：systemd 托管，
Type=simple+ExecStart=/usr/local/freeswitch/bin/freeswitch -nf -nonat（托管方案与排障链详见安装指南 4.10 节） - 控制台接入参数：Event Socket 监听
:::8021，默认密码ClueCon（出厂autoload_configs/event_socket.conf.xml）
版本号有个实测细节：二进制选项
-version回显是小写FreeSWITCH version:，而 fs_cli 里的 API 命令version回显是大写FreeSWITCH Version:——两者都真实存在，写脚本做版本比对时注意区分。
二、工具概览
2.1 三层分工
FreeSWITCH 的命令行管理不是「一个 CLI 包打天下」，而是三层各管一段：
| 层 | 工具/载体 | 职责 | 典型用法 |
|---|---|---|---|
| 服务进程层 | freeswitch 可执行文件 | 把核心跑起来：加载配置树、装载模块、启动呼叫引擎；选项控制前台/后台、优先级、目录覆盖 | 启动/停止、指定非默认配置目录调试、打印版本 |
| 控制台客户端层 | fs_cli | 经 ESL（Event Socket）连到运行中的核心，把你敲的命令送进去、把日志吐出来 | 单命令模式 -x、交互模式 |
| API 命令层 | 各模块注册的 API 命令 | 真正干活的一层：查状态、拨测试呼叫、踢通道、控并发 | 经 fs_cli 执行，如 status、sofia status、originate |
三者的调用链是单向的：
shell → fs_cli --ESL/TCP 8021--> FreeSWITCH 核心 → 各模块注册的 API
fs_cli 本身不处理任何呼叫逻辑，只是遥控器；freeswitch 的启动选项只影响核心进程本身，跑起来之后再改不了（改目录类选项必须重启进程）。理解这个分工后，「改了配置不生效」这类问题就能快速定位到该重启进程还是该 reloadxml（生效边界详见配置详解 3.4 节）。
2.2 帮助入口
三个入口各有分工，本文 4.1/4.2 的全量参数表即逐行照录自前两条命令的真实输出：
| 入口 | 命令 | 能查到什么 |
|---|---|---|
| 启动器选项 | /usr/local/freeswitch/bin/freeswitch -help | 全部启动选项（运行模式类 + 目录覆盖类） |
| 客户端选项 | /usr/local/freeswitch/bin/fs_cli --help | 全部连接参数 |
| API 命令清单 | /usr/local/freeswitch/bin/fs_cli -x help | 当前已注册的全部 API 命令（含所属模块） |
fs_cli -x help 输出为 Valid Commands: 开头的四列清单（命令、参数、说明、所属模块），篇幅 300+ 行，节选前几行看格式（实测）：
Valid Commands:
...,,Shutdown,mod_commands
acl,<ip> <list_name>,Compare an ip to an acl list,mod_commands
alias,[add|stickyadd] <alias> <command> | del [<alias>|*],Alias,mod_commands
banner,,Return the system banner,mod_commands
bgapi,<command>[ <arg>],Execute an api command in a thread,mod_commands
末列即注册该命令的模块，配合 4.3.2 的 show modules 可以精确定位「某个命令是谁提供的」。
三、前置条件
本文所有操作基于以下前提，逐条确认后即可复现：
- FreeSWITCH 正在运行：
systemctl is-active freeswitch→ 回显active（实测）。 - fs_cli 可连入：
/usr/local/freeswitch/bin/fs_cli -x status→ 回显含FreeSWITCH (Version 1.11.3 -release 64bit) is ready（实测）。 - Event Socket 出厂参数（
autoload_configs/event_socket.conf.xml实际内容）：
<configuration name="event_socket.conf" description="Socket Client">
<settings>
<param name="nat-map" value="false"/>
<param name="listen-ip" value="::"/>
<param name="listen-port" value="8021"/>
<param name="password" value="ClueCon"/>
若你已按配置详解 6.1 节把密码改为自有强密码，fs_cli 需带 -p <密码> 连接；未改则默认 ClueCon 即可。
- 注意两个密码不要混淆：fs_cli 连接用的是
event_socket.conf.xml的ClueCon（ESL 控制通道密码），不是vars.xml里的default_password（出厂值1234，SIP 分机注册密码）。fs_cli 连不上时先核对前者。 - 有 root（或 sudo）权限；若未把
/usr/local/freeswitch/bin加入 PATH，本文命令一律用全路径。
四、各工具详解
4.1 freeswitch：服务进程启动器
4.1.1 运行行为类选项全表
以下两表逐行照录 freeswitch -help 的原文输出（实测），「说明」列为对原文的中文解读：
| 选项 | -help 原文 | 说明 |
|---|---|---|
-nf | no forking | 不 fork，前台运行（systemd Type=simple 托管必用） |
-nc | do not output to a console and background | 后台守护运行，不占终端 |
-ncwait | do not output to a console and background but wait until the system is ready before exiting (implies -nc) | 后台运行且等系统就绪后才让启动命令返回（隐含 -nc） |
-c | output to a console and stay in the foreground | 前台运行并进入控制台（排查启动问题时用） |
-stop | stop freeswitch | 向默认运行目录下的实例发送停止指令 |
-version | print the version and exit | 打印版本后退出 |
-help | this message | 打印本帮助 |
-rp | enable high(realtime) priority settings | 高（实时）优先级运行 |
-lp | enable low priority settings | 低优先级运行 |
-np | enable normal priority settings | 普通优先级运行 |
-vg | run under valgrind | 在 valgrind 下运行（内存问题排查） |
-core | dump cores | 允许转储 core |
-nosql | disable internal sql scoreboard | 关闭内部 SQL 记分板 |
-heavy-timer | Heavy Timer, possibly more accurate but at a cost | 重型定时器，更精确但有开销 |
-nonat | disable auto nat detection | 关闭自动 NAT 探测 |
-nonatmap | disable auto nat port mapping | 关闭自动 NAT 端口映射 |
-nocal | disable clock calibration | 关闭时钟校准 |
-nort | disable clock clock_realtime | 不使用 realtime 时钟（help 原文即如此拼写） |
-reincarnate | restart the switch on an uncontrolled exit | 进程意外退出时自动拉起 |
-reincarnate-reexec | run execv on a restart (helpful for upgrades) | 重启时走 execv（便于升级场景） |
-u [user] | specify user to switch to | 降权到指定用户运行 |
-g [group] | specify group to switch to | 降权到指定组运行 |
⚠️ 1.11.3 重要差异：
-help全量输出中没有-pidfile选项。网上老文档里freeswitch -pidfile <路径>的写法在 1.11.3 已不可用，systemd 托管请直接用Type=simple+-nf前台方案（完整排障链见安装指南 4.10 节）。
4.1.2 目录覆盖类选项全表
同样是 -help 原文照录。这组选项不改行为，只把某个目录指到别处，多实例/自定义布局时使用：
| 选项 | -help 原文 | 说明 |
|---|---|---|
-base [basedir] | alternate prefix directory | 替换前缀目录（其余相对目录的基准） |
-cfgname [filename] | alternate filename for FreeSWITCH main configuration file | 替换主配置文件名 |
-conf [confdir] | alternate directory for FreeSWITCH configuration files | 替换配置目录 |
-log [logdir] | alternate directory for logfiles | 替换日志目录 |
-run [rundir] | alternate directory for runtime files | 替换运行目录（pid 等） |
-db [dbdir] | alternate directory for the internal database | 替换内部数据库目录 |
-mod [moddir] | alternate directory for modules | 替换模块目录 |
-htdocs [htdocsdir] | alternate directory for htdocs | 替换 htdocs 目录 |
-scripts [scriptsdir] | alternate directory for scripts | 替换脚本目录 |
-temp [directory] | alternate directory for temporary files | 替换临时文件目录 |
-grammar [directory] | alternate directory for grammar files | 替换语法文件目录 |
-certs [directory] | alternate directory for certificates | 替换证书目录 |
-recordings [directory] | alternate directory for recordings | 替换录音目录 |
-storage [directory] | alternate directory for voicemail storage | 替换留言存储目录 |
-cache [directory] | alternate directory for cache files | 替换缓存目录 |
-sounds [directory] | alternate directory for sound files | 替换提示音目录 |
这些目录的出厂落位（global_getvar 实测全表）见配置详解 4.2 节的目录变量表，两处可对照使用。
4.1.3 实测：-version 与 -help
/usr/local/freeswitch/bin/freeswitch -version
实测回显（退出码 0）：
FreeSWITCH version: 1.11.3-release~64bit (-release 64bit)
-help（即 4.1.1/4.1.2 两表的出处）实测退出码同样为 0。
运行行为类选项中，本文环境由 systemd 以 -nf -nonat 前台托管（安装指南 4.10 节实测），-nc/-c/-ncwait/-stop 未在托管环境中实测（避免干扰 systemd 状态管理），语义以 -help 原文为准；生产上启停一律走 systemctl start/stop freeswitch，原因见 5.1 节。
4.2 fs_cli：控制台客户端
4.2.1 连接参数全表
逐行照录 fs_cli --help 的 usage 原文（实测）：
| 参数 | --help 原文 | 说明 |
|---|---|---|
-?,-h --help | Usage Information | 打印本帮助 |
-H, --host=hostname | Host to connect | 目标主机（默认本机） |
-P, --port=port | Port to connect (1 - 65535) | 端口（默认取 event_socket 配置 8021） |
-u, --user=user@domain | user@domain | 以 user@domain 形式标明身份 |
-p, --password=password | Password | 密码（默认 ClueCon，改过配置则传新密码） |
-i, --interrupt | Allow Control-c to interrupt | 允许 Ctrl-C 中断而不退出 |
-x, --execute=command | Execute Command and Exit | 执行单条命令后退出 |
-l, --loglevel=command | Log Level | 日志级别 |
-U, --log-uuid | Include UUID in log output | 日志输出带完整 UUID |
-S, --log-uuid-short | Include shortened UUID in log output | 日志输出带短 UUID |
-q, --quiet | Disable logging | 关闭日志输出（脚本采集干净） |
-r, --retry | Retry connection on failure | 连接失败自动重试 |
-R, --reconnect | Reconnect if disconnected | 断线后自动重连 |
-d, --debug=level | Debug Level (0 - 7) | 调试级别 0-7 |
-b, --batchmode | Batch mode | 批处理模式 |
-t, --timeout | Timeout for API commands (in milliseconds) | API 命令超时（毫秒） |
-T, --connect-timeout | Timeout for socket connection (in milliseconds) | 建连超时（毫秒） |
-n, --no-color | Disable color | 关闭彩色输出（落日志/脚本友好） |
-s, --set-log-uuid | Set UUID to filter log events | 设置按 UUID 过滤日志事件 |
日常运维最高频的是 -x（单命令）与 -r（守护脚本里容忍服务重启瞬间）。交互模式进阶（/log、/uuid、/filter 等斜杠命令）见 4.2.3。
4.2.2 单命令模式：-x
-x 执行一条 API 命令即退出，是脚本化巡检的主力用法：
/usr/local/freeswitch/bin/fs_cli -x version
/usr/local/freeswitch/bin/fs_cli -x uptime
实测回显（依次对应）：
FreeSWITCH Version 1.11.3-release~64bit (-release 64bit)
250
uptime 返回核心已运行秒数（250 秒与同一会话窗口内 status 回显的 UP 0 years, 0 days, 0 hours, 4 minutes, 10 seconds 吻合）。
命令不存在时的真实表现：
/usr/local/freeswitch/bin/fs_cli -x foobar
实测回显：
-ERR foobar Command not found!
注意此时退出码是 0——脚本里不能只看退出码判断成败，要解析输出中的 -ERR 前缀（连接失败的退出码才是非 0，见 4.2.5）。
4.2.3 交互模式
直接运行 fs_cli 进入交互模式（实测）。连接成功先打印 banner 与一行日志级别确认，随后出现以主机名为后缀的提示符：
.=======================================================.
| _____ ____ ____ _ ___ |
| | ___/ ___| / ___| | |_ _| |
| | |_ \___ \ | | | | | | |
| | _| ___) | | |___| |___ | | |
| |_| |____/ \____|_____|___| |
| |
.=======================================================.
| Anthony Minessale II, Ken Rice, |
| Michael Jerris, Travis Cross |
| FreeSWITCH (http://www.freeswitch.org) |
| Paypal Donations Appreciated: paypal@freeswitch.org |
| Brought to you by ClueCon http://www.cluecon.com/ |
.=======================================================.
Type /help <enter> to see a list of commands
+OK log level [7]
freeswitch@5f8783896c5f>
（节选自实测输出；banner 后还有一幅 fs_cli 字符画，篇幅原因略。）
三个细节：+OK log level [7] 是连接建立时 fs_cli 自动订阅日志的确认；提示符 freeswitch@<主机名> 中的主机名随你的服务器变化，属正常现象；在提示符后可直接敲 API 命令（如 status），带斜杠 / 开头的则是 fs_cli 自身的控制命令，两者不混用。
交互内斜杠命令全表（/help 实测原文）：
Command Description
-----------------------------------------------
/help Help
/exit, /quit, /bye, ... Exit the program.
/event, /noevents, /nixevent Event commands.
/log, /nolog Log commands.
/uuid Filter logs for a single call uuid
/filter Filter commands.
/logfilter Filter Log for a single string.
/debug [0-7] Set debug level.
最常用的组合打法：先 /log 6 把日志级别压到 info，再 /uuid <通话UUID> 只看某一路通话的日志，排查完 /uuid 清除过滤、/quit 退出。退出用 /quit（或 /exit、/bye，等价）。
4.2.4 输出控制：-q 与 -n
脚本采集回显时建议 -q（关闭日志噪声）或至少 -n（去彩色控制符）：
/usr/local/freeswitch/bin/fs_cli -q -x status
实测回显（对比 4.2.3 交互模式，无 banner、无 +OK log level 行，直接是命令结果）：
UP 0 years, 0 days, 0 hours, 6 minutes, 43 seconds, 276 milliseconds, 526 microseconds
FreeSWITCH (Version 1.11.3 -release 64bit) is ready
2 session(s) since startup
其余日志类参数（-l 指定级别、-U/-S 给日志加 UUID 前缀、-s 按 UUID 过滤）按 4.2.1 表中原文语义使用即可，本文未逐一展开。
4.2.5 连接排错
密码不符时的真实报错（实测，-p 传入错误密码）：
/usr/local/freeswitch/bin/fs_cli -x status -p wrongpw
实测回显：
[ERROR] fs_cli.c:1699 main() Error Connecting []
退出码 255。Error Connecting [] 是 ESL 握手被拒后的统一表现，不仅限于密码错误——服务未启动、8021 端口不通、密码改过未同步，都是这一条报错。排查顺序：
systemctl is-active freeswitch确认服务活着；- 核对
event_socket.conf.xml的password与-p传值一致； - 远程连接时确认
listen-ip（出厂::即全监听）与防火墙放行 8021。
长驻脚本建议加 -r（连不上就重试，扛服务重启窗口）或 -R（运行中断线重连）；对自动化采集再加 -T 3000 给建连限时，避免网络异常时脚本吊死。
4.3 核心 API 命令实测
以下命令全部经 fs_cli -x 执行，回显逐条实测。为省篇幅，命令块中用 $B 代指 /usr/local/freeswitch/bin/fs_cli——实际执行时请写全路径。
4.3.1 系统状态类：status / version / uptime
/usr/local/freeswitch/bin/fs_cli -x status
实测回显（全新启动后）：
UP 0 years, 0 days, 0 hours, 3 minutes, 58 seconds, 254 milliseconds, 470 microseconds
FreeSWITCH (Version 1.11.3 -release 64bit) is ready
0 session(s) since startup
0 session(s) - peak 0, last 5min 0
0 session(s) per Sec out of max 30, peak 0, last 5min 0
1000 session(s) max
min idle cpu 0.00/95.77
Current Stack Size/Max 240K/8192K
逐行解读：
| 行 | 含义 | 关联参数 |
|---|---|---|
| UP … | 核心运行时长 | — |
| … is ready | 核心就绪标志 | — |
| … session(s) since startup | 启动以来累计会话数（含峰值） | — |
| … per Sec out of max 30 | 每秒新建会话数与上限 | switch.conf.xml 的 sessions-per-second（fsctl 可查，见 4.3.6） |
| 1000 session(s) max | 并发会话上限 | switch.conf.xml 的 max-sessions（修改生效边界见配置详解 3.4 节） |
| min idle cpu 0.00/95.77 | 空闲 CPU 保护线当前值/阈值 | switch.conf.xml 的 min-idle-cpu |
| Current Stack Size/Max 240K/8192K | 会话线程栈大小 | switch.conf.xml 的相关内核参数 |
version、uptime 的回显已在 4.2.2 给出（注意 version 大写 V 与二进制 -version 小写 v 的差异）。
4.3.2 模块管理类：show modules / module_exists / unload / load / reloadxml
/usr/local/freeswitch/bin/fs_cli -x "show modules"
实测回显（CSV 四列：类型、API 名、模块名、so 文件路径；节选）：
type,name,ikey,filename
api,...,mod_commands,/usr/local/freeswitch/lib/freeswitch/mod/mod_commands.so
api,acl,mod_commands,/usr/local/freeswitch/lib/freeswitch/mod/mod_commands.so
api,alias,mod_commands,/usr/local/freeswitch/lib/freeswitch/mod/mod_commands.so
api,banner,mod_commands,/usr/local/freeswitch/lib/freeswitch/mod/mod_commands.so
api,bgapi,mod_commands,/usr/local/freeswitch/lib/freeswitch/mod/mod_commands.so
api,cdr_csv,mod_cdr_csv,/usr/local/freeswitch/lib/freeswitch/mod/mod_cdr_csv.so
api,console,mod_console,/usr/local/freeswitch/lib/freeswitch/mod/mod_console.so
完整输出数百行（每个已加载模块的每个 API 一行），节选处不再重复。从 name 列可直接回答「这条命令是哪个模块注册的」。
模块动态卸载/装载闭环（以无副作用的 mod_console 为例，实测）：
/usr/local/freeswitch/bin/fs_cli -x "unload mod_console"
/usr/local/freeswitch/bin/fs_cli -x "module_exists mod_console"
/usr/local/freeswitch/bin/fs_cli -x "load mod_console"
/usr/local/freeswitch/bin/fs_cli -x "module_exists mod_console"
实测回显（依次对应）：
+OK
false
+OK Reloading XML
+OK
true
注意 load 的回显是两行（+OK Reloading XML + +OK），unload 只有一行；module_exists 返回 true/false 字面值。
配置重载：
/usr/local/freeswitch/bin/fs_cli -x reloadxml
实测回显：
+OK [Success]
reloadxml 只重读 XML 配置树，对 switch.conf.xml 核心参数（max-sessions 等）无效、必须重启进程——完整实测链路（改参 → fsctl 验证 → 重启生效 → 还原）见配置详解 3.4 节。
4.3.3 变量查看类：global_getvar / eval
/usr/local/freeswitch/bin/fs_cli -x "global_getvar"
实测回显（键=值 每行一个，节选前 24 行）：
hostname=5f8783896c5f
local_ip_v4=10.0.0.6
local_mask_v4=255.255.255.0
local_ip_v6=::1
base_dir=/usr/local/freeswitch
recordings_dir=/usr/local/freeswitch/var/lib/freeswitch/recordings
sounds_dir=/usr/local/freeswitch/share/freeswitch/sounds
conf_dir=/usr/local/freeswitch/etc/freeswitch
log_dir=/usr/local/freeswitch/var/log/freeswitch
run_dir=/usr/local/freeswitch/var/run/freeswitch
db_dir=/usr/local/freeswitch/var/lib/freeswitch/db
mod_dir=/usr/local/freeswitch/lib/freeswitch/mod
htdocs_dir=/usr/local/freeswitch/share/freeswitch/htdocs
script_dir=/usr/local/freeswitch/share/freeswitch/scripts
temp_dir=/tmp
grammar_dir=/usr/local/freeswitch/share/freeswitch/grammar
fonts_dir=/usr/local/freeswitch/share/freeswitch/fonts
images_dir=/usr/local/freeswitch/var/lib/freeswitch/images
certs_dir=/usr/local/freeswitch/etc/freeswitch/tls
storage_dir=/usr/local/freeswitch/var/lib/freeswitch/storage
cache_dir=/usr/local/freeswitch/var/cache/freeswitch
data_dir=/usr/local/freeswitch/share/freeswitch
localstate_dir=/usr/local/freeswitch/var/lib/freeswitch
core_uuid=389858bd-60a6-4956-8db8-cad0718d8b6b
这张表就是「当前进程眼里的全部全局变量」，排配置问题时以它为准而不是猜（完整 70 行与逐类解读见配置详解 4.1/4.2 节）。
取单个变量用 eval（注意 $${} 引用的是 vars.xml 预处理变量，实测）：
/usr/local/freeswitch/bin/fs_cli -x 'eval $${local_ip_v4}'
实测回显：
10.0.0.6
4.3.4 SIP 状态类：sofia status / sofia status profile internal
/usr/local/freeswitch/bin/fs_cli -x "sofia status"
实测回显：
Name Type Data State
=================================================================================================
external-ipv6 profile sip:mod_sofia@[::1]:5080 RUNNING (0)
external profile sip:mod_sofia@182.54.113.29:5080 RUNNING (0)
external::example.com gateway sip:joeuser@example.com NOREG
10.0.0.6 alias internal ALIASED
internal-ipv6 profile sip:mod_sofia@[::1]:5060 RUNNING (0)
internal profile sip:mod_sofia@182.54.113.29:5060 RUNNING (0)
=================================================================================================
4 profiles 1 alias
要点：每个 profile 一行，RUNNING (N) 括号内是活跃呼叫数；gateway 行的 NOREG 表示网关未注册（出厂示例网关 example.com 的正常状态）；alias 行是 10.0.0.6 到 internal 的别名映射。排查「分机注册不上/外呼不通」时，先看这里 profile 是否 RUNNING、网关是否按预期 REG。
看单个 profile 的完整参数快照：
/usr/local/freeswitch/bin/fs_cli -x "sofia status profile internal"
实测回显（节选前 21 行，完整 36 行含编解码/DTMF/呼叫统计等）：
=================================================================================================
Name internal
Domain Name N/A
Auto-NAT false
DBName sofia_reg_internal
Pres Hosts 10.0.0.6,10.0.0.6
Dialplan XML
Context public
Challenge Realm auto_from
RTP-IP 10.0.0.6
Ext-RTP-IP 182.54.113.29
SIP-IP 10.0.0.6
Ext-SIP-IP 182.54.113.29
URL sip:mod_sofia@182.54.113.29:5060
BIND-URL sip:mod_sofia@182.54.113.29:5060;maddr=10.0.0.6;transport=udp,tcp
WS-BIND-URL sip:mod_sofia@10.0.0.6:5066;transport=ws
WSS-BIND-URL sips:mod_sofia@10.0.0.6:7443;transport=wss
HOLD-MUSIC local_stream://moh
OUTBOUND-PROXY N/A
CODECS IN OPUS,G722,PCMU,PCMA,H264,VP8
CODECS OUT OPUS,G722,PCMU,PCMA,H264,VP8
TEL-EVENT 101
这一节输出等于把 sip_profiles/internal.xml 的关键参数「运行态翻译」了一遍（CALLS-IN/OUT、FAILED-CALLS、REGISTRATIONS 等计数在完整输出的尾部），与配置文件逐项对照的方法见配置详解 5.8 节。
4.3.5 通话操作类：originate / show channels / uuid_dump / uuid_kill
用 loopback 环回号码发起一路测试呼叫（不依赖任何真实终端，实测）：
/usr/local/freeswitch/bin/fs_cli -x 'originate loopback/2022 &echo'
实测回显（+OK 后跟主叫腿 UUID）：
+OK 191873d5-1d29-44a3-82de-5d7c6691adbf
立即查看在途通道：
/usr/local/freeswitch/bin/fs_cli -x "show channels"
实测回显（表头一行 + 数据两行，CSV 未截断）：
uuid,direction,created,created_epoch,name,state,cid_name,cid_num,ip_addr,dest,application,application_data,dialplan,context,read_codec,read_rate,read_bit_rate,write_codec,write_rate,write_bit_rate,secure,hostname,presence_id,presence_data,accountcode,callstate,callee_name,callee_num,callee_direction,call_uuid,sent_callee_name,sent_callee_num,initial_cid_name,initial_cid_num,initial_ip_addr,initial_dest,initial_dialplan,initial_context
191873d5-1d29-44a3-82de-5d7c6691adbf,outbound,2026-10-21 17:28:03,1792603683,loopback/2022-a,CS_EXECUTE,,0000000000,,2022,,,xml,default,L16,8000,128000,L16,8000,128000,,5f8783896c5f,,,,EARLY,Outbound Call,2022,,191873d5-1d29-44a3-82de-5d7c6691adbf,,,,0000000000,,2022,xml,default
29c46955-d380-413f-8f96-69d7b777bace,inbound,2026-10-21 17:28:03,1792603683,loopback/2022-b,CS_EXECUTE,,0000000000,,2022,sleep,10000,xml,default,L16,8000,128000,L16,8000,128000,,5f8783896c5f,,,,RINGING,Outbound Call,2022,,,,,,0000000000,,2022,xml,default
2 total.
一路 loopback 呼叫是两条通道：-a 腿（outbound，主叫侧）与 -b 腿（inbound，被叫侧），共享 call_uuid。name 列、state 列、application 列是排障时最先看的三列。
导出某条通道的全部变量（UUID 取自上一步，实测节选前 25 行）：
/usr/local/freeswitch/bin/fs_cli -x "uuid_dump 191873d5-1d29-44a3-82de-5d7c6691adbf"
实测回显（节选）：
Event-Name: CHANNEL_DATA
Core-UUID: 637e42bf-6565-410f-9bc3-17d39ef574ea
FreeSWITCH-Hostname: 5f8783896c5f
FreeSWITCH-Switchname: 5f8783896c5f
FreeSWITCH-IPv4: 10.0.0.6
FreeSWITCH-IPv6: %3A%3A1
Event-Date-Local: 2026-10-21%2017%3A28%3A13
Event-Date-GMT: Wed,%2021%20Oct%202026%2017%3A28%3A13%20GMT
Event-Date-Timestamp: 1792603693445591
Event-Calling-File: mod_commands.c
Event-Calling-Function: uuid_dump_function
Event-Calling-Line-Number: 6495
Event-Sequence: 619
Channel-State: CS_EXECUTE
Channel-Call-State: EARLY
Channel-State-Number: 4
Channel-Name: loopback/2022-a
Unique-ID: 191873d5-1d29-44a3-82de-5d7c6691adbf
Call-Direction: outbound
Presence-Call-Direction: outbound
Channel-HIT-Dialplan: true
Channel-Call-UUID: 191873d5-1d29-44a3-82de-5d7c6691adbf
Answer-State: early
Channel-Read-Codec-Name: L16
Channel-Read-Codec-Rate: 8000
（URL 编码字符如 %3A 是 : 的转义；完整输出含上百个通道变量，排查 dialplan 变量全靠它。）
挂断测试呼叫并确认回收：
/usr/local/freeswitch/bin/fs_cli -x "uuid_kill 191873d5-1d29-44a3-82de-5d7c6691adbf"
/usr/local/freeswitch/bin/fs_cli -x "show channels"
实测回显（uuid_kill 一行；show channels 为 kill 后立刻查询的真实快照）：
+OK
uuid,direction,created,created_epoch,name,state,cid_name,cid_num,ip_addr,dest,application,application_data,dialplan,context,read_codec,read_rate,read_bit_rate,write_codec,write_rate,write_bit_rate,secure,hostname,presence_id,presence_data,accountcode,callstate,callee_name,callee_num,callee_direction,call_uuid,sent_callee_name,sent_callee_num,initial_cid_name,initial_cid_num,initial_ip_addr,initial_dest,initial_dialplan,initial_context
191873d5-1d29-44a3-82de-5d7c6691adbf,outbound,2026-10-21 17:28:03,1792603683,loopback/2022-a,CS_CONSUME_MEDIA,,0000000000,,2022,,,xml,default,L16,8000,128000,L16,8000,128000,,5f8783896c5f,,,,DOWN,Outbound Call,2022,,191873d5-1d29-44a3-82de-5d7c6691adbf,,,,0000000000,,2022,xml,default
29c46955-d380-413f-8f96-69d7b777bace,inbound,2026-10-21 17:28:03,1792603683,loopback/2022-b,CS_EXECUTE,,0000000000,,2022,sleep,10000,xml,default,L16,8000,128000,L16,8000,128000,,5f8783896c5f,,,,RINGING,Outbound Call,2022,,,,,,0000000000,,2022,xml,default
2 total.
注意这条实测的教益：uuid_kill 返回 +OK 只表示「挂断指令已受理」，kill 后立刻查仍可能看到被杀腿处于收尾状态（上例 a 腿 callstate 已转 DOWN）、而 b 腿因为还在执行自己的应用（上例 sleep 10000）要等应用结束才消失。判断清理完成请以通道 state/callstate 为准，别只看 +OK。测试呼叫占的是真实并发配额（max-sessions），测完务必清理。
4.3.6 运行控制类：fsctl / console loglevel
fsctl 是核心运行态的总控。不带参数执行会打出全部子命令清单（实测原文）：
/usr/local/freeswitch/bin/fs_cli -x fsctl
实测回显：
-USAGE: [api_expansion [on|off]|recover|send_sighup|hupall|pause [inbound|outbound]|resume [inbound|outbound]|shutdown [cancel|elegant|asap|now|restart]|uuid_version [4|7]|sps|sps_peak_reset|sync_clock|sync_clock_when_idle|reclaim_mem|max_sessions|min_dtmf_duration [num]|max_dtmf_duration [num]|default_dtmf_duration [num]|min_idle_cpu|loglevel [level]|debug_level [level]|mdns_resolve [enable|disable]]
查询类子命令实测（并发上限与每秒新建上限）：
/usr/local/freeswitch/bin/fs_cli -x "fsctl max_sessions"
/usr/local/freeswitch/bin/fs_cli -x "fsctl sps"
实测回显（依次对应）：
+OK max sessions: 1000
+OK sessions per second: 30
sps 带参会当场修改运行值（重启后回落到配置值），实测修改→验证→还原闭环：
/usr/local/freeswitch/bin/fs_cli -x "fsctl sps 25"
/usr/local/freeswitch/bin/fs_cli -x "fsctl sps"
/usr/local/freeswitch/bin/fs_cli -x "fsctl sps 30"
/usr/local/freeswitch/bin/fs_cli -x "fsctl sps"
实测回显（依次对应）：
+OK sessions per second: 25
+OK sessions per second: 25
+OK sessions per second: 30
+OK sessions per second: 30
fsctl loglevel 查询核心日志级别，本文环境实测回显：
+OK log level: DISABLE [-1]
回显 DISABLE [-1] 表示核心日志过滤器当前为禁用态（本环境实测如此）；日常调日志级别不操作它——控制台日志级别由 console loglevel 管（见下）。
console loglevel 由 mod_console 注册，查询与设置共用同一响应格式，级别数字 0-7（0 最低、7 最高，出厂 console_loglevel=info 对应 INFO，实测 3=ERR、6=INFO）。查询→下调→还原实测：
/usr/local/freeswitch/bin/fs_cli -x "console loglevel"
/usr/local/freeswitch/bin/fs_cli -x "console loglevel 3"
/usr/local/freeswitch/bin/fs_cli -x "console loglevel"
/usr/local/freeswitch/bin/fs_cli -x "console loglevel 6"
/usr/local/freeswitch/bin/fs_cli -x "console loglevel"
实测回显（依次对应）：
+OK console log level set to INFO
+OK console log level set to ERR
+OK console log level set to ERR
+OK console log level set to INFO
+OK console log level set to INFO
该修改即时生效但同样不落盘（重启回落到 vars.xml 的 console_loglevel）。其余 fsctl 子命令（shutdown elegant 优雅停机、reclaim_mem 归还内存、sync_clock 时钟同步等）按 4.3.6 开头的 USAGE 原文使用；hupall/shutdown 属破坏性操作，生产执行前先 show channels 确认影响面。
五、注意事项
- systemd 托管下启停一律走 systemctl。
freeswitch -stop会绕过 systemd 直接停进程，导致systemctl status与真实状态脱节；本文环境未实测-stop正是出于此顾虑。停：sudo systemctl stop freeswitch；起：sudo systemctl start freeswitch。 - 修改核心配置后的生效边界：
reloadxml只对 dialplan/directory 类配置即改即生效；switch.conf.xml的max-sessions等核心参数必须重启进程（完整实测链见配置详解 3.4 节与 FAQ Q1）。改完用fsctl max_sessions验证运行值，别凭感觉。 - 脚本判断成败不能只看退出码：
-x对「命令不存在」返回退出码 0（输出-ERR ... Command not found!），只有连接层失败才是非 0（255）。巡检脚本请同时匹配-ERR与Error Connecting两种形态。 - 交互模式自带一行
+OK log level [7]，脚本采集时用-q去掉，避免污染输出（对比见 4.2.4）。 - 两个密码各管一摊：ESL 控制通道密码（
event_socket.conf.xml，出厂ClueCon）管 fs_cli 连接；分机注册密码（vars.xml的default_password，出厂1234）管 SIP 分机。改 ESL 密码后所有 fs_cli/ESL 调用方要同步更新（改法与验证见配置详解 6.1 节实测场景）。 - originate 测试呼叫是真实会话：占并发配额、计入
status的 session 计数，测完uuid_kill清理并确认通道消失（收尾窗口见 4.3.5 实测）。 - 版本输出有两套大小写：
freeswitch -version为FreeSWITCH version:，APIversion为FreeSWITCH Version:，脚本做版本比对别混用锚点。
六、常见问题（FAQ）
Q1：fs_cli 报 Error Connecting [] 怎么排查？
按 4.2.5 的顺序走：服务是否 active → 密码是否与 event_socket.conf.xml 一致 → 8021 是否可达。三个都是这一条报错，逐层排除即可。注意别拿 vars.xml 的 default_password 去连 ESL——那是分机注册密码，与控制通道无关（注意事项 5）。
Q2：敲某条命令返回 -ERR <命令名> Command not found!？
该 API 命令未注册：可能是所属模块未加载，或命令名拼写有误。先用 fs_cli -x help 查命令是否存在、末列确认所属模块；再用 module_exists <模块名> 确认模块状态（true/false 实测形态见 4.3.2）；未加载则 load <模块名> 补上。
Q3：status 里 out of max 30 和 1000 session(s) max 是什么关系？
前者是每秒新建会话数上限（sessions-per-second，防呼叫风暴），后者是并发会话总数上限（max-sessions）。运行值分别用 fsctl sps、fsctl max_sessions 查（实测见 4.3.6），两个都是保护阀，触发时新呼叫会被拒。
Q4：uptime 返回的数字单位是什么？
秒。实测 250 与同一时刻 status 的 UP 0 years, 0 days, 0 hours, 4 minutes, 10 seconds 吻合（4.2.2）。脚本里用它判断「服务是否刚被重启过」很方便。
Q5：老文档里 freeswitch -pidfile 为什么用不了？
1.11.3 的 -help 全量输出中没有该选项（4.1.1 表即原文佐证），沿用老写法会导致 systemd Type=forking 方案读不到 PID 文件而判启动超时。正确姿势是 Type=simple + freeswitch -nf -nonat 前台托管，完整排障链（含 Can't open PID file ... Operation not permitted 的失败现场）见安装指南 4.10 节。
Q6：怎么确认某条命令由哪个模块提供？
两条路：fs_cli -x help 的输出末列直接给出模块名（2.2 节节选）；或 show modules 按 name 列检索（CSV 实测格式见 4.3.2），同时能看到对应 so 文件路径，便于确认该模块是否真的加载自预期目录。
七、参考链接
- FreeSWITCH 官方文档（CLI、模块、API 文档导航入口）：https://developer.signalwire.com/freeswitch/
- Event Socket 模块文档（ESL 8021/密码）：https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Modules/mod%5Fevent%5Fsocket%5F8919977.html
- 1.11.3 源码包（
-help文本出处src/switch.c、src/fs_cli.c，含出厂默认配置）：https://files.freeswitch.org/releases/freeswitch/freeswitch-1.11.3.-release.tar.xz - FreeSWITCH GitHub 仓库（在线查阅源码）：https://github.com/signalwire/freeswitch
- 同专栏篇目：《FreeSWITCH 介绍与选型指南》、《Ubuntu 22.04 安装 FreeSWITCH 1.11 指南》、《FreeSWITCH 1.11 配置参数详解》