FusionPBX 5.6 配置参数详解

目标：逐层讲清 FusionPBX 5.6 的配置体系——FusionPBX 主配置 config.conf、存于 PostgreSQL 的 Default/Domain Settings、Nginx 与 PHP-FPM 配置、FreeSWITCH 侧 vars.xml 与 Sofia profile，以及 FusionPBX 用 mod_lua xml_handler 动态生成 FreeSWITCH 配置的机制。全部参数与默认值来自 Debian 12 实装环境实测（实测日期：2026-10-25）。

一、环境信息

• 操作系统：Debian 12（bookworm），按本专栏《Debian 12 安装 FusionPBX 5.6 指南》官方脚本路线安装
• 软件版本：FusionPBX 5.6 分支（自报 5.6.6）、FreeSWITCH 1.11.3-release、Nginx 1.22.1、PHP 8.4.27、PostgreSQL 18.6
• 演示账号：Web 管理员 admin / q1w2e3r4
• 关键路径：Web 代码 /var/www/fusionpbx；主配置 /etc/fusionpbx/config.conf；FreeSWITCH 配置 /etc/freeswitch；Nginx 站点 /etc/nginx/sites-available/fusionpbx；PHP-FPM 配置 /etc/php/8.4/fpm

二、前置条件

• FusionPBX 已安装完成且四个核心服务（freeswitch、nginx、php8.4-fpm、postgresql@18-main）为 active 状态；
• 能以 admin 登录 Web 管理界面（http://<服务器IP>/core/dashboard/）；
• 服务器上可使用 fs_cli、psql 等命令行工具（均在 /usr/bin 下）。

三、参数查看与修改方式

FusionPBX 的参数分布在四个层次，修改方式各不相同：

3.1 Web 界面（Default Settings / Domain Settings）

绝大多数业务参数（1793 行默认设置，实测 v_default_settings 表）存在 PostgreSQL 中，通过 Web 界面维护：Advanced → Default Settings 维护全局默认值；Accounts → Domains 进入具体域后维护 Domain Settings 覆盖默认值（实测新装环境 v_domain_settings 为 0 行，即默认全部继承全局）。修改后即时写入数据库，FreeSWITCH 侧通过下文 5.6 节的 xml_handler 机制按需取用。

3.2 配置文件直改

系统级参数在文本配置文件中：/etc/fusionpbx/config.conf（FusionPBX 主配置）、Nginx/PHP-FPM/FreeSWITCH 各自配置。改文本配置后需重载对应服务：

systemctl reload nginx

systemctl reload php8.4-fpm

3.3 fs_cli 运行时命令

FreeSWITCH 侧的运行时参数用 fs_cli 查看与重载，例如查看全局变量：

fs_cli -x 'global_getvar local_ip_v4'

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

10.89.56.10

修改 XML 类配置后执行 fs_cli -x 'reloadxml' 重载（实测回显 +OK [Success]）。

四、参数总览（配置文件地图）

五、核心参数分类详解

5.1 FusionPBX 主配置 /etc/fusionpbx/config.conf

该文件由安装脚本生成，采用 段.键=值 的 ini 风格。实测全文要点如下（演示口令 q1w2e3r4）：

# 主数据库：PostgreSQL
database.0.type=pgsql
database.0.host=127.0.0.1
database.0.port=5432
database.0.dbname=fusionpbx
database.0.username=fusionpbx
database.0.password=q1w2e3r4
database.0.sslmode=prefer

# 备用数据库：FreeSWITCH 自带的 sqlite 核心库
database.1.type=sqlite
database.1.path=/var/lib/freeswitch/db/core.db

# Web 代码根目录
document.root=/var/www/fusionpbx

# 缓存：文件方式
cache.method=file
cache.location=/var/cache/fusionpbx

# FreeSWITCH 各目录
switch.conf.dir=/etc/freeswitch
switch.sounds.dir=/usr/share/freeswitch/sounds
switch.recordings.dir=/var/lib/freeswitch/recordings
switch.storage.dir=/var/lib/freeswitch/storage
switch.voicemail.dir=/var/lib/freeswitch/storage/voicemail
switch.scripts.dir=/usr/share/freeswitch/scripts

