Wazo 介绍与选型指南

目标：为首次接触 Wazo Platform 的用户提供一份完整的软件认知地图——它是什么、能做什么、架构如何、适合谁、与主流 PBX 方案如何选型对比。本文内容基于 Wazo Platform 官方文档与 GitHub 仓库实查（查询日期 2026-10-27），所有版本号、特性清单以 v26.10 为准。

一、环境信息

• 文档撰写日期：2026-10-27
• Wazo Platform 最新稳定版：26.10（2026-10-12 发布，对应 Debian 12 Bookworm，Asterisk 22.11.0）
• Wazo 上游基础：Asterisk（Digium 开源软交换框架）
• 官方文档站：https://wazo-platform.org/uc-doc/
• GitHub 组织：wazo-platform（多仓库微服务形态）
• 开源协议：GPL 3.0（各子服务一致）

二、软件概述

Wazo Platform 是一套完整的开源统一通信（UC）解决方案，基于 Asterisk 构建，把 PBX（电话交换）、会议、即时消息、录音、队列、IVR、CTI 等功能打包成一个可通过 REST API 编排的微服务系统。Wazo 项目起源于法国电信公司 XiVO Solutions 的开源 PBX 产品 XiVO（2015 年前后更名开源），目前由 Wazo Platform 社区维护，是少数几个能与 FreePBX、Issabel、Elastix 比肩的全功能开源 UC 平台。

Wazo 的核心定位不是「一个 PBX 软件」，而是「一套可程序控制的 UC 中间件」：它以微服务架构把 Asterisk 封装成一组可独立部署的后端进程，每个进程暴露 REST API，管理员通过 wazo-confd（配置管理）、wazo-auth（认证）、wazo-websocketd（实时事件推送）、wazo-amid（Asterisk 管理器接口桥接）、wazo-provd（话机自动配置）等服务协同工作，Web 管理界面（Wazo Web Desktop）本身就是这些 API 的前端。

💡 技术拓展：PBX（Private Branch Exchange，专用分支交换机）的实现路线并非 Wazo 一家——

路线	代表产品	特点
Asterisk 纯手工	直接写 Asterisk dialplan	极致灵活、纯文本配置、无图形界面、维护成本高
Asterisk + Web 管理	FreePBX / Issabel / Elastix	图形界面成熟、社区大、但核心配置被 Web 工具接管，难与自动化集成
Asterisk + 微服务 API	Wazo Platform / 3CX（商业）	把 PBX 后端微服务化、REST API 驱动、可编程集成最佳
非 Asterisk 路线	FreeSWITCH / FusionPBX / Jami	不同底层、协议覆盖不同、生态大小差异大
商业 UC 全套	Cisco UCM / Avaya / Mitel	封闭、高成本、企业级 SLA

本文聚焦的是「Asterisk + 微服务 API」路线的代表——Wazo Platform。

三、核心架构

Wazo Platform 采用微服务架构，各组件以 systemd 服务独立运行，通过 PostgreSQL 共享配置数据、通过 RabbitMQ（可选的事件总线）和内部 HTTP 调用协同。

3.1 整体拓扑

[ Web 浏览器 / wazo-cli / 第三方应用 ]
            │ HTTPS :443 (Nginx 反代)
            ▼
        ┌───────────┐
        │  Nginx     │  ← 统一反向代理，内部服务默认也经由 Nginx 访问
        └─────┬─────┘
              │
      ┌───────┼─────────────────────────────────┐
      ▼       ▼                 ▼                ▼
