FreePBX 17 配置参数详解

目标：讲清 FreePBX 17 的参数体系——参数存在哪里、怎么查看、怎么修改、为什么直改配置文件会被覆盖，并逐类拆解分机/PJSIP、SIP 与 RTP、AMI、ARI 与内置 HTTP、队列、语音邮箱、拨号计划等核心参数域，最后给出可直接套用的生产配置模板。全部参数与回显均在 Debian 12（bookworm）裸机安装的 FreePBX 17.0.19.32 + Asterisk 22.11.0 环境实测采集。

一、环境信息

操作系统：Debian 12（bookworm），x86_64（与《Debian 12 安装 FreePBX 17 指南》同一实测环境）。
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。
配置根目录：/etc/asterisk/（Asterisk 与 FreePBX 各模块的生成配置全部落在此目录）。
参数存储：MariaDB asterisk 库（kvstore_* 键值表 + 各模块业务表）。
实测服务器 IP：10.89.72.20；示例分机 1001（密码 q1w2e3r4）、自建队列 700、自建拨号计划 8000。

二、前置条件

已按安装指南完成 FreePBX 17 安装并创建 admin 账号（mariadb asterisk -e 'select username from ampusers;' 能看到 admin）。
fwconsole 命令可用：fwconsole --version 正常输出版本号。
浏览器可访问 Web 管理台 http://10.89.72.20/（参数的第二修改入口）。
了解本文参数域划分的前提：FreePBX 的「参数」分两层——数据库里的设置值（真正的事实来源）与 /etc/asterisk/ 下的配置文件（FreePBX 用设置值渲染出来的结果）。改配置生效的正确路径是改第一层。

三、参数查看与修改方式

3.1 Web 界面（推荐入口）

FreePBX 的参数按模块分散在 Web 界面各处，常用的四个入口：

入口	覆盖参数域
Admin → Advanced Settings	高级设置全局项（HTTP/ARI 会话、拨号选项、设备默认值等）
Settings → Asterisk SIP Settings	SIP 传输、NAT、RTP 端口范围、编解码
Applications → Extensions / Queues	分机、队列等业务对象参数
Settings → Asterisk Manager Interface（AMI）	管理接口账号与 ACL

Web 界面保存后点右上角 Apply Config 提交，等价于 CLI 的 fwconsole reload，FreePBX 会把改动渲染进配置文件并重载 Asterisk。

3.2 CLI：fwconsole setting 查看、修改与应用

列出全部高级设置（实测节选，含当前值与默认值两列）：

fwconsole setting -l

+--------------------------------------------+------------------------------------------------+-----------------------------------+
| Name                                       | Value                                          | Default Value                     |
+--------------------------------------------+------------------------------------------------+-----------------------------------+
| AS_DISPLAY_FRIENDLY_NAME                   | 1                                              | 1                                 |
| AS_DISPLAY_READONLY_SETTINGS               | 0                                              | 0                                 |
| AS_OVERRIDE_READONLY                       | 0                                              | 0                                 |
| HTTPENABLESTATIC                           | 0                                              | 0                                 |
| HTTPENABLED                                | 1                                              | 0                                 |
| HTTPTLSENABLE                              | 1                                              | 0                                 |
| HTTPBINDADDRESS                            | 127.0.0.1                                      | ::                                |
| HTTPBINDPORT                               | 8088                                           | 8088                              |
| HTTPPREFIX                                 |                                                |                                   |
| HTTPTLSBINDADDRESS                         | ::                                             | ::                                |
| HTTPTLSBINDPORT                            | 8089                                           | 8089                              |
| TLSDISABLEV1                               | 1                                              | 1                                 |
| TLSDISABLEV11                              | 0                                              | 0                                 |
| TLSDISABLEV12                              | 0                                              | 0                                 |
| HTTPTLSCERTFILE                            | /etc/asterisk/keys/integration/certificate.pem |                                   |
| HTTPTLSPRIVATEKEY                          | /etc/asterisk/keys/integration/webserver.key   |                                   |
| HTTPSESSIONINACTIVITY                      | 30000                                          | 30000                             |
| HTTPSESSIONKEEPALIVE                       | 15000                                          | 15000                             |
| HTTPSESSIONLIMIT                           | 10000                                          | 100                               |
| AMPMGRPASS                                 | v8l1FohsSC/z                                   | amp111                            |
| AMPMGRUSER                                 | rPBmIbteyXiq                                   | admin                             |
| ARI_ALLOWED_ORIGINS                        | localhost:8088                                 | localhost:8088                    |
| ENABLE_ARI                                 | 0                                              | 0                                 |
| ENABLE_ARI_PP                              | 0                                              | 0                                 |
| ARI_WS_WRITE_TIMEOUT                       | 100                                            | 100                               |
+--------------------------------------------+------------------------------------------------+-----------------------------------+

