Debian 12 安装 FreePBX 17 指南

目标：在 Debian 12（bookworm）服务器上从零完成 FreePBX 17 + Asterisk 22 的安装与初始化，产出可登录的 Web 管理界面与可注册的 SIP 分机。全文提供「官方一键脚本」与「Sangoma apt 仓库手动安装」两种方案，以及安装后初始化、分机注册验证与常见问题处理，均已在 Debian 12（bookworm）真实环境逐条实测通过。

一、环境信息

操作系统：Debian 12（bookworm），/etc/os-release 实测 PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"，x86_64 架构。
FreePBX：17（deb 包 freepbx17 17.1-1.sng12，内置 framework 17.0.19.32，113 个模块 Enabled）。
底层引擎：Asterisk 22（deb 包 asterisk22 22.11.0-1.sng12）。
运行时依赖（脚本自动安装，实测版本）：
- PHP 8.2.35（CLI）
- Apache 2.4.68（Debian）
- MariaDB 10.11.19
- Redis 7.0.15
- Node.js 18.20.4
实测服务器 IP：10.89.72.20（下文统一以此 IP 示例）；SIP 测试客户端 IP：10.89.72.50。
关键端口（ss -lntup 实测）：Web 管理 80/tcp（Apache），SIP 5060/udp（Asterisk），AMI 5038/tcp 与 ARI 8088/tcp 仅监听 127.0.0.1，WSS 8089/tcp。
安装日志目录：/var/log/pbx/（官方脚本自动创建）。
网络依赖：deb.freepbx.org（Sangoma 软件源）、github.com（脚本版本自检）、mirror.freepbx.org（模块市场）。

二、前置条件

本节列出安装前必须确认的系统条件。官方脚本自身带硬性检查，任何一条不满足都会拒绝执行，提前核对可以避免装到一半失败。

root 权限：脚本强制要求以 root 执行，非 root 直接退出（提示 This script must be run as root）。
仅支持 Debian 12（bookworm）：脚本读取 /etc/os-release 的 VERSION_CODENAME，非 bookworm 直接拒绝（提示 Unsupported OS version. This script supports only Debian 12 (bookworm).）。
64 位系统：脚本检查架构，x86_64 方可继续（仓库源 deb [arch=amd64]）。
FQDN 主机名：脚本要求 hostname -f 能解析出完整域名，否则中止。确认方法：

hostname -f    # 需要输出形如 pbx.example.lan 的完整域名

若输出为空，先设置主机名（以 pbx01.example.lan 为例，按实际域名替换）：

hostnamectl set-hostname pbx01.example.lan
echo "10.89.72.20 pbx01.example.lan pbx01" >> /etc/hosts

网络可达：能访问 deb.freepbx.org（安装包）、github.com（脚本版本自检，离线环境可用 --skipversion 跳过）、mirror.freepbx.org（模块在线升级）。
时间同步：SIP 协议对时间敏感，脚本默认安装并启用 chrony（可用 --nochrony 跳过）。

三、版本选型说明

FreePBX 17 是当前官方主推的大版本，其定位、架构与同类方案（Asterisk 裸配置、FusionPBX 等）的量化对比见《FreePBX 17 介绍与选型指南》。本节只讲安装层面的选型要点。

操作系统：官方安装脚本硬性限定 Debian 12（bookworm）。选择 Debian 12 以外的发行版（Ubuntu、Rocky 等）没有官方脚本支撑，需要手动解决 PHP 8.2、依赖包与 systemd 服务脚本，踩坑成本高；本篇两种方案均基于 Debian 12。
Asterisk 版本：官方脚本默认安装 Asterisk 22（实测 22.11.0）。脚本支持 ASTVERSION 环境变量调整大版本，但 FreePBX 17 的模块适配以 Asterisk 22 为主，非必要不改动。
分发形态：Sangoma 将 Asterisk 22 与 FreePBX 17 打包为 deb 包（版本号后缀 .sng12 表示 Sangoma 为 Debian 12 构建），从 deb.freepbx.org 仓库分发，无需源码编译。安装路径、服务脚本、配置目录均由 deb 包托管，升级维护走 apt。
组件版本对照（实测安装所得）：

