基本概念

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

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

实际上，为了使系统保持简单，我们淡化了用户的使用。在最小最简的应用中，您可以只有一个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，称为一路通话，它包含两个通道。三方通话其实也是一个通话，但是会有三个通道，每个通道代表参与通话的一方。

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 等音视频编码。

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

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

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 配置文件，开启如下参数：

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 配置。