Asterisk 22.11.0 常用 CLI 命令与工具详解
Asterisk 22.11.0 常用 CLI 命令与工具详解：asterisk 启动参数与 core/pjsip/dialplan/logger/module/database 七大命令族逐条实测，含 AstDB 读写删闭环、logger rotate 落盘验证与服务停止排障。
Asterisk 22.11.0 常用 CLI 命令与工具详解
目标：把管理 Asterisk 22.11.0 的两套命令面——
asterisk二进制的启动参数与运行时 CLI 控制台的七大常用命令族（core/pjsip/dialplan/logger/module/database/channel）——逐条讲清并配真实回显，形成一套可照抄的日常运维命令手册。全部命令与回显均在 Ubuntu 22.04 x86_64 服务器的 Asterisk 22.11.0 实测采集；安装与配置参数背景见 《Ubuntu 22.04 安装 Asterisk 指南》 与 《Asterisk 22.11.0 配置参数详解》。
一、环境信息
本文所有命令与回显均在以下环境实测采集：
- 操作系统：Ubuntu 22.04 LTS（x86_64）；
- Asterisk 版本：22.11.0（当前最新 LTS，源码编译安装）；
- 运行形态：systemd 服务
asterisk.service（Type=notify）托管，运行用户asterisk； - CLI 通道：Unix 套接字
/var/run/asterisk/asterisk.ctl（asterisk -r/-rx经它连接）； - 示例对象：PJSIP 端点 100、6001、6002（来自配置篇与部署篇的实测环境）；
- 日志目录：
/var/log/asterisk（messages.log、full.log、queue_log）； - 模块规模：实测 316 个模块加载（
module show统计行）。
二、工具概览
管理 Asterisk 有两层命令面，先分清再上手：
- 第一层：
asterisk二进制（服务器 shell 里执行）。负责启停进程、连接控制台、单发 CLI 命令（-rx）——它是「入口」，本身不查业务状态； - 第二层：运行时 CLI（Asterisk 进程内的控制台命令）。数百条命令按族组织（core、pjsip、dialplan、logger、module、database、bridge、channel……），负责查看与操控运行中的 PBX。进入方式两种：交互式
asterisk -r（进入asterisk*CLI>提示符，exit退出），或单发式asterisk -rx "<命令>"（执行即退出，适合脚本与本文的全部演示）。
两层关系：asterisk -rx "core show uptime" 实际是「第一层连接套接字 → 第二层执行 core 族命令 → 返回结果退出」。
运行时 CLI 的全量命令清单用帮助体系自查（实测）：
asterisk -rx "core show help"
实测回显（输出节选，实测首尾；全量数百行）：
! -- Execute a shell command
acl show -- Show a named ACL or list all named ACLs
aeap show client -- Show AEAP client configuration by id
ael reload -- Reload AEL configuration
agent show -- Show information about an agent
agi show commands [topic] -- List AGI commands or specific help
ari show apps -- List registered ARI applications
bridge show all -- List all bridges
calendar show calendars -- Show registered calendars
cdr set debug [on|off] -- Enable debugging in the CDR engine
...
voicemail show users [for] -- List defined voicemail boxes
xmldoc dump -- Dump the XML docs to the specified file
xmldoc reload -- Reload the XML docs
💡 说明：
core show help输出「命令 -- 一句话说明」两列；任一命令后缀查询子帮助，如core show help core show channels。首行的!是交互控制台里临时执行 shell 命令的转义符（如!ls /var/log/asterisk），受 asterisk.conf 的disable_remote_console_shell开关约束（配置篇 5.1 节）。
日常运维命令按使用频率的族分布如下表，五、六、七节逐族详解：
| 命令族 | 用途 | 高频命令 |
|---|---|---|
| core | 内核状态与生命周期 | core show version/uptime/channels、core restart gracefully |
| pjsip | SIP 端点与信令诊断 | pjsip show endpoints、pjsip set logger on |
| dialplan | 拨号计划查看与重载 | dialplan show、dialplan reload |
| logger | 日志通道管理 | logger show channels、logger rotate |
| module | 模块加载管理 | module show like |
| database | 内置 AstDB 键值库 | database put/get/show/del |
| channel/bridge | 通道与桥接（通话中） | core show channels |
三、前置条件
本章确认命令手册可复现的环境基线：Asterisk 服务在跑、CLI 通道可用。完整安装步骤见 《Ubuntu 22.04 安装 Asterisk 指南》。
确认服务运行状态：
systemctl is-active asterisk
实测回显：
active
确认 CLI 通道应答正常：
asterisk -rx "core show version"
实测回显：
Asterisk 22.11.0 built by root @ 7d9aaf7362ca on a x86_64 running Linux on 2026-10-21 11:21:56 UTC
💡 说明：
-rx中的-r连接本机 Asterisk 控制台、-x执行命令后退出。版本串里的构建主机名与时间随安装环境不同而不同，以能返回版本号为准。若此处报Unable to connect to remote asterisk，直接转七、Q3 排障。
四、asterisk 命令行参数详解
asterisk -h 是第一层工具的权威参数表，实测全文如下：
asterisk -h
实测回显（全量）：
Asterisk 22.11.0, Copyright (C) 1999 - 2025, Sangoma Technologies Corporation and others.
Usage: asterisk [OPTIONS]
Valid Options:
-V Display version number and exit
-C <configfile> Use an alternate configuration file
-G <group> Run as a group other than the caller
-U <user> Run as a user other than the caller
-c Provide console CLI
-d Increase debugging (multiple d's = more debugging)
-f Do not fork
-F Always fork
-g Dump core in case of a crash
-h This help screen
-i Initialize crypto keys at startup
-L <load> Limit the maximum load average before rejecting new calls
-M <value> Limit the maximum number of calls to the specified value
-m Mute debugging and console output on the console
-n Disable console colorization. Can be used only at startup.
-p Run as pseudo-realtime thread
-q Quiet mode (suppress output)
-r Connect to Asterisk on this machine
-R Same as -r, except attempt to reconnect if disconnected
-s <socket> Connect to Asterisk via socket <socket> (only valid with -r)
-t Record soundfiles in /var/tmp and move them where they
belong after they are done
-T Display the time in [Mmm dd hh:mm:ss] format for each line
of output to the CLI. Cannot be used with remote console mode.
-v Increase verbosity (multiple v's = more verbose)
-x <cmd> Execute command <cmd> (implies -r)
-X Enable use of #exec in asterisk.conf
-W Adjust terminal colors to compensate for a light background
日常最高频的参数逐项说明：
| 参数 | 作用 | 典型用法 |
|---|---|---|
-V | 只打印版本号退出 | 升级后核对版本（回显 Asterisk 22.11.0） |
-r | 连接本机控制台进入交互 CLI | 排障时盯实时输出 |
-R | 同 -r，断线自动重连 | 长时间盯台 |
-x "<命令>" | 连上执行一条命令即退出（隐含 -r） | 脚本化巡检，本文主力 |
-c | 前台启动并直接进控制台 | 前台排障（配合 -f） |
-f / -F | 不 fork 前台跑 / 强制 fork | systemd 托管用 -f（见部署篇单元文件） |
-C <文件> | 指定主配置 | 多实例/备用配置测试 |
-U <用户> / -G <组> | 启动时切换运行身份 | apt 版单元 -U asterisk（部署篇 5.3 节） |
-v（可叠） | 提高控制台详细级别 | asterisk -rvvvvv 加深排障输出 |
-d（可叠） | 提高调试级别 | 内核问题深挖，生产慎用 |
-q | 安静模式 | systemd 单元 -mqf 组合成员 |
-m | 控制台输出静音/重定向 | 同上 |
-M <数> / -L <负载> | 限制最大呼叫数 / 负载阈值 | 等价 asterisk.conf 的 maxcalls/maxload 的命令行版 |
💡 说明：命令行参数与 asterisk.conf
[options]段是同一批开关的两个入口，命令行优先。systemd 托管后这些「启动类」参数都写在单元的ExecStart行里（源码版-mqf -C /etc/asterisk/asterisk.conf，apt 版-g -f -p -U asterisk），日常不再手工带参启动——第一层参数真正的高频使用只剩-V、-r、-rx三个。
五、运行时 CLI 命令族详解
本章按命令族逐条给出「命令 → 实测回显 → 说明」。全部通过 asterisk -rx 采集；在交互控制台（asterisk -r）里去掉外层包装执行效果相同。
5.1 core 族：内核状态与生命周期
（1）版本与运行时长。 版本见三、前置条件；运行时长：
asterisk -rx "core show uptime"
实测回显：
System uptime: 4 hours, 25 minutes, 57 seconds
Last reload: 4 hours, 25 minutes, 57 seconds
说明：System uptime 进程级时长；Last reload 最近一次全量重载时间。巡检时 uptime 突然变小意味着进程被重启过，应回查 systemd 日志。
（2）内核运行值总览。
asterisk -rx "core show settings"
实测回显（输出节选，实测首尾）：
PBX Core settings
-----------------
Version: 22.11.0
Maximum calls: Not set
Maximum open file handles: 1024
Root console verbosity: 0
Debug level: 0
Startup time: 11:48:01
Last reload time: 17:06:45
...
* Directories
-------------
Configuration file: /etc/asterisk/asterisk.conf
Configuration directory: /etc/asterisk
Module directory: /usr/lib/asterisk/modules
Log directory: /var/log/asterisk
Run/Sockets directory: /var/run/asterisk
说明：这一屏核对启动参数与目录布局是否如预期生效（与 asterisk.conf 参数的对照见配置篇 5.1 节）。
（3）通道与呼叫计数。
asterisk -rx "core show channels"
实测回显（空闲态）：
Channel Location State Application(Data)
0 active channels
0 active calls
0 calls processed
asterisk -rx "core show calls"
实测回显：
0 active calls
0 calls processed
说明：0 calls processed 自启动以来未处理过呼叫；有话务后此处是容量观察点——活跃通道数接近 asterisk.conf 的 maxcalls 就该扩容。通话进行中再执行 core show channels 会逐行列出通道名、所在拨号位置、当前应用与数据，是「现在谁在打电话、打到哪一步」的第一入口。
（4）编解码能力清单。
asterisk -rx "core show codecs"
实测回显（输出节选，实测首段）：
Disclaimer: this command is for informational purposes only.
It does not indicate anything about your configuration.
ID TYPE NAME FORMAT QUALITY DESCRIPTION
------------------------------------------------------------------------------------------------
4 audio alaw alaw 100 (G.711 a-law)
2 audio g723 g723 20 (G.723.1)
24 audio g722 g722 110 (G722)
19 audio g729 g729 45 (G.729A)
9 audio slin slin 115 (16 bit Signed Linear PCM)
34 video h264 h264 0 (H.264 video)
...
说明：首行 Disclaimer 明确提示这只列「编译时支持的编解码全集」，不代表 pjsip.conf 里放行了哪些——放行与否看 pjsip show endpoint <分机> 的 allow 值（配置篇 5.2 节实测为 (ulaw)）。
（5）全量配置热重载。
asterisk -rx "core reload"
实测回显（成功时静默返回）：
说明：按序重载全部支持热重载的配置（等价于依次执行 pjsip reload、dialplan reload、logger reload 等）；无输出即成功，疑有异常时用 core show uptime 看 Last reload 时间是否刷新。
（6）CLI 侧优雅重启。
asterisk -rx "core restart gracefully"
实测回显（命令本身无输出）：
验证重启确已发生（等十余秒后查）：
asterisk -rx "core show uptime"
实测回显：
System uptime: 11 seconds
Last reload: 11 seconds
说明：gracefully 等 busy 通道结束后再重启（core restart now 立即断话重启、core restart when convenient 空闲才重启）。命令无输出，以 uptime 归零为生效判据；生产执行前先看 core show channels 确认没有进行中的通话。实测环境空闲，重启在数秒内完成且服务恢复 active。
5.2 pjsip 族：SIP 端点与信令诊断
（1）端点总览。
asterisk -rx "pjsip show endpoints"
实测回显（输出节选，实测首尾）：
Endpoint: <Endpoint/CID.....................................> <State.....> <Channels.>
I/OAuth: <AuthId/UserName...........................................................>
Aor: <Aor............................................> <MaxContact>
...
==========================================================================================
Endpoint: 100 Unavailable 0 of inf
InAuth: auth100/100
Aor: 100 2
Endpoint: 6001 Unavailable 0 of inf
InAuth: auth6001/6001
Aor: 6001 2
Endpoint: 6002 Unavailable 0 of inf
InAuth: auth6002/6002
Aor: 6002 2
Objects found: 3
说明：State: Unavailable 表示该端点当前无注册 contact（七、Q4）；话机注册成功后该端点状态转 Available 并在 Aor 行下挂出 Contact 与 RTT。
（2）单端点参数明细（排编解码/DTMF/context 配置争议时的权威输出）：
asterisk -rx "pjsip show endpoint 6001"
实测回显（输出节选，实测首尾；全量约 150 行参数表）：
Endpoint: 6001 Unavailable 0 of inf
InAuth: auth6001/6001
Aor: 6001 2
ParameterName : ParameterValue
===================================================================================================
100rel : yes
allow : (ulaw)
context : from-internal
direct_media : true
dtmf_mode : rfc4733
media_encryption : no
rtp_symmetric : false
timers : yes
webrtc : no
（3）注册对象：AOR 与 Contact。
asterisk -rx "pjsip show aors"
实测回显：
Aor: <Aor..............................................> <MaxContact>
Contact: <Aor/ContactUri............................> <Hash....> <Status> <RTT(ms)..>
==========================================================================================
Aor: 100 2
Aor: 6001 2
Aor: 6002 2
Objects found: 3
asterisk -rx "pjsip show contacts"
实测回显（无设备注册时空态）：
No objects found.
说明：AOR 列出注册落点与 max_contacts 上限；Contact 列出实际注册的话机联系人。pjsip show contacts 为空与端点 Unavailable 互相印证，是「话机注册不上」时区分服务器侧/终端侧问题的分水岭——服务器侧有对象而 Contact 空，问题多在终端配置或网络可达性。
（4）传输层。
asterisk -rx "pjsip show transports"
实测回显：
Transport: <TransportId........> <Type> <cos> <tos> <BindAddress....................>
==========================================================================================
Transport: transport-udp udp 0 0 0.0.0.0:5060
Objects found: 1
（5）SIP 报文抓取开关。
asterisk -rx "pjsip set logger on"
实测回显：
PJSIP Logging enabled
asterisk -rx "pjsip set logger off"
实测回显：
PJSIP Logging disabled
说明：开启后全部收发的 SIP 报文（REGISTER/INVITE/响应）按时间戳打到控制台与 messages.log，是排注册失败、INVITE 401、No route 类问题最直接的取证手段。看完务必关回——报文体量大，会快速推高日志（配置篇 5.5 节日志治理）。
（6）pjsip 配置热重载。
asterisk -rx "pjsip reload"
实测回显：
Module 'res_pjsip.so' reloaded successfully.
Module 'res_pjsip_authenticator_digest.so' reloaded successfully.
Module 'res_pjsip_endpoint_identifier_ip.so' reloaded successfully.
Module 'res_pjsip_mwi.so' reloaded successfully.
Module 'res_pjsip_notify.so' reloaded successfully.
Module 'res_pjsip_outbound_publish.so' reloaded successfully.
Module 'res_pjsip_publish_asterisk.so' reloaded successfully.
Module 'res_pjsip_outbound_registration.so' reloaded successfully.
说明：逐模块回报重载结果，全部 successfully 即生效。⚠️ 例外：transport 段参数 reload 不生效需重启服务（配置篇七、Q1 实测）。
5.3 dialplan 族：拨号计划查看与重载
（1）查看单个 context。
asterisk -rx "dialplan show from-internal"
实测回显：
[ Context 'from-internal' created by 'pbx_config' ]
'6001' => 1. NoOp(demo call to 6001) [extensions.conf:892]
2. Dial(PJSIP/6001,20) [extensions.conf:893]
3. Hangup() [extensions.conf:894]
'6002' => 1. NoOp(demo call to 6002) [extensions.conf:895]
2. Dial(PJSIP/6002,20) [extensions.conf:896]
3. Hangup() [extensions.conf:897]
-= 2 extensions (6 priorities) in 1 context. =-
说明：每行右侧 [extensions.conf:行号] 直接定位规则在源文件中的位置；末行统计 context 内的分机与优先级总数。「改了拨号计划怎么验证」——重载后跑这条命令逐行比对即是最可靠的闭环。
（2）查看全局变量。
asterisk -rx "dialplan show globals"
实测回显：
OUTBOUND-TRUNKMSD=1
OUTBOUND-TRUNK="Zap/g2"
CONSOLE-AEL="Console/dsp"
TRUNKMSD=1
TRUNK=DAHDI/G2
CONSOLE=Console/dsp
-- 6 variable(s)
（3）拨号计划热重载。
asterisk -rx "dialplan reload"
实测回显：
Dialplan reloaded.
说明：extensions.conf 的改动到此生效，随即用 5.3（1）命令验证新规则；配置语法错误时重载会保留旧计划并在控制台报错行，按行号修正后再次 reload 即可。
5.4 logger 族：日志通道管理
（1）查看通道。
asterisk -rx "logger show channels"
实测回显：
Logger queue limit: 1000
Channel Type Formatter Status Configuration
------- ---- --------- ------ -------------
/var/log/asterisk/full.log File default Enabled - NOTICE WARNING ERROR VERBOSE
/var/log/asterisk/messages.log File default Enabled - NOTICE WARNING ERROR
Console default Enabled - NOTICE WARNING ERROR VERBOSE
说明：逐行对应 logger.conf [logfiles] 段的一个通道；Configuration 列是各通道生效的级别集，与配置文件比对可确认重载结果。
（2）日志配置热重载。
asterisk -rx "logger reload"
实测回显（成功时静默返回）：
（3）日志轮转。
asterisk -rx "logger rotate"
实测回显（成功时静默返回）：
落盘验证（rotate 后）：
ls -l /var/log/asterisk/*.log*
实测回显：
-rw-r--r-- 1 asterisk asterisk 117 Oct 21 17:14 /var/log/asterisk/full.log
-rw-r--r-- 1 asterisk asterisk 4899 Oct 21 17:07 /var/log/asterisk/full.log.0
-rw-r--r-- 1 asterisk asterisk 117 Oct 21 17:14 /var/log/asterisk/messages.log
-rw-r--r-- 1 asterisk asterisk 18156 Oct 21 17:07 /var/log/asterisk/messages.log.0
说明：rotate 后原日志改名 .0 归档、新同名文件从零写入（默认 rotatestrategy=sequential 的行为）；生产可把它挂进 cron 做定时轮转，或改用 logrotate 对接（logger.conf 的 rotatestrategy 参数见配置篇 5.5 节）。
5.5 module 族：模块加载管理
（1）按名字过滤查看。
asterisk -rx "module show like pjsip"
实测回显（输出节选，实测尾段）：
res_pjsip_transport_websocket.so PJSIP WebSocket Transport Support 0 Running core
res_pjsip_xpidf_body_generator.so PJSIP Extension State PIDF Provider 0 Running core
50 modules loaded
asterisk -rx "module show like res_hep"
实测回显（modules.conf 黑名单排除后的空态）：
Module Description Use Count Status Support Level
0 modules loaded
（2）全量清单。
asterisk -rx "module show"
实测回显（输出节选，实测尾段）：
udptl UDPTL 2 Running core
316 modules loaded
说明：like 子串过滤 + 末行计数是核对 modules.conf 生效与否的标准动作（黑名单参数详解见配置篇 5.6 节）；Use Count 非 0 说明有资源在引用该模块，此时 module unload 会被拒绝，属保护机制。
5.6 database 族：内置 AstDB 键值库
AstDB 是 Asterisk 自带的 Berkeley DB 键值库（落盘 /var/lib/asterisk/astdb），存少量运行状态（如黑名单、动态路由标记），拨号计划用 DB() 函数读、DB() 写。CLI 四件套实测闭环：
写入（database put <族> <键> <值>）：
asterisk -rx "database put demo extension 6001"
实测回显：
Updated database successfully
读取（database get <族> <键>）：
asterisk -rx "database get demo extension"
实测回显：
Value: 6001
全览（database show [前缀]）：
asterisk -rx "database show"
实测回显：
/demo/extension : 6001
/pbx/UUID : d0267c20-84e6-4ff8-96cd-75b22c2dbc60
2 results found.
删除（database del <族> <键>）并复核：
asterisk -rx "database del demo extension"
实测回显：
Database entry removed.
asterisk -rx "database show"
实测回显：
/pbx/UUID : d0267c20-84e6-4ff8-96cd-75b22c2dbc60
1 results found.
说明：键以 /族/键 两级组织；/pbx/UUID 是系统内置项（实例唯一标识）勿动。AstDB 持久化于 astdb 文件，重启不丢；排查「拨号计划里 DB 读不到值」时，先 database show 确认键真的存在。
六、注意事项
-rx与交互控制台的取舍：单发-rx每次新建连接，适合脚本与巡检；盯实时日志（如pjsip set logger on期间的报文流）用asterisk -r或-R（断线重连）交互进控制台，exit退出。- 重启类命令先看话务：
core restart now/gracefully/when convenient三个档位分别对应「立即断话重启/等通话结束重启/空闲才重启」。执行前先core show channels确认活跃通话，生产默认选 gracefully 或 when convenient。 - 诊断开关用完即关：
pjsip set logger on、core set verbose 5、core set debug这类加量开关都会成倍放大日志量，取证完成立即关回基线。 - 无输出 ≠ 失败：
core reload、logger reload、logger rotate、core restart gracefully成功时都不回显，必须用配套查询命令（uptime/logger show channels/ls 落盘）确认效果——本文各节已给出对应验证命令。 - 帮助优先于记忆：命令拼写拿不准时
core show help全量查、core show help <命令>细看子用法；本文覆盖的是高频子集，7 大族之外还有 bridge/ari/voicemail/parking 等族按需自查。
七、常见问题（FAQ）
Q1：core show globals 报 No such command？
22.x 已移除该命令，全局变量改由 dialplan 族管理。实测报错与正确命令：
No such command 'core show globals' (type 'core show help core show globals' for other possible commands)
改用 dialplan show globals（实测回显见 5.3 节）。旧版文档/脚本里的 core show globals 需同步替换。
Q2：dialplan show contexts 报 There is no existence of 'contexts' context？
dialplan show 后面跟的是 context 名字，没有 contexts 子命令。实测报错：
There is no existence of 'contexts' context
Command 'dialplan show contexts' failed.
正确用法：dialplan show from-internal 看单个（见 5.3 节）；不带参数的 dialplan show 输出全部 context（量大，建议管道 grep 过滤 context 名）。
Q3：asterisk -rx 报 Unable to connect to remote asterisk？
CLI 通道连不上运行中的进程。实测复现（服务停止时执行）：
Unable to connect to remote asterisk (does /var/run/asterisk/asterisk.ctl exist?)
按序排查：① systemctl is-active asterisk 确认服务真的在跑（实测停止态即复现上面报错，systemctl start asterisk 恢复后 -rx 正常返回版本）；② 服务在跑仍报错，查套接字文件与权限——ls -l /var/run/asterisk/asterisk.ctl，属主应为 asterisk 且当前用户在其组内（systemd 单元 RuntimeDirectory=asterisk 负责建目录，见部署篇 4.8 节）；③ -s <socket> 指向了自定义套接字的实例时需显式带上。
Q4：pjsip show endpoints 端点一直 Unavailable？
Unavailable 只表示「没有已注册的 contact」，不是配置错误（空环境实测即如此，见 5.2 节回显）。判断流程：pjsip show contacts 为空 + 端点 Unavailable → 话机还没注册成功，去终端侧核对服务器地址/账号口令（auth 段），服务器侧开 pjsip set logger on 看 REGISTER 是否到达、响应是 401 还是 200；Contact 出现且 Status 为 Avail → 注册链路已通。
Q5：core restart gracefully 敲完没任何输出，怎么知道执行了没有？
该命令设计即无回显。用 core show uptime 复核——实测执行后十余秒 System uptime: 11 seconds 归零即重启完成（见 5.1 节闭环）；若uptime 持续不归零，说明有 busy 通道在等 gracefully 排空，core show channels 看谁还挂着，紧急时用 core restart now（会断话）。
八、参考链接
- 官方文档站 CLI 手册（CLI Operations）：https://docs.asterisk.org/
- 官方 GitHub 仓库：https://github.com/asterisk/asterisk
- 本专栏部署篇（安装、systemd 托管与 -rx 验证基础）：《Ubuntu 22.04 安装 Asterisk 指南》
- 本专栏配置篇（各命令对应的配置文件与参数详解）：《Asterisk 22.11.0 配置参数详解》
- 本专栏选型篇：《Asterisk 22.11.0 介绍与选型指南》