查看单个参数（带类型）：

fwconsole setting DIAL_OPTIONS

Setting of "DIAL_OPTIONS" is (text)[HhTtr]

fwconsole setting HTTPBINDPORT

Setting of "HTTPBINDPORT" is (int)[8088]

修改单个参数（实测 set 机制的原始输出——即使新旧值相同也走完整写流程）：

fwconsole setting DIAL_OPTIONS HhTtr

Changing "DIAL_OPTIONS" from [HhTtr] to [HhTtr]

修改后必须应用配置才能渲染进文件并重载 Asterisk：

fwconsole reload

💡 说明：fwconsole setting 只覆盖 Admin → Advanced Settings 里那一层全局参数；分机、队列等业务对象的参数存在各自模块的表里，CLI 侧通过 asterisk -rx（Asterisk 运行时视图）与 Web 模块页管理，详见第五章各节。

3.3 配置文件体系：additional / custom / custom_post 三层

/etc/asterisk/ 下的配置文件分三类（以 PJSIP 为例，实测文件清单）：

pjsip.conf                    # 主文件，只做 include
pjsip.endpoint.conf           # 自动生成：全部端点定义
pjsip.aor.conf                # 自动生成：全部 AOR 定义
pjsip.auth.conf               # 自动生成：全部认证定义
pjsip.identify.conf           # 自动生成：识别定义
pjsip.endpoint_custom.conf    # 自定义追加（不会被覆盖）
pjsip.endpoint_custom_post.conf # 自定义追加（加载于生成文件之后）
pjsip.aor_custom.conf / pjsip.aor_custom_post.conf
pjsip.auth_custom.conf / pjsip.auth_custom_post.conf

自动生成文件的头部声明（实测原文）：

;--------------------------------------------------------------------------------;
;          Do NOT edit this file as it is auto-generated by FreePBX.             ;
;--------------------------------------------------------------------------------;

生成文件通过 #include 挂接自定义层（pjsip.endpoint.conf 实测开头）：

[0]
#include pjsip.endpoint_custom.conf

Asterisk 内置 HTTP 的 http.conf 同样是纯 include 结构（实测）：

#include http_additional.conf
#include http_custom.conf

要点：*_additional.conf 与主文件是 FreePBX 的渲染结果；*_custom.conf（渲染结果之前加载）与 *_custom_post.conf（渲染结果之后加载）是留给管理员的覆盖层。手工参数写 custom 文件，业务参数走 Web/数据库。

3.4 参数真正的存储位置：MariaDB asterisk 库

FreePBX 的设置值存在 asterisk 库的 kvstore_* 键值表与各模块业务表中（实测表名清单节选）：

kvstore_Dashboard
kvstore_FreePBX
kvstore_FreePBX_Framework
kvstore_FreePBX_Hooks
kvstore_FreePBX_Media
kvstore_FreePBX_Realtime
kvstore_FreePBX_modules_Adv_recovery
kvstore_FreePBX_modules_Amd
kvstore_FreePBX_modules_Api
kvstore_FreePBX_modules_Backup
kvstore_FreePBX_modules_Calendar
kvstore_FreePBX_modules_Cdr

