Debian 12 安装 FusionPBX 5.6 指南

目标：在一台最小化安装的 Debian 12（bookworm）服务器上，使用 FusionPBX 官方安装脚本完成 FusionPBX 5.6 + FreeSWITCH 1.11 + PostgreSQL 18 + Nginx + PHP 8.4 的完整部署，并通过服务状态、端口监听、Web 登录与真实呼叫四条链路验证可用。文中全部命令与回显均在 Debian 12 环境实测（实测日期：2026-10-25）。

一、环境信息

操作系统：Debian 12（bookworm，最小化安装，root 操作）
软件版本：FusionPBX 5.6 分支（安装完成后 upgrade.php --version 自报 5.6.6；安装当日 5.6 系列最新发布标签为 5.6.5，2026-09-21 发布）
底层引擎：FreeSWITCH 1.11.3-release（源码编译，git ef32e20，2026-08-28 构建）
组件版本（实测回显）：Nginx 1.22.1、PHP 8.4.27（sury.org 仓库）、PostgreSQL 18.6（PGDG 官方仓库）
安装方式：官方安装脚本 fusionpbx/fusionpbx-install.sh（Debian 主推）
监听端口（安装完成后实测）：HTTP 80 / HTTPS 443（Nginx）、SIP 5060 与 5080（TCP/UDP，FreeSWITCH Sofia）、Event Socket 8021（仅 127.0.0.1）、PostgreSQL 5432（仅 127.0.0.1）
演示账号：Web 管理员 admin / q1w2e3r4（本系列文档统一演示口令，生产环境务必使用高强度随机口令）

二、前置条件

一台全新最小化安装的 Debian 12 服务器：官方脚本面向净系统，已经装有 Web/数据库/邮件等服务的机器不建议直接执行，避免端口与软件包冲突。
root 权限：本文全部命令均以 root 执行。
可访问互联网：安装过程需要访问 Debian 软件源、GitHub（安装脚本与 FusionPBX/FreeSWITCH 源码）、sury.org（PHP 仓库）、apt.postgresql.org（PGDG 仓库）。若网络受限，先按「八、常见问题」的 8.1、8.2 处理软件源与代理。
硬件建议：≥2 vCPU、≥4 GB 内存、≥20 GB 磁盘（FreeSWITCH 源码编译需要足够的内存与磁盘空间）。
防火墙规划：对外放行 80/443（Web）、5060 与 5080 的 TCP+UDP（SIP 信令）、16384-32768/udp（RTP 媒体）；Event Socket 8021 与 PostgreSQL 5432 默认只监听 127.0.0.1，不要对外放行。

三、版本选型说明

官方安装脚本的关键默认值集中在 resources/config.sh，安装前先按下表确认选型：

维度	脚本默认值	说明
FusionPBX 分支	5.6（system_branch=5.6）	当前稳定系列；脚本也支持 master 开发分支
FreeSWITCH 路线	源码编译（switch_source=true）	默认路线，无需任何 token，本文方案 A 实测
FreeSWITCH 路线	二进制包（switch_package=true）	备选路线，需要 SignalWire Personal Auth Token，见方案 B
数据库	PostgreSQL 18（database_repo=official）	使用 PGDG 官方仓库安装
PHP	8.4（php_version=8.4）	使用 sury.org 仓库，可选 8.1–8.3
Web 服务器	Nginx + PHP-FPM	脚本固定组合
默认域	ip_address（domain_name=ip_address）	默认租户域取服务器 IP

💡 说明：FreeSWITCH 官方 deb 仓库自 2023 年起需要 SignalWire 账号的 Personal Auth Token 才能访问，没有 token 时只能走源码编译路线，这也是官方脚本默认 switch_source=true 的原因。两条路线的差异与选择见「六、方案对比与选择建议」。

四、官方脚本在线安装方案（A：FreeSWITCH 源码编译，官方推荐）

4.1 方案说明

官方安装脚本（github.com/fusionpbx/fusionpbx-install.sh）是 FusionPBX 官方主推的安装方式：一条命令起步，脚本自动完成系统依赖、PHP 8.4、Nginx、FreeSWITCH 1.11 源码编译、PostgreSQL 18、FusionPBX Web 代码部署（/var/www/fusionpbx）、fail2ban/snmpd 等周边组件以及全部 systemd 单元注册。适合可联网的全新 Debian 12 服务器，也是本文实测路线。

