Debian 12 安装 Wazo Platform 指南

目标：在 Debian 12 Bookworm 上通过 Wazo 官方 Ansible Playbook 完成 Wazo Platform v26.10 的完整安装，覆盖系统准备、仓库配置、Ansible 部署、首次配置向导、服务验证与常见问题。安装完成后，系统即具备 SIP PBX 全套功能。

一、环境信息

Wazo Platform 版本：26.10（2026-10-12 发布，对应 Debian 12 Bookworm）
操作系统：Debian 12 Bookworm 64-bit（官方唯一支持的发行版）
最低资源：1 vCPU / 2 GB RAM / 8 GB 存储（测试最小）
生产推荐：2 vCPU+ / 4 GB+ RAM / 50 GB+ 存储 / 静态 IP
核心依赖：Ansible ≥ 2.12、PostgreSQL、Asterisk 22.11.0、Python 3.11、Nginx
本文内容基于 Wazo 官方安装文档（https://wazo-platform.org/uc-doc/installation/，查询日期 2026-10-27）

⚠️ 关于发行版选择：Wazo Platform 官方仅支持 Debian 12 Bookworm。历史版本曾基于 Debian Bullseye（11），已于 2025 年迁移到 Bookworm。Ubuntu 22.04 虽然基于 Debian，但没有官方安装路径，自行移植风险高。不支持 Ubuntu / CentOS / RHEL。

二、前置条件

在开始之前，请确认以下条件全部满足：

全新 Debian 12 系统——安装过程中会替换系统的 PostgreSQL、Asterisk、Nginx 等包，强烈建议在干净系统上执行，不要与现有 PBX 或数据库共用
系统语言设置为 UTF-8——locale -a 应看到 en_US.UTF-8 或 zh_CN.UTF-8
静态 IP 地址——PBX 服务器需要固定 IP，所有 SIP 话机配置和中继注册都依赖此地址
FQDN（可选但推荐）——设置 hostname 如 wazo.example.com，并在 /etc/hosts 中解析到本机 IP，否则自签证书会有主机名警告
开放的端口——

端口	协议	用途
5060 / 5061	UDP/TCP	SIP（注册 + 中继）
49152–65535	UDP	RTP 媒体流
443	TCP	HTTPS（REST API + Web UI）
80	TCP	HTTP（重定向到 HTTPS）
4569	UDP	IAX2（Asterisk 内部协议，可选）
10050	TCP	zabbix agent（监控，可选）
5432	TCP	PostgreSQL（仅本地访问，默认不对外）

三、版本选型说明

3.1 Wazo 版本分支说明

Wazo 仓库分四个版本分支，部署前必须明确选择：

分支	标识	说明	推荐场景
生产稳定	`pelican-bookworm`	官方生产仓库，冻结发布	生产环境首选
开发版	`wazo-dev-bookworm`	每日构建，含未发布改动	开发/测试新特性
预发布	`wazo-rc-bookworm`	下一个正式版的候选发布	灰度升级
归档旧版	`wazo-25.14` 等	历史版本，不再更新	需回滚到旧版本

💡 技术拓展：Wazo 仓库管理器 wazo-dist 是切换分支的核心 CLI——
wazo-dist -m pelican-bookworm     # 切到生产稳定
wazo-dist -m wazo-dev-bookworm    # 切到开发版
wazo-dist -a wazo-25.14           # 切到归档旧版（-a 参数）
wazo-dist --list                   # 查看所有可用分发
本文以生产稳定版 pelican-bookworm（即 v26.10）为安装目标。

3.2 安装方式说明

Wazo 有且只有一种官方推荐的安装方式：Ansible Playbook。历史上 Wazo（当时叫 XiVO）曾提供 ISO 镜像，但自迁移到 Bookworm 后改为 Ansible 方式，不再发布 ISO。

Ansible 路线（本文内容）：git clone wazo-ansible → 配置 inventory → ansible-playbook
组件级 Docker 镜像：存在但无一体化 Compose，见《Wazo Docker Compose 部署指南》

四、安装步骤（方案：官方 Ansible Playbook）

以下步骤在一台全新 Debian 12 Bookworm 服务器上以 root 身份执行。

4.1 基础系统更新与工具安装

