FreePBX 17 常用 CLI 命令与工具详解
FreePBX 17 命令行工具实测详解：fwconsole 全套子命令（ma/setting/reload/job/bulkimport/mysql）、asterisk -rx 运行时查询（pjsip/rtp/dialplan/core）、sipsak 注册测试、systemctl SysV 托管特性与数据库直查，全部配真实回显与 FAQ（2026-10-26 实测）。
FreePBX 17 常用 CLI 命令与工具详解
目标：系统梳理 FreePBX 17 日常管理与排障所需的命令行工具——fwconsole 全套子命令、asterisk 运行时查询、sipsak SIP 测试、systemd 服务管理与数据库直查，全部命令配真实回显与易踩坑提示。已在 Debian 12（bookworm）裸机安装的 FreePBX 17.0.19.32 + Asterisk 22.11.0 环境逐条实测通过。
一、环境信息
- 操作系统：Debian 12（bookworm），x86_64。
- FreePBX：17（framework 17.0.19.32，
fwconsole --version→FW Console - FreePBX Utility 17.0.19.32）。 - Asterisk：22.11.0（
asterisk -V→Asterisk 22.11.0）。 - 安装方式：官方一键脚本在线安装，113 个模块 Enabled（与 《Debian 12 安装 FreePBX 17 指南》同一实测环境）。
- 服务器 IP：
10.89.72.20；SIP 测试客户端 IP：10.89.72.50（Debian + sipsak）。 - 示例资源：分机
1001（密码q1w2e3r4）、自建队列700、自建拨号计划8000。
二、工具概览
FreePBX 17 的命令行工具按「管理层」划分为五类：
| 工具 | 管理层 | 典型用途 |
|---|---|---|
fwconsole | FreePBX 层（PHP） | 模块管理、配置重载、参数查看、定时任务、批量导入、启停服务 |
asterisk -rx '<命令>' | Asterisk 层（核心引擎） | 运行时状态查询：分机/注册/RTP/拨号计划/通话 |
sipsak | 协议层（第三方工具） | 从终端视角模拟 SIP REGISTER/呼叫，验证注册链路 |
systemctl | 系统服务层 | asterisk / apache2 / mariadb 三个服务的启停与状态 |
mariadb（含 fwconsole mysql） | 数据层 | 直查配置库（asterisk/asteriskcdrdb）核对数据 |
分工口诀：FreePBX 的东西（模块/参数/重载）找 fwconsole；Asterisk 的东西（端点/信道/拨号计划）找 asterisk -rx；链路通不通找 sipsak；进程活不活找 systemctl。
三、前置条件
- root 或 sudo 权限（fwconsole 多数子命令需要 root，普通用户会报权限错误）。
fwconsole --version正常输出版本号（安装完成的最低验证）。- sipsak 已在测试客户端安装：
apt-get install -y sipsak（验证注册用，服务器端非必需）。
四、各工具详解
4.1 fwconsole：FreePBX 统一管理入口
4.1.1 版本与帮助
fwconsole --version
FW Console - FreePBX Utility 17.0.19.32
不带参数执行 fwconsole 显示 ASCII Logo 与全局选项，紧随其后的 Available commands 即子命令总览（实测节选）：
backup [bu] Run backup and restore jobs
bulkimport [bi] This command is used to import extensions and dids
chown Change ownership of files
context [cx] Shows the specified context from the dialplan
convert2pjsip Convert legacy chan_sip extensions to chan_pjsip
job Centralized job management
kvstore Manage kvstore
moduleadmin [ma] Module Administration
mysql [m] Run a mysql Query:
reload [r] Reload Configs
restart Start Asterisk and run other needed FreePBX commands
setting [set] View and update settings. Usage: fwconsole setting <keyword> or fwconsole setting <keyword> <newvalue>
sounds Sound Language Prompts
start Start Asterisk and run other needed FreePBX commands
stop Stop Asterisk and run other needed FreePBX commands
trunks Enable and disable trunks from the command line
userman User Manager
方括号是别名（如 fwconsole ma = fwconsole moduleadmin、fwconsole r = fwconsole reload）。
4.1.2 模块管理：fwconsole ma
列出全部模块及状态（实测首屏）：
fwconsole ma list
No repos specified, using: [standard] from last GUI settings
+---------------------+------------+---------+-------------+-----------+
| Module | Version | Status | License | Signature |
+---------------------+------------+---------+-------------+-----------+
| accountcodepreserve | 17.0.0.2 | Enabled | GPLv2 | Sangoma |
| adv_recovery | 17.0.10.1 | Enabled | Commercial | Sangoma |
| allowlist | 17.0.1.1 | Enabled | GPLv3+ | Sangoma |
| amd | 17.0.1 | Enabled | GPLv3+ | Sangoma |
| announcement | 17.0.2.1 | Enabled | GPLv3+ | Sangoma |
| api | 17.0.3 | Enabled | AGPLv3+ | Sangoma |
| areminder | 17.0.3.12 | Enabled | Commercial | Sangoma |
+---------------------+------------+---------+-------------+-----------+
统计已启用模块数（配合 grep 做安装完整性核对）：
fwconsole ma list | grep -c Enabled
113
常用子命令一览（实测环境的 17 语法）：
| 命令 | 作用 |
|---|---|
fwconsole ma list | 列出模块与版本/状态/签名 |
fwconsole ma downloadinstall <模块名> | 从模块市场下载并安装（自动解析依赖） |
fwconsole ma installlocal | 安装包内全部本地模块（安装期使用） |
fwconsole ma upgradeall | 全部模块在线升级 |
fwconsole ma refreshsignatures | 刷新模块签名 |
fwconsole ma enable <模块名> / disable <模块名> | 启用/停用模块 |
💡 说明：模块市场访问
mirror.freepbx.org。downloadinstall的依赖解析是自动的——实测安装 sipsettings 时连带装上了 filestore 与 backup，安装中途卡住重跑同一命令即可续装。
4.1.3 参数查看与修改：fwconsole setting
列出高级设置全表（Value 为当前值，Default Value 为默认值，实测节选）：
fwconsole setting -l
+--------------------------------------------+------------------------------------------------+-----------------------------------+
| Name | Value | Default Value |
+--------------------------------------------+------------------------------------------------+-----------------------------------+
| HTTPENABLED | 1 | 0 |
| HTTPBINDADDRESS | 127.0.0.1 | :: |
| HTTPBINDPORT | 8088 | 8088 |
| AMPMGRPASS | v8l1FohsSC/z | amp111 |
| AMPMGRUSER | rPBmIbteyXiq | admin |
| ENABLE_ARI | 0 | 0 |
+--------------------------------------------+------------------------------------------------+-----------------------------------+
（完整表含全部高级设置键，此处为节选。）
读单个参数（带类型标注）：
fwconsole setting DIAL_OPTIONS
Setting of "DIAL_OPTIONS" is (text)[HhTtr]
写单个参数（实测原样回显，写完需 reload 才渲染生效）：
fwconsole setting DIAL_OPTIONS HhTtr
Changing "DIAL_OPTIONS" from [HhTtr] to [HhTtr]
4.1.4 配置重载与启停：reload / start / stop / restart
fwconsole reload
{"message":"Reload Started"}
{"message":"Reload Complete"}
fwconsole reload 把数据库中的设置渲染进 /etc/asterisk/ 配置文件并让 Asterisk 重载——Web 界面点 Apply Config 的等价命令，任何参数修改后必须执行。别名 fwconsole r。
fwconsole start（服务已在运行时执行，幂等，实测回显）：
fwconsole start
Running Asterisk post from Ucp module
Starting UCP Node Server...
[>---------------------------] < 1 sec
Started UCP Node Server. PID is 124388
Running Asterisk post from Vqplus module
Queues Pro is not licensed.
fwconsole stop / fwconsole restart 同族：stop 停止 Asterisk 及 FreePBX 托管进程，restart 等于 stop+start。生产环境变更后优先 reload，仅在 Asterisk 状态异常时才 restart。
4.1.5 定时任务：fwconsole job
列出 FreePBX 集中管理的定时任务（实测首屏）：
fwconsole job --list
+----+----------------------+-----------------------------------+--------------+---------------------+----------------------------------------------------------------------------------------------------------------------------------------+---------+
| ID | Module | Job | Cron | Next Run | Action | Enabled |
+----+----------------------+-----------------------------------+--------------+---------------------+----------------------------------------------------------------------------------------------------------------------------------------+---------+
| 8 | cdrpro | livecallsync | */5 * * * * | 2026-10-26 03:20:00 | Class: FreePBX\modules\Cdrpro\Job | Yes |
| 16 | pbxmfa | checkUserTrustedDevicesAndLicense | 0 0 * * * | 2026-10-27 00:00:00 | Class: FreePBX\modules\Pbxmfa\Job | Yes |
| 31 | pagingpro | scheduler | * * * * * | 2026-10-26 03:20:00 | Class: FreePBX\modules\Pagingpro\Job | Yes |
| 3 | sysadmin | checkportal | @daily | 2026-10-27 00:00:00 | Command: [ -e /var/www/html/admin/modules/sysadmin/bin/check_portal.php ] && /var/www/html/admin/modules/sysadmin/bin/check_portal.php | Yes |
| 4 | sysadmin | ddnsupdate | @daily | 2026-10-27 00:00:00 | Class: FreePBX\modules\Sysadmin\Job\DdnsUpdate | Yes |
+----+----------------------+-----------------------------------+--------------+---------------------+----------------------------------------------------------------------------------------------------------------------------------------+---------+
模块的周期任务（备份、CDR 同步、DDNS 等）全部收口在此，排查「定时任务没跑」先看这张表的 Cron 与 Next Run。
4.1.6 批量导入分机：fwconsole bulkimport
从 CSV 批量导入分机/号码（实测流程）。准备 CSV（表头为固定格式）：
cat > /tmp/ext2.csv <<'EOF'
extension,name,tech,secret,voicemail,ringtimer,noanswer,recording,outboundcid,sipname,id,devicetype,user,description
2001,Sales-01,pjsip,q1w2e3r4,disabled,0,,inherit,,2001,,fixed,,Sales desk extension
EOF
执行导入：
fwconsole bulkimport --type=extensions --replace /tmp/ext2.csv
Importing bulk extensions
命令输出极简，结果以 Asterisk 侧为准（asterisk -rx 'pjsip show endpoints' | grep 2001，见 4.2.2）。--replace 表示同号覆盖；--type 还支持 dids 等类型。
4.1.7 快捷查库：fwconsole mysql
不进入交互式客户端直接执行 SQL 的快捷通道（SQL 从标准输入读入，不支持 -e 选项，实测报错见六、6.4）：
echo 'select username from ampusers;' | fwconsole mysql
username
admin
等价于 mariadb asterisk -e '...'，优点是自动带上 FreePBX 的数据库连接配置，不用手输库名与口令。
4.1.8 拨号计划核对：fwconsole context
按上下文名抽查渲染后的拨号计划（与 4.2.4 的 asterisk -rx 'dialplan show ...' 是同一份数据的两个视图）：
fwconsole context from-internal-custom
4.2 asterisk -rx：Asterisk 运行时查询
asterisk -rx '<命令>' 把命令发给运行中的 Asterisk 并回显结果，是排障的主力入口。
4.2.1 版本与运行时长
asterisk -V
Asterisk 22.11.0
asterisk -rx 'core show uptime'
System uptime: 2 hours, 56 minutes, 17 seconds
Last reload: 0 seconds
Last reload 可核对最近一次配置重载的时间点。
4.2.2 分机与注册状态：pjsip 系列
全部端点概览（pjsip show endpoints 节选，实测）：
Endpoint: <Endpoint/CID.....................................> <State.....> <Channels.>
I/OAuth: <AuthId/UserName...........................................................>
Aor: <Aor............................................> <MaxContact>
Contact: <Aor/ContactUri..........................> <Hash....> <Status> <RTT(ms)..>
Transport: <TransportId........> <Type> <cos> <tos> <BindAddress..................>
Identify: <Identify/Endpoint.........................................................>
Match: <criteria.........................>
Channel: <ChannelId......................................> <State.....> <Time.....>
Exten: <DialedExten...........> CLCID: <ConnectedLineCID.......>
==========================================================================================
Endpoint: 1001/1001 Unavailable 0 of inf
InAuth: 1001-auth/1001
Unavailable = 分机存在但当前无终端注册。筛选特定分机：
asterisk -rx 'pjsip show endpoints' | grep 'Endpoint:.*2001'
Endpoint: 2001/2001 Unavailable 0 of inf
当前注册联系人（实测，分机 1001 注册成功后）：
asterisk -rx 'pjsip show contacts'
Contact: <Aor/ContactUri..............................> <Hash....> <Status> <RTT(ms)..>
==========================================================================================
Contact: 1001/sip:1001@10.89.72.50:35988 5d858b4cd9 NonQual nan
Objects found: 1
NonQual 表示未做 qualify 主动探测。AOR 参数详情（实测节选）：
asterisk -rx 'pjsip show aor 1001'
default_expiration : 3600
max_contacts : 1
max_contacts=1 是「同号重复注册被拒」的根源（见六、6.3）。
4.2.3 RTP 配置核对：rtp show settings
asterisk -rx 'rtp show settings'
General Settings:
----------------
Port start: 10000
Port end: 20000
Checksums: Yes
DTMF Timeout: 1200
Strict RTP: Yes
Probation: 4 frames
Replay Protect: Yes
ICE support: Yes
媒体单向/无声音问题的第一排查点：这里的端口段必须被防火墙/NAT 放行。
4.2.4 拨号计划核对：dialplan show
asterisk -rx 'dialplan show 8000@from-internal-custom'
[ Context 'from-internal-custom' created by 'pbx_config' ]
'8000' => 1. Answer() [extensions_custom.conf:3]
2. Playback(hello-world) [extensions_custom.conf:4]
3. Hangup() [extensions_custom.conf:5]
-= 1 extension (3 priorities) in 1 context. =-
右侧标注了每条优先级来自哪个文件哪一行——验证自定义计划是否被加载的最直接方法。
4.2.5 其他高频命令
| 命令 | 用途 |
|---|---|
asterisk -rx 'core show channels' | 当前活跃通话信道 |
asterisk -rx 'core show channels count' | 活跃信道计数 |
asterisk -rx 'queue show 700' | 队列实时状态（成员/排队/接听统计） |
asterisk -rx 'core restart now' | 立即重启 Asterisk 核心（先确认无通话） |
asterisk -rx 'core show help' | Asterisk 侧全量命令帮助 |
4.3 sipsak：SIP 协议层测试
sipsak（SIP swiss army knife）从「终端视角」验证注册链路，绕开话机因素。
注册测试（客户端 IP 10.89.72.50 → PBX 10.89.72.20，实测命令）：
sipsak -U -s sip:1001@10.89.72.20 -H 10.89.72.50 --auth-username=1001 --password=q1w2e3r4
注册成功时以 usrloc 测试完成收尾（实测输出）：
All usrloc tests completed successful
Asterisk 对 REGISTER 的应答头会带版本标识，格式为 FPBX-<framework版本>(<Asterisk版本>)（实测可见 FPBX-17.0.19.32(22.11.0)）。
参数说明：
| 参数 | 含义 |
|---|---|
-U | usrloc 测试模式（REGISTER 注册/注销循环） |
-s sip:1001@10.89.72.20 | 目标注册 URI（分机@PBX地址） |
-H 10.89.72.50 | 本端发信地址 |
--auth-username / --password | 认证凭据（分机号与密码） |
注册被拒时实测报错（原因与处理见六、6.3）：
error: didn't received '200 OK' on register (see above). aborting
4.4 systemctl：服务层管理
FreePBX 17 涉及三个系统服务：
systemctl is-active asterisk apache2 mariadb
active
active
active
⚠️ 注意：
asterisk.service是 SysV 包装服务（/etc/init.d/asterisk），不是原生 systemd unit，systemctl is-enabled asterisk的输出是兼容层检查结果（实测返回disabled并提示asterisk.service is not a native service, redirecting to systemd-sysv-install），不代表服务异常。运行状态一律以is-active为准；需要开机自启执行systemctl enable asterisk。
启停顺序建议：
systemctl restart asterisk # 仅 Asterisk 核心异常时
systemctl restart apache2 # Web 界面异常时
fwconsole restart # FreePBX 托管进程全套重启（UCP Node 等）
4.5 数据层直查：mariadb
FreePBX 配置库为 asterisk（业务配置）与 asteriskcdrdb（通话记录）：
mariadb asterisk -e 'select username, email from ampusers;'
username email
admin
mariadb asterisk -e "select extension, voicemail from users where extension='1001';"
extension voicemail
1001 novm
高频库表：ampusers（Web 管理账号）、users（分机用户属性）、kvstore_*（模块键值设置）、queues_details/queues_conf（队列）、cdr（在 asteriskcdrdb 库）。
4.6 日志定位
| 日志 | 路径（实测） | 用途 |
|---|---|---|
| 安装日志 | /var/log/pbx/freepbx17-install-<时间戳>.log | 官方脚本安装全程，失败定位首选 |
| Asterisk 运行日志 | /var/log/asterisk/（messages、full 等） | 通话/注册/错误逐条记录 |
| CDR 输出 | /var/log/asterisk/cdr-csv/、cdr-custom/ | CSV 通话记录 |
| FreePBX 框架日志 | /var/log/asterisk/freepbx_*.log（reload/日志扫描等） | 模块与框架层错误 |
| Web 层 | /var/log/apache2/ | Apache 访问与错误 |
五、注意事项
- fwconsole 基本都要 root：非 root 执行
fwconsole ma、fwconsole reload等会报权限/文件归属错误；fwconsole chown用于修复/etc/asterisk、/var/www/html/admin等目录归属。 - 改配置必 reload：
fwconsole setting写库、Web 界面 Apply Config、fwconsole reload三者是同一条链路，漏掉 reload 就「改了不生效」。 asterisk -rx只读优先：核心级的core restart now、channel request hangup等会影响通话，执行前先用core show channels确认无活跃通话。- 模块在线操作依赖 mirror.freepbx.org：内网环境
fwconsole ma downloadinstall/upgradeall需要打通该域名或配置代理。 - 数据库直改需谨慎：直接 UPDATE 配置表后必须
fwconsole reload才渲染；不确定表结构时优先走 Web 界面。
六、常见问题（FAQ）
6.1 fwconsole status 提示命令不存在
现象（实测原样回显）：
$ fwconsole status
Command "status" is not defined.
原因：旧版资料中的 fwconsole status 在 FreePBX 17（实测 17.0.19.32）已移除。替代方案：服务进程用 systemctl is-active asterisk apache2 mariadb，模块用 fwconsole ma list，定时任务用 fwconsole job --list。
6.2 systemctl is-enabled asterisk 返回 disabled
SysV 包装服务特性（见 4.4 节 ⚠️）：is-active 返回 active 即服务正常；开机自启用 systemctl enable asterisk 建立兼容层链接。
6.3 sipsak 重复注册报 didn't received '200 OK' on register
原因：分机 AOR 默认 max_contacts=1（实测见 4.2.2），sipsak 每次运行使用新的随机源端口，占位联系人（租约内，default_expiration=3600）未过期时新 Contact 被拒。处理：查看并等待现有联系人过期（asterisk -rx 'pjsip show contacts'），或 systemctl restart asterisk 清空注册态后重试；多机同号场景把 AOR 的 max_contacts 调大。
6.4 fwconsole mysql 加 -e 报错
现象（实测原样回显）：
$ fwconsole mysql -e 'select 1;'
The "-e" option does not exist.
原因：fwconsole mysql 不接受 mariadb 客户端的 -e 参数，SQL 要从标准输入读入。正确用法：echo 'select ...;' | fwconsole mysql（见 4.1.7），或需要复杂选项时直接用 mariadb asterisk -e '...'。
6.5 fwconsole ma upgradeall 连接失败导致安装脚本报 FAILED
现象：安装日志末段 Unable to connect to servers from URLs provided: https://mirror.freepbx.org/... 后 ****** INSTALLATION FAILED *****。关键判断：失败发生在升级阶段，freepbx17 installed successfully.... 之前的核心安装已完整可用。处理：恢复网络后单独重跑 fwconsole ma upgradeall && fwconsole reload，不必重装。
6.6 执行 reload 后 Web 界面仍提示需要 Apply Config
原因：Web 界面的「待应用」标记存在数据库任务表中，CLI 的 fwconsole reload 执行的是渲染与重载，两者偶尔不同步。处理：fwconsole reload 后刷新页面；仍提示则 fwconsole restart 一次即可清除。
七、参考链接
- FreePBX 官方文档：https://docs.freepbx.org/
- fwconsole 官方 Wiki：https://wiki.freepbx.org/display/FOP/FreePBX+fwconsole+CLI
- Asterisk CLI 参考文档：https://docs.asterisk.org/（Asterisk CLI 一章）
- sipsak 项目主页：https://github.com/nils-ohlmeier/sipsak
- 专栏前篇 《FreePBX 17 介绍与选型指南》、《Debian 12 安装 FreePBX 17 指南》、《FreePBX 17 配置参数详解》