组件	包名	实测版本
FreePBX 主包	freepbx17	17.1-1.sng12（framework 17.0.19.32）
Asterisk 主程序	asterisk22	22.11.0-1.sng12
Asterisk 免费模块包	asterisk22.0-freepbx-asterisk-modules	1.0-1.sng12
Asterisk 版本切换工具	asterisk-version-switch	6.1-34.sng12
PHP	php8.2 系列	8.2.35
Web 服务器	apache2	2.4.68
数据库	mariadb-server	10.11.19
缓存	redis-server	7.0.15
前端构建	nodejs	18.20.4

关键点：FreePBX 17 的 deb 主包体积大、依赖多，apt 会自动解析 MariaDB/Apache/PHP 全部依赖；手动方案（方案 B）中不需要逐个安装这些运行时，装 freepbx17 一个包即可。

四、方案 A：官方一键脚本在线安装（推荐）

4.1 方案说明

官方脚本 sng_freepbx_debian_install.sh 由 Sangoma 维护（GitHub 仓库 FreePBX/sng_freepbx_debian_install），一条命令完成系统准备、软件源配置、Asterisk 22 + FreePBX 17 及全部依赖安装、模块初始化。脚本行为清单（实测归纳）：

硬性检查：Debian 12 bookworm、root、64 位、FQDN、剩余端口占用；
安装基础依赖（wget、gnupg、chrony、iptables-persistent、postfix 等）；
下载并导入 Sangoma GPG 密钥，向 /etc/apt/sources.list 追加 deb [arch=amd64] http://deb.freepbx.org/freepbx17-prod bookworm main，写入 apt Pin（99sangoma-fpbx-repository，Pin-Priority 600）；
写入 /etc/apt/preferences.d/99-block-trixie.pref 阻止系统升级到 Debian 13（FreePBX 尚不支持）；
apt 安装 asterisk22 全家桶（含 addons、sounds、version-switch 等 21 个包）；
apt 安装 freepbx17 主包（连带 MariaDB、Apache、PHP、Redis、Node.js 全部依赖）；
fwconsole ma installlocal 安装全部本地模块、fwconsole ma upgradeall 在线升级模块、fwconsole reload + fwconsole restart 应用配置、fwconsole ma refreshsignatures 刷新模块签名；
全程日志写入 /var/log/pbx/freepbx17-install-<时间戳>.log。

实测核心安装耗时约 9 分 24 秒（日志时间戳 00:14:12 至 00:23:36，不含前置依赖包下载时间）。

4.2 下载官方脚本

apt-get update && apt-get install -y wget
wget https://github.com/FreePBX/sng_freepbx_debian_install/raw/master/sng_freepbx_debian_install.sh
chmod +x sng_freepbx_debian_install.sh

下载后可核对脚本版本（实测脚本内置 SCRIPTVER="1.15"）：

head -30 sng_freepbx_debian_install.sh | grep SCRIPTVER

实测输出：

SCRIPTVER="1.15"

4.3 执行安装

网络正常的环境直接执行：

bash sng_freepbx_debian_install.sh

网络受限（无法访问 github.com 做版本自检）的环境加 --skipversion：

bash sng_freepbx_debian_install.sh --skipversion

⚠️ 注意：脚本会静默把 stderr 重定向到日志文件，终端只显示部分进度。安装是否失败以日志为准，另开一个终端跟踪：

tail -f /var/log/pbx/freepbx17-install-*.log

4.4 脚本参数速查

以下参数均从脚本源码逐项核对（实测脚本版本 1.15）：

参数	作用
`--skipversion`	跳过联网版本自检（离线/受限网络必加）
`--testing`	使用 `deb.freepbx.org/freepbx17-dev` 测试软件源（默认 `freepbx17-prod`）
`--dev`	开发者模式
`--nofreepbx`	只装 Asterisk 与依赖，不装 FreePBX
`--noasterisk`	只装 FreePBX，不装 Asterisk
`--opensourceonly`	只保留开源模块（安装后自动移除全部 Commercial 商业模块）
`--noaac`	不安装 AAC（Asterisk Audio/Conf conferencing 相关）
`--dahdi`	额外安装 DAHDI（PCI 语音卡驱动）
`--dahdi-only`	只装 DAHDI（等价于 `--nofreepbx --noasterisk --noaac --dahdi`）
`--nochrony`	不安装 chrony 时间同步
`--debianmirror <url>`	指定 Debian 仓库镜像（默认 `http://ftp.debian.org/debian`，内网可指向本地镜像）
`--npmmirror <url>`	指定 npm 镜像
`--disable-deb-update-v13`	仅修复 apt 源锁定 bookworm 并阻止升级 Debian 13 后退出，不执行安装