4.2 下载官方安装脚本

官方提供预安装脚本，负责安装 git 并把安装脚本仓库克隆到 /usr/src：

# 下载并执行预安装脚本
wget -O - https://raw.githubusercontent.com/fusionpbx/fusionpbx-install.sh/master/debian/pre-install.sh | sh

进入脚本目录：

cd /usr/src/fusionpbx-install.sh/debian

4.3 调整安装配置（config.sh）

脚本的可调参数集中在 resources/config.sh：

# 查看默认配置
cat /usr/src/fusionpbx-install.sh/debian/resources/config.sh

本文演示统一口令 q1w2e3r4，安装前编辑该文件，将 system_password 与 database_password 两行改为：

system_password=q1w2e3r4
database_password=q1w2e3r4

system_password：安装结束后 Web 管理员 admin 的初始登录密码；
database_password：PostgreSQL 中 fusionpbx 数据库账号的密码，会写入 /etc/fusionpbx/config.conf。

⚠️ 注意：不修改时脚本会生成随机密码，并在安装结束的输出中打印，务必保存该输出；生产环境请使用高强度随机口令而非本文演示口令。

4.4 执行安装

主安装脚本全程自动，但 FreeSWITCH 源码编译耗时较长（实测约 40–80 分钟，视 CPU 与网络而定），建议放后台执行并记录日志：

# 后台执行主安装脚本并记录日志
cd /usr/src/fusionpbx-install.sh/debian && nohup sh ./install.sh > /root/fusionpbx-install.log 2>&1 &

跟踪安装进度：

tail -f /root/fusionpbx-install.log

安装结束的标志是日志末尾出现（实测）：

Please save this information and reboot this system to complete the install.

同时脚本会打印访问信息（实测，域名为服务器 IP）：

domain name: https://10.89.56.10
username: admin
password: q1w2e3r4

⚠️ 注意：官方要求安装完成后重启一次系统（reboot），让所有服务以干净状态启动，重启后再做下面的验证。

4.5 systemd 托管与服务状态验证

脚本已为全部组件注册 systemd 单元（FreeSWITCH 单元文件位于 /lib/systemd/system/freeswitch.service，Type=forking，以 www-data 用户运行）。重启后逐一检查核心服务：

systemctl is-active freeswitch

systemctl is-active nginx

systemctl is-active php8.4-fpm

systemctl is-active postgresql@18-main

四条命令实测回显均为：

active

确认开机自启（脚本已注册，重复执行无副作用）：

systemctl enable freeswitch

systemctl enable nginx

systemctl enable php8.4-fpm

systemctl enable postgresql@18-main

核对各组件版本（实测回显）：

nginx -v

nginx version: nginx/1.22.1

php --version

PHP 8.4.27 (cli) (built: ...) (NTS)

（实测输出首行，构建时间部分省略；Copyright 行略）

psql --version

psql (PostgreSQL) 18.6 (Debian 18.6-1.pgdg12+2)

fs_cli -x 'version'

实测回显 FreeSWITCH 版本为 1.11.3-release（git ef32e20，2026-08-28 构建）。注意官方脚本把 FreeSWITCH 安装到系统路径：fs_cli 位于 /usr/bin/fs_cli，freeswitch 位于 /usr/bin/freeswitch（而非 /usr/local 下）。

检查监听端口：

ss -tlnp

实测要点：Nginx 监听 80 与 443；FreeSWITCH（Sofia）在服务器地址上监听 5060 与 5080（TCP/UDP 均有）；Event Socket 仅监听 127.0.0.1:8021；PostgreSQL 仅监听 127.0.0.1:5432。

4.6 Web 登录验证

浏览器访问 http://<服务器IP>/，未登录时实测 302 跳转到 /login.php。登录表单除 username、password 字段外还带一个 64 位十六进制的动态 token 隐藏字段（防重放），直接以 admin / q1w2e3r4 登录，成功后经两次 302 跳转最终落在 http://<服务器IP>/core/dashboard/（页面含 logout 链接），Dashboard 展示注册数、并发呼叫、CPU/内存等实时状态。

命令行快速验证登录页可达：

curl -sI http://127.0.0.1/ | head -n 3

实测返回 302，Location 指向 /login.php。

4.7 通话功能实测（内置测试号码）

FusionPBX 默认 dialplan 内置一批测试号码（context global，实测 v_dialplans 表）：