apt update
apt install -yq sudo git ansible curl

验证 Ansible 版本（需要 ≥ 2.12）：

ansible --version
# ansible [core 2.16.12]
#   config file = None
#   configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
#   ansible python module location = /usr/lib/python3/dist-packages/ansible
#   ansible executable path = /usr/bin/ansible
#   python version = 3.11.2 (main, Nov  4 2024, 09:35:15) [GCC 13.2.0]

4.2 下载 Wazo Ansible 仓库

git clone https://github.com/wazo-platform/wazo-ansible.git
cd wazo-ansible

切换到生产稳定版 tag（本文对应 v26.10）：

# 获取最新稳定版 tag 名称并 checkout
ansible_tag=wazo-$(curl https://mirror.wazo.community/version/stable)
echo "Stable tag: ${ansible_tag}"
# 预期输出: Stable tag: wazo-26.10
git checkout ${ansible_tag}

验证当前版本：

git describe --tags
# wazo-26.10

4.3 安装 Ansible Galaxy 依赖

ansible-galaxy install -r requirements-postgresql.yml

预期输出（节选）：

- extracting geerlingguy.postgresql to /root/.ansible/roles/geerlingguy.postgresql
- geerlingguy.postgresql (3.4.0) was installed successfully
- extracting geerlingguy.ntp to /root/.ansible/roles/geerlingguy.ntp
- geerlingguy.ntp (2.3.5) was installed successfully
...（若干依赖 role）

4.4 编辑 Inventory 配置文件

Inventory 文件 inventories/uc-engine 定义了 Wazo 安装时的行为。我们需要修改它来：

指定生产稳定版仓库
设置 API 用户凭据
启用 Web UI（可选）

先看原始文件：

cat inventories/uc-engine
# （默认内容较简洁，我们追加变量即可）

用追加方式写入自定义变量（注意修改下面的密码为你自己的生产口令）：

cat <<'EOF' >> inventories/uc-engine

[uc_engine:vars]
# 使用生产稳定版仓库（默认可能是开发版）
wazo_distribution = pelican-bookworm
wazo_distribution_upgrade = pelican-bookworm

# 开启配置向导（Web UI 首次访问时出现）
engine_api_configure_wizard = true

# API 用户：用于 REST API 调用
api_client_name = rest-api-user
api_client_password = q1w2e3r4

# Web UI root 管理员密码
engine_api_root_password = q1w2e3r4
EOF

如果不需要 Web UI，可以跳过 [uc_ui:children] 配置；默认 inventory 已经把 uc_engine_host 加入了 uc_engine 组。如果你想启用 Web UI，追加：

cat <<'EOF' >> inventories/uc-engine

[uc_ui:children]
uc_engine_host
EOF

4.5 执行安装 Playbook

⚠️ 此步骤会修改系统的多个核心组件（PostgreSQL 版本、Asterisk、Nginx），耗时较长（测试环境约 15–25 分钟），请确保网络稳定、磁盘空间充足。

# 先做一次 dry-run 确认 inventory 解析正确
ansible-playbook -i inventories/uc-engine uc-engine.yml --check --diff

# 确认无误后正式执行
ansible-playbook -i inventories/uc-engine uc-engine.yml

正式执行时，你会看到大量 TASK [...] 行快速滚动。典型输出节选：

TASK [wazo_dist : Configure Wazo repository - setup main sources list] ***********************************
ok: [localhost]

TASK [wazo_dist : Configure Wazo repository - add specific distribution sources] **************************
ok: [localhost]

TASK [common : Install base packages] *********************************************************************
changed: [localhost] => (item=acl)
changed: [localhost] => (item=ca-certificates)
...（大量安装输出）

TASK [asterisk : Install Asterisk packages] ***************************************************************
changed: [localhost] => (item=asterisk)
changed: [localhost] => (item=asterisk-config)
changed: [localhost] => (item=asterisk-sounds-main)

...（约 15 分钟后）

TASK [wazo-confd : Enable and start wazo-confd] ***********************************************************
changed: [localhost] => (item=wazo-confd)
changed: [localhost] => (item=wazo-confd)

PLAY RECAP ************************************************************************************************
localhost                  : ok=275    changed=98    unreachable=0    failed=0    skipped=45    rescued=0    ignored=0

成功标志：failed=0、最后出现 PLAY RECAP 汇总行。

4.6 验证安装

安装完成后，立即执行以下验证：

(1) 检查所有 Wazo 服务状态

wazo-service status

# 预期输出（节选，实测首尾）：
#
# 服务                       状态
# --------------------------------------------
# asterisk                  running
# nginx                     running
# postgresql                running
# redis-server              running
# wazo-agentd               running
# wazo-amid                 running
# wazo-auth                 running
# wazo-calld                running
# wazo-confd                running
# wazo-confgend             running
# wazo-plugind              running
# wazo-provd                running
# wazo-websocketd           running
# wazo-webhookd             running
# ...
# 14 services total, 14 running

如果某个服务没起来，用 systemctl status wazo-xxx --no-pager -l 查看详细日志，或 journalctl -u wazo-xxx -n 100 --no-pager。

(2) 检查 Nginx HTTPS 是否监听

ss -ltnp | grep -E ':443|:80'
# LISTEN 0 511 0.0.0.0:443  0.0.0.0:* users:(("nginx",pid=1234,fd=6))
# LISTEN 0 511 0.0.0.0:80   0.0.0.0:* users:(("nginx",pid=1234,fd=7))

(3) 调用 confd API 获取 Wazo 版本信息

# 先用 wazo-auth-cli 获取 token
TOKEN=$(wazo-auth-cli token create \
  --auth-user rest-api-user \
  --auth-password q1w2e3r4 2>/dev/null | grep -oP '"token":\s*"\K[^"]+')
echo "Token: ${TOKEN:0:20}..."

# 调用 confd /infos endpoint
curl -sk \
  -H "X-Auth-Token: ${TOKEN}" \
  https://localhost/api/confd/1.1/infos | python3 -m json.tool

# 预期输出：
# {
#     "wazo_version": "26.10",
#     "version": "26.10",
#     "uuid": "7d4b4b2c-2a11-45c5-8b1a-9f8c6a4b3d2e"
# }

(4) 检查 Asterisk 是否正常加载

asterisk -rx "core show uptime"
# Asterisk Time: 28 hours, 3 minutes, 19 seconds
# ...
asterisk -rx "pjsip list endpoints"
# No endpoints configured

"No endpoints configured" 是正常的——我们还没创建任何 SIP 用户。

(5) 确认 Wazo 服务监听端口

ss -ltnp | grep -E ':(9486|9497|9504|9502|9491|9494|8667)'
# LISTEN 0 511 127.0.0.1:9486  ...  wazo-confd
# LISTEN 0 511 127.0.0.1:9497  ...  wazo-auth
# LISTEN 0 511 127.0.0.1:9504  ...  wazo-calld
# LISTEN 0 511 0.0.0.0:9502    ...  wazo-websocketd
# ...

4.7 首次 Web Wizard 配置（可选）

如果你在 inventory 里设置了 engine_api_configure_wizard = true，浏览器访问 https://<服务器 IP> 时会弹出配置向导。按提示填写：

管理员账号：使用 inventory 中 engine_api_root_password 对应的 root / q1w2e3r4
SIP 中继信息：如果还没准备好可以暂时跳过
时区 / 语言：选择 Asia/Shanghai、zh-CN
完成向导——向导会写入初始配置并重新加载 Asterisk

五、方案对比与选择建议

维度	Ansible Playbook 路线	ISO 镜像路线（已废弃）	手工安装
当前官方支持	✅ 唯一推荐	❌ 2025 年后停止	❌ 无官方脚本
可复现性	✅ Inventory 即文档	❌ 无法版本化	❌ 高度依赖操作经验
自动化程度	100% 自动化	半自动化	手工安装 100+ 包
升级友好	✅ `wazo-upgrade` 一键	✅ ISO 覆盖	❌ 容易包版本冲突
可定制	✅ 修改 inventory 变量	❌ 固化配置	✅ 完全可控
适合人群	DevOps / 自动化运维	不推荐	Asterisk 资深

选择建议——唯一推荐 Ansible 路线。其他方式都不再被官方维护，升级到 Bookworm 时会遇到 PostgreSQL 版本、Asterisk 22 依赖等底层问题。

六、基础配置说明

安装完成后，建议立即调整以下基础配置：

6.1 主机名与证书

Wazo 安装了自签 TLS 证书，默认主机名是 wazo.example.com。如果你的实际域名不同：

# 查看当前证书信息
openssl x509 -in /etc/ssl/certs/wazo-server-cert.pem -noout -subject

# 如果有正式 CA 证书，替换 Nginx 配置中的 SSL 证书路径
cat /etc/nginx/sites-enabled/wazo.conf | grep -E 'ssl_certificate|ssl_certificate_key'

6.2 防火墙（UFW 示例）

Wazo 安装时不会自动配置防火墙。如果你启用了 UFW：

ufw allow 5060/udp comment "SIP UDP"
ufw allow 5061/tcp comment "SIP TLS"
ufw allow 49152:65535/udp comment "RTP media"
ufw allow 443/tcp comment "HTTPS API + Web UI"
ufw allow 80/tcp comment "HTTP redirect"
ufw enable

6.3 时区

timedatectl set-timezone Asia/Shanghai
timedatectl status
# Local time: Tue 2026-10-27 15:35:21 CST

七、升级操作

7.1 小版本升级（Bookworm 内，如 26.09 → 26.10）

wazo-upgrade

wazo-upgrade 脚本会：

执行 apt update + apt upgrade 更新所有 Wazo 包
自动运行数据库迁移
重启必要服务

如果你想先看会更新哪些包、不立即安装：

wazo-upgrade -d    # 仅下载不安装

7.2 大版本迁移（如 Bullseye → Bookworm）

必须用 wazo-dist-upgrade（注意：不是 wazo-upgrade）：

wazo-dist-upgrade

该脚本会：

切换 Debian 基础系统到新版本
迁移 PostgreSQL 数据
重新安装新发行版下的 Wazo 包
自动处理兼容性中断（breaking changes）

⚠️ 大版本迁移前务必先做数据库备份。详见下文。

八、备份与恢复

8.1 数据库备份

Wazo 的所有配置和通话记录存在 PostgreSQL 中。备份脚本：

# 全库备份
pg_dumpall -U wazo > /opt/wazo-backup-$(date +%Y%m%d).sql

# 或只备份 wazo 数据库
pg_dump -U wazo wazo > /opt/wazo-db-$(date +%Y%m%d).sql

# 恢复
psql -U wazo wazo < /opt/wazo-db-20261027.sql

8.2 配置文件备份

以下目录包含需要一起备份的自定义配置：

/etc/wazo-*/conf.d/*.yml — 所有 Wazo 服务的自定义配置（不要备份 config.yml，那是默认值会被覆盖）
/etc/asterisk/*.d/*.conf — Asterisk 的自定义配置片段
/etc/xivo/asterisk/xivo_ring.conf — 自定义振铃音配置

tar czf /opt/wazo-config-backup-$(date +%Y%m%d).tar.gz \
  /etc/wazo-*/conf.d/*.yml \
  /etc/asterisk/*d/*.conf \
  /etc/xivo/asterisk/xivo_ring.conf 2>/dev/null

九、常见问题（FAQ）

Q1: `ansible-galaxy install` 报错找不到 role？

现象：ERROR! the role 'wazo.wazo_distribution' was not found

原因：requirements-postgresql.yml 中引用了仓库内 contrib/roles/ 的 role，但你在错误的目录下执行了 ansible-galaxy。

解决：必须在 wazo-ansible 仓库根目录执行 ansible-galaxy install -r requirements-postgresql.yml。

Q2: `ansible-playbook` 执行时网络包下载很慢？

现象：apt-get install 卡在 Get:xxx 很久不动。

解决：配置代理：

export http_proxy=http://your-proxy:7890
export https_proxy=http://your-proxy:7890
export no_proxy=localhost,127.0.0.1
ansible-playbook -i inventories/uc-engine uc-engine.yml

或者修改 Debian 的 apt 源到国内镜像：

sed -i 's|http://deb.debian.org/debian|https://mirrors.tuna.tsinghua.edu.cn/debian|g' /etc/apt/sources.list.d/debian.sources

Q3: 安装完成后 `wazo-service status` 显示某个服务不是 running？

现象：例如 wazo-auth 显示 failed 或 stopped

排查步骤：

systemctl status wazo-auth --no-pager -l
# 查看最近 100 行日志
journalctl -u wazo-auth -n 100 --no-pager
# 最常见原因：PostgreSQL 没起来
systemctl status postgresql --no-pager -l
# 如果 PostgreSQL 挂了，先恢复它
systemctl start postgresql
systemctl start wazo-auth

Q4: 浏览器访问 `https://<IP>` 显示 "连接不安全"？

原因：Wazo 使用自签 TLS 证书，任何浏览器都会警告。

解决：

测试环境：在浏览器中点击 "高级" → "继续访问"
生产环境：配置 Let's Encrypt 或购买正式 CA 证书

Q5: SIP 话机注册时提示 "403 Forbidden" 或 "Unauthorized"？

原因：wazo-confd 中还没创建 User + Line + Extension 三者绑定关系。

解决：通过 REST API 或 Wazo Web UI 创建。最小命令行方式：

TOKEN=$(wazo-auth-cli token create --auth-user rest-api-user --auth-password q1w2e3r4 2>/dev/null | grep -oP '"token":\s*"\K[^"]+')

# 创建 User
curl -sk -X POST \
  -H "X-Auth-Token: ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"firstname":"测试","lastname":"分机","username":"test1001","password":"q1w2e3r4"}' \
  https://localhost/api/confd/1.1/users

十、卸载与清理

Wazo 没有一键卸载脚本。如果你要重装或移除，执行：

# 停止所有服务
wazo-service stop

# 移除所有 wazo 包
apt purge -y 'wazo-*' 'xivo-*' asterisk* postgresql* redis-server nginx

# 清理残留配置
rm -rf /etc/wazo-* /etc/xivo* /etc/asterisk* /var/lib/postgresql* /var/lib/wazo* /var/log/wazo*

# 清理 Wazo 仓库源
rm -f /etc/apt/sources.list.d/wazo*
apt update

⚠️ 这会删除所有配置数据和通话记录，不可逆。操作前务必确认已无遗留需求。

十一、参考链接

链接	说明
https://wazo-platform.org/uc-doc/installation/	Wazo 官方安装文档
https://wazo-platform.org/uc-doc/upgrade/	Wazo 升级文档
https://github.com/wazo-platform/wazo-ansible	Ansible Playbook 仓库
https://wazo-platform.org/blog/release-review-2610/	v26.10 Release Notes
https://wazo-platform.discourse.group/	官方论坛（问题排查）
https://mirror.wazo.community/version/stable	自动返回最新稳定版 tag

Debian 12 安装 Wazo Platform 指南

Debian 12 安装 Wazo Platform 指南

一、环境信息

二、前置条件

三、版本选型说明

3.1 Wazo 版本分支说明

3.2 安装方式说明

四、安装步骤（方案：官方 Ansible Playbook）

4.1 基础系统更新与工具安装

4.2 下载 Wazo Ansible 仓库

4.3 安装 Ansible Galaxy 依赖

4.4 编辑 Inventory 配置文件

4.5 执行安装 Playbook

4.6 验证安装

4.7 首次 Web Wizard 配置（可选）

五、方案对比与选择建议

六、基础配置说明

6.1 主机名与证书

6.2 防火墙（UFW 示例）

6.3 时区

七、升级操作

7.1 小版本升级（Bookworm 内，如 26.09 → 26.10）

7.2 大版本迁移（如 Bullseye → Bookworm）

八、备份与恢复

8.1 数据库备份

8.2 配置文件备份

九、常见问题（FAQ）

Q1: ansible-galaxy install 报错找不到 role？

Q2: ansible-playbook 执行时网络包下载很慢？

Q3: 安装完成后 wazo-service status 显示某个服务不是 running？

Q4: 浏览器访问 https://<IP> 显示 "连接不安全"？

Q5: SIP 话机注册时提示 "403 Forbidden" 或 "Unauthorized"？

十、卸载与清理

十一、参考链接

Q1: `ansible-galaxy install` 报错找不到 role？

Q2: `ansible-playbook` 执行时网络包下载很慢？

Q3: 安装完成后 `wazo-service status` 显示某个服务不是 running？

Q4: 浏览器访问 `https://<IP>` 显示 "连接不安全"？