关键提示：--opensourceonly 适合只想要纯开源组件的部署（脚本会 fwconsole ma -f remove 全部 License 为 Commercial 的模块）；--debianmirror 是内网部署的关键参数，配合本地 Debian 镜像源可实现半离线安装。

4.5 安装日志关键节点（实测节选）

安装日志按阶段推进，以下为实测日志关键行（原样摘抄）：

2026-10-26 00:23:36 - freepbx17 installed successfully....
2026-10-26 00:23:36 - ############################### 
2026-10-26 00:23:36 - Installing all local modules
Installing: customcontexts
Installing customcontexts...
Generating CSS...Done
Module customcontexts version 17.0.1.3 successfully installed
Updating Hooks...Done
Chowning directories...Done

Done. All modules installed.

看到 freepbx17 installed successfully.... 与 Done. All modules installed. 即代表核心安装完成。随后脚本会尝试在线升级模块（fwconsole ma upgradeall），受限网络下此阶段可能失败（详见八、8.2），不影响已装好的系统。

4.6 安装结果验证

逐项确认安装完整（以下均为实测命令与回显）：

fwconsole --version

FW Console - FreePBX Utility 17.0.19.32

asterisk -V

Asterisk 22.11.0

dpkg -l | grep -E '^ii +(asterisk22 |freepbx17 )'

ii  asterisk22  22.11.0-1.sng12  amd64  Asterisk 22 is a software implementation of a telephone private branch exchange (PBX)
ii  freepbx17   17.1-1.sng12     amd64  FreePBX 17 is a web-based open source GUI (graphical user interface) that controls and manages Asterisk

systemctl is-active asterisk apache2 mariadb

active
active
active

fwconsole ma list | grep -c Enabled

模块清单抽样（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   |
+---------------------+------------+---------+-------------+-----------+

端口监听验证：

ss -lntup | grep -E ':(80|443|5060|5038|8088|8089)\b'

udp   UNCONN 0      0            0.0.0.0:5060       0.0.0.0:*    users:(("asterisk",pid=117821,fd=19))
tcp   LISTEN 0      511          0.0.0.0:80         0.0.0.0:*    users:(("apache2",pid=120116,fd=3))
tcp   LISTEN 0      10         127.0.0.1:8088       0.0.0.0:*    users:(("asterisk",pid=117821,fd=13))
tcp   LISTEN 0      10         127.0.0.1:5038       0.0.0.0:*    users:(("asterisk",pid=117821,fd=15))
tcp   LISTEN 0      10                 *:8089             :*    users:(("asterisk",pid=117821,fd=14))

要点：Web 管理 80 端口由 Apache 监听并对外开放；SIP 5060/udp 对外；AMI（5038）与 ARI（8088）默认只监听本机回环，属安全默认值。

五、方案 B：Sangoma apt 仓库手动安装

5.1 方案说明

方案 A 的本质也是 Sangoma deb 仓库，区别仅在于脚本代劳了全部步骤。手动方案适合两类场景：一是需要精确控制每一步（如内网审计、分阶段执行）；二是脚本检查项与现场环境冲突（如已有自定义 postfix 配置、需要先做系统加固）时，绕开脚本直接操作仓库。本方案所有配置文件与包清单均来自方案 A 实测产物，可直接对照核对。

5.2 添加 GPG 密钥与软件源

apt-get update && apt-get install -y wget gnupg2

导入 Sangoma GPG 密钥（与脚本行为一致）：

wget -O - http://deb.freepbx.org/gpg/aptly-pubkey.asc | gpg --dearmor --yes -o /etc/apt/trusted.gpg.d/freepbx.gpg

追加仓库到 /etc/apt/sources.list：