┌────────┐┌──────────┐  ┌───────────────┐  ┌──────────────┐
│wazo-   ││wazo-auth │  │wazo-confd     │  │wazo-calld    │
│plagind ││ :9497    │  │ :9486         │  │ :9504        │
└────────┘└────┬─────┘  └──────┬────────┘  └──────┬───────┘
               │               │                   │
        ┌──────┴───────┐       │            ┌──────┴──────┐
        ▼              ▼       ▼            ▼             ▼
   ┌─────────┐  ┌────────────┐  ┌───────────┐  ┌─────────┐
   │Postgres │  │wazo-websocketd││wazo-amid  │  │wazo-    │
   │ :5432   │  │ :9502      │  │ :9491     │  │provd    │
   └─────────┘  └──────┬─────┘  └─────┬─────┘  └────┬────┘
                       │              │              │
                       ▼              ▼              ▼
                ┌──────────────────────────────────────┐
                │        Asterisk 22.11.0              │
                │        (PJSIP / dialplan / RTP)      │
                └──────────────────────────────────────┘
                                    │
                                    ▼
                              [话机 / SIP 中继 / PSTN]

3.2 关键组件职责速查

3.3 技术栈全景

• 语言：Python 3.11（绝大多数后端服务）+ Go（部分工具）+ JavaScript/TypeScript（Wazo Web Desktop 前端）
• 语音引擎：Asterisk 22.11.0（SIP 协议栈 PJSIP，媒体传输 RTP）
• 后端框架：Flask + Connexion（REST API 自动从 OpenAPI YAML 生成）
• 数据库：PostgreSQL（配置数据、用户、通话记录 CDR）
• 反向代理：Nginx（生产环境统一 HTTPS 入口，路径反代到各服务）
• 部署形态：官方推荐 Ansible Playbook（Debian 12 Bookworm），组件级 Docker 镜像存在但无一体化官方 Compose
• 系统托管：所有服务通过 systemd 管理

四、功能特性

4.1 核心 UC 功能矩阵

4.2 API 可编程性亮点

Wazo 的一个独特优势是几乎所有功能都可通过 REST API 编程：

• CRUD 一致性：创建一个用户 = POST /users，关联分机 = POST /users/{uuid}/lines/{uuid}，不需要手工改 Asterisk 配置文件
• 配置即时生效：修改通过 wazo-confgend 生成新的 Asterisk 配置并自动触发 dialplan reload / pjsip reload，不需手动重启 Asterisk
• 事件驱动集成：wazo-websocketd 和 wazo-amid 可以把 PBX 事件（来电振铃、接通、挂机、录音完成）实时推送到自建应用
• WebSocket 认证回调：支持第三方 Web 应用实现"点击拨出"（Click-to-Dial）

4.3 社区与生态

• Discourse 论坛：https://wazo-platform.discourse.group/ （英文社区活跃，法语次之）
• Mattermost：https://mm.wazo.community/ （实时开发讨论）
• 插件生态：wazo-plugind 管理的插件仓库（https://plugins.wazo.community/），覆盖话机品牌、集成场景、管理辅助工具
• 商业支持：XiVO Solutions（原公司名，现品牌 XiVO）仍提供商业版托管和付费支持
• 开源 SDK：Python SDK wazo-sdk，方便程序化集成

五、快速开始（最小可用示例）

⚠️ 以下步骤说明"Wazo 能做什么"，具体安装流程参见 《Debian 12 安装 Wazo Platform 指南》。本节以说明性命令为主，不执行实测。

Wazo 的最小可用链路是：创建 API 用户 → 获取 token → 通过 confd REST API 创建用户+分机 → 话机注册 SIP → 拨打电话。

第一步：创建 REST API 用户（通过 Wazo Web Wizard 或 confd API）

# 方式一：安装向导中直接创建
# 编辑 inventories/uc-engine 文件：
cat <<'EOF' >> inventories/uc-engine
[uc_engine:vars]
engine_api_configure_wizard = true
engine_api_root_password = q1w2e3r4
api_client_name = rest-api-user
api_client_password = q1w2e3r4
EOF

第二步：获取认证 token

# 本地用 wazo-auth-cli
wazo-auth-cli token create --auth-user rest-api-user --auth-password q1w2e3r4

# 或远程用 curl（把 wazo.example.com 换成你的 Wazo 地址）
curl -k -X POST \
  -u rest-api-user:q1w2e3r4 \
  -H 'Content-Type: application/json' \
  -d '{"expiration": 3600}' \
  https://wazo.example.com/api/auth/0.1/token