⚠️ 注意：直改 *_additional.conf 之类的生成文件，下一次 Apply Config / fwconsole reload 就会被数据库里的值覆盖回去（实测复现，见七、7.1）。配置文件是「结果」，数据库才是「原因」。

四、参数总览

参数域	自动生成文件（/etc/asterisk）	自定义覆盖文件	Web 入口	CLI 查看/修改
分机/端点（PJSIP）	pjsip.endpoint.conf、pjsip.aor.conf、pjsip.auth.conf	pjsip._custom.conf、pjsip._custom_post.conf	Applications → Extensions	`asterisk -rx 'pjsip show endpoint 1001'`
SIP 传输/NAT/RTP	pjsip.transports.conf、rtp_additional.conf	pjsip.transports_custom.conf、rtp_custom.conf	Settings → Asterisk SIP Settings	`fwconsole setting -l`（DEVICE_SIP_*）
AMI 管理接口	manager.conf（账号段由 manager 模块渲染）	manager_custom.conf	Settings → Asterisk Manager Interface	`cat /etc/asterisk/manager.conf`
ARI 与内置 HTTP	http.conf、http_additional.conf、ari.conf、ari_additional.conf	http_custom.conf、ari_custom.conf	Admin → Advanced Settings（HTTP/ARI）	`fwconsole setting HTTPBINDPORT` 等
队列	queues_additional.conf	queues_custom.conf	Applications → Queues	`fwconsole setting -l`（QUEUES_*）
语音邮箱	voicemail.conf	voicemail_general_custom.conf 等	Applications → Voicemail（模块页/UCP）	`cat /etc/asterisk/voicemail.conf`
拨号计划	extensions_additional.conf	extensions_custom.conf	Applications 模块各自页面	`cat /etc/asterisk/extensions_custom.conf`
全局高级设置	（落库，不直接生成文件）	—	Admin → Advanced Settings	`fwconsole setting -l` / `fwconsole setting <KEY> <VALUE>`

如何选：全局开关与默认值先看 Advanced Settings；每分机/每队列的业务参数在对应模块页；FreePBX 界面没有暴露的 Asterisk 原生参数才落到 *_custom.conf 手写。

五、核心参数分类详解

5.1 分机与端点参数（PJSIP endpoint / aor / auth）

每个分机在 PJSIP 侧渲染为三个配置块。实测分机 1001 的端点块（pjsip.endpoint.conf 节选，原文照抄）：

[1001]
type=endpoint
aors=1001
auth=1001-auth
tos_audio=ef
tos_video=af41
cos_audio=5
cos_video=4
allow=ulaw,alaw,gsm,g726,g722
context=from-internal
callerid=Lab Extension <1001>

dtmf_mode=rfc4733
direct_media=yes
mailboxes=1001@device

mwi_subscribe_replaces_unsolicited=yes
aggregate_mwi=no
use_avpf=no

逐项说明：

参数	实测值	含义
type=endpoint	endpoint	声明这是端点（SIP 对端定义）
aors / auth	1001 / 1001-auth	关联同号的 AOR（注册地址）与认证块
tos_audio=ef、cos_audio=5	ef / 5	语音 RTP 包的 DSCP/802.1p 标记，ef（Expedited Forwarding）是语音标准值
allow	ulaw,alaw,gsm,g726,g722	允许的编解码序列（越靠前优先级越高）
context=from-internal	from-internal	呼入该端点进入的拨号计划上下文
callerid	Lab Extension <1001>	外显主叫名与号码
dtmf_mode	rfc4733	DTMF 传送方式
direct_media	yes	允许终端间媒体直通（不强制过 PBX）
mailboxes	1001@device	绑定的语音邮箱（MWI 消息等待指示来源）
use_avpf	no	是否启用 AVPF（WebRTC 场景才需要）