echo "deb [arch=amd64] http://deb.freepbx.org/freepbx17-prod bookworm main" | tee -a /etc/apt/sources.list

写入 apt Pin（将 deb.freepbx.org 来源的包固定为高优先级，防止被 Debian 官方同名包覆盖）：

cat > /etc/apt/preferences.d/99sangoma-fpbx-repository <<'EOF'
Package: *
Pin: origin deb.freepbx.org
Pin-Priority: 600
EOF

阻止系统升级到 Debian 13 trixie（FreePBX 17 官方尚未支持）：

cat > /etc/apt/preferences.d/99-block-trixie.pref <<'EOF'
# Block Debian 13 Trixie
Package: *
Pin: release n=trixie
Pin-Priority: -1

EOF

刷新索引：

apt-get update

验证仓库配置（以下为方案 A 实测机器上的实际文件内容，手动方案完成后应完全一致）：

grep freepbx.org /etc/apt/sources.list

deb [arch=amd64] http://deb.freepbx.org/freepbx17-prod bookworm main

ls -l /etc/apt/trusted.gpg.d/freepbx.gpg /etc/apt/preferences.d/99sangoma-fpbx-repository

-rw-r--r-- 1 root root 2257 Oct 26 00:14 /etc/apt/trusted.gpg.d/freepbx.gpg
-rw-r--r-- 1 root root   60 Oct 26 00:14 /etc/apt/preferences.d/99sangoma-fpbx-repository

5.3 安装 Asterisk 22 及组件包

按官方脚本的包清单逐组安装（以下包名与版本均来自实测安装结果）：

apt-get install -y asterisk22 \
  asterisk22-addons asterisk22-addons-bluetooth asterisk22-addons-core \
  asterisk22-addons-mysql asterisk22-addons-ooh323 asterisk22-core \
  asterisk22-curl asterisk22-dahdi asterisk22-doc asterisk22-odbc \
  asterisk22-ogg asterisk22-flite asterisk22-g729 asterisk22-resample \
  asterisk22-snmp asterisk22-speex asterisk22-sqlite3 \
  asterisk22-res-digium-phone asterisk22-voicemail \
  asterisk22.0-freepbx-asterisk-modules asterisk-version-switch

安装语音提示音与音乐保持音（示例为常用英文核心集，其余语言按需追加）：

apt-get install -y asterisk-sounds-core-en-alaw asterisk-sounds-core-en-ulaw \
  asterisk-sounds-core-en-wideband asterisk-sounds-extra-en-ulaw \
  asterisk-sounds-moh-opsound-ulaw asterisk-sounds-moh-opsound-alaw \
  asterisk-sounds-moh-opsound-wideband asterisk-sounds-moh-opsound-sln

验证 Asterisk 可执行：

asterisk -V

Asterisk 22.11.0

dpkg -l | grep -E '^ii +asterisk22' | wc -l

5.4 安装 FreePBX 17 主包并初始化模块

freepbx17 一个包会连带安装 MariaDB、Apache、PHP 8.2、Redis、Node.js 等全部依赖，并完成 FreePBX 数据库初始化：

apt-get install -y freepbx17

安装完成后初始化本地模块并应用配置：

fwconsole ma installlocal
fwconsole reload
fwconsole restart

💡 说明：fwconsole 是 FreePBX 17 的统一命令行管理工具（模块管理、配置重载、日志查看等），常用子命令在本章 7.2、7.3 节均有使用示例。ma installlocal 会把 deb 包内置的全部 113 个模块一次性启用，等价于方案 A 脚本的同名步骤。

5.5 验证

验证项与方案 A 的 4.6 节完全一致，逐项执行：fwconsole --version（应为 17.0.x）、asterisk -V（Asterisk 22.11.0）、systemctl is-active asterisk apache2 mariadb（三行 active）、fwconsole ma list | grep -c Enabled（约 113）。全部通过后进入第七章初始化。

六、方案对比与选择建议

两种方案的实测对照如下：

