将 VitalPBX 连接到 IllyVoIP：PJSIP 中继与呼叫路由
配置 VitalPBX PJSIP 中继、呼入和呼出路由、主叫号码及音频设置，并按连接阶段排查问题。
本指南采用 VitalPBX 4/4.5 的 PJSIP 配置流程，依据于 2026 年 10 月 7 日核查的官方文档。不同版本的菜单名称可能不同。本文适用于已安装的 PBX，使用 IllyVoIP 密码认证；系统安装、改用 IP 认证以及紧急呼叫需要另行规划。
中继注册只建立 PBX 与 IllyVoIP 之间的连接。要正常通话，还需要分机有权使用的呼出路由，以及企业号码对应的呼入路由。请分别检查这三个阶段，避免因为路由问题而反复修改本来正确的密码。
开始前的准备
请准备 PBX 管理员权限、妥善保管的配置备份、一个正常工作的内部分机，以及使用 IllyVoIP 账户的授权。配置新线路时，应保留办公室原有路由。实际测试前，检查余额、目的地费率及线路或套餐限制：测试电话也可能产生费用。仅注册中继不需要购买号码；接听公网来电则需要一个已启用并指向该中继的号码。
1. 获取 IllyVoIP 连接参数
在 Portal 中打开 SIP Lines，选择要使用的线路，获取 SIP 用户名、SIP 密码、服务器主机名、目标端口和传输方式。这些不是 Portal 登录邮箱和密码。如果线路采用 IP 认证，请改为遵循该连接的说明；启用注册或更改认证方式可能中断现有设备。
使用账户提供的实际参数。不要从其他人的教程中复制服务器、密码、端口或其他运营商专用的 SIP 头字段。将凭据保存在私密的密码管理器中，不要放进截图或公开的求助帖子。
2. 在 VitalPBX 中创建 PJSIP 中继
在 VitalPBX 中打开 PBX → Calls Routing → Trunks。选择 PJSIP，并填写易于识别的 Description，例如 IllyVoIP。保持中继启用。在 General 部分配置远端连接，在 Outbound Registration Settings 中配置注册。这里的 PJSIP 是 Asterisk 通道驱动名称；IllyVoIP 连接仍然使用 SIP 协议。
| VitalPBX 字段 | 应填写或核对的内容 |
|---|---|
| Description | 本地名称，例如 IllyVoIP；不是认证用户名。 |
| Remote Host / Remote Port | IllyVoIP 连接提供的 SIP 服务器及目标端口。 |
| Remote Username / Remote Secret | 线路的 SIP 用户名和 SIP 密码。 |
| Require Registration | 本指南使用密码注册方式，应启用此选项。 |
| Transport | 与提供的 SIP 传输方式一致。使用 TLS 时应填写主机名，并正确验证证书。 |
| Local Username / Local Secret | 本地一侧的身份或认证字段，不要与远端凭据混淆。 |
| Contacts / Match / From Domain | 取决于连接要求的高级字段。仅采用已核实的参数，不要猜测 IP、填写过宽的匹配范围或照搬其他运营商配置。 |
不需要的高级选项保持不变。如果连接需要额外身份参数或呼入来源设置，先向 IllyVoIP 支持人员确认。检查输入后执行 Save 和 Apply Changes。中继名称、认证用户名和向对方显示的主叫号码用途不同，不能互相替代。
3. 配置通话前先检查注册
查看 Reports → PBX Reports → PJSIP Endpoints → Trunks。端点能回应可达性探测，不代表对外注册已成功。有授权 CLI 访问权限的管理员也可查看 pjsip show registrations。这是只读诊断，不要求修改界面生成的 Asterisk 配置文件。分机注册和中继注册需要分别确认。
收到认证质询后成功完成认证，可能是正常流程。反复认证失败、注册被拒或超时则需要排查。先核对用户名、密码、线路认证方式、DNS、目标端口和传输方式。避免快速反复重试或不断重置密码，也不要为了排查输错的凭据而扩大防火墙访问范围。
4. 创建访问受控的呼出路由
打开 PBX → Calls Routing → Outbound Routes，填写清晰的描述并选择 IllyVoIP 中继。先使用仅匹配自有测试目的地的严格号码规则，并通过相应的 Class of Service 和路由权限只允许测试分机使用。检查路由优先级及中继顺序，防止测试不知不觉经由其他运营商完成。
Pattern 匹配拨出的数字。Prefix 用于移除外线接入前缀，Prepend 则在号码发送前添加数字。例如员工额外拨 9 获取外线时，只应移除这一个接入数字，它不是国家代码的一部分。如果用户已经拨了国家代码，就不要再次添加。检查实际发送给 IllyVoIP 的最终号码，并使用该连接要求的国际号码格式。配置阶段不要启用不受限制的全匹配规则。
5. 配置 IllyVoIP 号码的呼入路由
先在 IllyVoIP 中把有效号码指向这台 PBX 使用的 SIP 线路，再到 VitalPBX 打开 PBX → Calls Routing → Inbound Routes。选择 Default，命名路由，并在 DID Pattern 中填写预期收到的被叫号码。在 Inbound Destination 中选择已确认正常工作的分机。除非有意限制来电者，否则将 CID Pattern 留空。
DID 是被拨打的号码，CID 是来电者的身份。DID 规则必须匹配实际收到的格式，包括是否有加号或其他标识。如果与预期不同，应先检查呼入信息，再考虑改变头字段提取或添加全匹配路由。两个规则都留空会形成 Any/Any 路由。测试分机正常响铃后，再添加需要的振铃组、队列、IVR 或时间表。不要让未匹配的公网来电获得无限制的外呼权限。
6. 核对主叫号码、音频与网络设置
选择 IllyVoIP 线路和套餐允许使用的主叫号码。VitalPBX 可以在分机、路由或中继层覆盖号码；配置时应避免互相冲突的覆盖设置。在 Trunk CID 中输入号码，并不会验证号码所有权或授予显示权限。注册成功也不意味着余额足够、目的地已开放或仍有空闲并发容量。
PBX 的媒体模式应与 SIP 线路一致：Standard RTP 不加密；SDES-SRTP 与 DTLS-SRTP 是不同的加密模式。TLS 保护 SIP 信令，不会自动启用音频加密。选择双方都支持的编解码器和 DTMF 方式。不要仅因为 IllyVoIP Webphone 使用某项设置，就给 PBX 选择面向浏览器的配置。
如果 PBX 位于 NAT 后，按已安装的 VitalPBX 版本核对外部地址、本地网络和实际 RTP 配置。单向音频通常需要独立于注册状态检查媒体路径。保持防火墙启用，只开放必要且已核实的来源和端口。公网 IP 或路由器变化后，应重新检查 NAT 和 IP 限制，而不是随意改动凭据。
按故障阶段排查
| 现象 | 优先检查 |
|---|---|
| 中继无法注册 | 远端凭据、认证方式、主机名解析、端口、传输方式及准确的响应信息。 |
| 已注册，但呼叫没有离开 PBX | 拨号规则、分机权限、路由优先级和所选中继。 |
| IllyVoIP 拒绝呼出 | 最终目的地格式、允许的主叫号码、余额、套餐权限、容量及记录的 SIP 响应。 |
| 拨打号码后没有电话响铃 | IllyVoIP 号码与线路的对应关系、收到的 DID、呼入目标、时间表及分机状态。 |
| 呼叫接通但无声或只有单向声音 | RTP 可达性、NAT、协商的编解码器以及线路与 PBX 的媒体加密是否匹配。 |
| 电话菜单无法识别按键 | 电话、PBX 和中继之间协商的 DTMF 方式；使用自己可控的菜单测试。 |
团队开始使用前的检查
确认注册后，进行一次获授权的呼出测试，并从外部拨打自己的号码。检查实际使用的中继、双向声音、显示的主叫号码、按键和正常挂断。确认没有权限的分机无法使用新呼出路由，然后再向计划中的用户和目的地开放。
某项检查失败时，一次只改一个设置，并保存原值。联系支持人员时，提供 PBX 版本、时间和时区、呼叫方向、去除隐私信息的错误提示，以及 Portal 中可用的公开呼叫参考编号。不要公开 SIP 密码或未经处理的账户日志。本文已与官方文档和 Portal 行为核对，但不代表通过真实 VitalPBX 通话完成了兼容性认证。紧急呼叫、传真及其他特殊用途仍需单独验证。