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