安装指南

XSwitch 以 Docker 镜像方式提供，需要先下载一些安装脚本，安装脚本在安装过程中需要从 XSwitch 官网上下载镜像及需要的资源文件，请保持网络畅通。在没有公网的环境下安装，请参考离线安装。

以下步骤将安装最新的 XSwitch v6.2.5 正式版（版本是基于 Debian 12 编译）。

如果你有 wget，可以通过如下命令下载：

社区版

wget https://xswitch.cn/download/xswitch-community-6.2.5.tar.gz --user xswitch --password password

或直接点击这里下载社区版；

企业版

wget https://xswitch.cn/download/xswitch-6.2.5.tar.gz --user xswitch --password password

开发版

wget https://xswitch.cn/download/xswitch-6.2.5-pre.tar.gz --user xswitch --password password

或直接点击这里下载开发版；

如果系统没有安装 wget，也可以通过系统自带的 curl 命令进行下载

curl -u xswitch:password -O https://xswitch.cn/download/xswitch-community-6.2.5.tar.gz
curl -u xswitch:password -O https://xswitch.cn/download/xswitch-6.2.5.tar.gz
curl -u xswitch:password -O https://xswitch.cn/download/xswitch-6.2.5-pre.tar.gz

我们推荐将 XSwitch 安装到以下位置（任选其一）：

• /usr/local/xswitch-community-6.2.5
• /opt/xswitch-community-6.2.5
• /root/xswitch-community-6.2.5
• /home/yourname/xswitch-community-6.2.5

下列命令将 XSwitch 安装到/usr/local/xswitch-community-6.2.5目录下，请确保有写入权限，如果使用企业版则修改相应的目录。

tar zxvf xswitch-community-6.2.5.tar.gz -C /usr/local

cd /usr/local/xswitch-community-6.2.5

请严格按照以下步骤执行。

make setup

执行此命令会自动从 XSwitch 官网下载声音文件和生成.env文件，.env里的参数为 Docker 容器运行时的环境变量。

注意：.env文件在 Linux 下默认是个隐藏文件，可以使用ls -la或find . -name .env、cat .env等命令显示，详见Docker 关于.env文件的相关说明。

打开.env文件，修改如下几个参数：

EXT_IP=22.22.2.2     # 这是外网地址（如果是内网使用，填写内网地址即可）
LOCAL_IP=192.168.1.1 # 这是内网地址（如果是内网使用，填写内网地址即可），如果是Mac则无此参数
FREESWITCH_DOMAIN=demo.xswitch.cn # 这是填写域的地方（用户或分机的域，可根据需要自行设置，也可以设成IP地址）

特别注意：FREESWITCH_DOMAIN 若是修改域名，会导致页面登录提示密码错误，需要执行bash update.sh命令。

NGINX_PROXY_IP=192.168.1.1 # 和LOCAL_IP填写相同内网地址即可，如果是Mac无需改动
HTTP_PORT=8080             # HTTP网址访问的端口（比如设置了8080，访问时输入http://ip:8080）

以下参数基本不用改动

DSN=postgresql://xui:xui@127.0.0.1/xui # 数据库连接地址，Mac下路径稍有不同
SIP_PORT=7060                          # UDP注册端口号
SIP_TLS_PORT=7061                      # TLS注册端口号
SIP_PUBLIC_PORT=7080                   # public对应端口号，用于网关对接等
SIP_PUBLIC_TLS_PORT=7081               # TLS Public对应端口号
VERTO_WS_PORT=8081                     # Verto WS对应端口号
VERTO_WSS_PORT=8082                    # Verto WSS对应端口号
RTP_START=10000                        # RTP媒体允许使用的最小端口
RTP_END=10099                          # RTP媒体允许使用的最大端口
ESL_PORT=8021                          # ESL对应端口

注意，如果在 NAT 环境下（非host网络，在 macOS 上必须使用 NAT）RTP 端口段不要开得太大，否则会影响效率。如果在生产环境中使用，请咨询 XSwitch 系统支持工程师获取最佳配置方案。