💡 技术拓展：dtmf_mode 不止 rfc4733 一种。常见取值对比——

取值原理适用场景
rfc4733（默认） RTP 包内带外传 DTMF 事件绝大多数现代话机/软终端
inband 把按键音混在语音流里老设备、经转码易失真
auto 协商失败时回退 inband 混合设备环境
info 用 SIP INFO 消息传少数网关
本文实测环境采用默认 rfc4733，与常见话机兼容性最好。

取值	原理	适用场景
rfc4733（默认）	RTP 包内带外传 DTMF 事件	绝大多数现代话机/软终端
inband	把按键音混在语音流里	老设备、经转码易失真
auto	协商失败时回退 inband	混合设备环境
info	用 SIP INFO 消息传	少数网关
本文实测环境采用默认 `rfc4733`，与常见话机兼容性最好。

AOR 块（pjsip.aor.conf 实测原文）：

[1001]
type=aor
mailboxes=1001@device

max_contacts=1
remove_existing=yes
maximum_expiration=7200
minimum_expiration=60
qualify_frequency=60

参数	实测值	含义
max_contacts	1	该 AOR 最多同时注册几个联系人；重复注册被拒的根源（见七、7.5）
remove_existing	yes	新注册到来时移除旧联系人（同一账号换端口重注册可成功）
maximum_expiration / minimum_expiration	7200 / 60	注册租约上下限（秒），终端请求的 expires 被钳制在该区间
qualify_frequency	60	每 60 秒对联系人发一次 OPTIONS 存活探测（qualify）

认证块（pjsip.auth.conf 实测原文）：

[1001-auth]
type=auth
auth_type=userpass
password=q1w2e3r4
username=1001

SIP 注册验证（终端侧 sipsak 发起，PBX 侧确认，实测回显）：

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

5.2 SIP 传输、NAT 与 RTP 参数

SIP 传输与 NAT 由 sipsettings 模块管理（Settings → Asterisk SIP Settings），全局默认值落在 Advanced Settings 的 DEVICE_SIP_* 键（实测节选）：

参数键	实测值	含义
DEVICE_SIP_CANREINVITE	no	是否允许会话内 re-INVITE 媒体重定向（no=媒体始终过 PBX，利于录音与统计）
DEVICE_SIP_DTMF	rfc2833	SIP 设备默认 DTMF 方式（rfc2833 与 PJSIP 的 rfc4733 是同一事件的旧/新称呼）
DEVICE_SIP_TRUSTRPID	yes	是否信任终端发来的 RPID/PAI 头
DEVICE_SIP_SENDRPID	pai	对外发送 PAI（P-Asserted-Identity）头
DEVICE_SIP_NAT	yes	对终端启用 NAT 穿透辅助
DEVICE_SIP_ENCRYPTION	no	是否强制 SRTP 加密
DEVICE_SIP_QUALIFYFREQ	60	默认存活探测间隔（秒）

RTP 端口范围（Asterisk 运行时实测）：

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

对应的生成文件 /etc/asterisk/rtp_additional.conf（实测）：

[general]
rtpstart=10000
rtpend=20000
rtpchecksums=yes
strictrtp=yes

参数	实测值	含义
rtpstart / rtpend	10000 / 20000	RTP 媒体端口池（防火墙/NAT 放行范围必须覆盖它）
rtpchecksums	yes	RTP 包校验和
strictrtp	yes	严格 RTP：丢弃来源不符的媒体包（防嗅探/注入，NAT 环境异常时再放宽）

5.3 AMI（Asterisk Manager Interface）参数

AMI 是 FreePBX 驱动 Asterisk 的内部通道，/etc/asterisk/manager.conf 实测：

[general]
enabled = yes
port = 5038
bindaddr = 127.0.0.1
displayconnects=no ;only effects 1.6+