号码	功能
*9196	echo 回声测试
*9195	delay echo 延迟回声
*9664	保持音乐（hold music）
*98	语音信箱主菜单（vmain）

不接任何话机，直接用 fs_cli 发起一路到保持音乐号码的呼叫，验证信令与媒体链路：

fs_cli -x 'originate loopback/*9664 &park'

实测回显为 +OK 后跟本次呼叫的通道 UUID。查看通道：

fs_cli -x 'show channels'

实测显示 2 个通道（loopback/*9664 的 a 腿处于 CS_EXECUTE park 状态，b 腿播放 silence_stream://2000，编解码 L16 8000），show calls 同样显示 2 total。用 originate 回显中的 UUID 挂断：

fs_cli -x 'uuid_kill 上一步回显中的UUID'

实测回显 +OK，再次 show channels 为 0 total，通话链路闭环验证通过。

⚠️ 注意：fs_cli 的 originate 参数里 * 号前不要加反斜杠转义，否则通道名会带 \* 字面量，呼叫以 NORMAL_CLEARING 立即结束（实测排障结论）。

4.8 fail2ban 入侵防护确认

官方脚本默认安装 fail2ban 保护 SIP 与 SSH。重启后确认状态：

systemctl is-active fail2ban

若为 active，查看已生效的 jail：

fail2ban-client status

实测 jail 列表：fusionpbx、fusionpbx-mac、nginx-404、nginx-dos、ssh、sshd。若 fail2ban 启动失败，按「八、常见问题」的 8.4 处理。

五、官方脚本在线安装方案（B：FreeSWITCH 二进制包，需 SignalWire token）

5.1 方案说明

与方案 A 使用同一官方脚本，区别仅在 FreeSWITCH 的安装来源：改为下载官方预编译 deb 包，免去源码编译，安装耗时可从 40–80 分钟缩短到十几分钟。代价是 FreeSWITCH 官方 deb 仓库需要 SignalWire 账号的 Personal Auth Token 才能访问（2023 年起生效），没有 token 无法使用该路线。本文未实测该路线（无 token），以下差异点来自官方脚本 config.sh 实测默认值与脚本注释。

5.2 与方案 A 的差异步骤

注册 signalwire.com 账号，在账号设置中生成 Personal Auth Token；
编辑 /usr/src/fusionpbx-install.sh/debian/resources/config.sh：将 switch_source 改为 false、switch_package 改为 true，并按脚本内注释填入 SignalWire token（具体键名以脚本内注释为准）；
其余步骤与方案 A 完全相同：执行 sh ./install.sh，验证方式一致。

六、方案对比与选择建议

维度	方案 A：源码编译（实测）	方案 B：二进制包
FreeSWITCH 版本	1.11.3-release（git ef32e20）	官方 deb 仓库当前版本
是否需联网	需要	需要
额外凭证	无	SignalWire Personal Auth Token
安装耗时	约 40–80 分钟（实测）	十几分钟（免编译）
systemd 服务名	freeswitch	freeswitch
优点	零凭证、版本最新、官方默认	速度快、二进制可复现
缺点	耗时长、编译期占用 CPU/内存	依赖 SignalWire 账号与仓库可用性

选择建议：无 SignalWire 账号或要紧跟 FreeSWITCH 最新修复 → 选方案 A；已有 SignalWire 账号、追求安装速度与可复现性 → 选方案 B。

七、配置说明

安装完成后各组件的关键路径（实测）：

组件	路径	说明
FusionPBX Web 代码	/var/www/fusionpbx	PHP 应用根目录
FusionPBX 主配置	/etc/fusionpbx/config.conf	数据库连接、缓存、FreeSWITCH 路径等
FreeSWITCH 配置	/etc/freeswitch	autoload_configs、dialplan 等
Nginx 站点	/etc/nginx/sites-available/fusionpbx	80/443 两个 server 段，fastcgi 走 php8.4-fpm.sock
PHP-FPM	/etc/php/8.4/fpm	pool 为 www.conf，监听 /run/php/php8.4-fpm.sock
PostgreSQL	/etc/postgresql/18/main	仅监听 127.0.0.1:5432

常用后续操作：

修改 admin 密码：登录 Web 管理界面，在 Accounts（账户）菜单的 Users 中编辑 admin 用户；
数据库连接参数：在 /etc/fusionpbx/config.conf 的 database.0.* 段（pgsql，127.0.0.1:5432，库名 fusionpbx）；
各配置项的逐项含义与默认值见本专栏《FusionPBX 5.6 配置参数详解》。

八、常见问题

Q1：执行安装脚本时 apt 官方源（deb.debian.org）拉取极慢或卡死怎么办？

将 Debian 软件源切换到就近的镜像站后重跑脚本。以阿里云镜像站为例：

# 备份并替换为阿里云镜像站源（bookworm）
cp /etc/apt/sources.list /etc/apt/sources.list.bak
cat > /etc/apt/sources.list <<'EOF'
deb http://mirrors.aliyun.com/debian/ bookworm main contrib non-free non-free-firmware
deb http://mirrors.aliyun.com/debian/ bookworm-updates main contrib non-free non-free-firmware
deb http://mirrors.aliyun.com/debian-security bookworm-security main contrib non-free non-free-firmware
EOF
apt-get update

实测切换后依赖安装恢复正常。

Q2：GitHub（raw.githubusercontent.com / git clone）直连不通，预安装或脚本拉源码失败？

为 git 与当前 shell 配置可用代理后重跑。示例代理地址 192.168.1.62:7897，请替换为实际可用的代理：

git config --global http.proxy http://192.168.1.62:7897
export http_proxy=http://192.168.1.62:7897
export https_proxy=http://192.168.1.62:7897

实测配置代理后 GitHub 克隆与源码下载恢复正常；安装完成后可用 git config --global --unset http.proxy 还原。

Q3：安装被中断（如 SSH 断开、误杀进程）后，重跑脚本时报 dpkg 锁定/配置错误？

先修复 dpkg 状态再重跑脚本：

dpkg --configure -a

实测安装进程被中断后出现 dpkg 状态异常，执行该命令修复后可继续安装。

Q4：fail2ban 服务启动失败？

实测 fail2ban 首次启动可能 failed，用 journalctl -u fail2ban 可见两类原因，逐一处理：

Have not found any log file for sshd jail——全新系统还没有产生认证日志，创建空文件即可：

touch /var/log/auth.log

fusionpbx-mac jail 找不到 /var/log/syslog（最小化系统未装 rsyslog）：

touch /var/log/syslog

然后重启并确认：

systemctl restart fail2ban
systemctl is-active fail2ban

实测回显 active，fail2ban-client status sshd 可见 File list 已包含 /var/log/auth.log、Currently banned 0。

Q5：安装日志卡在 FreeSWITCH 编译很久不动？

方案 A 的 FreeSWITCH 1.11 源码编译本身就是耗时大头，实测占总时长一半以上属正常现象；只要 tail -f /root/fusionpbx-install.log 仍在滚动输出编译信息即为正常。若机器内存小于 4 GB，建议增加 swap 或改用方案 B。

九、卸载与清理

官方脚本不提供卸载功能，按以下顺序手动清理（先停服务、再删数据、最后卸包）：

systemctl stop freeswitch

systemctl stop nginx

systemctl stop php8.4-fpm

systemctl stop fail2ban

systemctl disable freeswitch

systemctl disable nginx

systemctl disable php8.4-fpm

systemctl disable fail2ban

删除 PostgreSQL 中的 FusionPBX 数据库（在卸载 PostgreSQL 之前执行）：

su - postgres -c "dropdb fusionpbx"

删除 FusionPBX 与 FreeSWITCH 的全部文件：

rm -rf /var/www/fusionpbx /etc/fusionpbx /etc/freeswitch /usr/share/freeswitch /var/lib/freeswitch /var/log/freeswitch /var/cache/fusionpbx /usr/src/fusionpbx-install.sh

卸载软件包并清理第三方仓库：

apt-get remove --purge -y 'postgresql*' 'php8.4*' nginx fail2ban
rm -f /etc/apt/sources.list.d/pgdg.list /etc/apt/sources.list.d/php.list
apt-get update && apt-get autoremove -y

十、参考链接

官网：https://www.fusionpbx.com/
官方文档：https://docs.fusionpbx.com/
主仓库：https://github.com/fusionpbx/fusionpbx
官方安装脚本：https://github.com/fusionpbx/fusionpbx-install.sh
本专栏介绍篇：《FusionPBX 5.6 介绍与选型指南》
底层引擎安装（姊妹专栏）：《Ubuntu 22.04 安装 FreeSWITCH 1.11 指南》