维度	方案 A：官方一键脚本	方案 B：apt 仓库手动安装
操作步骤	1 条命令	约 10 组命令
系统检查	脚本自动（OS/root/64位/FQDN/端口）	需自行确认
软件源配置	自动（GPG + 仓库 + Pin + 锁 trixie）	手动逐个写入
包安装	自动（Asterisk 22 全家桶 + freepbx17）	手动按清单安装
模块初始化	installlocal + upgradeall + reload + refreshsignatures	手动 installlocal + reload + restart
可控性	低（黑盒执行，中途失败需读日志定位）	高（每步可检查、可暂停）
耗时（实测）	约 10 分钟	约 15-20 分钟（含逐项验证）
适用场景	全新裸机快速交付	内网审计、系统已有定制、脚本检查项冲突

选择建议：全新 Debian 12 裸机首选方案 A，省时且步骤与官方演进同步；系统已有定制（如自建 postfix/iptables 规则）或需要分阶段审批的内网环境选方案 B，把脚本行为拆成可控步骤执行。两方案结果等价——最终都得到 freepbx17 17.1-1.sng12 + asterisk22 22.11.0-1.sng12 的同一套系统。

七、安装后配置说明

7.1 首次登录与初始化向导（创建 admin 账号）

浏览器访问 http://10.89.72.20/，首次进入会强制跳转到初始化向导（Setup wizard），按表单填写：

表单字段	说明	实测填写值
Username	管理员用户名	admin
Password1 / Password2	管理员密码（两次一致）	q1w2e3r4
Email	管理员邮箱	admin@example.lan
System Identifier	系统标识（用于模块市场识别这台机器）	pbx01
Automatic Module Updates	自动模块更新	Disabled（生产建议手动）
Automatic Security Updates	安全更新自动安装	Enabled
Unsigned Module Notification	未签名模块告警邮件	默认勾选
Update Every	更新检查周期	Daily
Update Period	更新检查时段	Nightly

提交后向导完成，进入 FreePBX 管理后台。验证账号已落库（实测回显）：

mariadb asterisk -e 'select username, email from ampusers;'

username	email
admin

💡 说明：ampusers 表存放 Web 管理账号。邮箱列实测为空是向导提交时邮箱字段可空所致，不影响登录。管理后台所有功能入口都在顶部菜单：Applications（分机/队列/IVR）、Connectivity（中继/路由）、Reports（CDR 通话记录）、Settings（系统配置）、Admin（模块管理与用户）。

7.2 服务管理与开机自启

FreePBX 17 涉及三个服务进程，实测状态：

systemctl is-active asterisk apache2 mariadb

active
active
active

⚠️ 注意：asterisk.service 是 SysV 包装服务（/etc/init.d/asterisk），不是原生 systemd unit，因此 systemctl is-enabled asterisk 返回的是 SysV 检查结果（实测输出 disabled，并附带提示 asterisk.service is not a native service, redirecting to systemd-sysv-install）。这是包的托管方式使然，不代表服务异常；systemctl start/stop/restart/is-active asterisk 均正常可用。

需要确保开机自启时逐个检查并启用：

systemctl is-enabled apache2
systemctl is-enabled mariadb
systemctl enable asterisk
systemctl enable apache2
systemctl enable mariadb

日常重启顺序（配置变更后先 reload FreePBX，异常时再重启进程）：

fwconsole reload
systemctl restart asterisk
systemctl restart apache2

7.3 创建分机并验证 SIP 注册

分机（Extension）是最基础的 PBX 资源。创建方式有两种：Web 界面（Applications → Extensions → Add Extension）与 CLI 批量导入（fwconsole bulkimport）。后者适合一次性建几十上百个分机，实测流程如下。

准备 CSV 文件（表头为 bulkimport 固定格式，实测可用列）：

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
cat /tmp/ext2.csv

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

执行导入（--replace 表示同号覆盖）：

fwconsole bulkimport --type=extensions --replace /tmp/ext2.csv

Importing bulk extensions

命令输出很简短，结果以 Asterisk 侧为准：

asterisk -rx 'pjsip show endpoints' | grep 'Endpoint:.*2001'

 Endpoint:  2001/2001                                            Unavailable   0 of inf

💡 说明：Unavailable 表示分机存在但当前无终端注册，属正常初始状态。

在测试客户端（Debian 客户端安装 apt-get install -y sipsak）用 sipsak 发起注册验证：

sipsak -U -s sip:1001@10.89.72.20 -H 10.89.72.50 --auth-username=1001 --password=q1w2e3r4