# 响应（节选）：
# {"data": {"expires_at": "2026-10-28T02:45:00+08:00", "token": "eyJhbGciOi...xxxxx"}}

第三步：通过 confd 创建一个 SIP 用户

export TOKEN="上一步返回的 token 值"
curl -k -X POST \
  -H "X-Auth-Token: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "张三",
    "lastname": "技术部",
    "username": "zhangsan",
    "password": "q1w2e3r4"
  }' \
  https://wazo.example.com/api/confd/1.1/users

# 响应返回 user uuid，后续给用户绑定 SIP line 和 extension

六、适用场景与限制

6.1 典型适用场景

6.2 使用限制与已知坑

• 官方仅支持 Debian 12 Bookworm：其他发行版（Ubuntu/CentOS/RHEL）没有官方安装路径，自行移植风险高
• 资源门槛：Asterisk + PostgreSQL + 多个 Python 微服务，测试最小 2GB 内存，生产 4GB+
• 无一体化 Docker Compose：社区有组件镜像但无官方生产 Compose 栈，自己拼装需要理解各服务依赖
• SIP NAT：企业内网部署对接公网 SIP 中继时，需要正确配置 externaddr、localnet、nat 等 PJSIP 参数
• Asterisk 模块自动管理：Wazo 自动生成 modules.conf，手工编辑会被覆盖，启用新模块需要通过 wazo-confgend 配置
• Wazo Web Desktop 闭源：前端界面（Wazo Web & Desktop）是商业产品的免费版本，核心后端服务开源；纯开源栈可以不用 Web UI 完全靠 API

七、同类选型对比

7.1 主要竞品对比表（2026-10-27 查询）

选型建议——

• 要图形化 IVR 设计器 / 不想碰命令行：选 FreePBX 或 Issabel
• 要 REST API + WebSocket 驱动的可编程 UC 中间件、要跟 CRM / 自研应用深度集成：选 Wazo
• 预算充足、需要商业 SLA、Windows 环境：选 3CX
• 倾向 FreeSWITCH 生态：选 FusionPBX

7.2 Wazo 独特优势总结

1. 微服务架构天然适合可编程：wazo-confd 不是 Asterisk 配置的 Web 壳——它是一个完整的配置数据库 API，配置数据通过 confgend 转换成 Asterisk 配置文件。这意味着你可以构建"CRM 来电弹屏自动创建临时 IVR""排队 30 秒未接通自动切到外部坐席""AI 语音助手拦截骚扰电话"这类 Wazo 之外的应用
2. wazo-auth + ACL 权限模型：每个 REST API 调用必须 token 认证 + ACL 白名单。可以创建"只能读 queue 状态"的 token 给大屏应用，创建"只能修改自己的 voicemail"的 token 给自助门户
3. WebSocket 实时事件：wazo-websocketd 提供 Wazo 独有的实时事件推送——来电振铃、坐席 Ready/Busy、录音完成、IVR 按键事件。这是构建桌面通知、手机 App、运维大屏的基础
4. Python 栈 = 好维护：绝大多数服务是 Python Flask + Connexion，懂 Python 的团队可以轻松二次开发；而 FreePBX 是 PHP + 大量 amportal shell 脚本，可维护性相对弱

7.3 Wazo 劣势总结

1. 学习曲线陡：wazo-confd 的 REST API 有 50+ 资源端点（users、lines、extensions、trunks、pjsip、incalls、outcalls、queues、groups、voicemails、meetings、agents、funckeys、contact_directories...），要搞懂三者绑定关系（User ↔ Line ↔ Extension）需要时间
2. 官方仅 Debian 12：Ubuntu 22.04 无法用官方 Ansible 直接部署，需自行移植
3. 容器化不完整：没有官方一体化 Docker Compose，测试需要跑完整 Ansible Playbook
4. SIP NAT 排障复杂：企业内网部署时，PJSIP 的 NAT 参数（externaddr、localnet、endpoint 级 nat 策略）配置错误会表现为"能振铃但听不到声音""单向音频"等经典 SIP NAT 症状

八、参考链接