分机管理

分机（Extension）是 RustPBX 中连接坐席、终端或机器人实例的核心对象。本节介绍如何创建、批量维护与保护分机。

1. 分机模型

基础字段：号码、显示名称、所属部门、SIP 密码/证书。
策略字段：并发限制、呼出权限、媒体参数（DTMF、RTP 端口、编解码）。
关联对象：可绑定队列、计费模板、频率限制（models/frequency_limit.rs）。

2. 新建分机

打开控制台「Extensions → 创建」。
填写基本信息，并选择认证方式：
- 密码认证：系统生成或手动输入强密码。
- 证书认证：与 WebRTC 客户端配合使用。
配置呼叫权限：可启用黑白名单、国际/国内拨号策略。
保存后，下载或复制配置给坐席设备。

文件/脚本方式

若需批量导入，可使用 API 或在数据库层按 models/extension.rs 结构写入，并触发缓存刷新。

3. 注册与设备

SIP 软终端：输入服务器地址、分机号、密码，启用 TLS/SRTP 时需导入证书。
JWT 方式注册：分机可以不使用 SIP 密码，通过在 X-Auth-Token SIP 头或 WebSocket ?token= 查询参数中携带 JWT 令牌完成注册。详见第 5 节。
硬件话机：通过 Auto Provision 模板或手工配置，建议限制 IP 范围。
WebRTC 客户端：使用 static/phone_jssip.html 或 phone_sipjs.html 示例，依靠浏览器与 PBX 建立安全通道。

遇忙插叫（Busy-wait / Camp-on）

0.5 起，指向本地分机的 forward 路由可以携带 [busy_wait] 表。当分机以 486 Busy 拒接时，主叫被驻留并循环播放等待音（183 early media），同时每隔 retry_interval_secs 重新拨打该分机，直到其空闲（接通）或 max_wait_secs 超时。主叫挂断或非忙类失败会立即退出等待。

# 在指向本地分机的 forward 路由中
[busy_wait]
enabled = true
max_wait_secs = 120        # 0 = 无限等待
retry_interval_secs = 15
hold_audio = "sounds/hold-music.wav"   # 文件路径或 http(s) URL

适用于总机线路和内部服务台等场景——让主叫选择等待,而不是在语音信箱里来回折腾。

4. 分机生命周期钩子

自 v0.4.10 起，插件可通过 Addon::on_extension_created、on_extension_updated 和 on_extension_deleting 方法接入分机生命周期事件。这些钩子在通过控制台、API 或 CSV 导入修改分机时自动执行。

事件	触发时机	常见用途
`on_extension_created`	分机记录插入数据库后	自动创建语音信箱、添加默认队列成员
`on_extension_updated`	分机记录更新后	同步语音信箱 PIN/邮箱变更、更新终端配置
`on_extension_deleting`	分机记录删除前	清理语音信箱和录音、移除队列绑定

语音信箱插件示例：启用语音信箱插件（addon-voicemail）后，创建分机会自动创建对应的语音信箱，删除分机会自动删除信箱和录音。插件钩子中的错误仅记录日志，不会阻塞分机操作。

5. JWT 认证

当 [proxy.jwt_auth].enabled = true 时，代理会检查 X-Auth-Token SIP 头中的 JWT（或 WebSocket 上的 ?token= 参数）。如果 JWT 有效且 user_id_claim 与分机号匹配，注册将直接通过，无需 Digest 质询。

JWT 认证还支持预认证注册表：通过 JWT 认证后，代理会存储一个短期绑定，后续的对话内请求（BYE、re-INVITE、ACK）可快速通过，无需重新校验。对于 WebSocket 客户端，将 token 作为查询参数传入：wss://<host>:<ws_port>/ws?token=<jwt> JWT 注册适用于语音代理、自动拨号器和基于浏览器的 WebRTC 软电话等场景。

6. 安全与限额

频率限制：在 models/frequency_limit.rs 中定义规则，通过控制台关联到分机，防止暴力呼叫。
ACL：结合 config/acl/，控制分机可访问的 IP/网段。
登录告警：在 Diagnostics 中开启登录失败告警，异常增多时自动封锁源 IP。

7. 运维动作

任务	建议做法
密码轮换	每季度批量重置一次，可使用 API 脚本自动化
状态检查	Diagnostics → SIP 注册面板，筛选长期离线的分机
批量升级	借助设备厂商的 Provision 服务器，修改模板后让终端自动重启获取配置
停用/离职	在分机详情中一键禁用，必要时撤销队列/技能组绑定

8. 常见问题

注册不上：检查密码、SIP 代理端口、设备时间与 TLS 证书；或是否被 ACL 拦截。
呼叫失败：确认路由动作中已允许该分机呼出；检查频率限制是否触发。
音质差：调低编解码复杂度，或在分机侧开启 QoS；必要时切换媒体服务器区域。

通过以上实践可以确保分机安全可控，并与路由/队列协同工作。