注册成功时 sipsak 以 usrloc 测试完成收尾（实测输出）：

All usrloc tests completed successful

Asterisk 对注册请求的应答中会带上版本标识（实测抓包可见应答头 User-Agent: FPBX-17.0.19.32(22.11.0)，格式为 FPBX-<framework版本>(<Asterisk版本>)）。

在 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

注册链路验证完成：sipsak 报告 usrloc 测试全部通过，PBX 侧 pjsip show contacts 出现对应 Contact（NonQual 表示未开启 qualify 主动探测，属默认行为）。至此「安装 → 初始化 → 分机 → 注册」全链路打通。

八、常见问题（FAQ）

8.1 脚本启动即失败：版本检查联网被拒

现象：脚本在 Performing version check... 阶段中止，日志尾部出现：

2026-10-26 00:13:15 - Performing version check...
--2026-10-26 00:13:15--  https://github.com/FreePBX/sng_freepbx_debian_install/raw/master/sng_freepbx_debian_install.sh
Resolving github.com (github.com)... 20.205.243.166
Connecting to github.com (github.com)|20.205.243.166|:443... failed: Connection refused.

原因：脚本每次运行都会联网比对最新脚本版本，github.com 不可达即中止。处理：加 --skipversion 跳过自检重跑：

bash sng_freepbx_debian_install.sh --skipversion

8.2 安装末段报 ** INSTALLATION FAILED *：模块在线升级不通

现象：日志已出现 freepbx17 installed successfully....，但在 Upgrading FreePBX 17 modules 阶段中止：

Upgrading module 'framework' from 17.0.19.32 to 17.0.33.2
Downloading module 'framework'
Processing framework
The following error(s) occured:
 - Unable to connect to servers from URLs provided: https://mirror.freepbx.org/modules/packages/framework/framework-17.0.33.2.tgz.gpg
2026-10-26 00:23:39 - ****** INSTALLATION FAILED *****
2026-10-26 00:23:39 - Error at line: 1307 exiting with code 2 (last command was: fwconsole ma upgradeall >> "$log")

原因：fwconsole ma upgradeall 需要访问模块市场 mirror.freepbx.org，受限网络不可达导致脚本以退出码 2 结束。关键判断：失败发生在升级阶段而非安装阶段，freepbx17 installed successfully 之前的产物（113 个本地模块、Web 界面、CLI）全部完整可用。处理：恢复 mirror.freepbx.org 访问（或配置代理）后单独重跑：

fwconsole ma upgradeall
fwconsole reload

8.3 systemctl is-enabled asterisk 显示 disabled

现象：

$ systemctl is-enabled asterisk
asterisk.service is not a native service, redirecting to systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install is-enabled asterisk
disabled

原因：FreePBX 17 的 asterisk 服务由 SysV 脚本（/etc/init.d/asterisk）托管，systemd 通过 systemd-sysv-install 兼容层处理，is-enabled 读的是 SysV rc 链接状态。处理：确认运行状态用 systemctl is-active asterisk（返回 active 即正常）；要开机自启则执行 systemctl enable asterisk（兼容层会创建 rc 链接），再复核 ls /etc/rc*.d/ | grep asterisk 可见 S 符号链接。

8.4 sipsak 重复注册报 didn't received '200 OK' on register

现象：首次 sipsak 注册成功，再次执行报错：

error: didn't received '200 OK' on register (see above). aborting

原因：FreePBX 默认分机 AOR 的 max_contacts = 1（实测 asterisk -rx 'pjsip show aor 1001' 输出 max_contacts : 1、default_expiration : 3600），且 sipsak 每次运行使用新的随机源端口，新 Contact URI 会被拒绝。处理：先查看当前占用：

asterisk -rx 'pjsip show contacts'

已有 Contact 在位则等 3600 秒默认租约过期，或重启 Asterisk 清空注册态（PJSIP 注册信息默认保存在内存中）：

systemctl restart asterisk

8.5 bulkimport 导入的 voicemail 字段不生效

现象：CSV 中 voicemail 列填 enabled 或 default，导入后分机语音信箱仍是关闭状态，直接查询可复现：

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

extension  voicemail
1001       novm