# 会话安全
session.cookie_secure=true

关键参数说明：

⚠️ 注意：session.cookie_secure=true 意味着未配置 HTTPS 证书前，若强制只走 HTTPS 之外的纯 HTTP 登录可能出现会话异常；生产应配置有效证书走 443。

5.2 Nginx 站点 /etc/nginx/sites-available/fusionpbx

官方脚本生成的站点配置含 80 与 443 两个 server 段，实测要点：

server {
    listen 127.0.0.1:80;
    server_name 127.0.0.1;
    ...
}
server {
    listen [::]:80;
    listen 80;
    server_name fusionpbx;
    root /var/www/fusionpbx;
    client_max_body_size 80M;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;
        ...
    }

    # 升级页面执行时间长，单独放宽超时
    location /core/upgrade/index.php {
        fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;
        fastcgi_read_timeout 15m;
    }

    # 禁止直接访问敏感文件
    location ~* \.(ht|db|git|lua)$ { deny all; }
}

（配置节选，实测关键指令如上）

5.3 PHP-FPM 与 php.ini

PHP-FPM 池配置 /etc/php/8.4/fpm/pool.d/www.conf 实测：

user = www-data
group = www-data
listen = /run/php/php8.4-fpm.sock
pm = dynamic
pm.max_children = 5
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 3

php.ini（/etc/php/8.4/fpm/php.ini）实测关键值：

💡 说明：FreeSWITCH 进程同样以 www-data 运行（见 5.7），因此 Web 端 PHP 与 FreeSWITCH 对录音、语音信箱目录有共同的读写权限，这是官方脚本的刻意设计。

5.4 FreeSWITCH 全局变量 vars.xml

/etc/freeswitch/vars.xml 中的 X-PRE-PROCESS 实测：

<X-PRE-PROCESS cmd="set" data="default_language=en"/>
<X-PRE-PROCESS cmd="set" data="default_dialect=us"/>
<X-PRE-PROCESS cmd="set" data="default_voice=callie"/>
<X-PRE-PROCESS cmd="set" data="hold_music=local_stream://default"/>

⚠️ 注意：会话上限与 RTP 端口范围不在 vars.xml，而在 /etc/freeswitch/autoload_configs/switch.conf.xml 中。实测该文件中 max-sessions 为 1000、sessions-per-second 为 30（第 53、55 行）；rtp-start-port（16384）与 rtp-end-port（32768）两行以注释形式给出，即未显式启用、运行时采用 FreeSWITCH 内置默认范围 16384-32768/udp。

运行时目录类全局变量（用 fs_cli -x 'global_getvar conf_dir' 这样的命令逐个查询，实测值如下）：

5.5 Sofia SIP Profiles（internal / external）

新装环境 v_sip_profiles 表实测 4 行，全部 enabled：internal（5060）、external（5080）、internal-ipv6、external-ipv6。fs_cli -x 'sofia status' 实测 4 个 profile 均 RUNNING：internal 绑定服务器地址:5060，external 绑定 :5080，两个 ipv6 profile 绑定 ::1。

profile 的 XML 不由静态文件提供，而是由 xml_handler 从数据库动态生成（见 5.6）。fs_cli -x 'sofia status profile internal' 实测关键参数：

修改 profile 参数后使之生效：

fs_cli -x 'sofia profile internal rescan'

实测回显：

+OK scan complete

5.6 mod_lua xml_handler 动态配置机制（理解 FusionPBX 配置的关键）

FusionPBX 5.6 不使用 mod_xml_curl 下发配置（实测 mod_xml_curl 未加载），而是使用 mod_lua 的 xml_handler。/etc/freeswitch/autoload_configs/lua.conf.xml 实测：

<param name="xml-handler-script" value="app.lua xml_handler"/>
<param name="xml-handler-bindings" value="configuration,dialplan,directory,languages"/>