[rPBmIbteyXiq]

参数	实测值	含义
enabled	yes	AMI 开关（FreePBX 依赖它，不能关）
port / bindaddr	5038 / 127.0.0.1	监听端口与地址——默认只绑回环，外部无法直连 AMI（安全默认值）
displayconnects	no	不在 CLI 回显连接事件
[rPBmIbteyXiq]	随机账号	安装时自动生成的 FreePBX 内部 AMI 账号，用户名/密码即 Advanced Settings 的 AMPMGRUSER/AMPMGRPASS（实测 `rPBmIbteyXiq` / `v8l1FohsSC/z`，默认值原本是 admin/amp111）

自建 AMI 账号应写在 manager_custom.conf，例如：

[myapp]
secret = q1w2e3r4
deny = 0.0.0.0/0.0.0.0
permit = 127.0.0.1/255.255.255.255
read = call,event
write = call,originate

💡 技术拓展：Asterisk 的北向接口不止 AMI 一种——

接口形态适合
AMI（5038） TCP 长连接 + 文本事件流实时事件订阅、点击外呼
ARI（8088/8089） REST + WebSocket 应用层媒体控制、IVR 引擎
CLI（asterisk -rx）单次命令排障与巡检
AGI 每呼叫进程内脚本拨号计划内嵌逻辑
FreePBX 本体用 AMI；本文实测环境 ENABLE_ARI=0（未启用 ARI）。

接口	形态	适合
AMI（5038）	TCP 长连接 + 文本事件流	实时事件订阅、点击外呼
ARI（8088/8089）	REST + WebSocket	应用层媒体控制、IVR 引擎
CLI（asterisk -rx）	单次命令	排障与巡检
AGI	每呼叫进程内脚本	拨号计划内嵌逻辑
FreePBX 本体用 AMI；本文实测环境 ENABLE_ARI=0（未启用 ARI）。

5.4 ARI 与 Asterisk 内置 HTTP 参数

Asterisk 自带 HTTP 服务（ARI 与 WebSocket 挂载其上），相关键全部在 Advanced Settings（实测值见 3.2 节表格）：

