XSwitch用户手册

基本概念

本章描述XSwitch系统中的基本概念和设计原则。

用户及组织架构

  • 用户指一个人,属性有用户名、密码、电子邮件、手机号等,可以登录Web系统。
  • 用户名只可以是字母与数字的组合,区分大小写,除“-_.”外不能有特殊符号。
  • 组织架构对应公司的组织架构。
  • 组织架构可以级连。
  • 组织架构与用户是一对多关系,比如一个部门有个多个用户,但一个用户只属于一个部门。
  • 用户组是一组用户。
  • 用户组与用户是多对多关系,即一个用户可以属于多个组。
  • 用户与分机是一对多关系,即一个用户可以有多个分机。
  • 用户可以在呼叫中心中作为座席使用,可以把工号当做用户名和登录名。
  • 只有用户可以登录Web系统,根据设置,可以使用用户名、电子邮件、分机号、手机号等登录系统。
  • 在API调用时,为避免每次都使用密码调用,可以使用Token,或者开发Key调用。
  • 系统默认有两个特殊用户:
    • ID为0system用户,没有任何权限,不能登录系统,不能被删除。当对应不到真人的时候可以使用它,如不属于任何人的分机号,可以关联到该用户。
    • ID为1admin用户,该用户是最高级的管理员,在简单的场景中可以使用,在复杂的权限管理下,每个管理员都应该使用自己的账号登录。

实际上,为了使系统保持简单,我们淡化了用户的使用。在最小最简的应用中,您可以只有一个admin用户,但它下面可以挂很多分机。

分机

  • 一个用户可以有0个或多个分机。创建一个用户可以选择同时创建一个同名分机。
  • 在简单场景下,可以只有一个admin用户,其它分机都挂在该用户下(当然也可以挂在system用户下)。
  • 也可以用户与分机一一对应。
  • 分机可以使用密码或Token鉴权,如果在Websocket/WebRTC端使用,可以使用用户登录,再获取分机的Token(详见API手册)。
  • 如果是SIP客户端软件,在可以获取Token的情况下,可以/建议使用Token鉴权,如果是硬件话机则仍使用用户名/密码登录。
  • 用户管理分机,分机用于打电话。
  • 分机必须属于一个用户,在小规模应用场景下,为每个分机都建立一个对应的用户可能有点复杂,这时候,可以让分机属于system用户。

权限

权限指Web界面和API的使用权限。权限采用业界流行的RBAC(Role Based Access Control,基于角色的访问控制)设计。可以给一个用户分配多个不同的角色,不同的角色可以分配不同的权限。用户总是从自己所属的角色上获取权限。权限用于控制某些菜单对用户是否可见,某些API对用户是否可以访问等。

呼叫方向和呼叫流程

呼叫方向有入局(Inbound、Incoming)和出局(Outbound、Outgoing)呼叫两种。所有方向都是相对于XSwitch本身而言的。即呼叫的方向是相对的,看参照物是谁。比如我打了你一拳,我就是拳,而对于你就是拳了。

一个通常的误解是用户描述电话故障的时候通常说电话打不出去,这时候,他(她)其实是站在自己(电话机)的角度说的,对于XSwitch而言,可能是入局故障(从话机到XSwitch),也可能是出局故障(从XSwitch到落地网关或运营商)。所以在排查电话故障时,一定注意参照物,把呼叫流程搞清楚再下手。

XSwitch是一个B2BUA(背靠背用户代理),一个典型的呼叫流程如下:

路由

路由是本系统中最最重要的概念。路由即电话从哪里来到哪里去。呼叫源用于描述电话从哪里来,目的地描述电话到哪里去。在路由上可以做“号码变换”,设置计费规则,是否自动录音,设置不同时间段目的地等。

本系统路由均根据被叫号码判断。在默认配置中,来自“本地分机”(即注册分机)的呼叫,一般呼叫源为default,来自中继网关的外部呼叫,一般为public,在实际部署时可能有所不同。

呼叫源是针对来话而言的,系统允许在最先收到来话的地方设置关联的呼叫源,如本地注册用户来话、中继来话、网关来话等。

DID和DOD中的号码映射规则优先级要高于路由,除此之外,所有送到系统的呼叫都要通过路由决定去向,详见\ref{routes} 路由

呼叫权限

呼叫权限指分机的呼叫权限,可以在分机上指定。如果分机的呼叫权限大于或等于路由上设置的呼叫权限,电话就能通,反之不通。

会话和通道

会话(Session)和通道(Channel)在XSwitch中是一对一的。XSwitch是一个背靠背的用户代理(B2BUA)。分机A通过XSwitch打给分机B,在XSwitch内会产生两个通道,也就是两个会话。同理,分机A通过XSwitch拨打一个手机号,也会产生两个通道。分机或外线打电话到IVR或会议,只会产生一个通道。每一个通道都有一个唯一的UUID(Universally Unique Identifier,通用唯一识别码,全球唯一,包含36个字符,如“00000000-0000-0000-0000-000000000000”)。

XSwitch的许可证是按通道授权的,分机打IVR或会议只占用一个通道授权,但通过网关打外线电话则占用两个授权。

通话

通话指一路电话、一个电话、或一通电话,指通信的两个实体间逻辑的概念。如分机A打给B,称为一路通话,它包含两个通道。三方通话其实也是一个通话,但是会有三个通道,每个通道代表参与通话的一方。

WebRTC

XSwitch支持基于SIP信令(SIP Over Websocket)及Verto信令的WebRTC通话,但是,WebRTC通话通常需要相应的https及相关证书。如何部署WebRTC通话不在本文档范围内,可以参考在线文档如何在XSwitch中使用WebRTC

如果已经部署了WebRTC功能,则可以在最新版的Chrome、Firefox、Microsoft Edge等主流浏览器中使用WebRTC通话。

WebRTC通话支持PCMA、PCMU、OPUS、H264、H265、VP8等音视频编码。

可以通过以下方法设置证书。

GoDaddy获取到的证书

客户需要提供自己的私钥(申请证书时上传的私钥)以及下载的证书

openssl x509 -in gd_bundle-g2-g1.crt -out chain.pem -outform PEM
cat 客户提供的证书.pem chain.pem > fullchain.pem
cat fullchain.pem 客户的私钥.pem > wss.pem
cat 客户提供的证书.pem 客户的私钥.pem > agent.pem

将生成的wss.pem上传到容器内/usr/local/freeswitch/certs/下即可,一般来说在Docker环境下该目录会映射到宿主机上相应的目录。

Nginx配置

如果存在Nginx镜像,修改Nginx配置文件,开启如下参数:

ssl_certificate /data/xswitch.cn/fullchain.pem;
ssl_certificate_key /data/xswitch.cn/客户私钥.pem;
ssl_trusted_certificate /data/xswitch.cn/chain.pem;

其他途径获取的证书

提供私钥以及证书即可。

按照上述方式上传到/usr/local/freeswitch/cert/以及修改Nginx配置。

快速上手