工作机制：

1. FreeSWITCH 需要 configuration（模块配置）、dialplan（拨号计划）、directory（分机名录）、languages 四类 XML 时，调用 /usr/share/freeswitch/scripts/app.lua 的 xml_handler；
2. 该脚本进一步分派到 app/xml_handler/resources/scripts/ 下的 configuration、dialplan、directory、languages 四个 Lua 子脚本；
3. 子脚本实时查询 PostgreSQL（必要时结合文件缓存），拼出 XML 返回给 FreeSWITCH。

证据链（实测）：静态目录 /etc/freeswitch/sip_profiles、dialplan、directory 下全是 .noload 与 empty.xml 占位文件；fsxml 缓存中 sofia profiles 段为空——配置全部来自数据库动态生成。

💡 技术拓展：FreeSWITCH 动态配置下发的两种主流方式——

方式	原理	特点
mod_xml_curl	呼叫发生时 HTTP 请求外部 Web 服务取 XML	跨语言通用，多一跳 HTTP 开销
mod_lua xml_handler	FreeSWITCH 内嵌 Lua 直接查库拼 XML	FusionPBX 5.6 采用，低延迟、少组件

老版本 FusionPBX 曾提供 mod_xml_curl 方案，5.6 已统一到 Lua 路线。

运维含义：在 Web 界面改了分机、dialplan 后不需要手工 reloadxml 即可对新呼叫生效（每次呼叫实时取数）；但修改 vars.xml 等静态文件仍需 reloadxml。

5.7 FreeSWITCH systemd 单元参数

/lib/systemd/system/freeswitch.service 实测要点：

[Unit]
Description=freeswitch
[Service]
Type=forking
EnvironmentFile=-/etc/default/freeswitch
ExecStart=/usr/bin/freeswitch -u www-data -g www-data -ncwait -nonat
LimitNOFILE=100000

启动默认值还可放入 /etc/default/freeswitch（EnvironmentFile 引用，文件不存在时 - 前缀保证不报错）。

六、生产配置模板

以下模板以「8 vCPU / 16GB 内存 / NVMe SSD / 500 分机以内企业 PBX」为基准场景，仅列需要调整的项，其余保持默认：

更大规模（数千分机/呼叫中心）场景：将 cache.method 改为 memcache、PostgreSQL 独立部署并把 database.0.host 指向库服务器、按队列坐席数上调 max_children 与数据库连接数。

七、常见问题

Q1：在 Web 界面改了设置，FreeSWITCH 侧没生效？

先确认改的是 Default Settings 还是 Domain Settings（域设置覆盖全局）；业务参数由 xml_handler 实时取数，对新呼叫即时生效，但已存在的通道不受影响。SIP profile 级改动执行：

fs_cli -x 'sofia profile internal rescan'

静态 XML（vars.xml、autoload_configs）改动执行：

fs_cli -x 'reloadxml'

实测回显：

+OK [Success]
+ Reload XML [Success]

Q2：想确认某 profile/分机配置到底下发成什么样？

用 xml_handler 的思路反向验证：静态目录下是 .noload/empty.xml 占位属正常（见 5.6）；实际下发内容以 sofia status profile internal 等运行时查询为准，例如默认域为服务器 IP 时，可用 fs_cli -x 'user_exists id 1000@10.89.56.10' 验证分机 1000 是否已下发（把 1000 与 10.89.56.10 换成实际分机号与服务器 IP）。

Q3：纯 HTTP 访问登录后掉线/无会话？

检查 config.conf 的 session.cookie_secure=true：该值要求 Cookie 仅走 HTTPS。未配证书期间要么临时改为 false 并 reload php8.4-fpm，要么直接配置证书走 443（推荐后者）。

Q4：上传大录音/固件文件报 413 或超时？

三层限制需同时满足：Nginx client_max_body_size 80M、php.ini post_max_size 80M、upload_max_filesize 80M。调大时三处一起改，并相应放宽 PHP-FPM 与 Nginx 超时。

八、参考链接

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