参数键	实测值	含义
HTTPENABLED	1（默认 0）	内置 HTTP 服务开关；FreePBX 17 安装后默认打开
HTTPBINDADDRESS	127.0.0.1（默认 `::`）	绑定地址——安装器改成了仅回环，外部不能访问 ARI
HTTPBINDPORT	8088	HTTP 端口
HTTPTLSENABLE	1	HTTPS（WSS）开关
HTTPTLSBINDPORT	8089	HTTPS 端口（实测监听在所有地址 `*:8089`）
HTTPTLSCERTFILE / HTTPTLSPRIVATEKEY	/etc/asterisk/keys/integration/*.pem/key	TLS 证书（certman 模块生成的集成证书）
HTTPSESSIONLIMIT	10000（默认 100）	HTTP 会话上限（安装器已放宽）
ENABLE_ARI	0	ARI 应用接口开关（未启用）

验证监听（实测）：

ss -lntp | grep -E ':(8088|8089|5038)\b'

LISTEN 0      10          127.0.0.1:8088       0.0.0.0:*    users:(("asterisk",pid=117821,fd=13))
LISTEN 0      10          127.0.0.1:5038       0.0.0.0:*    users:(("asterisk",pid=117821,fd=15))
LISTEN 0      10                *:8089             *:*    users:(("asterisk",pid=117821,fd=14))

5.5 队列参数（Queues）

队列的全局默认值在 Advanced Settings（实测 QUEUES_* 键节选）：

参数键	实测值	含义
QUEUES_UPDATECDR	0	队列事件回写 CDR
QUEUES_MIX_MONITOR	1	座席录音用 MixMonitor（双声道分离）
QUEUES_EVENTS_WHEN_CALLED_DEFAULT	0	呼叫座席时是否生成 agent 事件

单个队列的参数实测（自建队列 700，写在 queues_custom.conf，原文照抄）：

[700]
strategy=ringall
timeout=15
retry=5
maxlen=0
joinempty=yes
leavewhenempty=no
ringinuse=no
musicclass=default
announce-frequency=0
announce-holdtime=no
announce-position=no
member => PJSIP/1001,0,Lab Agent

参数	实测值	含义
strategy	ringall	分配策略
timeout / retry	15 / 5	单次振铃秒数 / 未接后重试间隔
maxlen	0	排队人数上限（0=不限）
joinempty / leavewhenempty	yes / no	无座席时是否允许加入 / 是否自动离开
ringinuse	no	忙碌座席是否参与振铃
musicclass	default	等待音乐类
announce-frequency	0	排队位置播报间隔（0=不播报）
member	PJSIP/1001,0,Lab Agent	静态成员：技术/罚时秒数/名称

💡 技术拓展：队列分配策略 strategy 常见取值对比——

取值逻辑适用场景
ringall（本文实测所用）全部空闲座席同振小型客服组，响应速度优先
rrmemory 轮询并记住上次位置座席负载均衡
leastrecent 派给最久未接的座席均衡历史工作量
fewestcalls 派给当前通话最少的座席均衡实时负载
linear 按成员列表顺序有明确的优先座席顺序

取值	逻辑	适用场景
ringall（本文实测所用）	全部空闲座席同振	小型客服组，响应速度优先
rrmemory	轮询并记住上次位置	座席负载均衡
leastrecent	派给最久未接的座席	均衡历史工作量
fewestcalls	派给当前通话最少的座席	均衡实时负载
linear	按成员列表顺序	有明确的优先座席顺序

5.6 语音邮箱参数（Voicemail）

/etc/asterisk/voicemail.conf 的 [general] 段（实测节选）：

[general]
emailbody=${VM_NAME},\n\nThere is a new voicemail in mailbox ${VM_MAILBOX}:\n\n\tFrom:\t${VM_CALLERID}\n\tLength:\t${VM_DUR} seconds\n\tDate:\t${VM_DATE}\n\nDial *98 to access your voicemail by phone.\nVisit /ucp to check your voicemail with a web browser.\n
pollmailboxes=yes
pollfreq=10
forcegreetings=yes
forcename=yes
emailsubject=PBX Voicemail Notification
fromstring=PBX Phone System
charset=UTF-8
envelope=yes
operator=yes
review=no

参数	实测值	含义
emailbody / emailsubject / fromstring	见上	留言通知邮件的正文模板（`${VM_*}` 变量）、主题与发件人名
pollmailboxes / pollfreq	yes / 10	每 10 秒轮询邮箱目录刷新 MWI 灯
forcegreetings / forcename	yes / yes	首次使用强制录问候语/录姓名
envelope	yes	播报留言前先播时间戳信封信息
operator	yes	留言后允许按 0 转接
review	no	留言后不允许回听重录

⚠️ 注意：fwconsole bulkimport 的 CSV voicemail 列实测填 enabled/default 都不会改变分机的邮箱状态（导入后 users.voicemail 仍是 novm），需导入后在 Web 界面逐分机开启。分机在 PJSIP 侧的 MWI 关联由 mailboxes=1001@device 承担（见 5.1）。

5.7 拨号计划自定义（extensions_custom.conf）

FreePBX 渲染的 extensions_additional.conf 禁止手改，自定义拨号计划写在 extensions_custom.conf。实测的演示计划（拨 8000 听 hello-world）：

[from-internal-custom]
exten => 8000,1,Answer()
 same => n,Playback(hello-world)
 same => n,Hangup()

要点：

挂在 [from-internal-custom] 是因为它被 from-internal 上下文 include，内部分机即可拨打。
验证方式：分机注册后拨 8000 听到 hello-world 提示音；CLI 侧核对：

asterisk -rx 'dialplan show 8000@from-internal-custom'

FreePBX 自带的应用（队列、IVR、振铃组）生成的拨号计划都在 extensions_additional.conf，其内部钩子的挂接点也在 custom 文件体系内，改动后 fwconsole reload 生效。

5.8 拨号选项 DIAL_OPTIONS

DIAL_OPTIONS（Advanced Settings，实测值 HhTtr）决定分机间 Dial() 的默认行为标志：

💡 技术拓展：Dial 选项字母含义速查——

字母含义
H 允许被叫按 * 挂断（结束本腿）
h 允许主叫按 * 挂断
T 允许被叫按 # 转接
t 允许主叫按 # 转接
r 指示回铃音生成
R 被叫忙时诱导回铃（非真实振铃）
实测环境为默认 HhTtr：保留挂断与转接能力。若全局禁转接（合规要求），改为 Hh 后所有分机按 # 转接失效。

字母	含义
H	允许被叫按 `*` 挂断（结束本腿）
h	允许主叫按 `*` 挂断
T	允许被叫按 `#` 转接
t	允许主叫按 `#` 转接
r	指示回铃音生成
R	被叫忙时诱导回铃（非真实振铃）
实测环境为默认 `HhTtr`：保留挂断与转接能力。若全局禁转接（合规要求），改为 `Hh` 后所有分机按 `#` 转接失效。

六、生产配置模板

适用场景声明：4GB 内存 / 50GB 系统盘 / 50 分机规模的中型办公 PBX（纯内网或专线接入、无 PCI 语音卡、录音保留 30 天）。以下参数全部来自本文实测参数域，可直接对照修改：

参数	推荐值	修改入口	依据
DEVICE_SIP_NAT	yes（内网终端）/ 视拓扑	Asterisk SIP Settings	终端经 NAT 注册时必须
DEVICE_SIP_CANREINVITE	no	Asterisk SIP Settings	媒体过 PBX，保证录音/统计完整
DEVICE_SIP_QUALIFYFREQ	60	Asterisk SIP Settings	默认值，50 分机探测压力可忽略
RTP 范围 rtpstart/rtpend	10000-20000（默认）或缩窄为实际放行段	Asterisk SIP Settings → RTP Settings	防火墙放行段必须与之一致
max_contacts（每分机 AOR）	1	Extensions → Advanced	一号一机，防串线
qualify_frequency	60	Extensions → Advanced	默认值
HTTPENABLED	1	Advanced Settings	FreePBX 内部功能依赖
HTTPBINDADDRESS	127.0.0.1	Advanced Settings	ARI/HTTP 不对外
HTTPSESSIONLIMIT	10000	Advanced Settings	安装器默认已放宽
AMI bindaddr	127.0.0.1	manager.conf/自定义	AMI 永不直接对外
DIAL_OPTIONS	HhTtr（默认）或 Hh（禁转接）	Advanced Settings	按合规要求取舍
QUEUES_MIX_MONITOR	1	Advanced Settings	队列录音双声道
voicemail pollfreq	10	voicemail.conf（模块页）	MWI 灯刷新速度
Apache KeepAlive/MPM	系统默认	/etc/apache2	50 分机规模 Web 并发极低，无需调

磁盘预算参考（50 分机）：录音按 G.722 双声道约 1.6MB/分钟，30 天保留按每分机日均 30 分钟通话计约 72GB——超出 50GB 盘时把录音保留天数降到 15 天或外接存储。数据库（asterisk+asteriskcdrdb）在 50 分机规模下数月内通常不超过 2GB，MariaDB 默认配置即可。

模板套用后的验证基线（全部为本文实测命令）：

fwconsole setting DIAL_OPTIONS          # 确认全局拨号选项
asterisk -rx 'rtp show settings'        # 确认 RTP 段与防火墙一致
asterisk -rx 'pjsip show contacts'      # 确认分机注册
ss -lntp | grep -E ':(8088|8089|5038)\b' # 确认北向接口仅按预期暴露

七、常见问题（FAQ）

7.1 手改配置文件后又被改回去了

现象：直接编辑 /etc/asterisk/rtp_additional.conf（或任何 *_additional.conf），fwconsole reload / Apply Config 后改动消失。实测生成文件的完整头注释（原文照抄）：

;--------------------------------------------------------------------------------;
;          Do NOT edit this file as it is auto-generated by FreePBX.             ;
;--------------------------------------------------------------------------------;
; For information on adding additional paramaters to this file, please visit the ;
; FreePBX.org wiki page, or ask on IRC. This file was created by the new FreePBX ;
; BMO - Big Module Object. Any similarity in naming with BMO from Adventure Time ;
; is totally deliberate.                                                         ;
;--------------------------------------------------------------------------------;

原因：这些文件是 FreePBX 按数据库设置值渲染的结果。处理：改数据库层——Web 界面对应模块页或 fwconsole setting <KEY> <VALUE>；Asterisk 原生但 FreePBX 未暴露的参数写 *_custom.conf（或 *_custom_post.conf），它们不会被覆盖。

7.2 改了参数但不生效

排查顺序：

是否点了 Apply Config / 执行了 fwconsole reload——Web 改动与 CLI 的 fwconsole setting 都只写库，不重载不生效；
用 asterisk -rx 查运行时实际值（如 pjsip show endpoint 1001）确认是否已渲染；
是否改错了层——fwconsole setting 只管 Advanced Settings 层，分机参数要去 Extensions 页或写 custom 文件。

7.3 bulkimport 导入的 voicemail 字段不生效

实测：CSV voicemail 列填 enabled 或 default，导入后查询仍是 novm：

mariadb asterisk -e "select extension, voicemail from users where extension='1001';"

extension  voicemail
1001       novm

处理：导入后对需要的分机在 Web 界面 Applications → Extensions → 该分机 → Voicemail 选项单独开启；或更新 users 表后 fwconsole reload。

7.4 AMI 账号名不是 admin，密码不认识

原因：安装器把 Advanced Settings 的 AMPMGRUSER/AMPMGRPASS 重置成了随机值（实测 rPBmIbteyXiq / v8l1FohsSC/z，表默认值才是 admin/amp111）。查看当前真实凭据：

fwconsole setting AMPMGRUSER
fwconsole setting AMPMGRPASS

⚠️ 注意：这两个值是 FreePBX 自用凭据，仅回环监听（127.0.0.1:5038）；不要把它们用于外部应用，外部应用按 5.3 节自建 AMI 账号。

7.5 同一分机重复注册被拒绝

现象：终端报注册失败（如 sipsak error: didn't received '200 OK' on register）。原因：AOR 默认 max_contacts=1（实测见 5.1），且终端每次重连使用新源端口时 Contact URI 变化，占位联系人尚在租约内（maximum_expiration=7200、default_expiration=3600）时新联系人被拒。处理：等租约到期、重启 asterisk 清空注册态，或把该分机 AOR 的 max_contacts 调大（多机同号场景才建议）。

7.6 内置 HTTP（8088）改了绑定地址还是只能本机访问

排查：HTTPBINDADDRESS（实测 127.0.0.1）改后需 Apply Config，且确认 ss -lntp 中 8088 的绑定地址已变化；8089（TLS）绑定在 ::，与 HTTP 绑定是两个独立参数（HTTPTLSBINDADDRESS）。

八、参考链接

FreePBX 官方文档：https://docs.freepbx.org/
Asterisk 配置参考（pjsip.conf/rtp.conf/manager.conf 等）：https://docs.asterisk.org/
Advanced Settings 官方说明：https://wiki.freepbx.org/display/FOP/Advanced+Settings
专栏前篇《FreePBX 17 介绍与选型指南》、《Debian 12 安装 FreePBX 17 指南》