目前测试能够支持bookworm镜像的最低docker-ce版本是20.10.10，同时它还与libseccomp版本有关，如果低版本docker不想升级，或者由于系统版本过低，不能升级。可以通过添加参数--security-opt seccomp=unconfined，禁用内核安全配置来解决这个问题。 docker-compose.yml中禁用seccomp的办法。

    security_opt:
      - seccomp:unconfined

make up

启动系统。首次运行会自动拉取镜象。启动后，可以通过 http://你的服务器IP:8081 访问 Web 界面。默认用户名是admin，默认密码获取请关注小樱桃科技微信公众号，关注成功后，输入admin即可获取新版本密码。

如果使用 NATS 功能，使用以下命令可以启动/关闭 nats。默认端口：4222。调用地址：nats://xswitch-nats:4222。

make nats

make down-nats

注意，WARN[0000] /usr/local/xswitch-community-6.2.2/docker-compose.yml: version is obsolete;启动时，如有上述警告，可将docker-compose.yml文件第一行注释掉。

在 Windows 上安装 XSwitch 有两种方法，一种是在 Windows 上通过 Docker Desktop 运行 XSwitch，另一种是在 WSL 2 内部的 Linux 系统中通过 Docker Engine 运行 XSwitch 。这两种方式都需要你安装 WSL 2。

下面，我们分别介绍这两种方法。你可以选择一种方式安装和运行 XSwitch，也可以根据情况切换。

首先你需要安装 WSL 2（适用于 Linux 的 Windows 子系统）和 Docker Desktop。

WSL 2 可以让你在 Windows 计算机上运行 Linux 环境，而无需单独的虚拟机或双引导。

Docker Desktop 可以让你在 Windows 上运行 Docker 。

点击这里查看 Docker Desktop 和 WSL 2 的安装方式。

以下命令要在 Windows Terminal 中运行。

curl -u xswitch:password "https://xswitch.cn/download/xswitch-community-6.2.5.tar.gz" --output xswitch-community-6.2.5.tar.gz

tar zxvf xswitch-community-6.2.5.tar.gz

cd xswitch-community-6.2.5

.\build.cmd setup

用 sublime text 或 vscode 等编辑器打开 .env 文件，将 EXT_IP 的值修改为 Windows 的 IP 地址，如果想修改其他配置参数可以参考XSwitch 官方文档 。

.\build.cmd start

等待服务启动，首次启动需要拉取镜像，根据网络状况大概需要 2 - 5 分钟时间。

进入 XSwitch 容器

.\build.cmd bash

进入 XSwitch Cli 控制台

.\build.cmd cli

实时查看 XSwitch 日志

.\build.cmd logs

停止服务

.\build.cmd stop

WSL 2 有两种网络模式，默认模式为 NAT 模式，还有一种叫镜像模式网络。

这里我们推荐使用镜像模式网络，因为 NAT 模式下想要让局域网内的设备访问 XSwitch 的服务，需要在 Windows 上做端口代理，而官方给的代理方案是用 netsh interface portproxy，这种代理仅支持 TCP 协议，而 XSwitch 的媒体传输协议是 UDP ，所以局域网内的终端与 XSwitch 的媒体是不通的。

需要启用镜像模式网络，点击查看镜像模式启用方法 。

在 Windows Terminal 中输入 wsl 进入 Linux 环境。

安装 XSwitch 的方法与 如何在 Linux 和 Mac OS 上安装 XSwitch 相同 。

在自己的 Windows 上访问 XSwitch ，可以通过 localhost 或者 Windows 的 IP 地址访问。

从局域网访问 XSwitch，需要关闭 Windows 的防火墙或者给所有用到的端口添加相应的入站出站规则，然后访问 Windows 的 IP 地址即可。

通过执行docker ps可查看 docker 服务是否已正常启动。

如果有服务启动出错，可通过执行docker logs -f xswitch查看xswitch容器相关日志（xswitch为容器名）。

通过执行make bash进入xswitch容器内部，然后输入fs_cli可以连接控制台查看系统运行情况。