原因：bulkimport 的 voicemail 列与 users.voicemail 字段的值域不匹配（novm 表示 no voicemail），实测填 enabled/default 均不会改写该字段。处理：导入后对需要语音信箱的分机，在 Web 界面 Applications → Extensions → 该分机 → Voicemail 选项中单独开启，或逐台用 SQL 修正后 fwconsole reload。

8.6 fwconsole status 报 Command "status" is not defined

现象：

$ 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。

九、卸载与清理

完全移除 FreePBX 17 与 Asterisk 22（按依赖反向顺序执行）。

停止并禁用服务（逐个执行）：

systemctl stop asterisk
systemctl stop apache2
systemctl disable asterisk

卸载主包与 Asterisk 全家桶（purge 连配置文件一起删除）：

apt-get purge -y freepbx17 asterisk22 asterisk22-addons asterisk22-addons-bluetooth \
  asterisk22-addons-core asterisk22-addons-mysql asterisk22-addons-ooh323 \
  asterisk22-core asterisk22-curl asterisk22-dahdi asterisk22-doc asterisk22-odbc \
  asterisk22-ogg asterisk22-flite asterisk22-g729 asterisk22-resample \
  asterisk22-snmp asterisk22-speex asterisk22-sqlite3 asterisk22-res-digium-phone \
  asterisk22-voicemail asterisk22.0-freepbx-asterisk-modules asterisk-version-switch
apt-get autoremove -y --purge

清理软件源配置：

vi /etc/apt/sources.list        # 删除 deb.freepbx.org 开头的行
rm -f /etc/apt/trusted.gpg.d/freepbx.gpg
rm -f /etc/apt/preferences.d/99sangoma-fpbx-repository
rm -f /etc/apt/preferences.d/99-block-trixie.pref
apt-get update

清理数据与运行目录（含通话记录库）：

mariadb -e 'drop database if exists asterisk; drop database if exists asteriskcdrdb;'
mariadb -e "drop user if exists 'freepbxuser'@'localhost';"
rm -rf /etc/asterisk /var/lib/asterisk /var/spool/asterisk /var/log/asterisk /var/log/pbx /var/www/html/admin

验证卸载干净：

which fwconsole asterisk

（两条命令均无输出，即已移除）

ss -lntup | grep -E ':(5060|80)\b'

（无 asterisk/apache2 相关监听行，即已移除）

十、参考链接

官方安装脚本仓库：https://github.com/FreePBX/sng_freepbx_debian_install
FreePBX 官网：https://www.freepbx.org/
FreePBX Wiki（模块与配置文档）：https://wiki.freepbx.org/
Asterisk 官方文档：https://docs.asterisk.org/
Sangoma 商业支持：https://www.sangoma.com/
专栏前篇《FreePBX 17 介绍与选型指南》

Debian 12 安装 FreePBX 17 指南

Debian 12 安装 FreePBX 17 指南

一、环境信息

二、前置条件

三、版本选型说明

四、方案 A：官方一键脚本在线安装（推荐）

4.1 方案说明

4.2 下载官方脚本

4.3 执行安装

4.4 脚本参数速查

4.5 安装日志关键节点（实测节选）

4.6 安装结果验证

五、方案 B：Sangoma apt 仓库手动安装

5.1 方案说明

5.2 添加 GPG 密钥与软件源

5.3 安装 Asterisk 22 及组件包

5.4 安装 FreePBX 17 主包并初始化模块

5.5 验证

六、方案对比与选择建议

七、安装后配置说明

7.1 首次登录与初始化向导（创建 admin 账号）

7.2 服务管理与开机自启

7.3 创建分机并验证 SIP 注册

八、常见问题（FAQ）

8.1 脚本启动即失败：版本检查联网被拒

8.2 安装末段报 ****** INSTALLATION FAILED *****：模块在线升级不通

8.3 systemctl is-enabled asterisk 显示 disabled

8.4 sipsak 重复注册报 didn't received '200 OK' on register

8.5 bulkimport 导入的 voicemail 字段不生效

8.6 fwconsole status 报 Command "status" is not defined

九、卸载与清理

十、参考链接

8.2 安装末段报 ** INSTALLATION FAILED *：模块在线升级不通